list\[ChatMessage\] | str | None) – A list of `ChatMessage` objects or a string template. The component looks for Jinja2 template syntax and
+ renders the prompt with the provided variables. Provide the template in either
+ the `init` method`or the`run\` method.
+- **required_variables** (list\[str\] | Literal['\*'] | None) – List variables that must be provided as input to ChatPromptBuilder.
+ If a variable listed as required is not provided, an exception is raised.
+ If set to `"*"`, all variables found in the prompt are required. Optional.
+- **variables** (list\[str\] | None) – List input variables to use in prompt templates instead of the ones inferred from the
+ `template` parameter. For example, to use more variables during prompt engineering than the ones present
+ in the default template, you can provide them here.
+
+#### run
+
+```python
+run(
+ template: list[ChatMessage] | str | None = None,
+ template_variables: dict[str, Any] | None = None,
+ **kwargs: Any
+) -> dict[str, list[ChatMessage]]
+```
+
+Renders the prompt template with the provided variables.
+
+It applies the template variables to render the final prompt. You can provide variables with pipeline kwargs.
+To overwrite the default template, you can set the `template` parameter.
+To overwrite pipeline kwargs, you can set the `template_variables` parameter.
+
+**Parameters:**
+
+- **template** (list\[ChatMessage\] | str | None) – An optional list of `ChatMessage` objects or string template to overwrite ChatPromptBuilder's default
+ template.
+ If `None`, the default template provided at initialization is used.
+- **template_variables** (dict\[str, Any\] | None) – An optional dictionary of template variables to overwrite the pipeline variables.
+- **kwargs** (Any) – Pipeline variables used for rendering the prompt.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `prompt`: The updated list of `ChatMessage` objects after rendering the templates.
+
+**Raises:**
+
+- ValueError – If `chat_messages` is empty or contains elements that are not instances of `ChatMessage`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the component.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized dictionary representation of the component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChatPromptBuilder
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize and create the component.
+
+**Returns:**
+
+- ChatPromptBuilder – The deserialized component.
+
+## prompt_builder
+
+### PromptBuilder
+
+Renders a prompt filling in any variables so that it can send it to a Generator.
+
+The prompt uses Jinja2 template syntax.
+The variables in the default template are used as PromptBuilder's input and are all optional.
+If they're not provided, they're replaced with an empty string in the rendered prompt.
+To try out different prompts, you can replace the prompt template at runtime by
+providing a template for each pipeline run invocation.
+
+### Usage examples
+
+#### On its own
+
+This example uses PromptBuilder to render a prompt template and fill it with `target_language`
+and `snippet`. PromptBuilder returns a prompt with the string "Translate the following context to Spanish.
+Context: I can't speak Spanish.; Translation:".
+
+```python
+from haystack.components.builders import PromptBuilder
+
+template = "Translate the following context to {{ target_language }}. Context: {{ snippet }}; Translation:"
+builder = PromptBuilder(template=template)
+builder.run(target_language="spanish", snippet="I can't speak spanish.")
+```
+
+#### In a Pipeline
+
+This is an example of a RAG pipeline where PromptBuilder renders a custom prompt template and fills it
+with the contents of the retrieved documents and a query. The rendered prompt is then sent to a Generator.
+
+```python
+from haystack import Pipeline, Document
+from haystack.utils import Secret
+from haystack.components.generators import OpenAIGenerator
+from haystack.components.builders.prompt_builder import PromptBuilder
+
+# in a real world use case documents could come from a retriever, web, or any other source
+documents = [Document(content="Joe lives in Berlin"), Document(content="Joe is a software engineer")]
+prompt_template = """
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ Question: {{query}}
+ Answer:
+ """
+p = Pipeline()
+p.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+p.add_component(instance=OpenAIGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")), name="llm")
+p.connect("prompt_builder", "llm")
+
+question = "Where does Joe live?"
+result = p.run({"prompt_builder": {"documents": documents, "query": question}})
+print(result)
+```
+
+#### Changing the template at runtime (prompt engineering)
+
+You can change the prompt template of an existing pipeline, like in this example:
+
+```python
+documents = [
+ Document(content="Joe lives in Berlin", meta={"name": "doc1"}),
+ Document(content="Joe is a software engineer", meta={"name": "doc1"}),
+]
+new_template = """
+ You are a helpful assistant.
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ Document {{ loop.index }}:
+ Document name: {{ doc.meta['name'] }}
+ {{ doc.content }}
+ {% endfor %}
+
+ Question: {{ query }}
+ Answer:
+ """
+p.run({
+ "prompt_builder": {
+ "documents": documents,
+ "query": question,
+ "template": new_template,
+ },
+})
+```
+
+To replace the variables in the default template when testing your prompt,
+pass the new variables in the `variables` parameter.
+
+#### Overwriting variables at runtime
+
+To overwrite the values of variables, use `template_variables` during runtime:
+
+```python
+language_template = """
+You are a helpful assistant.
+Given these documents, answer the question.
+Documents:
+{% for doc in documents %}
+ Document {{ loop.index }}:
+ Document name: {{ doc.meta['name'] }}
+ {{ doc.content }}
+{% endfor %}
+
+Question: {{ query }}
+Please provide your answer in {{ answer_language | default('English') }}
+Answer:
+"""
+p.run({
+ "prompt_builder": {
+ "documents": documents,
+ "query": question,
+ "template": language_template,
+ "template_variables": {"answer_language": "German"},
+ },
+})
+```
+
+Note that `language_template` introduces variable `answer_language` which is not bound to any pipeline variable.
+If not set otherwise, it will use its default value 'English'.
+This example overwrites its value to 'German'.
+Use `template_variables` to overwrite pipeline variables (such as documents) as well.
+
+#### __init__
+
+```python
+__init__(
+ template: str,
+ required_variables: list[str] | Literal["*"] | None = None,
+ variables: list[str] | None = None,
+) -> None
+```
+
+Constructs a PromptBuilder component.
+
+**Parameters:**
+
+- **template** (str) – A prompt template that uses Jinja2 syntax to add variables. For example:
+ `"Summarize this document: {{ documents[0].content }}\nSummary:"`
+ It's used to render the prompt.
+ The variables in the default template are input for PromptBuilder and are all optional,
+ unless explicitly specified.
+ If an optional variable is not provided, it's replaced with an empty string in the rendered prompt.
+- **required_variables** (list\[str\] | Literal['\*'] | None) – List variables that must be provided as input to PromptBuilder.
+ If a variable listed as required is not provided, an exception is raised.
+ If set to `"*"`, all variables found in the prompt are required. Optional.
+- **variables** (list\[str\] | None) – List input variables to use in prompt templates instead of the ones inferred from the
+ `template` parameter. For example, to use more variables during prompt engineering than the ones present
+ in the default template, you can provide them here.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the component.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized dictionary representation of the component.
+
+#### run
+
+```python
+run(
+ template: str | None = None,
+ template_variables: dict[str, Any] | None = None,
+ **kwargs: Any
+) -> dict[str, Any]
+```
+
+Renders the prompt template with the provided variables.
+
+It applies the template variables to render the final prompt. You can provide variables via pipeline kwargs.
+In order to overwrite the default template, you can set the `template` parameter.
+In order to overwrite pipeline kwargs, you can set the `template_variables` parameter.
+
+**Parameters:**
+
+- **template** (str | None) – An optional string template to overwrite PromptBuilder's default template. If None, the default template
+ provided at initialization is used.
+- **template_variables** (dict\[str, Any\] | None) – An optional dictionary of template variables to overwrite the pipeline variables.
+- **kwargs** (Any) – Pipeline variables used for rendering the prompt.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `prompt`: The updated prompt text after rendering the prompt template.
+
+**Raises:**
+
+- ValueError – If any of the required template variables is not provided.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/cachings_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/cachings_api.md
new file mode 100644
index 0000000000..b854ee0d06
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/cachings_api.md
@@ -0,0 +1,114 @@
+---
+title: "Caching"
+id: caching-api
+description: "Checks if any document coming from the given URL is already present in the store."
+slug: "/caching-api"
+---
+
+
+## cache_checker
+
+### CacheChecker
+
+Checks for the presence of documents in a Document Store based on a specified field in each document's metadata.
+
+If matching documents are found, they are returned as "hits". If not found in the cache, the items
+are returned as "misses".
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.caching.cache_checker import CacheChecker
+
+docstore = InMemoryDocumentStore()
+documents = [
+ Document(content="doc1", meta={"url": "https://example.com/1"}),
+ Document(content="doc2", meta={"url": "https://example.com/2"}),
+ Document(content="doc3", meta={"url": "https://example.com/1"}),
+ Document(content="doc4", meta={"url": "https://example.com/2"}),
+]
+docstore.write_documents(documents)
+checker = CacheChecker(docstore, cache_field="url")
+results = checker.run(items=["https://example.com/1", "https://example.com/5"])
+assert results == {"hits": [documents[0], documents[2]], "misses": ["https://example.com/5"]}
+```
+
+#### __init__
+
+```python
+__init__(document_store: DocumentStore, cache_field: str) -> None
+```
+
+Creates a CacheChecker component.
+
+**Parameters:**
+
+- **document_store** (DocumentStore) – Document Store to check for the presence of specific documents.
+- **cache_field** (str) – Name of the document's metadata field
+ to check for cache hits.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CacheChecker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- CacheChecker – Deserialized component.
+
+#### run
+
+```python
+run(items: list[Any]) -> dict[str, Any]
+```
+
+Checks if any document associated with the specified cache field is already present in the store.
+
+**Parameters:**
+
+- **items** (list\[Any\]) – Values to be checked against the cache field.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with two keys:
+- `hits` - Documents that matched with at least one of the items.
+- `misses` - Items that were not present in any documents.
+
+#### run_async
+
+```python
+run_async(items: list[Any]) -> dict[str, Any]
+```
+
+Asynchronously checks if any document associated with the specified cache field is already present in the store.
+
+**Parameters:**
+
+- **items** (list\[Any\]) – Values to be checked against the cache field.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with two keys:
+- `hits` - Documents that matched with at least one of the items.
+- `misses` - Items that were not present in any documents.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/classifiers_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/classifiers_api.md
new file mode 100644
index 0000000000..5785ad31d6
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/classifiers_api.md
@@ -0,0 +1,247 @@
+---
+title: "Classifiers"
+id: classifiers-api
+description: "Classify documents based on the provided labels."
+slug: "/classifiers-api"
+---
+
+
+## document_language_classifier
+
+### DocumentLanguageClassifier
+
+Classifies the language of each document and adds it to its metadata.
+
+Provide a list of languages during initialization. If the document's text doesn't match any of the
+specified languages, the metadata value is set to "unmatched".
+To route documents based on their language, use the MetadataRouter component after DocumentLanguageClassifier.
+For routing plain text, use the TextLanguageRouter component instead.
+
+### Usage example
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.classifiers import DocumentLanguageClassifier
+from haystack.components.routers import MetadataRouter
+from haystack.components.writers import DocumentWriter
+
+docs = [Document(id="1", content="This is an English document"),
+ Document(id="2", content="Este es un documento en español")]
+
+document_store = InMemoryDocumentStore()
+
+p = Pipeline()
+p.add_component(instance=DocumentLanguageClassifier(languages=["en"]), name="language_classifier")
+p.add_component(
+instance=MetadataRouter(rules={
+ "en": {
+ "field": "meta.language",
+ "operator": "==",
+ "value": "en"
+ }
+}),
+name="router")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+p.connect("language_classifier.documents", "router.documents")
+p.connect("router.en", "writer.documents")
+
+p.run({"language_classifier": {"documents": docs}})
+
+written_docs = document_store.filter_documents()
+assert len(written_docs) == 1
+assert written_docs[0] == Document(id="1", content="This is an English document", meta={"language": "en"})
+```
+
+#### __init__
+
+```python
+__init__(languages: list[str] | None = None) -> None
+```
+
+Initializes the DocumentLanguageClassifier component.
+
+**Parameters:**
+
+- **languages** (list\[str\] | None) – A list of ISO language codes.
+ See the supported languages in [`langdetect` documentation](https://github.com/Mimino666/langdetect#languages).
+ If not specified, defaults to ["en"].
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Classifies the language of each document and adds it to its metadata.
+
+If the document's text doesn't match any of the languages specified at initialization,
+sets the metadata value to "unmatched".
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents for language classification.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following key:
+- `documents`: A list of documents with an added `language` metadata field.
+
+**Raises:**
+
+- TypeError – if the input is not a list of Documents.
+
+## zero_shot_document_classifier
+
+### TransformersZeroShotDocumentClassifier
+
+Performs zero-shot classification of documents based on given labels and adds the predicted label to their metadata.
+
+The component uses a Hugging Face pipeline for zero-shot classification.
+Provide the model and the set of labels to be used for categorization during initialization.
+Additionally, you can configure the component to allow multiple labels to be true.
+
+Classification is run on the document's content field by default. If you want it to run on another field, set the
+`classification_field` to one of the document's metadata fields.
+
+Available models for the task of zero-shot-classification include:
+\- `valhalla/distilbart-mnli-12-3`
+\- `cross-encoder/nli-distilroberta-base`
+\- `cross-encoder/nli-deberta-v3-xsmall`
+
+### Usage example
+
+The following is a pipeline that classifies documents based on predefined classification labels
+retrieved from a search pipeline:
+
+```python
+from haystack import Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.core.pipeline import Pipeline
+from haystack.components.classifiers import TransformersZeroShotDocumentClassifier
+
+documents = [Document(id="0", content="Today was a nice day!"),
+ Document(id="1", content="Yesterday was a bad day!")]
+
+document_store = InMemoryDocumentStore()
+retriever = InMemoryBM25Retriever(document_store=document_store)
+document_classifier = TransformersZeroShotDocumentClassifier(
+ model="cross-encoder/nli-deberta-v3-xsmall",
+ labels=["positive", "negative"],
+)
+
+document_store.write_documents(documents)
+
+pipeline = Pipeline()
+pipeline.add_component(instance=retriever, name="retriever")
+pipeline.add_component(instance=document_classifier, name="document_classifier")
+pipeline.connect("retriever", "document_classifier")
+
+queries = ["How was your day today?", "How was your day yesterday?"]
+expected_predictions = ["positive", "negative"]
+
+for idx, query in enumerate(queries):
+ result = pipeline.run({"retriever": {"query": query, "top_k": 1}})
+ assert result["document_classifier"]["documents"][0].to_dict()["id"] == str(idx)
+ assert (result["document_classifier"]["documents"][0].to_dict()["classification"]["label"]
+ == expected_predictions[idx])
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ labels: list[str],
+ multi_label: bool = False,
+ classification_field: str | None = None,
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ huggingface_pipeline_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Initializes the TransformersZeroShotDocumentClassifier.
+
+See the Hugging Face [website](https://huggingface.co/models?pipeline_tag=zero-shot-classification&sort=downloads&search=nli)
+for the full list of zero-shot classification models (NLI) models.
+
+**Parameters:**
+
+- **model** (str) – The name or path of a Hugging Face model for zero shot document classification.
+- **labels** (list\[str\]) – The set of possible class labels to classify each document into, for example,
+ ["positive", "negative"]. The labels depend on the selected model.
+- **multi_label** (bool) – Whether or not multiple candidate labels can be true.
+ If `False`, the scores are normalized such that
+ the sum of the label likelihoods for each sequence is 1. If `True`, the labels are considered
+ independent and probabilities are normalized for each candidate by doing a softmax of the entailment
+ score vs. the contradiction score.
+- **classification_field** (str | None) – Name of document's meta field to be used for classification.
+ If not set, `Document.content` is used by default.
+- **device** (ComponentDevice | None) – The device on which the model is loaded. If `None`, the default device is automatically
+ selected. If a device/device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter.
+- **token** (Secret | None) – The Hugging Face token to use as HTTP bearer authorization.
+ Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **huggingface_pipeline_kwargs** (dict\[str, Any\] | None) – Dictionary containing keyword arguments used to initialize the
+ Hugging Face pipeline for text classification.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TransformersZeroShotDocumentClassifier
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- TransformersZeroShotDocumentClassifier – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document], batch_size: int = 1) -> dict[str, Any]
+```
+
+Classifies the documents based on the provided labels and adds them to their metadata.
+
+The classification results are stored in the `classification` dict within
+each document's metadata. If `multi_label` is set to `True`, the scores for each label are available under
+the `details` key within the `classification` dictionary.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to process.
+- **batch_size** (int) – Batch size used for processing the content in each document.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following key:
+- `documents`: A list of documents with an added metadata field called `classification`.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/connectors_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/connectors_api.md
new file mode 100644
index 0000000000..2544984122
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/connectors_api.md
@@ -0,0 +1,275 @@
+---
+title: "Connectors"
+id: connectors-api
+description: "Various connectors to integrate with external services."
+slug: "/connectors-api"
+---
+
+
+## openapi
+
+### OpenAPIConnector
+
+OpenAPIConnector enables direct invocation of REST endpoints defined in an OpenAPI specification.
+
+The OpenAPIConnector serves as a bridge between Haystack pipelines and any REST API that follows
+the OpenAPI(formerly Swagger) specification. It dynamically interprets the API specification and
+provides an interface for executing API operations. It is usually invoked by passing input
+arguments to it from a Haystack pipeline run method or by other components in a pipeline that
+pass input arguments to this component.
+
+Example:
+
+
+
+```python
+from haystack.utils import Secret
+from haystack.components.connectors.openapi import OpenAPIConnector
+
+serper_dev_token = Secret.from_env_var("SERPERDEV_API_KEY")
+
+def my_custom_config_factory():
+ # Create and return a custom configuration for the OpenAPIClient
+ pass
+
+connector = OpenAPIConnector(
+ openapi_spec="https://bit.ly/serperdev_openapi",
+ credentials=serper_dev_token,
+ service_kwargs={"config_factory": my_custom_config_factory()}
+)
+response = connector.run(
+ operation_id="search",
+ arguments={"q": "Who was Nikola Tesla?"}
+)
+```
+
+Note:
+
+- The `service_kwargs` argument is optional, it can be used to pass additional options to the OpenAPIClient.
+
+#### __init__
+
+```python
+__init__(
+ openapi_spec: str,
+ credentials: Secret | None = None,
+ service_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the OpenAPIConnector with a specification and optional credentials.
+
+**Parameters:**
+
+- **openapi_spec** (str) – URL, file path, or raw string of the OpenAPI specification
+- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret
+- **service_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments passed to OpenAPIClient.from_spec()
+ For example, you can pass a custom config_factory or other configuration options.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAPIConnector
+```
+
+Deserialize this component from a dictionary.
+
+#### run
+
+```python
+run(
+ operation_id: str, arguments: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Invokes a REST endpoint specified in the OpenAPI specification.
+
+**Parameters:**
+
+- **operation_id** (str) – The operationId from the OpenAPI spec to invoke
+- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters)
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary containing the service response
+
+## openapi_service
+
+### patch_request
+
+```python
+patch_request(
+ self: Operation,
+ base_url: str,
+ *,
+ data: Any | None = None,
+ parameters: dict[str, Any] | None = None,
+ raw_response: bool = False,
+ security: dict[str, str] | None = None,
+ session: Any | None = None,
+ verify: bool | str = True
+) -> Any | None
+```
+
+Sends an HTTP request as described by this path.
+
+**Parameters:**
+
+- **base_url** (str) – The URL to append this operation's path to when making
+ the call.
+- **data** (Any | None) – The request body to send.
+- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path.
+- **raw_response** (bool) – If true, return the raw response instead of validating
+ and extrapolating it.
+- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to
+ process successfully.
+- **session** (Any | None) – A persistent request session.
+- **verify** (bool | str) – If we should do an SSL verification on the request or not.
+ In case str was provided, will use that as the CA.
+
+**Returns:**
+
+- Any | None – The response data, either raw or processed depending on raw_response flag.
+
+### OpenAPIServiceConnector
+
+A component which connects the Haystack framework to OpenAPI services.
+
+The `OpenAPIServiceConnector` component connects the Haystack framework to OpenAPI services, enabling it to call
+operations as defined in the OpenAPI specification of the service.
+
+It integrates with `ChatMessage` dataclass, where the `ToolCall` entries in messages are used to determine the
+method to be called and the parameters to be passed. The method name and parameters are then used to invoke the
+method on the OpenAPI service. The response from the service is returned as a `ChatMessage`.
+
+Before using this component, users usually resolve service endpoint parameters with a help of
+`OpenAPIServiceToFunctions` component.
+
+The example below demonstrates how to use the `OpenAPIServiceConnector` to invoke a method on a https://serper.dev/
+service specified via OpenAPI specification.
+
+Note, however, that `OpenAPIServiceConnector` is usually not meant to be used directly, but rather as part of a
+pipeline that includes the `OpenAPIServiceToFunctions` component and a Chat Generator component using an LLM
+with tool calling capabilities. In the example below we use the tool call payload directly, but in a
+real-world scenario, the tool calls would usually be generated by the Chat Generator component.
+
+You need to define the `serper_token` variable with your Serper.dev API token for the example to work.
+Can be through the `SERPERDEV_API_KEY` environment variable or by directly assigning the token string to the
+variable in the code.
+
+Usage example:
+
+
+
+```python
+import json
+import httpx
+
+from haystack.components.connectors import OpenAPIServiceConnector
+from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.utils import Secret
+
+tool_call = ToolCall(
+ tool_name="search",
+ arguments={"q": "Why was Sam Altman ousted from OpenAI?"},
+)
+message = ChatMessage.from_assistant(tool_calls=[tool_call])
+
+serper_token = Secret.from_env_var("SERPERDEV_API_KEY").resolve_value()
+serperdev_openapi_spec = json.loads(httpx.get("https://bit.ly/serper_dev_spec", follow_redirects=True).text)
+service_connector = OpenAPIServiceConnector()
+result = service_connector.run(
+ messages=[message],
+ service_openapi_spec=serperdev_openapi_spec,
+ service_credentials=serper_token,
+)
+print(result)
+
+# {'service_response': ChatMessage(_role=[bool | str | None) – Decide if to use SSL verification to the requests or not,
+ in case a string is passed, will be used as the CA.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ service_openapi_spec: dict[str, Any],
+ service_credentials: dict | str | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Processes a list of chat messages to invoke a method on an OpenAPI service.
+
+It parses the last message in the list, expecting it to contain tool calls.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message
+ should contain the tool calls.
+- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs
+ should already be resolved.
+- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service.
+ Currently, only the http and apiKey OpenAPI security schemes are supported.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `service_response`: a list of `ChatMessage` objects, each containing the response from the service. The
+ response is in JSON format, and the `content` attribute of the `ChatMessage` contains
+ the JSON string.
+
+**Raises:**
+
+- ValueError – If the last message is not from the assistant or if it does not contain tool calls.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- OpenAPIServiceConnector – The deserialized component.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/converters_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/converters_api.md
new file mode 100644
index 0000000000..dd0f1a02cd
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/converters_api.md
@@ -0,0 +1,1950 @@
+---
+title: "Converters"
+id: converters-api
+description: "Various converters to transform data from one format to another."
+slug: "/converters-api"
+---
+
+
+## azure
+
+### AzureOCRDocumentConverter
+
+Converts files to documents using Azure's Document Intelligence service.
+
+Supported file formats are: PDF, JPEG, PNG, BMP, TIFF, DOCX, XLSX, PPTX, and HTML.
+
+To use this component, you need an active Azure account
+and a Document Intelligence or Cognitive Services resource. For help with setting up your resource, see
+[Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/quickstarts/get-started-sdks-rest-api).
+
+### Usage example
+
+
+
+```python
+import os
+from datetime import datetime
+from haystack.components.converters import AzureOCRDocumentConverter
+from haystack.utils import Secret
+
+converter = AzureOCRDocumentConverter(
+ endpoint=os.environ["CORE_AZURE_CS_ENDPOINT"],
+ api_key=Secret.from_env_var("CORE_AZURE_CS_API_KEY"),
+)
+results = converter.run(
+ sources=["test/test_files/pdf/react_paper.pdf"],
+ meta={"date_added": datetime.now().isoformat()},
+)
+documents = results["documents"]
+print(documents[0].content)
+# 'This is a text from the PDF file.'
+```
+
+#### __init__
+
+```python
+__init__(
+ endpoint: str,
+ api_key: Secret = Secret.from_env_var("AZURE_AI_API_KEY"),
+ model_id: str = "prebuilt-read",
+ preceding_context_len: int = 3,
+ following_context_len: int = 3,
+ merge_multiple_column_headers: bool = True,
+ page_layout: Literal["natural", "single_column"] = "natural",
+ threshold_y: float | None = 0.05,
+ store_full_path: bool = False,
+) -> None
+```
+
+Creates an AzureOCRDocumentConverter component.
+
+**Parameters:**
+
+- **endpoint** (str) – The endpoint of your Azure resource.
+- **api_key** (Secret) – The API key of your Azure resource.
+- **model_id** (str) – The ID of the model you want to use. For a list of available models, see [Azure documentation]
+ (https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/choose-model-feature).
+- **preceding_context_len** (int) – Number of lines before a table to include as preceding context
+ (this will be added to the metadata).
+- **following_context_len** (int) – Number of lines after a table to include as subsequent context (
+ this will be added to the metadata).
+- **merge_multiple_column_headers** (bool) – If `True`, merges multiple column header rows into a single row.
+- **page_layout** (Literal['natural', 'single_column']) – The type reading order to follow. Possible options:
+- `natural`: Uses the natural reading order determined by Azure.
+- `single_column`: Groups all lines with the same height on the page based on a threshold
+ determined by `threshold_y`.
+- **threshold_y** (float | None) – Only relevant if `single_column` is set to `page_layout`.
+ The threshold, in inches, to determine if two recognized PDF elements are grouped into a
+ single line. This is crucial for section headers or numbers which may be spatially separated
+ from the remaining text on the horizontal axis.
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, Any]
+```
+
+Convert a list of files to Documents using Azure's Document Intelligence service.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced Documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will be
+ zipped. If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of created Documents
+- `raw_azure_response`: List of raw Azure responses used to create the Documents
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureOCRDocumentConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- AzureOCRDocumentConverter – The deserialized component.
+
+## csv
+
+### CSVToDocument
+
+Converts CSV files to Documents.
+
+By default, it uses UTF-8 encoding when converting files but
+you can also set a custom encoding.
+It can attach metadata to the resulting documents.
+
+### Usage example
+
+```python
+from haystack.components.converters.csv import CSVToDocument
+from datetime import datetime
+
+converter = CSVToDocument()
+results = converter.run(
+ sources=["test/test_files/csv/sample_1.csv"], meta={"date_added": datetime.now().isoformat()}
+)
+documents = results["documents"]
+
+print(documents[0].content)
+# >> 'col1,col2\nrow1,row1\nrow2,row2\n'
+```
+
+#### __init__
+
+```python
+__init__(
+ encoding: str = "utf-8",
+ store_full_path: bool = False,
+ *,
+ conversion_mode: Literal["file", "row"] = "file",
+ delimiter: str = ",",
+ quotechar: str = '"'
+) -> None
+```
+
+Creates a CSVToDocument component.
+
+**Parameters:**
+
+- **encoding** (str) – The encoding of the csv files to convert.
+ If the encoding is specified in the metadata of a source ByteStream,
+ it overrides this value.
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+- **conversion_mode** (Literal['file', 'row']) – - "file" (default): one Document per CSV file whose content is the raw CSV text.
+- "row": convert each CSV row to its own Document (requires `content_column` in `run()`).
+- **delimiter** (str) – CSV delimiter used when parsing in row mode (passed to `csv.DictReader`).
+- **quotechar** (str) – CSV quote character used when parsing in row mode (passed to `csv.DictReader`).
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ *,
+ content_column: str | None = None,
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, Any]
+```
+
+Converts CSV files to a Document (file mode) or to one Document per row (row mode).
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects.
+- **content_column** (str | None) – **Required when** `conversion_mode="row"`.
+ The column name whose values become `Document.content` for each row.
+ The column must exist in the CSV header.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will
+ be zipped.
+ If `sources` contains ByteStream objects, their `meta` will be added to the output documents.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: Created documents
+
+## docx
+
+### DOCXMetadata
+
+Describes the metadata of Docx file.
+
+**Parameters:**
+
+- **author** (str) – The author
+- **category** (str) – The category
+- **comments** (str) – The comments
+- **content_status** (str) – The content status
+- **created** (str | None) – The creation date (ISO formatted string)
+- **identifier** (str) – The identifier
+- **keywords** (str) – Available keywords
+- **language** (str) – The language of the document
+- **last_modified_by** (str) – User who last modified the document
+- **last_printed** (str | None) – The last printed date (ISO formatted string)
+- **modified** (str | None) – The last modification date (ISO formatted string)
+- **revision** (int) – The revision number
+- **subject** (str) – The subject
+- **title** (str) – The title
+- **version** (str) – The version
+
+### DOCXTableFormat
+
+Bases: Enum
+
+Supported formats for storing DOCX tabular data in a Document.
+
+#### from_str
+
+```python
+from_str(string: str) -> DOCXTableFormat
+```
+
+Convert a string to a DOCXTableFormat enum.
+
+### DOCXLinkFormat
+
+Bases: Enum
+
+Supported formats for storing DOCX link information in a Document.
+
+#### from_str
+
+```python
+from_str(string: str) -> DOCXLinkFormat
+```
+
+Convert a string to a DOCXLinkFormat enum.
+
+### DOCXToDocument
+
+Converts DOCX files to Documents.
+
+Uses `python-docx` library to convert the DOCX file to a document.
+This component does not preserve page breaks in the original document.
+
+Usage example:
+
+```python
+from haystack.components.converters.docx import DOCXToDocument, DOCXTableFormat, DOCXLinkFormat
+from datetime import datetime
+
+converter = DOCXToDocument(table_format=DOCXTableFormat.CSV, link_format=DOCXLinkFormat.MARKDOWN)
+results = converter.run(
+ sources=["test/test_files/docx/sample_docx.docx"], meta={"date_added": datetime.now().isoformat()}
+)
+documents = results["documents"]
+
+print(documents[0].content)
+# >> 'This is a text from the DOCX file.'
+```
+
+#### __init__
+
+```python
+__init__(
+ table_format: str | DOCXTableFormat = DOCXTableFormat.CSV,
+ link_format: str | DOCXLinkFormat = DOCXLinkFormat.NONE,
+ store_full_path: bool = False,
+) -> None
+```
+
+Create a DOCXToDocument component.
+
+**Parameters:**
+
+- **table_format** (str | DOCXTableFormat) – The format for table output. Can be either DOCXTableFormat.MARKDOWN,
+ DOCXTableFormat.CSV, "markdown", or "csv".
+- **link_format** (str | DOCXLinkFormat) – The format for link output. Can be either:
+ DOCXLinkFormat.MARKDOWN or "markdown" to get `[text](address)`,
+ DOCXLinkFormat.PLAIN or "plain" to get text (address),
+ DOCXLinkFormat.NONE or "none" to get text without links.
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DOCXToDocument
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- DOCXToDocument – The deserialized component.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, Any]
+```
+
+Converts DOCX files to Documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced Documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will
+ be zipped.
+ If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: Created Documents
+
+## file_to_file_content
+
+### FileToFileContent
+
+Converts files to FileContent objects to be included in ChatMessage objects.
+
+### Usage example
+
+
+
+```python
+from haystack.components.converters import FileToFileContent
+
+converter = FileToFileContent()
+
+sources = ["document.pdf", "video.mp4"]
+
+file_contents = converter.run(sources=sources)["file_contents"]
+print(file_contents)
+
+# [FileContent(base64_data='...',
+# mime_type='application/pdf',
+# filename='document.pdf',
+# extra={}),
+# ...]
+```
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ *,
+ extra: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, list[FileContent]]
+```
+
+Converts files to FileContent objects.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects to convert.
+- **extra** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional extra information to attach to the FileContent objects. Can be used to store provider-specific
+ information.
+ To avoid serialization issues, values should be JSON serializable.
+ This value can be a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the extra of all produced FileContent objects.
+ If it's a list, its length must match the number of sources as they're zipped together.
+
+**Returns:**
+
+- dict\[str, list\[FileContent\]\] – A dictionary with the following keys:
+- `file_contents`: A list of FileContent objects.
+
+## html
+
+### HTMLToDocument
+
+Converts an HTML file to a Document.
+
+Usage example:
+
+```python
+from haystack.components.converters import HTMLToDocument
+
+converter = HTMLToDocument()
+results = converter.run(sources=["test/test_files/html/paul_graham_superlinear.html"])
+documents = results["documents"]
+
+print(documents[0].content)
+# >> 'This is a text from the HTML file.'
+```
+
+#### __init__
+
+```python
+__init__(
+ extraction_kwargs: dict[str, Any] | None = None,
+ store_full_path: bool = False,
+) -> None
+```
+
+Create an HTMLToDocument component.
+
+**Parameters:**
+
+- **extraction_kwargs** (dict\[str, Any\] | None) – A dictionary containing keyword arguments to customize the extraction process. These
+ are passed to the underlying Trafilatura `extract` function. For the full list of available arguments, see
+ the [Trafilatura documentation](https://trafilatura.readthedocs.io/en/latest/corefunctions.html#extract).
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HTMLToDocument
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- HTMLToDocument – The deserialized component.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+ extraction_kwargs: dict[str, Any] | None = None,
+) -> dict[str, Any]
+```
+
+Converts a list of HTML files to Documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of HTML file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced Documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will
+ be zipped.
+ If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+- **extraction_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments to customize the extraction process.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: Created Documents
+
+## image/document_to_image
+
+### DocumentToImageContent
+
+Converts documents sourced from PDF and image files into ImageContents.
+
+This component processes a list of documents and extracts visual content from supported file formats, converting
+them into ImageContents that can be used for multimodal AI tasks. It handles both direct image files and PDF
+documents by extracting specific pages as images.
+
+Documents are expected to have metadata containing:
+
+- The `file_path_meta_field` key with a valid file path that exists when combined with `root_path`
+- A supported image format (MIME type must be one of the supported image types)
+- For PDF files, a `page_number` key specifying which page to extract
+
+### Usage example
+
+
+
+```python
+from haystack import Document
+from haystack.components.converters.image.document_to_image import DocumentToImageContent
+
+converter = DocumentToImageContent(
+ file_path_meta_field="file_path",
+ root_path="/data/files",
+ detail="high",
+ size=(800, 600)
+)
+
+documents = [
+ Document(content="Optional description of image.jpg", meta={"file_path": "image.jpg"}),
+ Document(content="Text content of page 1 of doc.pdf", meta={"file_path": "doc.pdf", "page_number": 1})
+]
+
+result = converter.run(documents)
+image_contents = result["image_contents"]
+# [ImageContent(
+# base64_image='/9j/4A...', mime_type='image/jpeg', detail='high', meta={'file_path': 'image.jpg'}
+# ),
+# ImageContent(
+# base64_image='/9j/4A...', mime_type='image/jpeg', detail='high',
+# meta={'page_number': 1, 'file_path': 'doc.pdf'}
+# )]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ file_path_meta_field: str = "file_path",
+ root_path: str | None = None,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None
+) -> None
+```
+
+Initialize the DocumentToImageContent component.
+
+**Parameters:**
+
+- **file_path_meta_field** (str) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (str | None) – The root directory path where document files are located. If provided, file paths in
+ document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low".
+ This will be passed to the created ImageContent objects.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[ImageContent | None]]
+```
+
+Convert documents with image or PDF sources into ImageContent objects.
+
+This method processes the input documents, extracting images from supported file formats and converting them
+into ImageContent objects.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to process. Each document should have metadata containing at minimum
+ a 'file_path_meta_field' key. PDF documents additionally require a 'page_number' key to specify which
+ page to convert.
+
+**Returns:**
+
+- dict\[str, list\[ImageContent | None\]\] – Dictionary containing one key:
+- "image_contents": ImageContents created from the processed documents. These contain base64-encoded image
+ data and metadata. The order corresponds to order of input documents.
+
+**Raises:**
+
+- ValueError – If any document is missing the required metadata keys, has an invalid file path, or has an unsupported
+ MIME type. The error message will specify which document and what information is missing or incorrect.
+
+## image/file_to_document
+
+### ImageFileToDocument
+
+Converts image file references into empty Document objects with associated metadata.
+
+This component is useful in pipelines where image file paths need to be wrapped in `Document` objects to be
+processed by downstream components such as the `SentenceTransformersImageDocumentEmbedder`.
+
+It does **not** extract any content from the image files, instead it creates `Document` objects with `None` as
+their content and attaches metadata such as file path and any user-provided values.
+
+### Usage example
+
+```python
+from haystack.components.converters.image import ImageFileToDocument
+
+converter = ImageFileToDocument()
+
+sources = ["image.jpg", "another_image.png"]
+
+result = converter.run(sources=sources)
+documents = result["documents"]
+
+print(documents)
+
+# [Document(id=..., meta: {'file_path': 'image.jpg'}),
+# Document(id=..., meta: {'file_path': 'another_image.png'})]
+```
+
+#### __init__
+
+```python
+__init__(*, store_full_path: bool = False) -> None
+```
+
+Initialize the ImageFileToDocument component.
+
+**Parameters:**
+
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+ *,
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, list[Document]]
+```
+
+Convert image files into empty Document objects with metadata.
+
+This method accepts image file references (as file paths or ByteStreams) and creates `Document` objects
+without content. These documents are enriched with metadata derived from the input source and optional
+user-provided metadata.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects to convert.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the documents.
+ This value can be a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced documents.
+ If it's a list, its length must match the number of sources, as they are zipped together.
+ For ByteStream objects, their `meta` is added to the output documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing:
+- `documents`: A list of `Document` objects with empty content and associated metadata.
+
+## image/file_to_image
+
+### ImageFileToImageContent
+
+Converts image files to ImageContent objects.
+
+### Usage example
+
+```python
+from haystack.components.converters.image import ImageFileToImageContent
+
+converter = ImageFileToImageContent()
+
+sources = ["image.jpg", "another_image.png"]
+
+image_contents = converter.run(sources=sources)["image_contents"]
+print(image_contents)
+
+# [ImageContent(base64_image='...',
+# mime_type='image/jpeg',
+# detail=None,
+# meta={'file_path': 'image.jpg'}),
+# ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None
+) -> None
+```
+
+Create the ImageFileToImageContent component.
+
+**Parameters:**
+
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+ This will be passed to the created ImageContent objects.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+ *,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None
+) -> dict[str, list[ImageContent]]
+```
+
+Converts files to ImageContent objects.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects to convert.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the ImageContent objects.
+ This value can be a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced ImageContent objects.
+ If it's a list, its length must match the number of sources as they're zipped together.
+ For ByteStream objects, their `meta` is added to the output ImageContent objects.
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+ This will be passed to the created ImageContent objects.
+ If not provided, the detail level will be the one set in the constructor.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+ If not provided, the size value will be the one set in the constructor.
+
+**Returns:**
+
+- dict\[str, list\[ImageContent\]\] – A dictionary with the following keys:
+- `image_contents`: A list of ImageContent objects.
+
+## image/pdf_to_image
+
+### PDFToImageContent
+
+Converts PDF files to ImageContent objects.
+
+### Usage example
+
+```python
+from haystack.components.converters.image import PDFToImageContent
+
+converter = PDFToImageContent()
+
+sources = ["file.pdf", "another_file.pdf"]
+
+image_contents = converter.run(sources=sources)["image_contents"]
+print(image_contents)
+
+# [ImageContent(base64_image='...',
+# mime_type='application/pdf',
+# detail=None,
+# meta={'file_path': 'file.pdf', 'page_number': 1}),
+# ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None,
+ page_range: list[str | int] | None = None
+) -> None
+```
+
+Create the PDFToImageContent component.
+
+**Parameters:**
+
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+ This will be passed to the created ImageContent objects.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+- **page_range** (list\[str | int\] | None) – List of page numbers and/or page ranges to convert to images. Page numbers start at 1.
+ If None, all pages in the PDF will be converted. Pages outside the valid range (1 to number of pages)
+ will be skipped with a warning. For example, page_range=[1, 3] will convert only the first and third
+ pages of the document. It also accepts printable range strings, e.g.: ['1-3', '5', '8', '10-12']
+ will convert pages 1, 2, 3, 5, 8, 10, 11, 12.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+ *,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None,
+ page_range: list[str | int] | None = None
+) -> dict[str, list[ImageContent]]
+```
+
+Converts files to ImageContent objects.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects to convert.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the ImageContent objects.
+ This value can be a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced ImageContent objects.
+ If it's a list, its length must match the number of sources as they're zipped together.
+ For ByteStream objects, their `meta` is added to the output ImageContent objects.
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+ This will be passed to the created ImageContent objects.
+ If not provided, the detail level will be the one set in the constructor.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+ If not provided, the size value will be the one set in the constructor.
+- **page_range** (list\[str | int\] | None) – List of page numbers and/or page ranges to convert to images. Page numbers start at 1.
+ If None, all pages in the PDF will be converted. Pages outside the valid range (1 to number of pages)
+ will be skipped with a warning. For example, page_range=[1, 3] will convert only the first and third
+ pages of the document. It also accepts printable range strings, e.g.: ['1-3', '5', '8', '10-12']
+ will convert pages 1, 2, 3, 5, 8, 10, 11, 12.
+ If not provided, the page_range value will be the one set in the constructor.
+
+**Returns:**
+
+- dict\[str, list\[ImageContent\]\] – A dictionary with the following keys:
+- `image_contents`: A list of ImageContent objects.
+
+## json
+
+### JSONConverter
+
+Converts one or more JSON files into a text document.
+
+### Usage examples
+
+```python
+import json
+
+from haystack.components.converters import JSONConverter
+from haystack.dataclasses import ByteStream
+
+source = ByteStream.from_string(json.dumps({"text": "This is the content of my document"}))
+
+converter = JSONConverter(content_key="text")
+results = converter.run(sources=[source])
+documents = results["documents"]
+print(documents[0].content)
+# 'This is the content of my document'
+```
+
+Optionally, you can also provide a `jq_schema` string to filter the JSON source files and `extra_meta_fields`
+to extract from the filtered data:
+
+```python
+import json
+
+from haystack.components.converters import JSONConverter
+from haystack.dataclasses import ByteStream
+
+data = {
+ "laureates": [
+ {
+ "firstname": "Enrico",
+ "surname": "Fermi",
+ "motivation": "for his demonstrations of the existence of new radioactive elements produced "
+ "by neutron irradiation, and for his related discovery of nuclear reactions brought about by"
+ " slow neutrons",
+ },
+ {
+ "firstname": "Rita",
+ "surname": "Levi-Montalcini",
+ "motivation": "for their discoveries of growth factors",
+ },
+ ],
+}
+source = ByteStream.from_string(json.dumps(data))
+converter = JSONConverter(
+ jq_schema=".laureates[]", content_key="motivation", extra_meta_fields={"firstname", "surname"}
+)
+
+results = converter.run(sources=[source])
+documents = results["documents"]
+print(documents[0].content)
+# 'for his demonstrations of the existence of new radioactive elements produced by
+# neutron irradiation, and for his related discovery of nuclear reactions brought
+# about by slow neutrons'
+
+print(documents[0].meta)
+# {'firstname': 'Enrico', 'surname': 'Fermi'}
+
+print(documents[1].content)
+# 'for their discoveries of growth factors'
+
+print(documents[1].meta)
+# {'firstname': 'Rita', 'surname': 'Levi-Montalcini'}
+```
+
+#### __init__
+
+```python
+__init__(
+ jq_schema: str | None = None,
+ content_key: str | None = None,
+ extra_meta_fields: set[str] | Literal["*"] | None = None,
+ store_full_path: bool = False,
+) -> None
+```
+
+Creates a JSONConverter component.
+
+An optional `jq_schema` can be provided to extract nested data in the JSON source files.
+See the [official jq documentation](https://jqlang.github.io/jq/) for more info on the filters syntax.
+If `jq_schema` is not set, whole JSON source files will be used to extract content.
+
+Optionally, you can provide a `content_key` to specify which key in the extracted object must
+be set as the document's content.
+
+If both `jq_schema` and `content_key` are set, the component will search for the `content_key` in
+the JSON object extracted by `jq_schema`. If the extracted data is not a JSON object, it will be skipped.
+
+If only `jq_schema` is set, the extracted data must be a scalar value. If it's a JSON object or array,
+it will be skipped.
+
+If only `content_key` is set, the source JSON file must be a JSON object, else it will be skipped.
+
+`extra_meta_fields` can either be set to a set of strings or a literal `"*"` string.
+If it's a set of strings, it must specify fields in the extracted objects that must be set in
+the extracted documents. If a field is not found, the meta value will be `None`.
+If set to `"*"`, all fields that are not `content_key` found in the filtered JSON object will
+be saved as metadata.
+
+Initialization will fail if neither `jq_schema` nor `content_key` are set.
+
+**Parameters:**
+
+- **jq_schema** (str | None) – Optional jq filter string to extract content.
+ If not specified, whole JSON object will be used to extract information.
+- **content_key** (str | None) – Optional key to extract document content.
+ If `jq_schema` is specified, the `content_key` will be extracted from that object.
+- **extra_meta_fields** (set\[str\] | Literal['\*'] | None) – An optional set of meta keys to extract from the content.
+ If `jq_schema` is specified, all keys will be extracted from that object.
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JSONConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- JSONConverter – Deserialized component.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, Any]
+```
+
+Converts a list of JSON files to documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – A list of file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced documents.
+ If it's a list, the length of the list must match the number of sources.
+ If `sources` contain ByteStream objects, their `meta` will be added to the output documents.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of created documents.
+
+## markdown
+
+### MarkdownToDocument
+
+Converts a Markdown file into a text Document.
+
+Usage example:
+
+```python
+from haystack.components.converters import MarkdownToDocument
+from datetime import datetime
+
+converter = MarkdownToDocument()
+results = converter.run(
+ sources=["test/test_files/markdown/sample.md"], meta={"date_added": datetime.now().isoformat()}
+)
+documents = results["documents"]
+print(documents[0].content)
+# 'This is a text from the markdown file.'
+```
+
+#### __init__
+
+```python
+__init__(
+ table_to_single_line: bool = False,
+ progress_bar: bool = True,
+ store_full_path: bool = False,
+) -> None
+```
+
+Create a MarkdownToDocument component.
+
+**Parameters:**
+
+- **table_to_single_line** (bool) – If True converts table contents into a single line.
+- **progress_bar** (bool) – If True shows a progress bar when running.
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, Any]
+```
+
+Converts a list of Markdown files to Documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced Documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will
+ be zipped.
+ If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of created Documents
+
+## msg
+
+### MSGToDocument
+
+Converts Microsoft Outlook .msg files into Haystack Documents.
+
+This component extracts email metadata (such as sender, recipients, CC, BCC, subject) and body content from .msg
+files and converts them into structured Haystack Documents. Additionally, any file attachments within the .msg
+file are extracted as ByteStream objects.
+
+### Example Usage
+
+```python
+from haystack.components.converters.msg import MSGToDocument
+from datetime import datetime
+
+converter = MSGToDocument()
+results = converter.run(sources=["test/test_files/msg/sample.msg"], meta={"date_added": datetime.now().isoformat()})
+documents = results["documents"]
+attachments = results["attachments"]
+print(documents[0].content)
+```
+
+#### __init__
+
+```python
+__init__(store_full_path: bool = False) -> None
+```
+
+Creates a MSGToDocument component.
+
+**Parameters:**
+
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document] | list[ByteStream]]
+```
+
+Converts MSG files to Documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced Documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will
+ be zipped.
+ If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | list\[ByteStream\]\] – A dictionary with the following keys:
+- `documents`: Created Documents.
+- `attachments`: Created ByteStream objects from file attachments.
+
+## multi_file_converter
+
+### MultiFileConverter
+
+A file converter that handles conversion of multiple file types.
+
+The MultiFileConverter handles the following file types:
+
+- CSV
+- DOCX
+- HTML
+- JSON
+- MD
+- TEXT
+- PDF (no OCR)
+- PPTX
+- XLSX
+
+Usage example:
+
+```
+from haystack.super_components.converters import MultiFileConverter
+
+converter = MultiFileConverter()
+converter.run(sources=["test/test_files/txt/doc_1.txt", "test/test_files/pdf/sample_pdf_1.pdf"], meta={})
+```
+
+#### __init__
+
+```python
+__init__(encoding: str = 'utf-8', json_content_key: str = 'content') -> None
+```
+
+Initialize the MultiFileConverter.
+
+**Parameters:**
+
+- **encoding** (str) – The encoding to use when reading files.
+- **json_content_key** (str) – The key to use in a content field in a document when converting JSON files.
+
+## openapi_functions
+
+### OpenAPIServiceToFunctions
+
+Converts OpenAPI service definitions to a format suitable for OpenAI function calling.
+
+The definition must respect OpenAPI specification 3.0.0 or higher.
+It can be specified in JSON or YAML format.
+Each function must have:
+\- unique operationId
+\- description
+\- requestBody and/or parameters
+\- schema for the requestBody and/or parameters
+For more details on OpenAPI specification see the [official documentation](https://github.com/OAI/OpenAPI-Specification).
+For more details on OpenAI function calling see the [official documentation](https://platform.openai.com/docs/guides/function-calling).
+
+Usage example:
+
+```python
+from haystack.components.converters import OpenAPIServiceToFunctions
+from haystack.dataclasses.byte_stream import ByteStream
+
+converter = OpenAPIServiceToFunctions()
+spec = ByteStream.from_string(
+ '{"openapi":"3.0.0","info":{"title":"API","version":"1.0.0"},"paths":{"/search":{"get":{"operationId":"search","summary":"Search","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}]}}}}'
+)
+result = converter.run(sources=[spec])
+assert result["functions"]
+```
+
+#### __init__
+
+```python
+__init__() -> None
+```
+
+Create an OpenAPIServiceToFunctions component.
+
+#### run
+
+```python
+run(sources: list[str | Path | ByteStream]) -> dict[str, Any]
+```
+
+Converts OpenAPI definitions in OpenAI function calling format.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format).
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- functions: Function definitions in JSON object format
+- openapi_specs: OpenAPI specs in JSON/YAML object format with resolved references
+
+**Raises:**
+
+- RuntimeError – If the OpenAPI definitions cannot be downloaded or processed.
+- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions.
+
+## output_adapter
+
+### OutputAdaptationException
+
+Bases: Exception
+
+Exception raised when there is an error during output adaptation.
+
+### OutputAdapter
+
+Adapts output of a Component using Jinja templates.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.converters import OutputAdapter
+
+adapter = OutputAdapter(template="{{ documents[0].content }}", output_type=str)
+documents = [Document(content="Test content")]
+result = adapter.run(documents=documents)
+
+assert result["output"] == "Test content"
+```
+
+#### __init__
+
+```python
+__init__(
+ template: str,
+ output_type: TypeAlias,
+ custom_filters: dict[str, Callable] | None = None,
+ unsafe: bool = False,
+) -> None
+```
+
+Create an OutputAdapter component.
+
+**Parameters:**
+
+- **template** (str) – A Jinja template that defines how to adapt the input data.
+ The variables in the template define the input of this instance.
+ e.g.
+ With this template:
+
+```
+{{ documents[0].content }}
+```
+
+The Component input will be `documents`.
+
+- **output_type** (TypeAlias) – The type of output this instance will return.
+- **custom_filters** (dict\[str, Callable\] | None) – A dictionary of custom Jinja filters used in the template.
+- **unsafe** (bool) – Enable execution of arbitrary code in the Jinja template.
+ This should only be used if you trust the source of the template as it can be lead to remote code execution.
+
+#### run
+
+```python
+run(**kwargs: Any) -> dict[str, Any]
+```
+
+Renders the Jinja template with the provided inputs.
+
+**Parameters:**
+
+- **kwargs** (Any) – Must contain all variables used in the `template` string.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `output`: Rendered Jinja template.
+
+**Raises:**
+
+- OutputAdaptationException – If template rendering fails.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OutputAdapter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- OutputAdapter – The deserialized component.
+
+## pdfminer
+
+### PDFMinerToDocument
+
+Converts PDF files to Documents.
+
+Uses `pdfminer` compatible converters to convert PDF files to Documents. https://pdfminersix.readthedocs.io/en/latest/
+
+Usage example:
+
+```python
+from haystack.components.converters.pdfminer import PDFMinerToDocument
+from datetime import datetime
+
+converter = PDFMinerToDocument()
+results = converter.run(
+ sources=["test/test_files/pdf/sample_pdf_1.pdf"], meta={"date_added": datetime.now().isoformat()}
+)
+
+print(results["documents"][0].content)
+# >> 'This is a text from the PDF file.'
+```
+
+#### __init__
+
+```python
+__init__(
+ line_overlap: float = 0.5,
+ char_margin: float = 2.0,
+ line_margin: float = 0.5,
+ word_margin: float = 0.1,
+ boxes_flow: float | None = 0.5,
+ detect_vertical: bool = True,
+ all_texts: bool = False,
+ store_full_path: bool = False,
+) -> None
+```
+
+Create a PDFMinerToDocument component.
+
+**Parameters:**
+
+- **line_overlap** (float) – This parameter determines whether two characters are considered to be on
+ the same line based on the amount of overlap between them.
+ The overlap is calculated relative to the minimum height of both characters.
+- **char_margin** (float) – Determines whether two characters are part of the same line based on the distance between them.
+ If the distance is less than the margin specified, the characters are considered to be on the same line.
+ The margin is calculated relative to the width of the character.
+- **word_margin** (float) – Determines whether two characters on the same line are part of the same word
+ based on the distance between them. If the distance is greater than the margin specified,
+ an intermediate space will be added between them to make the text more readable.
+ The margin is calculated relative to the width of the character.
+- **line_margin** (float) – This parameter determines whether two lines are part of the same paragraph based on
+ the distance between them. If the distance is less than the margin specified,
+ the lines are considered to be part of the same paragraph.
+ The margin is calculated relative to the height of a line.
+- **boxes_flow** (float | None) – This parameter determines the importance of horizontal and vertical position when
+ determining the order of text boxes. A value between -1.0 and +1.0 can be set,
+ with -1.0 indicating that only horizontal position matters and +1.0 indicating
+ that only vertical position matters. Setting the value to 'None' will disable advanced
+ layout analysis, and text boxes will be ordered based on the position of their bottom left corner.
+- **detect_vertical** (bool) – This parameter determines whether vertical text should be considered during layout analysis.
+- **all_texts** (bool) – If layout analysis should be performed on text in figures.
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### detect_undecoded_cid_characters
+
+```python
+detect_undecoded_cid_characters(text: str) -> dict[str, Any]
+```
+
+Look for character sequences of CID, i.e.: characters that haven't been properly decoded from their CID format.
+
+This is useful to detect if the text extractor is not able to extract the text correctly, e.g. if the PDF uses
+non-standard fonts.
+
+A PDF font may include a ToUnicode map (mapping from character code to Unicode) to support operations like
+searching strings or copy & paste in a PDF viewer. This map immediately provides the mapping the text extractor
+needs. If that map is not available the text extractor cannot decode the CID characters and will return them
+as is.
+
+see: https://pdfminersix.readthedocs.io/en/latest/faq.html#why-are-there-cid-x-values-in-the-textual-output
+
+**Parameters:**
+
+- **text** (str) – The text to check for undecoded CID characters
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing detection results
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, Any]
+```
+
+Converts PDF files to Documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of PDF file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced Documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will
+ be zipped.
+ If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: Created Documents
+
+## pptx
+
+### PPTXToDocument
+
+Converts PPTX files to Documents.
+
+Usage example:
+
+```python
+from haystack.components.converters.pptx import PPTXToDocument
+from datetime import datetime
+
+converter = PPTXToDocument()
+results = converter.run(
+ sources=["test/test_files/pptx/sample_pptx.pptx"], meta={"date_added": datetime.now().isoformat()}
+)
+documents = results["documents"]
+
+print(documents[0].content)
+# >> 'This is the text from the PPTX file.'
+```
+
+#### __init__
+
+```python
+__init__(
+ store_full_path: bool = False,
+ link_format: Literal["markdown", "plain", "none"] = "none",
+) -> None
+```
+
+Create a PPTXToDocument component.
+
+**Parameters:**
+
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+- **link_format** (Literal['markdown', 'plain', 'none']) – The format for link output. Possible options:
+- `"markdown"`: `[text](url)`
+- `"plain"`: `text (url)`
+- `"none"`: Only the text is extracted, link addresses are ignored.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, Any]
+```
+
+Converts PPTX files to Documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced Documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will
+ be zipped.
+ If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: Created Documents
+
+## pypdf
+
+### PyPDFExtractionMode
+
+Bases: Enum
+
+The mode to use for extracting text from a PDF.
+
+#### from_str
+
+```python
+from_str(string: str) -> PyPDFExtractionMode
+```
+
+Convert a string to a PyPDFExtractionMode enum.
+
+### PyPDFToDocument
+
+Converts PDF files to documents your pipeline can query.
+
+This component uses the PyPDF library.
+You can attach metadata to the resulting documents.
+
+### Usage example
+
+```python
+from haystack.components.converters.pypdf import PyPDFToDocument
+from datetime import datetime
+
+converter = PyPDFToDocument()
+results = converter.run(
+ sources=["test/test_files/pdf/sample_pdf_1.pdf"], meta={"date_added": datetime.now().isoformat()}
+)
+documents = results["documents"]
+
+print(documents[0].content)
+# >> 'This is a text from the PDF file.'
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ extraction_mode: str | PyPDFExtractionMode = PyPDFExtractionMode.PLAIN,
+ plain_mode_orientations: tuple = (0, 90, 180, 270),
+ plain_mode_space_width: float = 200.0,
+ layout_mode_space_vertically: bool = True,
+ layout_mode_scale_weight: float = 1.25,
+ layout_mode_strip_rotated: bool = True,
+ layout_mode_font_height_weight: float = 1.0,
+ store_full_path: bool = False
+) -> None
+```
+
+Create an PyPDFToDocument component.
+
+**Parameters:**
+
+- **extraction_mode** (str | PyPDFExtractionMode) – The mode to use for extracting text from a PDF.
+ Layout mode is an experimental mode that adheres to the rendered layout of the PDF.
+- **plain_mode_orientations** (tuple) – Tuple of orientations to look for when extracting text from a PDF in plain mode.
+ Ignored if `extraction_mode` is `PyPDFExtractionMode.LAYOUT`.
+- **plain_mode_space_width** (float) – Forces default space width if not extracted from font.
+ Ignored if `extraction_mode` is `PyPDFExtractionMode.LAYOUT`.
+- **layout_mode_space_vertically** (bool) – Whether to include blank lines inferred from y distance + font height.
+ Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`.
+- **layout_mode_scale_weight** (float) – Multiplier for string length when calculating weighted average character width.
+ Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`.
+- **layout_mode_strip_rotated** (bool) – Layout mode does not support rotated text. Set to `False` to include rotated text anyway.
+ If rotated text is discovered, layout will be degraded and a warning will be logged.
+ Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`.
+- **layout_mode_font_height_weight** (float) – Multiplier for font height when calculating blank line height.
+ Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`.
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PyPDFToDocument
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary with serialized data.
+
+**Returns:**
+
+- PyPDFToDocument – Deserialized component.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Converts PDF files to documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects to convert.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the documents.
+ This value can be a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced documents.
+ If it's a list, its length must match the number of sources, as they are zipped together.
+ For ByteStream objects, their `meta` is added to the output documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: A list of converted documents.
+
+## tika
+
+### XHTMLParser
+
+Bases: HTMLParser
+
+Custom parser to extract pages from Tika XHTML content.
+
+#### handle_starttag
+
+```python
+handle_starttag(tag: str, attrs: list[tuple[str, str | None]]) -> None
+```
+
+Identify the start of a page div.
+
+#### handle_endtag
+
+```python
+handle_endtag(tag: str) -> None
+```
+
+Identify the end of a page div.
+
+#### handle_data
+
+```python
+handle_data(data: str) -> None
+```
+
+Populate the page content.
+
+### TikaDocumentConverter
+
+Converts files of different types to Documents.
+
+This component uses [Apache Tika](https://tika.apache.org/) for parsing the files and, therefore,
+requires a running Tika server.
+For more options on running Tika,
+see the [official documentation](https://github.com/apache/tika-docker/blob/main/README.md#usage).
+
+Usage example:
+
+
+
+```python
+from haystack.components.converters.tika import TikaDocumentConverter
+from datetime import datetime
+
+converter = TikaDocumentConverter()
+results = converter.run(
+ sources=["sample.docx", "my_document.rtf", "archive.zip"],
+ meta={"date_added": datetime.now().isoformat()}
+)
+documents = results["documents"]
+
+print(documents[0].content)
+# >> 'This is a text from the docx file.'
+```
+
+#### __init__
+
+```python
+__init__(
+ tika_url: str = "http://localhost:9998/tika", store_full_path: bool = False
+) -> None
+```
+
+Create a TikaDocumentConverter component.
+
+**Parameters:**
+
+- **tika_url** (str) – Tika server URL.
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Converts files to Documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of HTML file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced Documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will
+ be zipped.
+ If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Created Documents
+
+## txt
+
+### TextFileToDocument
+
+Converts text files to documents your pipeline can query.
+
+By default, it uses UTF-8 encoding when converting files but
+you can also set custom encoding.
+It can attach metadata to the resulting documents.
+
+### Usage example
+
+```python
+from haystack.components.converters.txt import TextFileToDocument
+
+converter = TextFileToDocument()
+results = converter.run(sources=["test/test_files/txt/doc_1.txt"])
+documents = results["documents"]
+
+print(documents[0].content)
+# >> 'This is the content from the txt file.'
+```
+
+#### __init__
+
+```python
+__init__(encoding: str = 'utf-8', store_full_path: bool = False) -> None
+```
+
+Creates a TextFileToDocument component.
+
+**Parameters:**
+
+- **encoding** (str) – The encoding of the text files to convert.
+ If the encoding is specified in the metadata of a source ByteStream,
+ it overrides this value.
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Converts text files to documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of text file paths or ByteStream objects to convert.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the documents.
+ This value can be a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced documents.
+ If it's a list, its length must match the number of sources as they're zipped together.
+ For ByteStream objects, their `meta` is added to the output documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: A list of converted documents.
+
+## xlsx
+
+### XLSXToDocument
+
+Converts XLSX (Excel) files into Documents.
+
+Supports reading data from specific sheets or all sheets in the Excel file. If all sheets are read, a Document is
+created for each sheet. The content of the Document is the table which can be saved in CSV or Markdown format.
+
+### Usage example
+
+```python
+from haystack.components.converters.xlsx import XLSXToDocument
+from datetime import datetime
+
+converter = XLSXToDocument()
+results = converter.run(
+ sources=["test/test_files/xlsx/basic_tables_two_sheets.xlsx"], meta={"date_added": datetime.now().isoformat()}
+)
+documents = results["documents"]
+
+print(documents[0].content)
+# >> ",A,B\n1,col_a,col_b\n2,1.5,test\n"
+```
+
+#### __init__
+
+```python
+__init__(
+ table_format: Literal["csv", "markdown"] = "csv",
+ sheet_name: str | int | list[str | int] | None = None,
+ read_excel_kwargs: dict[str, Any] | None = None,
+ table_format_kwargs: dict[str, Any] | None = None,
+ *,
+ link_format: Literal["markdown", "plain", "none"] = "none",
+ store_full_path: bool = False
+) -> None
+```
+
+Creates a XLSXToDocument component.
+
+**Parameters:**
+
+- **table_format** (Literal['csv', 'markdown']) – The format to convert the Excel file to.
+- **sheet_name** (str | int | list\[str | int\] | None) – The name of the sheet to read. If None, all sheets are read.
+- **read_excel_kwargs** (dict\[str, Any\] | None) – Additional arguments to pass to `pandas.read_excel`.
+ See https://pandas.pydata.org/docs/reference/api/pandas.read_excel.html#pandas-read-excel
+- **table_format_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments to pass to the table format function.
+- If `table_format` is "csv", these arguments are passed to `pandas.DataFrame.to_csv`.
+ See https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_csv.html#pandas-dataframe-to-csv
+- If `table_format` is "markdown", these arguments are passed to `pandas.DataFrame.to_markdown`.
+ See https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html#pandas-dataframe-to-markdown
+- **link_format** (Literal['markdown', 'plain', 'none']) – The format for link output. Possible options:
+- `"markdown"`: `[text](url)`
+- `"plain"`: `text (url)`
+- `"none"`: Only the text is extracted, link addresses are ignored.
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Converts a XLSX file to a Document.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will
+ be zipped.
+ If `sources` contains ByteStream objects, their `meta` will be added to the output documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Created documents
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/data_classes_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/data_classes_api.md
new file mode 100644
index 0000000000..3b7b14dd5c
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/data_classes_api.md
@@ -0,0 +1,1349 @@
+---
+title: "Data Classes"
+id: data-classes-api
+description: "Core classes that carry data through the system."
+slug: "/data-classes-api"
+---
+
+
+## answer
+
+### ExtractedAnswer
+
+Holds an answer extracted by an extractive Reader (query, score, text, and optional document/context).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the object to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized dictionary representation of the object.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ExtractedAnswer
+```
+
+Deserialize the object from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary representation of the object.
+
+**Returns:**
+
+- ExtractedAnswer – Deserialized object.
+
+### GeneratedAnswer
+
+Holds a generated answer from a Generator (answer text, query, referenced documents, and metadata).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the object to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized dictionary representation of the object.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GeneratedAnswer
+```
+
+Deserialize the object from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary representation of the object.
+
+**Returns:**
+
+- GeneratedAnswer – Deserialized object.
+
+## breakpoints
+
+### Breakpoint
+
+A dataclass to hold a breakpoint for a component.
+
+**Parameters:**
+
+- **component_name** (str) – The name of the component where the breakpoint is set.
+- **visit_count** (int) – The number of times the component must be visited before the breakpoint is triggered.
+- **snapshot_file_path** (str | None) – Optional path to store a snapshot of the pipeline when the breakpoint is hit.
+ This is useful for debugging purposes, allowing you to inspect the state of the pipeline at the time of the
+ breakpoint and to resume execution from that point.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the Breakpoint to a dictionary representation.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the component name, visit count, and debug path.
+
+#### from_dict
+
+```python
+from_dict(data: dict) -> Breakpoint
+```
+
+Populate the Breakpoint from a dictionary representation.
+
+**Parameters:**
+
+- **data** (dict) – A dictionary containing the component name, visit count, and debug path.
+
+**Returns:**
+
+- Breakpoint – An instance of Breakpoint.
+
+### ToolBreakpoint
+
+Bases: Breakpoint
+
+A dataclass representing a breakpoint specific to tools used within an Agent component.
+
+Inherits from Breakpoint and adds the ability to target individual tools. If `tool_name` is None,
+the breakpoint applies to all tools within the Agent component.
+
+**Parameters:**
+
+- **tool_name** (str | None) – The name of the tool to target within the Agent component. If None, applies to all tools.
+
+### AgentBreakpoint
+
+A dataclass representing a breakpoint tied to an Agent’s execution.
+
+This allows for debugging either a specific component (e.g., the chat generator) or a tool used by the agent.
+It enforces constraints on which component names are valid for each breakpoint type.
+
+**Parameters:**
+
+- **agent_name** (str) – The name of the agent component in a pipeline where the breakpoint is set.
+- **break_point** (Breakpoint | ToolBreakpoint) – An instance of Breakpoint or ToolBreakpoint indicating where to break execution.
+
+**Raises:**
+
+- ValueError – If the component_name is invalid for the given breakpoint type:
+- Breakpoint must have component_name='chat_generator'.
+- ToolBreakpoint must have component_name='tool_invoker'.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the AgentBreakpoint to a dictionary representation.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the agent name and the breakpoint details.
+
+#### from_dict
+
+```python
+from_dict(data: dict) -> AgentBreakpoint
+```
+
+Populate the AgentBreakpoint from a dictionary representation.
+
+**Parameters:**
+
+- **data** (dict) – A dictionary containing the agent name and the breakpoint details.
+
+**Returns:**
+
+- AgentBreakpoint – An instance of AgentBreakpoint.
+
+### AgentSnapshot
+
+Snapshot of an Agent's state at a breakpoint (component inputs, visit counts, and breakpoint).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the AgentSnapshot to a dictionary representation.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the agent state, timestamp, and breakpoint.
+
+#### from_dict
+
+```python
+from_dict(data: dict) -> AgentSnapshot
+```
+
+Populate the AgentSnapshot from a dictionary representation.
+
+**Parameters:**
+
+- **data** (dict) – A dictionary containing the agent state, timestamp, and breakpoint.
+
+**Returns:**
+
+- AgentSnapshot – An instance of AgentSnapshot.
+
+### PipelineState
+
+A dataclass to hold the state of the pipeline at a specific point in time.
+
+**Parameters:**
+
+- **component_visits** (dict\[str, int\]) – A dictionary mapping component names to their visit counts.
+- **inputs** (dict\[str, Any\]) – The inputs processed by the pipeline at the time of the snapshot.
+- **pipeline_outputs** (dict\[str, Any\]) – Dictionary containing the final outputs of the pipeline up to the breakpoint.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the PipelineState to a dictionary representation.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the inputs, component visits,
+ and pipeline outputs.
+
+#### from_dict
+
+```python
+from_dict(data: dict) -> PipelineState
+```
+
+Populate the PipelineState from a dictionary representation.
+
+**Parameters:**
+
+- **data** (dict) – A dictionary containing the inputs, component visits,
+ and pipeline outputs.
+
+**Returns:**
+
+- PipelineState – An instance of PipelineState.
+
+### PipelineSnapshot
+
+A dataclass to hold a snapshot of the pipeline at a specific point in time.
+
+**Parameters:**
+
+- **original_input_data** (dict\[str, Any\]) – The original input data provided to the pipeline.
+- **ordered_component_names** (list\[str\]) – A list of component names in the order they were visited.
+- **pipeline_state** (PipelineState) – The state of the pipeline at the time of the snapshot.
+- **break_point** (AgentBreakpoint | Breakpoint) – The breakpoint that triggered the snapshot.
+- **agent_snapshot** (AgentSnapshot | None) – Optional agent snapshot if the breakpoint is an agent breakpoint.
+- **timestamp** (datetime | None) – A timestamp indicating when the snapshot was taken.
+- **include_outputs_from** (set\[str\]) – Set of component names whose outputs should be included in the pipeline results.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the PipelineSnapshot to a dictionary representation.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the pipeline state, timestamp, breakpoint, agent snapshot, original input data,
+ ordered component names, include_outputs_from, and pipeline outputs.
+
+#### from_dict
+
+```python
+from_dict(data: dict) -> PipelineSnapshot
+```
+
+Populate the PipelineSnapshot from a dictionary representation.
+
+**Parameters:**
+
+- **data** (dict) – A dictionary containing the pipeline state, timestamp, breakpoint, agent snapshot, original input
+ data, ordered component names, include_outputs_from, and pipeline outputs.
+
+## byte_stream
+
+### ByteStream
+
+Base data class representing a binary object in the Haystack API.
+
+**Parameters:**
+
+- **data** (bytes) – The binary data stored in Bytestream.
+- **meta** (dict\[str, Any\]) – Additional metadata to be stored with the ByteStream.
+- **mime_type** (str | None) – The mime type of the binary data.
+
+#### to_file
+
+```python
+to_file(destination_path: Path) -> None
+```
+
+Write the ByteStream to a file. Note: the metadata will be lost.
+
+**Parameters:**
+
+- **destination_path** (Path) – The path to write the ByteStream to.
+
+#### from_file_path
+
+```python
+from_file_path(
+ filepath: Path,
+ mime_type: str | None = None,
+ meta: dict[str, Any] | None = None,
+ guess_mime_type: bool = False,
+) -> ByteStream
+```
+
+Create a ByteStream from the contents read from a file.
+
+**Parameters:**
+
+- **filepath** (Path) – A valid path to a file.
+- **mime_type** (str | None) – The mime type of the file.
+- **meta** (dict\[str, Any\] | None) – Additional metadata to be stored with the ByteStream.
+- **guess_mime_type** (bool) – Whether to guess the mime type from the file.
+
+#### from_string
+
+```python
+from_string(
+ text: str,
+ encoding: str = "utf-8",
+ mime_type: str | None = None,
+ meta: dict[str, Any] | None = None,
+) -> ByteStream
+```
+
+Create a ByteStream encoding a string.
+
+**Parameters:**
+
+- **text** (str) – The string to encode
+- **encoding** (str) – The encoding used to convert the string into bytes
+- **mime_type** (str | None) – The mime type of the file.
+- **meta** (dict\[str, Any\] | None) – Additional metadata to be stored with the ByteStream.
+
+#### to_string
+
+```python
+to_string(encoding: str = 'utf-8') -> str
+```
+
+Convert the ByteStream to a string, metadata will not be included.
+
+**Parameters:**
+
+- **encoding** (str) – The encoding used to convert the bytes to a string. Defaults to "utf-8".
+
+**Returns:**
+
+- str – The string representation of the ByteStream.
+
+**Raises:**
+
+- UnicodeDecodeError – If the ByteStream data cannot be decoded with the specified encoding.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the ByteStream to a dictionary representation.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys 'data', 'meta', and 'mime_type'.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ByteStream
+```
+
+Create a ByteStream from a dictionary representation.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – A dictionary with keys 'data', 'meta', and 'mime_type'.
+
+**Returns:**
+
+- ByteStream – A ByteStream instance.
+
+## chat_message
+
+### ChatRole
+
+Bases: str, Enum
+
+Enumeration representing the roles within a chat.
+
+#### from_str
+
+```python
+from_str(string: str) -> ChatRole
+```
+
+Convert a string to a ChatRole enum.
+
+### TextContent
+
+The textual content of a chat message.
+
+**Parameters:**
+
+- **text** (str) – The text content of the message.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert TextContent into a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TextContent
+```
+
+Create a TextContent from a dictionary.
+
+### ToolCall
+
+Represents a Tool call prepared by the model, usually contained in an assistant message.
+
+**Parameters:**
+
+- **id** (str | None) – The ID of the Tool call.
+- **tool_name** (str) – The name of the Tool to call.
+- **arguments** (dict\[str, Any\]) – The arguments to call the Tool with.
+- **extra** (dict\[str, Any\] | None) – Dictionary of extra information about the Tool call. Use to store provider-specific
+ information. To avoid serialization issues, values should be JSON serializable.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert ToolCall into a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys 'tool_name', 'arguments', 'id', and 'extra'.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ToolCall
+```
+
+Creates a new ToolCall object from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to build the ToolCall object.
+
+**Returns:**
+
+- ToolCall – The created object.
+
+### ToolCallResult
+
+Represents the result of a Tool invocation.
+
+**Parameters:**
+
+- **result** (ToolCallResultContentT) – The result of the Tool invocation.
+- **origin** (ToolCall) – The Tool call that produced this result.
+- **error** (bool) – Whether the Tool invocation resulted in an error.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Converts ToolCallResult into a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys 'result', 'origin', and 'error'.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ToolCallResult
+```
+
+Creates a ToolCallResult from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to build the ToolCallResult object.
+
+**Returns:**
+
+- ToolCallResult – The created object.
+
+### ReasoningContent
+
+Represents the optional reasoning content prepared by the model, usually contained in an assistant message.
+
+**Parameters:**
+
+- **reasoning_text** (str) – The reasoning text produced by the model.
+- **extra** (dict\[str, Any\]) – Dictionary of extra information about the reasoning content. Use to store provider-specific
+ information. To avoid serialization issues, values should be JSON serializable.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert ReasoningContent into a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys 'reasoning_text', and 'extra'.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ReasoningContent
+```
+
+Creates a new ReasoningContent object from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to build the ReasoningContent object.
+
+**Returns:**
+
+- ReasoningContent – The created object.
+
+### ChatMessage
+
+Represents a message in a LLM chat conversation.
+
+Use the `from_assistant`, `from_user`, `from_system`, and `from_tool` class methods to create a ChatMessage.
+
+#### role
+
+```python
+role: ChatRole
+```
+
+Returns the role of the entity sending the message.
+
+#### meta
+
+```python
+meta: dict[str, Any]
+```
+
+Returns the metadata associated with the message.
+
+#### name
+
+```python
+name: str | None
+```
+
+Returns the name associated with the message.
+
+#### texts
+
+```python
+texts: list[str]
+```
+
+Returns the list of all texts contained in the message.
+
+#### text
+
+```python
+text: str | None
+```
+
+Returns the first text contained in the message.
+
+#### tool_calls
+
+```python
+tool_calls: list[ToolCall]
+```
+
+Returns the list of all Tool calls contained in the message.
+
+#### tool_call
+
+```python
+tool_call: ToolCall | None
+```
+
+Returns the first Tool call contained in the message.
+
+#### tool_call_results
+
+```python
+tool_call_results: list[ToolCallResult]
+```
+
+Returns the list of all Tool call results contained in the message.
+
+#### tool_call_result
+
+```python
+tool_call_result: ToolCallResult | None
+```
+
+Returns the first Tool call result contained in the message.
+
+#### images
+
+```python
+images: list[ImageContent]
+```
+
+Returns the list of all images contained in the message.
+
+#### image
+
+```python
+image: ImageContent | None
+```
+
+Returns the first image contained in the message.
+
+#### files
+
+```python
+files: list[FileContent]
+```
+
+Returns the list of all files contained in the message.
+
+#### file
+
+```python
+file: FileContent | None
+```
+
+Returns the first file contained in the message.
+
+#### reasonings
+
+```python
+reasonings: list[ReasoningContent]
+```
+
+Returns the list of all reasoning contents contained in the message.
+
+#### reasoning
+
+```python
+reasoning: ReasoningContent | None
+```
+
+Returns the first reasoning content contained in the message.
+
+#### is_from
+
+```python
+is_from(role: ChatRole | str) -> bool
+```
+
+Check if the message is from a specific role.
+
+**Parameters:**
+
+- **role** (ChatRole | str) – The role to check against.
+
+**Returns:**
+
+- bool – True if the message is from the specified role, False otherwise.
+
+#### from_user
+
+```python
+from_user(
+ text: str | None = None,
+ meta: dict[str, Any] | None = None,
+ name: str | None = None,
+ *,
+ content_parts: (
+ Sequence[TextContent | str | ImageContent | FileContent] | None
+ ) = None
+) -> ChatMessage
+```
+
+Create a message from the user.
+
+**Parameters:**
+
+- **text** (str | None) – The text content of the message. Specify this or content_parts.
+- **meta** (dict\[str, Any\] | None) – Additional metadata associated with the message.
+- **name** (str | None) – An optional name for the participant. This field is only supported by OpenAI.
+- **content_parts** (Sequence\[TextContent | str | ImageContent | FileContent\] | None) – A list of content parts to include in the message. Specify this or text.
+
+**Returns:**
+
+- ChatMessage – A new ChatMessage instance.
+
+**Raises:**
+
+- ValueError – If neither or both of text and content_parts are provided, or if content_parts is empty.
+- TypeError – If a content part is not a str, TextContent, ImageContent, or FileContent.
+
+#### from_system
+
+```python
+from_system(
+ text: str, meta: dict[str, Any] | None = None, name: str | None = None
+) -> ChatMessage
+```
+
+Create a message from the system.
+
+**Parameters:**
+
+- **text** (str) – The text content of the message.
+- **meta** (dict\[str, Any\] | None) – Additional metadata associated with the message.
+- **name** (str | None) – An optional name for the participant. This field is only supported by OpenAI.
+
+**Returns:**
+
+- ChatMessage – A new ChatMessage instance.
+
+#### from_assistant
+
+```python
+from_assistant(
+ text: str | None = None,
+ meta: dict[str, Any] | None = None,
+ name: str | None = None,
+ tool_calls: list[ToolCall] | None = None,
+ *,
+ reasoning: str | ReasoningContent | None = None
+) -> ChatMessage
+```
+
+Create a message from the assistant.
+
+**Parameters:**
+
+- **text** (str | None) – The text content of the message.
+- **meta** (dict\[str, Any\] | None) – Additional metadata associated with the message.
+- **name** (str | None) – An optional name for the participant. This field is only supported by OpenAI.
+- **tool_calls** (list\[ToolCall\] | None) – The Tool calls to include in the message.
+- **reasoning** (str | ReasoningContent | None) – The reasoning content to include in the message.
+
+**Returns:**
+
+- ChatMessage – A new ChatMessage instance.
+
+**Raises:**
+
+- TypeError – If `reasoning` is not a string or ReasoningContent object.
+
+#### from_tool
+
+```python
+from_tool(
+ tool_result: ToolCallResultContentT,
+ origin: ToolCall,
+ error: bool = False,
+ meta: dict[str, Any] | None = None,
+) -> ChatMessage
+```
+
+Create a message from a Tool.
+
+**Parameters:**
+
+- **tool_result** (ToolCallResultContentT) – The result of the Tool invocation.
+- **origin** (ToolCall) – The Tool call that produced this result.
+- **error** (bool) – Whether the Tool invocation resulted in an error.
+- **meta** (dict\[str, Any\] | None) – Additional metadata associated with the message.
+
+**Returns:**
+
+- ChatMessage – A new ChatMessage instance.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Converts ChatMessage into a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized version of the object.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChatMessage
+```
+
+Creates a new ChatMessage object from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to build the ChatMessage object.
+
+**Returns:**
+
+- ChatMessage – The created object.
+
+**Raises:**
+
+- ValueError – If the `role` field is missing from the dictionary.
+- TypeError – If the `content` field is not a list or string.
+
+#### to_openai_dict_format
+
+```python
+to_openai_dict_format(require_tool_call_ids: bool = True) -> dict[str, Any]
+```
+
+Convert a ChatMessage to the dictionary format expected by OpenAI's Chat Completions API.
+
+**Parameters:**
+
+- **require_tool_call_ids** (bool) – If True (default), enforces that each Tool Call includes a non-null `id` attribute.
+ Set to False to allow Tool Calls without `id`, which may be suitable for shallow OpenAI-compatible APIs.
+
+**Returns:**
+
+- dict\[str, Any\] – The ChatMessage in the format expected by OpenAI's Chat Completions API.
+
+**Raises:**
+
+- ValueError – If the message format is invalid, or if `require_tool_call_ids` is True and any Tool Call is missing an
+ `id` attribute.
+
+#### from_openai_dict_format
+
+```python
+from_openai_dict_format(message: dict[str, Any]) -> ChatMessage
+```
+
+Create a ChatMessage from a dictionary in the format expected by OpenAI's Chat API.
+
+NOTE: While OpenAI's API requires `tool_call_id` in both tool calls and tool messages, this method
+accepts messages without it to support shallow OpenAI-compatible APIs.
+If you plan to use the resulting ChatMessage with OpenAI, you must include `tool_call_id` or you'll
+encounter validation errors.
+
+**Parameters:**
+
+- **message** (dict\[str, Any\]) – The OpenAI dictionary to build the ChatMessage object.
+
+**Returns:**
+
+- ChatMessage – The created ChatMessage object.
+
+**Raises:**
+
+- ValueError – If the message dictionary is missing required fields.
+
+## document
+
+### Document
+
+Base data class containing some data to be queried.
+
+Can contain text snippets and file paths to images or audios. Documents can be sorted by score and saved
+to/from dictionary and JSON.
+
+**Parameters:**
+
+- **id** (str) – Unique identifier for the document. When not set, it's generated based on the Document fields' values.
+- **content** (str | None) – Text of the document, if the document contains text.
+- **blob** (ByteStream | None) – Binary data associated with the document, if the document has any binary data associated with it.
+- **meta** (dict\[str, Any\]) – Additional custom metadata for the document. Must be JSON-serializable.
+- **score** (float | None) – Score of the document. Used for ranking, usually assigned by retrievers.
+- **embedding** (list\[float\] | None) – dense vector representation of the document.
+- **sparse_embedding** (SparseEmbedding | None) – sparse vector representation of the document.
+
+#### to_dict
+
+```python
+to_dict(flatten: bool = True) -> dict[str, Any]
+```
+
+Converts Document into a dictionary.
+
+`blob` field is converted to a JSON-serializable type.
+
+**Parameters:**
+
+- **flatten** (bool) – Whether to flatten `meta` field or not. Defaults to `True` to be backward-compatible with Haystack 1.x.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Document
+```
+
+Creates a new Document object from a dictionary.
+
+The `blob` field is converted to its original type.
+
+#### content_type
+
+```python
+content_type: str
+```
+
+Returns the type of the content for the document.
+
+This is necessary to keep backward compatibility with 1.x.
+
+## file_content
+
+### FileContent
+
+The file content of a chat message.
+
+**Parameters:**
+
+- **base64_data** (str) – A base64 string representing the file.
+- **mime_type** (str | None) – The MIME type of the file (e.g. "application/pdf").
+ Providing this value is recommended, as most LLM providers require it.
+ If not provided, the MIME type is guessed from the base64 string, which can be slow and not always reliable.
+- **filename** (str | None) – Optional filename of the file. Some LLM providers use this information.
+- **extra** (dict\[str, Any\]) – Dictionary of extra information about the file. Can be used to store provider-specific information.
+ To avoid serialization issues, values should be JSON serializable.
+- **validation** (bool) – If True (default), a validation process is performed:
+- Check whether the base64 string is valid;
+- Guess the MIME type if not provided.
+ Set to False to skip validation and speed up initialization.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert FileContent into a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FileContent
+```
+
+Create an FileContent from a dictionary.
+
+#### from_file_path
+
+```python
+from_file_path(
+ file_path: str | Path,
+ *,
+ filename: str | None = None,
+ extra: dict[str, Any] | None = None
+) -> FileContent
+```
+
+Create an FileContent object from a file path.
+
+**Parameters:**
+
+- **file_path** (str | Path) – The path to the file.
+- **filename** (str | None) – Optional file name. Some LLM providers use this information. If not provided, the filename is extracted
+ from the file path.
+- **extra** (dict\[str, Any\] | None) – Dictionary of extra information about the file. Can be used to store provider-specific information.
+ To avoid serialization issues, values should be JSON serializable.
+
+**Returns:**
+
+- FileContent – An FileContent object.
+
+#### from_url
+
+```python
+from_url(
+ url: str,
+ *,
+ retry_attempts: int = 2,
+ timeout: int = 10,
+ filename: str | None = None,
+ extra: dict[str, Any] | None = None
+) -> FileContent
+```
+
+Create an FileContent object from a URL. The file is downloaded and converted to a base64 string.
+
+**Parameters:**
+
+- **url** (str) – The URL of the file.
+- **retry_attempts** (int) – The number of times to retry to fetch the URL's content.
+- **timeout** (int) – Timeout in seconds for the request.
+- **filename** (str | None) – Optional filename of the file. Some LLM providers use this information. If not provided, the filename is
+ extracted from the URL.
+- **extra** (dict\[str, Any\] | None) – Dictionary of extra information about the file. Can be used to store provider-specific information.
+ To avoid serialization issues, values should be JSON serializable.
+
+**Returns:**
+
+- FileContent – An FileContent object.
+
+## image_content
+
+### ImageContent
+
+The image content of a chat message.
+
+**Parameters:**
+
+- **base64_image** (str) – A base64 string representing the image.
+- **mime_type** (str | None) – The MIME type of the image (e.g. "image/png", "image/jpeg").
+ Providing this value is recommended, as most LLM providers require it.
+ If not provided, the MIME type is guessed from the base64 string, which can be slow and not always reliable.
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+- **meta** (dict\[str, Any\]) – Optional metadata for the image.
+- **validation** (bool) – If True (default), a validation process is performed:
+- Check whether the base64 string is valid;
+- Guess the MIME type if not provided;
+- Check if the MIME type is a valid image MIME type.
+ Set to False to skip validation and speed up initialization.
+
+#### show
+
+```python
+show() -> None
+```
+
+Shows the image.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert ImageContent into a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ImageContent
+```
+
+Create an ImageContent from a dictionary.
+
+#### from_file_path
+
+```python
+from_file_path(
+ file_path: str | Path,
+ *,
+ size: tuple[int, int] | None = None,
+ detail: Literal["auto", "high", "low"] | None = None,
+ meta: dict[str, Any] | None = None
+) -> ImageContent
+```
+
+Create an ImageContent object from a file path.
+
+It exposes similar functionality as the `ImageFileToImageContent` component. For PDF to ImageContent conversion,
+use the `PDFToImageContent` component.
+
+**Parameters:**
+
+- **file_path** (str | Path) – The path to the image file. PDF files are not supported. For PDF to ImageContent conversion, use the
+ `PDFToImageContent` component.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+- **meta** (dict\[str, Any\] | None) – Additional metadata for the image.
+
+**Returns:**
+
+- ImageContent – An ImageContent object.
+
+#### from_url
+
+```python
+from_url(
+ url: str,
+ *,
+ retry_attempts: int = 2,
+ timeout: int = 10,
+ size: tuple[int, int] | None = None,
+ detail: Literal["auto", "high", "low"] | None = None,
+ meta: dict[str, Any] | None = None
+) -> ImageContent
+```
+
+Create an ImageContent object from a URL. The image is downloaded and converted to a base64 string.
+
+For PDF to ImageContent conversion, use the `PDFToImageContent` component.
+
+**Parameters:**
+
+- **url** (str) – The URL of the image. PDF files are not supported. For PDF to ImageContent conversion, use the
+ `PDFToImageContent` component.
+- **retry_attempts** (int) – The number of times to retry to fetch the URL's content.
+- **timeout** (int) – Timeout in seconds for the request.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+- **meta** (dict\[str, Any\] | None) – Additional metadata for the image.
+
+**Returns:**
+
+- ImageContent – An ImageContent object.
+
+**Raises:**
+
+- ValueError – If the URL does not point to an image or if it points to a PDF file.
+
+## sparse_embedding
+
+### SparseEmbedding
+
+Class representing a sparse embedding.
+
+**Parameters:**
+
+- **indices** (list\[int\]) – List of indices of non-zero elements in the embedding.
+- **values** (list\[float\]) – List of values of non-zero elements in the embedding.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the SparseEmbedding object to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized sparse embedding.
+
+#### from_dict
+
+```python
+from_dict(sparse_embedding_dict: dict[str, Any]) -> SparseEmbedding
+```
+
+Deserializes the sparse embedding from a dictionary.
+
+**Parameters:**
+
+- **sparse_embedding_dict** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SparseEmbedding – Deserialized sparse embedding.
+
+## streaming_chunk
+
+### ToolCallDelta
+
+Represents a Tool call prepared by the model, usually contained in an assistant message.
+
+**Parameters:**
+
+- **index** (int) – The index of the Tool call in the list of Tool calls.
+- **tool_name** (str | None) – The name of the Tool to call.
+- **arguments** (str | None) – Either the full arguments in JSON format or a delta of the arguments.
+- **id** (str | None) – The ID of the Tool call.
+- **extra** (dict\[str, Any\] | None) – Dictionary of extra information about the Tool call. Use to store provider-specific
+ information. To avoid serialization issues, values should be JSON serializable.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the ToolCallDelta.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys 'index', 'tool_name', 'arguments', 'id', and 'extra'.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ToolCallDelta
+```
+
+Creates a ToolCallDelta from a serialized representation.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary containing ToolCallDelta's attributes.
+
+**Returns:**
+
+- ToolCallDelta – A ToolCallDelta instance.
+
+### ComponentInfo
+
+The `ComponentInfo` class encapsulates information about a component.
+
+**Parameters:**
+
+- **type** (str) – The type of the component.
+- **name** (str | None) – The name of the component assigned when adding it to a pipeline.
+
+#### from_component
+
+```python
+from_component(component: Component) -> ComponentInfo
+```
+
+Create a `ComponentInfo` object from a `Component` instance.
+
+**Parameters:**
+
+- **component** (Component) – The `Component` instance.
+
+**Returns:**
+
+- ComponentInfo – The `ComponentInfo` object with the type and name of the given component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of ComponentInfo.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys 'type' and 'name'.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ComponentInfo
+```
+
+Creates a ComponentInfo from a serialized representation.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary containing ComponentInfo's attributes.
+
+**Returns:**
+
+- ComponentInfo – A ComponentInfo instance.
+
+### StreamingChunk
+
+The `StreamingChunk` class encapsulates a segment of streamed content along with associated metadata.
+
+This structure facilitates the handling and processing of streamed data in a systematic manner.
+
+**Parameters:**
+
+- **content** (str) – The content of the message chunk as a string.
+- **meta** (dict\[str, Any\]) – A dictionary containing metadata related to the message chunk.
+- **component_info** (ComponentInfo | None) – A `ComponentInfo` object containing information about the component that generated the chunk,
+ such as the component name and type.
+- **index** (int | None) – An optional integer index representing which content block this chunk belongs to.
+- **tool_calls** (list\[ToolCallDelta\] | None) – An optional list of ToolCallDelta object representing a tool call associated with the message
+ chunk.
+- **tool_call_result** (ToolCallResult | None) – An optional ToolCallResult object representing the result of a tool call.
+- **start** (bool) – A boolean indicating whether this chunk marks the start of a content block.
+- **finish_reason** (FinishReason | None) – An optional value indicating the reason the generation finished.
+ Standard values follow OpenAI's convention: "stop", "length", "tool_calls", "content_filter",
+ plus Haystack-specific value "tool_call_results".
+- **reasoning** (ReasoningContent | None) – An optional ReasoningContent object representing the reasoning content associated
+ with the message chunk.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the StreamingChunk.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized dictionary representation of the calling object.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> StreamingChunk
+```
+
+Creates a deserialized StreamingChunk instance from a serialized representation.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary containing the StreamingChunk's attributes.
+
+**Returns:**
+
+- StreamingChunk – A StreamingChunk instance.
+
+### select_streaming_callback
+
+```python
+select_streaming_callback(
+ init_callback: StreamingCallbackT | None,
+ runtime_callback: StreamingCallbackT | None,
+ requires_async: bool,
+) -> StreamingCallbackT | None
+```
+
+Picks the correct streaming callback given an optional initial and runtime callback.
+
+The runtime callback takes precedence over the initial callback.
+
+**Parameters:**
+
+- **init_callback** (StreamingCallbackT | None) – The initial callback.
+- **runtime_callback** (StreamingCallbackT | None) – The runtime callback.
+- **requires_async** (bool) – Whether the selected callback must be async compatible.
+
+**Returns:**
+
+- StreamingCallbackT | None – The selected callback.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/document_stores_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/document_stores_api.md
new file mode 100644
index 0000000000..635ffe2a63
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/document_stores_api.md
@@ -0,0 +1,593 @@
+---
+title: "Document Stores"
+id: document-stores-api
+description: "Stores your texts and meta data and provides them to the Retriever at query time."
+slug: "/document-stores-api"
+---
+
+
+## document_store
+
+### BM25DocumentStats
+
+A dataclass for managing document statistics for BM25 retrieval.
+
+**Parameters:**
+
+- **freq_token** (dict\[str, int\]) – A Counter of token frequencies in the document.
+- **doc_len** (int) – Number of tokens in the document.
+
+### InMemoryDocumentStore
+
+Stores data in-memory. It's ephemeral and cannot be saved to disk.
+
+#### __init__
+
+```python
+__init__(
+ bm25_tokenization_regex: str = "(?u)\\b\\w+\\b",
+ bm25_algorithm: Literal["BM25Okapi", "BM25L", "BM25Plus"] = "BM25L",
+ bm25_parameters: dict | None = None,
+ embedding_similarity_function: Literal[
+ "dot_product", "cosine"
+ ] = "dot_product",
+ index: str | None = None,
+ async_executor: ThreadPoolExecutor | None = None,
+ return_embedding: bool = True,
+) -> None
+```
+
+Initializes the DocumentStore.
+
+**Parameters:**
+
+- **bm25_tokenization_regex** (str) – The regular expression used to tokenize the text for BM25 retrieval.
+- **bm25_algorithm** (Literal['BM25Okapi', 'BM25L', 'BM25Plus']) – The BM25 algorithm to use. One of "BM25Okapi", "BM25L", or "BM25Plus".
+- **bm25_parameters** (dict | None) – Parameters for BM25 implementation in a dictionary format.
+ For example: `{'k1':1.5, 'b':0.75, 'epsilon':0.25}`
+ You can learn more about these parameters by visiting https://github.com/dorianbrown/rank_bm25.
+- **embedding_similarity_function** (Literal['dot_product', 'cosine']) – The similarity function used to compare Documents embeddings.
+ One of "dot_product" (default) or "cosine". To choose the most appropriate function, look for information
+ about your embedding model.
+- **index** (str | None) – A specific index to store the documents. If not specified, a random UUID is used.
+ Using the same index allows you to store documents across multiple InMemoryDocumentStore instances.
+- **async_executor** (ThreadPoolExecutor | None) – Optional ThreadPoolExecutor to use for async calls. If not provided, a single-threaded
+ executor will be initialized and used.
+- **return_embedding** (bool) – Whether to return the embedding of the retrieved Documents. Default is True.
+
+#### shutdown
+
+```python
+shutdown() -> None
+```
+
+Explicitly shutdown the executor if we own it.
+
+#### storage
+
+```python
+storage: dict[str, Document]
+```
+
+Utility property that returns the storage used by this instance of InMemoryDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> InMemoryDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- InMemoryDocumentStore – The deserialized component.
+
+#### save_to_disk
+
+```python
+save_to_disk(path: str) -> None
+```
+
+Write the database and its data to disk as a JSON file.
+
+**Parameters:**
+
+- **path** (str) – The path to the JSON file.
+
+#### load_from_disk
+
+```python
+load_from_disk(path: str) -> InMemoryDocumentStore
+```
+
+Load the database and its data from disk as a JSON file.
+
+**Parameters:**
+
+- **path** (str) – The path to the JSON file.
+
+**Returns:**
+
+- InMemoryDocumentStore – The loaded InMemoryDocumentStore.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns the number of documents present in the DocumentStore.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply. For a detailed specification of the filters, refer to the
+ [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Refer to the DocumentStore.write_documents() protocol documentation.
+
+If `policy` is set to `DuplicatePolicy.NONE` defaults to `DuplicatePolicy.FAIL`.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with matching document_ids from the DocumentStore.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – The document_ids to delete.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents in the document store.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see filter_documents.
+- **meta** (dict\[str, Any\]) – The metadata fields to update. These will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+**Raises:**
+
+- ValueError – if filters have invalid syntax.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see filter_documents.
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+**Raises:**
+
+- ValueError – if filters have invalid syntax.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply.
+ For a detailed specification of the filters, refer to the
+ [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the number of unique values for each specified metadata field from documents matching the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply.
+ For a detailed specification of the filters, refer to the
+ [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+- **metadata_fields** (list\[str\]) – List of field names to count unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each metadata field name (without "meta." prefix)
+ to the count of its unique values among the filtered documents.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns information about the metadata fields present in the stored documents.
+
+Types are inferred from the stored values (keyword, int, float, boolean).
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary mapping each metadata field name to a dict with a "type" key.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for the given metadata field across all documents.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name. Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with "min" and "max" keys. Returns `{"min": None, "max": None}`
+ if the field is missing or has no values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str, search_term: str | None = None
+) -> tuple[list[str], int]
+```
+
+Returns unique values for a metadata field, optionally filtered by a search term in content.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name. Can include or omit the "meta." prefix.
+- **search_term** (str | None) – If set, only documents whose content contains this term (case-insensitive)
+ are considered.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple of (list of unique values, total count of unique values).
+
+#### bm25_retrieval
+
+```python
+bm25_retrieval(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ scale_score: bool = False,
+) -> list[Document]
+```
+
+Retrieves documents that are most relevant to the query using BM25 algorithm.
+
+**Parameters:**
+
+- **query** (str) – The query string.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space.
+- **top_k** (int) – The number of top documents to retrieve. Default is 10.
+- **scale_score** (bool) – Whether to scale the scores of the retrieved documents. Default is False.
+
+**Returns:**
+
+- list\[Document\] – A list of the top_k documents most relevant to the query.
+
+#### embedding_retrieval
+
+```python
+embedding_retrieval(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ scale_score: bool = False,
+ return_embedding: bool | None = False,
+) -> list[Document]
+```
+
+Retrieves documents that are most similar to the query embedding using a vector similarity metric.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space.
+- **top_k** (int) – The number of top documents to retrieve. Default is 10.
+- **scale_score** (bool) – Whether to scale the scores of the retrieved Documents. Default is False.
+- **return_embedding** (bool | None) – Whether to return the embedding of the retrieved Documents.
+ If not provided, the value of the `return_embedding` parameter set at component
+ initialization will be used. Default is False.
+
+**Returns:**
+
+- list\[Document\] – A list of the top_k documents most relevant to the query.
+
+**Raises:**
+
+- ValueError – if filters have invalid syntax.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Returns the number of documents present in the DocumentStore.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply. For a detailed specification of the filters, refer to the
+ [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Refer to the DocumentStore.write_documents() protocol documentation.
+
+If `policy` is set to `DuplicatePolicy.NONE` defaults to `DuplicatePolicy.FAIL`.
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Deletes all documents with matching document_ids from the DocumentStore.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – The document_ids to delete.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see filter_documents.
+- **meta** (dict\[str, Any\]) – The metadata fields to update. These will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply.
+ For a detailed specification of the filters, refer to the
+ [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the number of unique values for each specified metadata field from documents matching the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply.
+ For a detailed specification of the filters, refer to the
+ [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+- **metadata_fields** (list\[str\]) – List of field names to count unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each metadata field name (without "meta." prefix)
+ to the count of its unique values among the filtered documents.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Returns information about the metadata fields present in the stored documents.
+
+Types are inferred from the stored values (keyword, int, float, boolean).
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary mapping each metadata field name to a dict with a "type" key.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for the given metadata field across all documents.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name. Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with "min" and "max" keys. Returns `{"min": None, "max": None}`
+ if the field is missing or has no values.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str, search_term: str | None = None
+) -> tuple[list[str], int]
+```
+
+Returns unique values for a metadata field, optionally filtered by a search term in content.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name. Can include or omit the "meta." prefix.
+- **search_term** (str | None) – If set, only documents whose content contains this term (case-insensitive)
+ are considered.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple of (list of unique values, total count of unique values).
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async() -> None
+```
+
+Deletes all documents in the document store.
+
+#### bm25_retrieval_async
+
+```python
+bm25_retrieval_async(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ scale_score: bool = False,
+) -> list[Document]
+```
+
+Retrieves documents that are most relevant to the query using BM25 algorithm.
+
+**Parameters:**
+
+- **query** (str) – The query string.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space.
+- **top_k** (int) – The number of top documents to retrieve. Default is 10.
+- **scale_score** (bool) – Whether to scale the scores of the retrieved documents. Default is False.
+
+**Returns:**
+
+- list\[Document\] – A list of the top_k documents most relevant to the query.
+
+#### embedding_retrieval_async
+
+```python
+embedding_retrieval_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ scale_score: bool = False,
+ return_embedding: bool = False,
+) -> list[Document]
+```
+
+Retrieves documents that are most similar to the query embedding using a vector similarity metric.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space.
+- **top_k** (int) – The number of top documents to retrieve. Default is 10.
+- **scale_score** (bool) – Whether to scale the scores of the retrieved Documents. Default is False.
+- **return_embedding** (bool) – Whether to return the embedding of the retrieved Documents. Default is False.
+
+**Returns:**
+
+- list\[Document\] – A list of the top_k documents most relevant to the query.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/document_writers_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/document_writers_api.md
new file mode 100644
index 0000000000..8e33452fc8
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/document_writers_api.md
@@ -0,0 +1,129 @@
+---
+title: "Document Writers"
+id: document-writers-api
+description: "Writes Documents to a DocumentStore."
+slug: "/document-writers-api"
+---
+
+
+## document_writer
+
+### DocumentWriter
+
+Writes documents to a DocumentStore.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+docs = [
+ Document(content="Python is a popular programming language"),
+]
+doc_store = InMemoryDocumentStore()
+writer = DocumentWriter(document_store=doc_store)
+writer.run(docs)
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: DocumentStore,
+ policy: DuplicatePolicy = DuplicatePolicy.NONE,
+) -> None
+```
+
+Create a DocumentWriter component.
+
+**Parameters:**
+
+- **document_store** (DocumentStore) – The instance of the document store where you want to store your documents.
+- **policy** (DuplicatePolicy) – The policy to apply when a Document with the same ID already exists in the DocumentStore.
+- `DuplicatePolicy.NONE`: Default policy, relies on the DocumentStore settings.
+- `DuplicatePolicy.SKIP`: Skips documents with the same ID and doesn't write them to the DocumentStore.
+- `DuplicatePolicy.OVERWRITE`: Overwrites documents with the same ID.
+- `DuplicatePolicy.FAIL`: Raises an error if a Document with the same ID is already in the DocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DocumentWriter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- DocumentWriter – The deserialized component.
+
+**Raises:**
+
+- DeserializationError – If the document store is not properly specified in the serialization data or its type cannot be imported.
+
+#### run
+
+```python
+run(
+ documents: list[Document], policy: DuplicatePolicy | None = None
+) -> dict[str, int]
+```
+
+Run the DocumentWriter on the given input data.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to write to the document store.
+- **policy** (DuplicatePolicy | None) – The policy to use when encountering duplicate documents.
+
+**Returns:**
+
+- dict\[str, int\] – Number of documents written to the document store.
+
+**Raises:**
+
+- ValueError – If the specified document store is not found.
+
+#### run_async
+
+```python
+run_async(
+ documents: list[Document], policy: DuplicatePolicy | None = None
+) -> dict[str, int]
+```
+
+Asynchronously run the DocumentWriter on the given input data.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to write to the document store.
+- **policy** (DuplicatePolicy | None) – The policy to use when encountering duplicate documents.
+
+**Returns:**
+
+- dict\[str, int\] – Number of documents written to the document store.
+
+**Raises:**
+
+- ValueError – If the specified document store is not found.
+- TypeError – If the specified document store does not implement `write_documents_async`.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/embedders_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/embedders_api.md
new file mode 100644
index 0000000000..9638aca1d0
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/embedders_api.md
@@ -0,0 +1,1588 @@
+---
+title: "Embedders"
+id: embedders-api
+description: "Transforms queries into vectors to look for similar or relevant Documents."
+slug: "/embedders-api"
+---
+
+
+## azure_document_embedder
+
+### AzureOpenAIDocumentEmbedder
+
+Bases: OpenAIDocumentEmbedder
+
+Calculates document embeddings using OpenAI models deployed on Azure.
+
+### Usage example
+
+
+
+```python
+from haystack import Document
+from haystack.components.embedders import AzureOpenAIDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+document_embedder = AzureOpenAIDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ azure_endpoint: str | None = None,
+ api_version: str | None = "2023-05-15",
+ azure_deployment: str = "text-embedding-ada-002",
+ dimensions: int | None = None,
+ api_key: Secret | None = Secret.from_env_var(
+ "AZURE_OPENAI_API_KEY", strict=False
+ ),
+ azure_ad_token: Secret | None = Secret.from_env_var(
+ "AZURE_OPENAI_AD_TOKEN", strict=False
+ ),
+ organization: str | None = None,
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ *,
+ default_headers: dict[str, str] | None = None,
+ azure_ad_token_provider: AzureADTokenProvider | None = None,
+ http_client_kwargs: dict[str, Any] | None = None,
+ raise_on_failure: bool = False
+) -> None
+```
+
+Creates an AzureOpenAIDocumentEmbedder component.
+
+**Parameters:**
+
+- **azure_endpoint** (str | None) – The endpoint of the model deployed on Azure.
+- **api_version** (str | None) – The version of the API to use.
+- **azure_deployment** (str) – The name of the model deployed on Azure. The default model is text-embedding-ada-002.
+- **dimensions** (int | None) – The number of dimensions of the resulting embeddings. Only supported in text-embedding-3
+ and later models.
+- **api_key** (Secret | None) – The Azure OpenAI API key.
+ You can set it with an environment variable `AZURE_OPENAI_API_KEY`, or pass with this
+ parameter during initialization.
+- **azure_ad_token** (Secret | None) – Microsoft Entra ID token, see Microsoft's
+ [Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id)
+ documentation for more information. You can set it with an environment variable
+ `AZURE_OPENAI_AD_TOKEN`, or pass with this parameter during initialization.
+ Previously called Azure Active Directory.
+- **organization** (str | None) – Your organization ID. See OpenAI's
+ [Setting Up Your Organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization)
+ for more information.
+- **prefix** (str) – A string to add at the beginning of each text.
+- **suffix** (str) – A string to add at the end of each text.
+- **batch_size** (int) – Number of documents to embed at once.
+- **progress_bar** (bool) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (str) – Separator used to concatenate the metadata fields to the document text.
+- **timeout** (float | None) – The timeout for `AzureOpenAI` client calls, in seconds.
+ If not set, defaults to either the
+ `OPENAI_TIMEOUT` environment variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact AzureOpenAI after an internal error.
+ If not set, defaults to either the `OPENAI_MAX_RETRIES` environment variable or to 5 retries.
+- **default_headers** (dict\[str, str\] | None) – Default headers to send to the AzureOpenAI client.
+- **azure_ad_token_provider** (AzureADTokenProvider | None) – A function that returns an Azure Active Directory token, will be invoked on
+ every request.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+- **raise_on_failure** (bool) – Whether to raise an exception if the embedding request fails. If `False`, the component will log the error
+ and continue processing the remaining documents. If `True`, it will raise an exception on failure.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureOpenAIDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AzureOpenAIDocumentEmbedder – Deserialized component.
+
+## azure_text_embedder
+
+### AzureOpenAITextEmbedder
+
+Bases: OpenAITextEmbedder
+
+Embeds strings using OpenAI models deployed on Azure.
+
+### Usage example
+
+
+
+```python
+from haystack.components.embedders import AzureOpenAITextEmbedder
+
+text_to_embed = "I love pizza!"
+text_embedder = AzureOpenAITextEmbedder()
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+# 'meta': {'model': 'text-embedding-ada-002-v2',
+# 'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
+```
+
+#### __init__
+
+```python
+__init__(
+ azure_endpoint: str | None = None,
+ api_version: str | None = "2023-05-15",
+ azure_deployment: str = "text-embedding-ada-002",
+ dimensions: int | None = None,
+ api_key: Secret | None = Secret.from_env_var(
+ "AZURE_OPENAI_API_KEY", strict=False
+ ),
+ azure_ad_token: Secret | None = Secret.from_env_var(
+ "AZURE_OPENAI_AD_TOKEN", strict=False
+ ),
+ organization: str | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ prefix: str = "",
+ suffix: str = "",
+ *,
+ default_headers: dict[str, str] | None = None,
+ azure_ad_token_provider: AzureADTokenProvider | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an AzureOpenAITextEmbedder component.
+
+**Parameters:**
+
+- **azure_endpoint** (str | None) – The endpoint of the model deployed on Azure.
+- **api_version** (str | None) – The version of the API to use.
+- **azure_deployment** (str) – The name of the model deployed on Azure. The default model is text-embedding-ada-002.
+- **dimensions** (int | None) – The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3
+ and later models.
+- **api_key** (Secret | None) – The Azure OpenAI API key.
+ You can set it with an environment variable `AZURE_OPENAI_API_KEY`, or pass with this
+ parameter during initialization.
+- **azure_ad_token** (Secret | None) – Microsoft Entra ID token, see Microsoft's
+ [Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id)
+ documentation for more information. You can set it with an environment variable
+ `AZURE_OPENAI_AD_TOKEN`, or pass with this parameter during initialization.
+ Previously called Azure Active Directory.
+- **organization** (str | None) – Your organization ID. See OpenAI's
+ [Setting Up Your Organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization)
+ for more information.
+- **timeout** (float | None) – The timeout for `AzureOpenAI` client calls, in seconds.
+ If not set, defaults to either the
+ `OPENAI_TIMEOUT` environment variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact AzureOpenAI after an internal error.
+ If not set, defaults to either the `OPENAI_MAX_RETRIES` environment variable, or to 5 retries.
+- **prefix** (str) – A string to add at the beginning of each text.
+- **suffix** (str) – A string to add at the end of each text.
+- **default_headers** (dict\[str, str\] | None) – Default headers to send to the AzureOpenAI client.
+- **azure_ad_token_provider** (AzureADTokenProvider | None) – A function that returns an Azure Active Directory token, will be invoked on
+ every request.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureOpenAITextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AzureOpenAITextEmbedder – Deserialized component.
+
+## hugging_face_api_document_embedder
+
+### HuggingFaceAPIDocumentEmbedder
+
+Embeds documents using Hugging Face APIs.
+
+Use it with the following Hugging Face APIs:
+
+- [Free Serverless Inference API](https://huggingface.co/inference-api)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+
+### Usage examples
+
+#### With free serverless inference API
+
+
+
+```python
+from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
+from haystack.utils import Secret
+from haystack.dataclasses import Document
+
+doc = Document(content="I love pizza!")
+
+doc_embedder = HuggingFaceAPIDocumentEmbedder(api_type="serverless_inference_api",
+ api_params={"model": "BAAI/bge-small-en-v1.5"},
+ token=Secret.from_token("HFEmbeddingAPIType | str) – The type of Hugging Face API to use.
+- **api_params** (dict\[str, str\]) – A dictionary with the following keys:
+- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.
+- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or
+ `TEXT_EMBEDDINGS_INFERENCE`.
+- **token** (Secret | None) – The Hugging Face token to use as HTTP bearer authorization.
+ Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **prefix** (str) – A string to add at the beginning of each text.
+- **suffix** (str) – A string to add at the end of each text.
+- **truncate** (bool | None) – Truncates the input text to the maximum length supported by the model.
+ Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS`
+ if the backend uses Text Embeddings Inference.
+ If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
+- **normalize** (bool | None) – Normalizes the embeddings to unit length.
+ Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS`
+ if the backend uses Text Embeddings Inference.
+ If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
+- **batch_size** (int) – Number of documents to process at once.
+- **progress_bar** (bool) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (str) – Separator used to concatenate the metadata fields to the document text.
+- **concurrency_limit** (int) – The maximum number of requests that should be allowed to run concurrently.
+ This parameter is only used in the `run_async` method.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPIDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- HuggingFaceAPIDocumentEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embeds a list of documents asynchronously.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+
+## hugging_face_api_text_embedder
+
+### HuggingFaceAPITextEmbedder
+
+Embeds strings using Hugging Face APIs.
+
+Use it with the following Hugging Face APIs:
+
+- [Free Serverless Inference API](https://huggingface.co/inference-api)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+
+### Usage examples
+
+#### With free serverless inference API
+
+
+
+```python
+from haystack.components.embedders import HuggingFaceAPITextEmbedder
+from haystack.utils import Secret
+
+text_embedder = HuggingFaceAPITextEmbedder(api_type="serverless_inference_api",
+ api_params={"model": "BAAI/bge-small-en-v1.5"},
+ token=Secret.from_token("HFEmbeddingAPIType | str) – The type of Hugging Face API to use.
+- **api_params** (dict\[str, str\]) – A dictionary with the following keys:
+- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.
+- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or
+ `TEXT_EMBEDDINGS_INFERENCE`.
+- **token** (Secret | None) – The Hugging Face token to use as HTTP bearer authorization.
+ Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **prefix** (str) – A string to add at the beginning of each text.
+- **suffix** (str) – A string to add at the end of each text.
+- **truncate** (bool | None) – Truncates the input text to the maximum length supported by the model.
+ Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS`
+ if the backend uses Text Embeddings Inference.
+ If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
+- **normalize** (bool | None) – Normalizes the embeddings to unit length.
+ Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS`
+ if the backend uses Text Embeddings Inference.
+ If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPITextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- HuggingFaceAPITextEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embeds a single string.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, Any]
+```
+
+Embeds a single string asynchronously.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+
+## image/sentence_transformers_doc_image_embedder
+
+### SentenceTransformersDocumentImageEmbedder
+
+A component for computing Document embeddings based on images using Sentence Transformers models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+### Usage example
+
+
+
+```python
+from haystack import Document
+from haystack.components.embedders.image import SentenceTransformersDocumentImageEmbedder
+
+embedder = SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32")
+
+documents = [
+ Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
+ Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}),
+]
+
+result = embedder.run(documents=documents)
+documents_with_embeddings = result["documents"]
+print(documents_with_embeddings)
+
+# [Document(id=...,
+# content='A photo of a cat',
+# meta={'file_path': 'cat.jpg',
+# 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}},
+# embedding=vector of size 512),
+# ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ file_path_meta_field: str = "file_path",
+ root_path: str | None = None,
+ model: str = "sentence-transformers/clip-ViT-B-32",
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ normalize_embeddings: bool = False,
+ trust_remote_code: bool = False,
+ local_files_only: bool = False,
+ model_kwargs: dict[str, Any] | None = None,
+ tokenizer_kwargs: dict[str, Any] | None = None,
+ config_kwargs: dict[str, Any] | None = None,
+ precision: Literal[
+ "float32", "int8", "uint8", "binary", "ubinary"
+ ] = "float32",
+ encode_kwargs: dict[str, Any] | None = None,
+ backend: Literal["torch", "onnx", "openvino"] = "torch"
+) -> None
+```
+
+Creates a SentenceTransformersDocumentEmbedder component.
+
+**Parameters:**
+
+- **file_path_meta_field** (str) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (str | None) – The root directory path where document files are located. If provided, file paths in
+ document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **model** (str) – The Sentence Transformers model to use for calculating embeddings. Pass a local path or ID of the model on
+ Hugging Face. To be used with this component, the model must be able to embed images and text into the same
+ vector space. Compatible models include:
+- "sentence-transformers/clip-ViT-B-32"
+- "sentence-transformers/clip-ViT-L-14"
+- "sentence-transformers/clip-ViT-B-16"
+- "sentence-transformers/clip-ViT-B-32-multilingual-v1"
+- "jinaai/jina-embeddings-v4"
+- "jinaai/jina-clip-v1"
+- "jinaai/jina-clip-v2".
+- **device** (ComponentDevice | None) – The device to use for loading the model.
+ Overrides the default device.
+- **token** (Secret | None) – The API token to download private models from Hugging Face.
+- **batch_size** (int) – Number of documents to embed at once.
+- **progress_bar** (bool) – If `True`, shows a progress bar when embedding documents.
+- **normalize_embeddings** (bool) – If `True`, the embeddings are normalized using L2 normalization, so that each embedding has a norm of 1.
+- **trust_remote_code** (bool) – If `False`, allows only Hugging Face verified model architectures.
+ If `True`, allows custom models and scripts.
+- **local_files_only** (bool) – If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files.
+- **model_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
+ when loading the model. Refer to specific model documentation for available kwargs.
+- **tokenizer_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
+ Refer to specific model documentation for available kwargs.
+- **config_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration.
+- **precision** (Literal['float32', 'int8', 'uint8', 'binary', 'ubinary']) – The precision to use for the embeddings.
+ All non-float32 precisions are quantized embeddings.
+ Quantized embeddings are smaller and faster to compute, but may have a lower accuracy.
+ They are useful for reducing the size of the embeddings of a corpus for semantic search, among other tasks.
+- **encode_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `SentenceTransformer.encode` when embedding documents.
+ This parameter is provided for fine customization. Be careful not to clash with already set parameters and
+ avoid passing parameters that change the output type.
+- **backend** (Literal['torch', 'onnx', 'openvino']) – The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino".
+ Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html)
+ for more information on acceleration and quantization options.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SentenceTransformersDocumentImageEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SentenceTransformersDocumentImageEmbedder – Deserialized component.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Documents with embeddings.
+
+## openai_document_embedder
+
+### OpenAIDocumentEmbedder
+
+Computes document embeddings using OpenAI models.
+
+### Usage example
+
+
+
+```python
+from haystack import Document
+from haystack.components.embedders import OpenAIDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+document_embedder = OpenAIDocumentEmbedder()
+result = document_embedder.run([doc])
+
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
+ model: str = "text-embedding-ada-002",
+ dimensions: int | None = None,
+ api_base_url: str | None = None,
+ organization: str | None = None,
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None,
+ *,
+ raise_on_failure: bool = False
+) -> None
+```
+
+Creates an OpenAIDocumentEmbedder component.
+
+Before initializing the component, you can set the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES'
+environment variables to override the `timeout` and `max_retries` parameters respectively
+in the OpenAI client.
+
+**Parameters:**
+
+- **api_key** (Secret) – The OpenAI API key.
+ You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter
+ during initialization.
+- **model** (str) – The name of the model to use for calculating embeddings.
+ The default model is `text-embedding-ada-002`.
+- **dimensions** (int | None) – The number of dimensions of the resulting embeddings. Only `text-embedding-3` and
+ later models support this parameter.
+- **api_base_url** (str | None) – Overrides the default base URL for all HTTP requests.
+- **organization** (str | None) – Your OpenAI organization ID. See OpenAI's
+ [Setting Up Your Organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization)
+ for more information.
+- **prefix** (str) – A string to add at the beginning of each text.
+- **suffix** (str) – A string to add at the end of each text.
+- **batch_size** (int) – Number of documents to embed at once.
+- **progress_bar** (bool) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (str) – Separator used to concatenate the metadata fields to the document text.
+- **timeout** (float | None) – Timeout for OpenAI client calls. If not set, it defaults to either the
+ `OPENAI_TIMEOUT` environment variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact OpenAI after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or 5 retries.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+- **raise_on_failure** (bool) – Whether to raise an exception if the embedding request fails. If `False`, the component will log the error
+ and continue processing the remaining documents. If `True`, it will raise an exception on failure.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAIDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OpenAIDocumentEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, Any]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, Any]
+```
+
+Embeds a list of documents asynchronously.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+## openai_text_embedder
+
+### OpenAITextEmbedder
+
+Embeds strings using OpenAI models.
+
+You can use it to embed user query and send it to an embedding Retriever.
+
+### Usage example
+
+
+
+```python
+from haystack.components.embedders import OpenAITextEmbedder
+
+text_to_embed = "I love pizza!"
+text_embedder = OpenAITextEmbedder()
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+# 'meta': {'model': 'text-embedding-ada-002-v2',
+# 'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
+ model: str = "text-embedding-ada-002",
+ dimensions: int | None = None,
+ api_base_url: str | None = None,
+ organization: str | None = None,
+ prefix: str = "",
+ suffix: str = "",
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Creates an OpenAITextEmbedder component.
+
+Before initializing the component, you can set the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES'
+environment variables to override the `timeout` and `max_retries` parameters respectively
+in the OpenAI client.
+
+**Parameters:**
+
+- **api_key** (Secret) – The OpenAI API key.
+ You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter
+ during initialization.
+- **model** (str) – The name of the model to use for calculating embeddings.
+ The default model is `text-embedding-ada-002`.
+- **dimensions** (int | None) – The number of dimensions of the resulting embeddings. Only `text-embedding-3` and
+ later models support this parameter.
+- **api_base_url** (str | None) – Overrides default base URL for all HTTP requests.
+- **organization** (str | None) – Your organization ID. See OpenAI's
+ [production best practices](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization)
+ for more information.
+- **prefix** (str) – A string to add at the beginning of each text to embed.
+- **suffix** (str) – A string to add at the end of each text to embed.
+- **timeout** (float | None) – Timeout for OpenAI client calls. If not set, it defaults to either the
+ `OPENAI_TIMEOUT` environment variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact OpenAI after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAITextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OpenAITextEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embeds a single string.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, Any]
+```
+
+Asynchronously embed a single string.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+## sentence_transformers_document_embedder
+
+### SentenceTransformersDocumentEmbedder
+
+Calculates document embeddings using Sentence Transformers models.
+
+It stores the embeddings in the `embedding` metadata field of each document.
+You can also embed documents' metadata.
+Use this component in indexing pipelines to embed input documents
+and send them to DocumentWriter to write into a Document Store.
+
+### Usage example:
+
+
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+doc = Document(content="I love pizza!")
+doc_embedder = SentenceTransformersDocumentEmbedder()
+
+result = doc_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [-0.07804739475250244, 0.1498992145061493, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "sentence-transformers/all-mpnet-base-v2",
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ normalize_embeddings: bool = False,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ trust_remote_code: bool = False,
+ local_files_only: bool = False,
+ truncate_dim: int | None = None,
+ model_kwargs: dict[str, Any] | None = None,
+ tokenizer_kwargs: dict[str, Any] | None = None,
+ config_kwargs: dict[str, Any] | None = None,
+ precision: Literal[
+ "float32", "int8", "uint8", "binary", "ubinary"
+ ] = "float32",
+ encode_kwargs: dict[str, Any] | None = None,
+ backend: Literal["torch", "onnx", "openvino"] = "torch",
+ revision: str | None = None,
+) -> None
+```
+
+Creates a SentenceTransformersDocumentEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – The model to use for calculating embeddings.
+ Pass a local path or ID of the model on Hugging Face.
+- **device** (ComponentDevice | None) – The device to use for loading the model.
+ Overrides the default device.
+- **token** (Secret | None) – The API token to download private models from Hugging Face.
+- **prefix** (str) – A string to add at the beginning of each document text.
+ Can be used to prepend the text with an instruction, as required by some embedding models,
+ such as E5 and bge.
+- **suffix** (str) – A string to add at the end of each document text.
+- **batch_size** (int) – Number of documents to embed at once.
+- **progress_bar** (bool) – If `True`, shows a progress bar when embedding documents.
+- **normalize_embeddings** (bool) – If `True`, the embeddings are normalized using L2 normalization, so that each embedding has a norm of 1.
+- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (str) – Separator used to concatenate the metadata fields to the document text.
+- **trust_remote_code** (bool) – If `False`, allows only Hugging Face verified model architectures.
+ If `True`, allows custom models and scripts.
+- **local_files_only** (bool) – If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files.
+- **truncate_dim** (int | None) – The dimension to truncate sentence embeddings to. `None` does no truncation.
+ If the model wasn't trained with Matryoshka Representation Learning,
+ truncating embeddings can significantly affect performance.
+- **model_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
+ when loading the model. Refer to specific model documentation for available kwargs.
+- **tokenizer_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
+ Refer to specific model documentation for available kwargs.
+- **config_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration.
+- **precision** (Literal['float32', 'int8', 'uint8', 'binary', 'ubinary']) – The precision to use for the embeddings.
+ All non-float32 precisions are quantized embeddings.
+ Quantized embeddings are smaller and faster to compute, but may have a lower accuracy.
+ They are useful for reducing the size of the embeddings of a corpus for semantic search, among other tasks.
+- **encode_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `SentenceTransformer.encode` when embedding documents.
+ This parameter is provided for fine customization. Be careful not to clash with already set parameters and
+ avoid passing parameters that change the output type.
+- **backend** (Literal['torch', 'onnx', 'openvino']) – The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino".
+ Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html)
+ for more information on acceleration and quantization options.
+- **revision** (str | None) – The specific model version to use. It can be a branch name, a tag name, or a commit id,
+ for a stored model on Hugging Face.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SentenceTransformersDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SentenceTransformersDocumentEmbedder – Deserialized component.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Documents with embeddings.
+
+## sentence_transformers_sparse_document_embedder
+
+### SentenceTransformersSparseDocumentEmbedder
+
+Calculates document sparse embeddings using sparse embedding models from Sentence Transformers.
+
+It stores the sparse embeddings in the `sparse_embedding` metadata field of each document.
+You can also embed documents' metadata.
+Use this component in indexing pipelines to embed input documents
+and send them to DocumentWriter to write a into a Document Store.
+
+### Usage example:
+
+
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersSparseDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+doc_embedder = SentenceTransformersSparseDocumentEmbedder()
+
+result = doc_embedder.run([doc])
+print(result['documents'][0].sparse_embedding)
+
+# SparseEmbedding(indices=[999, 1045, ...], values=[0.918, 0.867, ...])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "prithivida/Splade_PP_en_v2",
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ trust_remote_code: bool = False,
+ local_files_only: bool = False,
+ model_kwargs: dict[str, Any] | None = None,
+ tokenizer_kwargs: dict[str, Any] | None = None,
+ config_kwargs: dict[str, Any] | None = None,
+ backend: Literal["torch", "onnx", "openvino"] = "torch",
+ revision: str | None = None
+) -> None
+```
+
+Creates a SentenceTransformersSparseDocumentEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – The model to use for calculating sparse embeddings.
+ Pass a local path or ID of the model on Hugging Face.
+- **device** (ComponentDevice | None) – The device to use for loading the model.
+ Overrides the default device.
+- **token** (Secret | None) – The API token to download private models from Hugging Face.
+- **prefix** (str) – A string to add at the beginning of each document text.
+- **suffix** (str) – A string to add at the end of each document text.
+- **batch_size** (int) – Number of documents to embed at once.
+- **progress_bar** (bool) – If `True`, shows a progress bar when embedding documents.
+- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (str) – Separator used to concatenate the metadata fields to the document text.
+- **trust_remote_code** (bool) – If `False`, allows only Hugging Face verified model architectures.
+ If `True`, allows custom models and scripts.
+- **local_files_only** (bool) – If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files.
+- **model_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
+ when loading the model. Refer to specific model documentation for available kwargs.
+- **tokenizer_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
+ Refer to specific model documentation for available kwargs.
+- **config_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration.
+- **backend** (Literal['torch', 'onnx', 'openvino']) – The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino".
+ Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html)
+ for more information on acceleration and quantization options.
+- **revision** (str | None) – The specific model version to use. It can be a branch name, a tag name, or a commit id,
+ for a stored model on Hugging Face.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SentenceTransformersSparseDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SentenceTransformersSparseDocumentEmbedder – Deserialized component.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Documents with sparse embeddings under the `sparse_embedding` field.
+
+## sentence_transformers_sparse_text_embedder
+
+### SentenceTransformersSparseTextEmbedder
+
+Embeds strings using sparse embedding models from Sentence Transformers.
+
+You can use it to embed user query and send it to a sparse embedding retriever.
+
+Usage example:
+
+
+
+```python
+from haystack.components.embedders import SentenceTransformersSparseTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = SentenceTransformersSparseTextEmbedder()
+
+print(text_embedder.run(text_to_embed))
+
+# {'sparse_embedding': SparseEmbedding(indices=[999, 1045, ...], values=[0.918, 0.867, ...])}
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "prithivida/Splade_PP_en_v2",
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ prefix: str = "",
+ suffix: str = "",
+ trust_remote_code: bool = False,
+ local_files_only: bool = False,
+ model_kwargs: dict[str, Any] | None = None,
+ tokenizer_kwargs: dict[str, Any] | None = None,
+ config_kwargs: dict[str, Any] | None = None,
+ backend: Literal["torch", "onnx", "openvino"] = "torch",
+ revision: str | None = None
+) -> None
+```
+
+Create a SentenceTransformersSparseTextEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – The model to use for calculating sparse embeddings.
+ Specify the path to a local model or the ID of the model on Hugging Face.
+- **device** (ComponentDevice | None) – Overrides the default device used to load the model.
+- **token** (Secret | None) – An API token to use private models from Hugging Face.
+- **prefix** (str) – A string to add at the beginning of each text to be embedded.
+- **suffix** (str) – A string to add at the end of each text to embed.
+- **trust_remote_code** (bool) – If `False`, permits only Hugging Face verified model architectures.
+ If `True`, permits custom models and scripts.
+- **local_files_only** (bool) – If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files.
+- **model_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
+ when loading the model. Refer to specific model documentation for available kwargs.
+- **tokenizer_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
+ Refer to specific model documentation for available kwargs.
+- **config_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration.
+- **backend** (Literal['torch', 'onnx', 'openvino']) – The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino".
+ Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html)
+ for more information on acceleration and quantization options.
+- **revision** (str | None) – The specific model version to use. It can be a branch name, a tag name, or a commit id,
+ for a stored model on Hugging Face.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SentenceTransformersSparseTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SentenceTransformersSparseTextEmbedder – Deserialized component.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embed a single string.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `sparse_embedding`: The sparse embedding of the input text.
+
+## sentence_transformers_text_embedder
+
+### SentenceTransformersTextEmbedder
+
+Embeds strings using Sentence Transformers models.
+
+You can use it to embed user query and send it to an embedding retriever.
+
+Usage example:
+
+
+
+```python
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = SentenceTransformersTextEmbedder()
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]}
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "sentence-transformers/all-mpnet-base-v2",
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ normalize_embeddings: bool = False,
+ trust_remote_code: bool = False,
+ local_files_only: bool = False,
+ truncate_dim: int | None = None,
+ model_kwargs: dict[str, Any] | None = None,
+ tokenizer_kwargs: dict[str, Any] | None = None,
+ config_kwargs: dict[str, Any] | None = None,
+ precision: Literal[
+ "float32", "int8", "uint8", "binary", "ubinary"
+ ] = "float32",
+ encode_kwargs: dict[str, Any] | None = None,
+ backend: Literal["torch", "onnx", "openvino"] = "torch",
+ revision: str | None = None,
+) -> None
+```
+
+Create a SentenceTransformersTextEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – The model to use for calculating embeddings.
+ Specify the path to a local model or the ID of the model on Hugging Face.
+- **device** (ComponentDevice | None) – Overrides the default device used to load the model.
+- **token** (Secret | None) – An API token to use private models from Hugging Face.
+- **prefix** (str) – A string to add at the beginning of each text to be embedded.
+ You can use it to prepend the text with an instruction, as required by some embedding models,
+ such as E5 and bge.
+- **suffix** (str) – A string to add at the end of each text to embed.
+- **batch_size** (int) – Number of texts to embed at once.
+- **progress_bar** (bool) – If `True`, shows a progress bar for calculating embeddings.
+ If `False`, disables the progress bar.
+- **normalize_embeddings** (bool) – If `True`, the embeddings are normalized using L2 normalization, so that the embeddings have a norm of 1.
+- **trust_remote_code** (bool) – If `False`, permits only Hugging Face verified model architectures.
+ If `True`, permits custom models and scripts.
+- **local_files_only** (bool) – If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files.
+- **truncate_dim** (int | None) – The dimension to truncate sentence embeddings to. `None` does no truncation.
+ If the model has not been trained with Matryoshka Representation Learning,
+ truncation of embeddings can significantly affect performance.
+- **model_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
+ when loading the model. Refer to specific model documentation for available kwargs.
+- **tokenizer_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
+ Refer to specific model documentation for available kwargs.
+- **config_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration.
+- **precision** (Literal['float32', 'int8', 'uint8', 'binary', 'ubinary']) – The precision to use for the embeddings.
+ All non-float32 precisions are quantized embeddings.
+ Quantized embeddings are smaller in size and faster to compute, but may have a lower accuracy.
+ They are useful for reducing the size of the embeddings of a corpus for semantic search, among other tasks.
+- **encode_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `SentenceTransformer.encode` when embedding texts.
+ This parameter is provided for fine customization. Be careful not to clash with already set parameters and
+ avoid passing parameters that change the output type.
+- **backend** (Literal['torch', 'onnx', 'openvino']) – The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino".
+ Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html)
+ for more information on acceleration and quantization options.
+- **revision** (str | None) – The specific model version to use. It can be a branch name, a tag name, or a commit id,
+ for a stored model on Hugging Face.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SentenceTransformersTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SentenceTransformersTextEmbedder – Deserialized component.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embed a single string.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/evaluation_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/evaluation_api.md
new file mode 100644
index 0000000000..1c0f644694
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/evaluation_api.md
@@ -0,0 +1,108 @@
+---
+title: "Evaluation"
+id: evaluation-api
+description: "Represents the results of evaluation."
+slug: "/evaluation-api"
+---
+
+
+## eval_run_result
+
+### EvaluationRunResult
+
+Contains the inputs and the outputs of an evaluation pipeline and provides methods to inspect them.
+
+#### __init__
+
+```python
+__init__(
+ run_name: str,
+ inputs: dict[str, list[Any]],
+ results: dict[str, dict[str, Any]],
+) -> None
+```
+
+Initialize a new evaluation run result.
+
+**Parameters:**
+
+- **run_name** (str) – Name of the evaluation run.
+- **inputs** (dict\[str, list\[Any\]\]) – Dictionary containing the inputs used for the run. Each key is the name of the input and its value is a list
+ of input values. The length of the lists should be the same.
+- **results** (dict\[str, dict\[str, Any\]\]) – Dictionary containing the results of the evaluators used in the evaluation pipeline. Each key is the name
+ of the metric and its value is dictionary with the following keys:
+ - 'score': The aggregated score for the metric.
+ - 'individual_scores': A list of scores for each input sample.
+
+#### aggregated_report
+
+```python
+aggregated_report(
+ output_format: Literal["json", "csv", "df"] = "json",
+ csv_file: str | None = None,
+) -> Union[dict[str, list[Any]], DataFrame, str]
+```
+
+Generates a report with aggregated scores for each metric.
+
+**Parameters:**
+
+- **output_format** (Literal['json', 'csv', 'df']) – The output format for the report, "json", "csv", or "df", default to "json".
+- **csv_file** (str | None) – Filepath to save CSV output if `output_format` is "csv", must be provided.
+
+**Returns:**
+
+- Union\[dict\[str, list\[Any\]\], DataFrame, str\] – JSON or DataFrame with aggregated scores, in case the output is set to a CSV file, a message confirming the
+ successful write or an error message.
+
+#### detailed_report
+
+```python
+detailed_report(
+ output_format: Literal["json", "csv", "df"] = "json",
+ csv_file: str | None = None,
+) -> Union[dict[str, list[Any]], DataFrame, str]
+```
+
+Generates a report with detailed scores for each metric.
+
+**Parameters:**
+
+- **output_format** (Literal['json', 'csv', 'df']) – The output format for the report, "json", "csv", or "df", default to "json".
+- **csv_file** (str | None) – Filepath to save CSV output if `output_format` is "csv", must be provided.
+
+**Returns:**
+
+- Union\[dict\[str, list\[Any\]\], DataFrame, str\] – JSON or DataFrame with the detailed scores, in case the output is set to a CSV file, a message confirming
+ the successful write or an error message.
+
+#### comparative_detailed_report
+
+```python
+comparative_detailed_report(
+ other: EvaluationRunResult,
+ keep_columns: list[str] | None = None,
+ output_format: Literal["json", "csv", "df"] = "json",
+ csv_file: str | None = None,
+) -> Union[str, DataFrame, None]
+```
+
+Generates a report with detailed scores for each metric from two evaluation runs for comparison.
+
+**Parameters:**
+
+- **other** (EvaluationRunResult) – Results of another evaluation run to compare with.
+- **keep_columns** (list\[str\] | None) – List of common column names to keep from the inputs of the evaluation runs to compare.
+- **output_format** (Literal['json', 'csv', 'df']) – The output format for the report, "json", "csv", or "df", default to "json".
+- **csv_file** (str | None) – Filepath to save CSV output if `output_format` is "csv", must be provided.
+
+**Returns:**
+
+- Union\[str, DataFrame, None\] – JSON or DataFrame with a comparison of the detailed scores, in case the output is set to a CSV file,
+ a message confirming the successful write or an error message.
+
+**Raises:**
+
+- TypeError – If `other` is not an EvaluationRunResult instance, or if the detailed reports are not
+ dictionaries.
+- ValueError – If the `other` parameter is missing required attributes.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/evaluators_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/evaluators_api.md
new file mode 100644
index 0000000000..5161417fb6
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/evaluators_api.md
@@ -0,0 +1,1057 @@
+---
+title: "Evaluators"
+id: evaluators-api
+description: "Evaluate your pipelines or individual components."
+slug: "/evaluators-api"
+---
+
+
+## answer_exact_match
+
+### AnswerExactMatchEvaluator
+
+An answer exact match evaluator class.
+
+The evaluator that checks if the predicted answers matches any of the ground truth answers exactly.
+The result is a number from 0.0 to 1.0, it represents the proportion of predicted answers
+that matched one of the ground truth answers.
+There can be multiple ground truth answers and multiple predicted answers as input.
+
+Usage example:
+
+```python
+from haystack.components.evaluators import AnswerExactMatchEvaluator
+
+evaluator = AnswerExactMatchEvaluator()
+result = evaluator.run(
+ ground_truth_answers=["Berlin", "Paris"],
+ predicted_answers=["Berlin", "Lyon"],
+)
+
+print(result["individual_scores"])
+# [1, 0]
+print(result["score"])
+# 0.5
+```
+
+#### run
+
+```python
+run(
+ ground_truth_answers: list[str], predicted_answers: list[str]
+) -> dict[str, Any]
+```
+
+Run the AnswerExactMatchEvaluator on the given inputs.
+
+The `ground_truth_answers` and `retrieved_answers` must have the same length.
+
+**Parameters:**
+
+- **ground_truth_answers** (list\[str\]) – A list of expected answers.
+- **predicted_answers** (list\[str\]) – A list of predicted answers.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following outputs:
+- `individual_scores` - A list of 0s and 1s, where 1 means that the predicted answer matched one of the
+ ground truth.
+- `score` - A number from 0.0 to 1.0 that represents the proportion of questions where any predicted
+ answer matched one of the ground truth answers.
+
+## context_relevance
+
+### ContextRelevanceEvaluator
+
+Bases: LLMEvaluator
+
+Evaluator that checks if a provided context is relevant to the question.
+
+An LLM breaks up a context into multiple statements and checks whether each statement
+is relevant for answering a question.
+The score for each context is either binary score of 1 or 0, where 1 indicates that the context is relevant
+to the question and 0 indicates that the context is not relevant.
+The evaluator also provides the relevant statements from the context and an average score over all the provided
+input questions contexts pairs.
+
+Usage example:
+
+```python
+from haystack.components.evaluators import ContextRelevanceEvaluator
+
+questions = ["Who created the Python language?", "Why does Java needs a JVM?", "Is C++ better than Python?"]
+contexts = [
+ [(
+ "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming "
+ "language. Its design philosophy emphasizes code readability, and its language constructs aim to help "
+ "programmers write clear, logical code for both small and large-scale software projects."
+ )],
+ [(
+ "Java is a high-level, class-based, object-oriented programming language that is designed to have as few "
+ "implementation dependencies as possible. The JVM has two primary functions: to allow Java programs to run"
+ "on any device or operating system (known as the 'write once, run anywhere' principle), and to manage and"
+ "optimize program memory."
+ )],
+ [(
+ "C++ is a general-purpose programming language created by Bjarne Stroustrup as an extension of the C "
+ "programming language."
+ )],
+]
+
+evaluator = ContextRelevanceEvaluator()
+result = evaluator.run(questions=questions, contexts=contexts)
+print(result["score"])
+# 0.67
+print(result["individual_scores"])
+# [1,1,0]
+print(result["results"])
+# [{
+# 'relevant_statements': ['Python, created by Guido van Rossum in the late 1980s.'],
+# 'score': 1.0
+# },
+# {
+# 'relevant_statements': ['The JVM has two primary functions: to allow Java programs to run on any device or
+# operating system (known as the "write once, run anywhere" principle), and to manage and
+# optimize program memory'],
+# 'score': 1.0
+# },
+# {
+# 'relevant_statements': [],
+# 'score': 0.0
+# }]
+```
+
+#### __init__
+
+```python
+__init__(
+ examples: list[dict[str, Any]] | None = None,
+ progress_bar: bool = True,
+ raise_on_failure: bool = True,
+ chat_generator: ChatGenerator | None = None,
+) -> None
+```
+
+Creates an instance of ContextRelevanceEvaluator.
+
+If no LLM is specified using the `chat_generator` parameter, the component will use OpenAI in JSON mode.
+
+**Parameters:**
+
+- **examples** (list\[dict\[str, Any\]\] | None) – Optional few-shot examples conforming to the expected input and output format of ContextRelevanceEvaluator.
+ Default examples will be used if none are provided.
+ Each example must be a dictionary with keys "inputs" and "outputs".
+ "inputs" must be a dictionary with keys "questions" and "contexts".
+ "outputs" must be a dictionary with "relevant_statements".
+ Expected format:
+
+```python
+[{
+ "inputs": {
+ "questions": "What is the capital of Italy?", "contexts": ["Rome is the capital of Italy."],
+ },
+ "outputs": {
+ "relevant_statements": ["Rome is the capital of Italy."],
+ },
+}]
+```
+
+- **progress_bar** (bool) – Whether to show a progress bar during the evaluation.
+- **raise_on_failure** (bool) – Whether to raise an exception if the API call fails.
+- **chat_generator** (ChatGenerator | None) – a ChatGenerator instance which represents the LLM.
+ In order for the component to work, the LLM should be configured to return a JSON object. For example,
+ when using the OpenAIChatGenerator, you should pass `{"response_format": {"type": "json_object"}}` in the
+ `generation_kwargs`.
+
+#### run
+
+```python
+run(**inputs: Any) -> dict[str, Any]
+```
+
+Run the LLM evaluator.
+
+**Parameters:**
+
+- **questions** – A list of questions.
+- **contexts** – A list of lists of contexts. Each list of contexts corresponds to one question.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following outputs:
+ - `score`: Mean context relevance score over all the provided input questions.
+ - `results`: A list of dictionaries with `relevant_statements` and `score` for each input context.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ContextRelevanceEvaluator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- ContextRelevanceEvaluator – The deserialized component instance.
+
+## document_map
+
+### DocumentMAPEvaluator
+
+A Mean Average Precision (MAP) evaluator for documents.
+
+Evaluator that calculates the mean average precision of the retrieved documents, a metric
+that measures how high retrieved documents are ranked.
+Each question can have multiple ground truth documents and multiple retrieved documents.
+
+`DocumentMAPEvaluator` doesn't normalize its inputs, the `DocumentCleaner` component
+should be used to clean and normalize the documents before passing them to this evaluator.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentMAPEvaluator
+
+evaluator = DocumentMAPEvaluator()
+result = evaluator.run(
+ ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+ ],
+ retrieved_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="10th century"), Document(content="9th")],
+ ],
+)
+
+print(result["individual_scores"])
+# [1.0, 0.8333333333333333]
+print(result["score"])
+# 0.9166666666666666
+```
+
+#### __init__
+
+```python
+__init__(document_comparison_field: str = 'content') -> None
+```
+
+Create a DocumentMAPEvaluator component.
+
+**Parameters:**
+
+- **document_comparison_field** (str) – The Document field to use for comparison. Possible options:
+- `"content"`: uses `doc.content`
+- `"id"`: uses `doc.id`
+- A `meta.` prefix followed by a key name: uses `doc.meta["dict\[str, Any\] – Dictionary with serialized data.
+
+#### run
+
+```python
+run(
+ ground_truth_documents: list[list[Document]],
+ retrieved_documents: list[list[Document]],
+) -> dict[str, Any]
+```
+
+Run the DocumentMAPEvaluator on the given inputs.
+
+All lists must have the same length.
+
+**Parameters:**
+
+- **ground_truth_documents** (list\[list\[Document\]\]) – A list of expected documents for each question.
+- **retrieved_documents** (list\[list\[Document\]\]) – A list of retrieved documents for each question.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following outputs:
+- `score` - The average of calculated scores.
+- `individual_scores` - A list of numbers from 0.0 to 1.0 that represents how high retrieved documents
+ are ranked.
+
+## document_mrr
+
+### DocumentMRREvaluator
+
+Evaluator that calculates the mean reciprocal rank of the retrieved documents.
+
+MRR measures how high the first retrieved document is ranked.
+Each question can have multiple ground truth documents and multiple retrieved documents.
+
+`DocumentMRREvaluator` doesn't normalize its inputs, the `DocumentCleaner` component
+should be used to clean and normalize the documents before passing them to this evaluator.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentMRREvaluator
+
+evaluator = DocumentMRREvaluator()
+result = evaluator.run(
+ ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+ ],
+ retrieved_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="10th century"), Document(content="9th")],
+ ],
+)
+print(result["individual_scores"])
+# [1.0, 1.0]
+print(result["score"])
+# 1.0
+```
+
+#### __init__
+
+```python
+__init__(document_comparison_field: str = 'content') -> None
+```
+
+Create a DocumentMRREvaluator component.
+
+**Parameters:**
+
+- **document_comparison_field** (str) – The Document field to use for comparison. Possible options:
+- `"content"`: uses `doc.content`
+- `"id"`: uses `doc.id`
+- A `meta.` prefix followed by a key name: uses `doc.meta["dict\[str, Any\] – Dictionary with serialized data.
+
+#### run
+
+```python
+run(
+ ground_truth_documents: list[list[Document]],
+ retrieved_documents: list[list[Document]],
+) -> dict[str, Any]
+```
+
+Run the DocumentMRREvaluator on the given inputs.
+
+`ground_truth_documents` and `retrieved_documents` must have the same length.
+
+**Parameters:**
+
+- **ground_truth_documents** (list\[list\[Document\]\]) – A list of expected documents for each question.
+- **retrieved_documents** (list\[list\[Document\]\]) – A list of retrieved documents for each question.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following outputs:
+- `score` - The average of calculated scores.
+- `individual_scores` - A list of numbers from 0.0 to 1.0 that represents how high the first retrieved
+ document is ranked.
+
+## document_ndcg
+
+### DocumentNDCGEvaluator
+
+Evaluator that calculates the normalized discounted cumulative gain (NDCG) of retrieved documents.
+
+Each question can have multiple ground truth documents and multiple retrieved documents.
+If the ground truth documents have relevance scores, the NDCG calculation uses these scores.
+Otherwise, it assumes binary relevance of all ground truth documents.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentNDCGEvaluator
+
+evaluator = DocumentNDCGEvaluator()
+result = evaluator.run(
+ ground_truth_documents=[[Document(content="France", score=1.0), Document(content="Paris", score=0.5)]],
+ retrieved_documents=[[Document(content="France"), Document(content="Germany"), Document(content="Paris")]],
+)
+print(result["individual_scores"])
+# [0.8869]
+print(result["score"])
+# 0.8869
+```
+
+#### run
+
+```python
+run(
+ ground_truth_documents: list[list[Document]],
+ retrieved_documents: list[list[Document]],
+) -> dict[str, Any]
+```
+
+Run the DocumentNDCGEvaluator on the given inputs.
+
+`ground_truth_documents` and `retrieved_documents` must have the same length.
+The list items within `ground_truth_documents` and `retrieved_documents` can differ in length.
+
+**Parameters:**
+
+- **ground_truth_documents** (list\[list\[Document\]\]) – Lists of expected documents, one list per question. Binary relevance is used if documents have no scores.
+- **retrieved_documents** (list\[list\[Document\]\]) – Lists of retrieved documents, one list per question.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following outputs:
+- `score` - The average of calculated scores.
+- `individual_scores` - A list of numbers from 0.0 to 1.0 that represents the NDCG for each question.
+
+#### validate_inputs
+
+```python
+validate_inputs(
+ gt_docs: list[list[Document]], ret_docs: list[list[Document]]
+) -> None
+```
+
+Validate the input parameters.
+
+**Parameters:**
+
+- **gt_docs** (list\[list\[Document\]\]) – The ground_truth_documents to validate.
+- **ret_docs** (list\[list\[Document\]\]) – The retrieved_documents to validate.
+
+**Raises:**
+
+- ValueError – If the ground_truth_documents or the retrieved_documents are an empty a list.
+ If the length of ground_truth_documents and retrieved_documents differs.
+ If any list of documents in ground_truth_documents contains a mix of documents with and without a score.
+
+#### calculate_dcg
+
+```python
+calculate_dcg(gt_docs: list[Document], ret_docs: list[Document]) -> float
+```
+
+Calculate the discounted cumulative gain (DCG) of the retrieved documents.
+
+**Parameters:**
+
+- **gt_docs** (list\[Document\]) – The ground truth documents.
+- **ret_docs** (list\[Document\]) – The retrieved documents.
+
+**Returns:**
+
+- float – The discounted cumulative gain (DCG) of the retrieved
+ documents based on the ground truth documents.
+
+#### calculate_idcg
+
+```python
+calculate_idcg(gt_docs: list[Document]) -> float
+```
+
+Calculate the ideal discounted cumulative gain (IDCG) of the ground truth documents.
+
+**Parameters:**
+
+- **gt_docs** (list\[Document\]) – The ground truth documents.
+
+**Returns:**
+
+- float – The ideal discounted cumulative gain (IDCG) of the ground truth documents.
+
+## document_recall
+
+### RecallMode
+
+Bases: Enum
+
+Enum for the mode to use for calculating the recall score.
+
+#### from_str
+
+```python
+from_str(string: str) -> RecallMode
+```
+
+Convert a string to a RecallMode enum.
+
+### DocumentRecallEvaluator
+
+Evaluator that calculates the Recall score for a list of documents.
+
+Returns both a list of scores for each question and the average.
+There can be multiple ground truth documents and multiple predicted documents as input.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentRecallEvaluator
+
+evaluator = DocumentRecallEvaluator()
+result = evaluator.run(
+ ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+ ],
+ retrieved_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="10th century"), Document(content="9th")],
+ ],
+)
+print(result["individual_scores"])
+# [1.0, 1.0]
+print(result["score"])
+# 1.0
+```
+
+#### __init__
+
+```python
+__init__(
+ mode: str | RecallMode = RecallMode.SINGLE_HIT,
+ document_comparison_field: str = "content",
+) -> None
+```
+
+Create a DocumentRecallEvaluator component.
+
+**Parameters:**
+
+- **mode** (str | RecallMode) – Mode to use for calculating the recall score.
+- **document_comparison_field** (str) – The Document field to use for comparison. Possible options:
+- `"content"`: uses `doc.content`
+- `"id"`: uses `doc.id`
+- A `meta.` prefix followed by a key name: uses `doc.meta["list\[list\[Document\]\]) – A list of expected documents for each question.
+- **retrieved_documents** (list\[list\[Document\]\]) – A list of retrieved documents for each question.
+ A dictionary with the following outputs:
+ - `score` - The average of calculated scores.
+ - `individual_scores` - A list of numbers from 0.0 to 1.0 that represents the proportion of matching
+ documents retrieved. If the mode is `single_hit`, the individual scores are 0 or 1.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+## faithfulness
+
+### FaithfulnessEvaluator
+
+Bases: LLMEvaluator
+
+Evaluator that checks if a generated answer can be inferred from the provided contexts.
+
+An LLM separates the answer into multiple statements and checks whether the statement can be inferred from the
+context or not. The final score for the full answer is a number from 0.0 to 1.0. It represents the proportion of
+statements that can be inferred from the provided contexts.
+
+Usage example:
+
+```python
+from haystack.components.evaluators import FaithfulnessEvaluator
+
+questions = ["Who created the Python language?"]
+contexts = [
+ [(
+ "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming "
+ "language. Its design philosophy emphasizes code readability, and its language constructs aim to help "
+ "programmers write clear, logical code for both small and large-scale software projects."
+ )],
+]
+predicted_answers = [
+ "Python is a high-level general-purpose programming language that was created by George Lucas."
+]
+evaluator = FaithfulnessEvaluator()
+result = evaluator.run(questions=questions, contexts=contexts, predicted_answers=predicted_answers)
+
+print(result["individual_scores"])
+# [0.5]
+print(result["score"])
+# 0.5
+print(result["results"])
+# [{'statements': ['Python is a high-level general-purpose programming language.',
+# 'Python was created by George Lucas.'], 'statement_scores': [1, 0], 'score': 0.5}]
+```
+
+#### __init__
+
+```python
+__init__(
+ examples: list[dict[str, Any]] | None = None,
+ progress_bar: bool = True,
+ raise_on_failure: bool = True,
+ chat_generator: ChatGenerator | None = None,
+) -> None
+```
+
+Creates an instance of FaithfulnessEvaluator.
+
+If no LLM is specified using the `chat_generator` parameter, the component will use OpenAI in JSON mode.
+
+**Parameters:**
+
+- **examples** (list\[dict\[str, Any\]\] | None) – Optional few-shot examples conforming to the expected input and output format of FaithfulnessEvaluator.
+ Default examples will be used if none are provided.
+ Each example must be a dictionary with keys "inputs" and "outputs".
+ "inputs" must be a dictionary with keys "questions", "contexts", and "predicted_answers".
+ "outputs" must be a dictionary with "statements" and "statement_scores".
+ Expected format:
+
+```python
+[{
+ "inputs": {
+ "questions": "What is the capital of Italy?", "contexts": ["Rome is the capital of Italy."],
+ "predicted_answers": "Rome is the capital of Italy with more than 4 million inhabitants.",
+ },
+ "outputs": {
+ "statements": ["Rome is the capital of Italy.", "Rome has more than 4 million inhabitants."],
+ "statement_scores": [1, 0],
+ },
+}]
+```
+
+- **progress_bar** (bool) – Whether to show a progress bar during the evaluation.
+- **raise_on_failure** (bool) – Whether to raise an exception if the API call fails.
+- **chat_generator** (ChatGenerator | None) – a ChatGenerator instance which represents the LLM.
+ In order for the component to work, the LLM should be configured to return a JSON object. For example,
+ when using the OpenAIChatGenerator, you should pass `{"response_format": {"type": "json_object"}}` in the
+ `generation_kwargs`.
+
+#### run
+
+```python
+run(**inputs: Any) -> dict[str, Any]
+```
+
+Run the LLM evaluator.
+
+**Parameters:**
+
+- **questions** – A list of questions.
+- **contexts** – A nested list of contexts that correspond to the questions.
+- **predicted_answers** – A list of predicted answers.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following outputs:
+ - `score`: Mean faithfulness score over all the provided input answers.
+ - `individual_scores`: A list of faithfulness scores for each input answer.
+ - `results`: A list of dictionaries with `statements` and `statement_scores` for each input answer.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FaithfulnessEvaluator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- FaithfulnessEvaluator – The deserialized component instance.
+
+## llm_evaluator
+
+### LLMEvaluator
+
+Uses an LLM to evaluate inputs based on a prompt containing instructions and examples.
+
+The default API requires an OpenAI API key to be provided as an environment variable "OPENAI_API_KEY".
+The inputs are lists that are user-defined depending on the desired metric.
+The output is a dictionary with a key `results` containing a list of evaluation results.
+Each result is a dictionary with user-defined keys and values of either 0 for FALSE or 1 for TRUE respectively.
+
+Usage example:
+
+```python
+from haystack.components.evaluators import LLMEvaluator
+evaluator = LLMEvaluator(
+ instructions="Is this answer problematic for children?",
+ inputs=[("predicted_answers", list[str])],
+ outputs=["score"],
+ examples=[
+ {"inputs": {"predicted_answers": "Damn, this is straight outta hell!!!"}, "outputs": {"score": 1}},
+ {"inputs": {"predicted_answers": "Football is the most popular sport."}, "outputs": {"score": 0}},
+ ],
+)
+predicted_answers = [
+ "Football is the most popular sport with around 4 billion followers worldwide",
+ "Python language was created by Guido van Rossum.",
+]
+results = evaluator.run(predicted_answers=predicted_answers)
+print(results)
+# {'results': [{'score': 0}, {'score': 0}]}
+```
+
+#### __init__
+
+```python
+__init__(
+ instructions: str,
+ inputs: list[tuple[str, type[list]]],
+ outputs: list[str],
+ examples: list[dict[str, Any]],
+ progress_bar: bool = True,
+ *,
+ raise_on_failure: bool = True,
+ chat_generator: ChatGenerator | None = None
+) -> None
+```
+
+Creates an instance of LLMEvaluator.
+
+If no LLM is specified using the `chat_generator` parameter, the component will use OpenAI in JSON mode.
+
+**Parameters:**
+
+- **instructions** (str) – The prompt instructions to use for evaluation.
+ Should be a question about the inputs that can be answered with yes or no.
+- **inputs** (list\[tuple\[str, type\[list\]\]\]) – The inputs that the component expects as incoming connections and that it evaluates.
+ Each input is a tuple of an input name and input type. Input types must be lists.
+- **outputs** (list\[str\]) – Output names of the evaluation results. They correspond to keys in the output dictionary.
+- **examples** (list\[dict\[str, Any\]\]) – Few-shot examples conforming to the expected input and output format as defined in the `inputs` and
+ `outputs` parameters.
+ Each example is a dictionary with keys "inputs" and "outputs"
+ They contain the input and output as dictionaries respectively.
+- **raise_on_failure** (bool) – If True, the component will raise an exception on an unsuccessful API call.
+- **progress_bar** (bool) – Whether to show a progress bar during the evaluation.
+- **chat_generator** (ChatGenerator | None) – a ChatGenerator instance which represents the LLM.
+ In order for the component to work, the LLM should be configured to return a JSON object. For example,
+ when using the OpenAIChatGenerator, you should pass `{"response_format": {"type": "json_object"}}` in the
+ `generation_kwargs`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the component by warming up the underlying chat generator.
+
+#### validate_init_parameters
+
+```python
+validate_init_parameters(
+ inputs: list[tuple[str, type[list]]],
+ outputs: list[str],
+ examples: list[dict[str, Any]],
+) -> None
+```
+
+Validate the init parameters.
+
+**Parameters:**
+
+- **inputs** (list\[tuple\[str, type\[list\]\]\]) – The inputs to validate.
+- **outputs** (list\[str\]) – The outputs to validate.
+- **examples** (list\[dict\[str, Any\]\]) – The examples to validate.
+
+**Raises:**
+
+- ValueError – If the inputs are not a list of tuples with a string and a type of list.
+ If the outputs are not a list of strings.
+ If the examples are not a list of dictionaries.
+ If any example does not have keys "inputs" and "outputs" with values that are dictionaries with string keys.
+
+#### run
+
+```python
+run(**inputs: Any) -> dict[str, Any]
+```
+
+Run the LLM evaluator.
+
+**Parameters:**
+
+- **inputs** (Any) – The input values to evaluate. The keys are the input names and the values are lists of input values.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with a `results` entry that contains a list of results.
+ Each result is a dictionary containing the keys as defined in the `outputs` parameter of the LLMEvaluator
+ and the evaluation results as the values. If an exception occurs for a particular input value, the result
+ will be `None` for that entry.
+ If the API is "openai" and the response contains a "meta" key, the metadata from OpenAI will be included
+ in the output dictionary, under the key "meta".
+
+**Raises:**
+
+- ValueError – Only in the case that `raise_on_failure` is set to True and the received inputs are not lists or have
+ different lengths, or if the output is not a valid JSON or doesn't contain the expected keys.
+
+#### prepare_template
+
+```python
+prepare_template() -> str
+```
+
+Prepare the prompt template.
+
+Combine instructions, inputs, outputs, and examples into one prompt template with the following format:
+Instructions:
+`- `
+Consider the instructions and the examples below to determine those values.
+
+Examples:
+`
str – The prompt template.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LLMEvaluator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- LLMEvaluator – The deserialized component instance.
+
+#### validate_input_parameters
+
+```python
+validate_input_parameters(
+ expected: dict[str, Any], received: dict[str, Any]
+) -> None
+```
+
+Validate the input parameters.
+
+**Parameters:**
+
+- **expected** (dict\[str, Any\]) – The expected input parameters.
+- **received** (dict\[str, Any\]) – The received input parameters.
+
+**Raises:**
+
+- ValueError – If not all expected inputs are present in the received inputs
+ If the received inputs are not lists or have different lengths
+
+## sas_evaluator
+
+### SASEvaluator
+
+SASEvaluator computes the Semantic Answer Similarity (SAS) between a list of predictions and a one of ground truths.
+
+It's usually used in Retrieval Augmented Generation (RAG) pipelines to evaluate the quality of the generated
+answers. The SAS is computed using a pre-trained model from the Hugging Face model hub. The model can be either a
+Bi-Encoder or a Cross-Encoder. The choice of the model is based on the `model` parameter.
+
+Usage example:
+
+```python
+from haystack.components.evaluators.sas_evaluator import SASEvaluator
+
+evaluator = SASEvaluator(model="cross-encoder/ms-marco-MiniLM-L-6-v2")
+ground_truths = [
+ "A construction budget of US $2.3 billion",
+ "The Eiffel Tower, completed in 1889, symbolizes Paris's cultural magnificence.",
+ "The Meiji Restoration in 1868 transformed Japan into a modernized world power.",
+]
+predictions = [
+ "A construction budget of US $2.3 billion",
+ "The Eiffel Tower, completed in 1889, symbolizes Paris's cultural magnificence.",
+ "The Meiji Restoration in 1868 transformed Japan into a modernized world power.",
+]
+result = evaluator.run(
+ ground_truth_answers=ground_truths, predicted_answers=predictions
+)
+
+print(result["score"])
+# 0.9999673763910929
+
+print(result["individual_scores"])
+# [0.9999765157699585, 0.999968409538269, 0.9999572038650513]
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "sentence-transformers/paraphrase-multilingual-mpnet-base-v2",
+ batch_size: int = 32,
+ device: ComponentDevice | None = None,
+ token: Secret = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+) -> None
+```
+
+Creates a new instance of SASEvaluator.
+
+**Parameters:**
+
+- **model** (str) – SentenceTransformers semantic textual similarity model, should be path or string pointing to a downloadable
+ model.
+- **batch_size** (int) – Number of prediction-label pairs to encode at once.
+- **device** (ComponentDevice | None) – The device on which the model is loaded. If `None`, the default device is automatically selected.
+- **token** (Secret) – The Hugging Face token for HTTP bearer authorization.
+ You can find your HF token in your [account settings](https://huggingface.co/settings/tokens)
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SASEvaluator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- SASEvaluator – The deserialized component instance.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(
+ ground_truth_answers: list[str], predicted_answers: list[str]
+) -> dict[str, float | list[float]]
+```
+
+SASEvaluator component run method.
+
+Run the SASEvaluator to compute the Semantic Answer Similarity (SAS) between a list of predicted answers
+and a list of ground truth answers. Both must be list of strings of same length.
+
+**Parameters:**
+
+- **ground_truth_answers** (list\[str\]) – A list of expected answers for each question.
+- **predicted_answers** (list\[str\]) – A list of generated answers for each question.
+
+**Returns:**
+
+- dict\[str, float | list\[float\]\] – A dictionary with the following outputs:
+ - `score`: Mean SAS score over all the predictions/ground-truth pairs.
+ - `individual_scores`: A list of similarity scores for each prediction/ground-truth pair.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/extractors_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/extractors_api.md
new file mode 100644
index 0000000000..a18fbc5b17
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/extractors_api.md
@@ -0,0 +1,691 @@
+---
+title: "Extractors"
+id: extractors-api
+description: "Components to extract specific elements from textual data."
+slug: "/extractors-api"
+---
+
+
+## image/llm_document_content_extractor
+
+### LLMDocumentContentExtractor
+
+Extracts textual content and optionally metadata from image-based documents using a vision-enabled LLM.
+
+One prompt and one LLM call per document. The component converts each document to an image via
+DocumentToImageContent and sends it to the ChatGenerator. The prompt must not contain Jinja variables.
+
+Response handling:
+
+- If the LLM returns a **plain string** (non-JSON or not a JSON object), it is written to the document's content.
+- If the LLM returns a **JSON object with only the key** `document_content`, that value is written to content.
+- If the LLM returns a **JSON object with multiple keys**, the value of `document_content` (if present) is
+ written to content and all other keys are merged into the document's metadata.
+
+The ChatGenerator can be configured to return JSON (e.g. `response_format={"type": "json_object"}`
+in `generation_kwargs`).
+
+Documents that fail extraction are returned in `failed_documents` with `content_extraction_error` in metadata.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+
+prompt = """
+Extract the content from the provided image.
+Format everything as markdown. Return only the extracted content as a JSON object with the key 'document_content'.
+No markdown, no code fence, only raw JSON.
+
+Extract metadata about the image like source of the image, date of creation, etc. if you can.
+Return this metadata as additional key-value pairs in the same JSON object.
+"""
+
+chat_generator = OpenAIChatGenerator(
+ generation_kwargs={
+ "response_format": {
+ "type": "json_schema",
+ "json_schema": {
+ "name": "entity_extraction",
+ "schema": {
+ "type": "object",
+ "properties": {
+ "document_content": {"type": "string"},
+ "author": {"type": "string"},
+ "date": {"type": "string"},
+ "document_type": {"type": "string"},
+ "title": {"type": "string"},
+ },
+ "additionalProperties": False,
+ },
+ },
+ }
+ }
+ )
+
+extractor = LLMDocumentContentExtractor(
+ chat_generator=chat_generator,
+ file_path_meta_field="file_path",
+ raise_on_failure=False
+)
+
+documents = [
+ Document(content="", meta={"file_path": "test/test_files/images/image_metadata.png"}),
+ Document(content="", meta={"file_path": "test/test_files/images/apple.jpg", "page_number": 1})
+]
+result = extractor.run(documents=documents)
+updated_documents = result["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ chat_generator: ChatGenerator,
+ prompt: str = DEFAULT_PROMPT_TEMPLATE,
+ file_path_meta_field: str = "file_path",
+ root_path: str | None = None,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None,
+ raise_on_failure: bool = False,
+ max_workers: int = 3
+) -> None
+```
+
+Initialize the LLMDocumentContentExtractor component.
+
+**Parameters:**
+
+- **chat_generator** (ChatGenerator) – A ChatGenerator that supports vision input. Optionally configured for JSON
+ (e.g. `response_format={"type": "json_object"}` in `generation_kwargs`).
+- **prompt** (str) – Prompt for extraction. Must not contain Jinja variables.
+- **file_path_meta_field** (str) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (str | None) – The root directory path where document files are located. If provided, file paths in
+ document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low".
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within (width, height) while keeping aspect ratio.
+- **raise_on_failure** (bool) – If True, exceptions from the LLM are raised. If False, failed documents are returned.
+- **max_workers** (int) – Maximum number of threads for parallel LLM calls.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the ChatGenerator if it has a warm_up method.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LLMDocumentContentExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary with serialized data.
+
+**Returns:**
+
+- LLMDocumentContentExtractor – An instance of the component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Run extraction on image-based documents. One LLM call per document.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of image-based documents to process. Each must have a valid file path in its metadata.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with "documents" (successfully processed) and "failed_documents" (with failure metadata).
+
+## llm_metadata_extractor
+
+### LLMMetadataExtractor
+
+Extracts metadata from documents using a Large Language Model (LLM).
+
+The metadata is extracted by providing a prompt to an LLM that generates the metadata.
+
+This component expects as input a list of documents and a prompt. The prompt should have a variable called
+`document` that will point to a single document in the list of documents. So to access the content of the document,
+you can use `{{ document.content }}` in the prompt.
+
+The component will run the LLM on each document in the list and extract metadata from the document. The metadata
+will be added to the document's metadata field. If the LLM fails to extract metadata from a document, the document
+will be added to the `failed_documents` list. The failed documents will have the keys `metadata_extraction_error` and
+`metadata_extraction_response` in their metadata. These documents can be re-run with another extractor to
+extract metadata by using the `metadata_extraction_response` and `metadata_extraction_error` in the prompt.
+
+```python
+from haystack import Document
+from haystack.components.extractors.llm_metadata_extractor import LLMMetadataExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+NER_PROMPT = '''
+-Goal-
+Given text and a list of entity types, identify all entities of those types from the text.
+
+-Steps-
+1. Identify all entities. For each identified entity, extract the following information:
+- entity: Name of the entity
+- entity_type: One of the following types: [organization, product, service, industry]
+Format each entity as a JSON like: {"entity": str) – The prompt to be used for the LLM.
+- **chat_generator** (ChatGenerator) – a ChatGenerator instance which represents the LLM. In order for the component to work,
+ the LLM should be configured to return a JSON object. For example, when using the OpenAIChatGenerator, you
+ should pass `{"response_format": {"type": "json_object"}}` in the `generation_kwargs`.
+- **expected_keys** (list\[str\] | None) – The keys expected in the JSON output from the LLM.
+- **page_range** (list\[str | int\] | None) – A range of pages to extract metadata from. For example, page_range=['1', '3'] will extract
+ metadata from the first and third pages of each document. It also accepts printable range strings, e.g.:
+ ['1-3', '5', '8', '10-12'] will extract metadata from pages 1, 2, 3, 5, 8, 10,11, 12.
+ If None, metadata will be extracted from the entire document for each document in the documents list.
+ This parameter is optional and can be overridden in the `run` method.
+- **raise_on_failure** (bool) – Whether to raise an error on failure during the execution of the Generator or
+ validation of the JSON output.
+- **max_workers** (int) – The maximum number of workers to use in the thread pool executor.
+ This parameter is used limit the maximum number of requests that should be allowed to run concurrently
+ when using the `run_async` method.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the LLM provider component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LLMMetadataExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary with serialized data.
+
+**Returns:**
+
+- LLMMetadataExtractor – An instance of the component.
+
+#### run
+
+```python
+run(
+ documents: list[Document], page_range: list[str | int] | None = None
+) -> dict[str, Any]
+```
+
+Extract metadata from documents using a Large Language Model.
+
+If `page_range` is provided, the metadata will be extracted from the specified range of pages. This component
+will split the documents into pages and extract metadata from the specified range of pages. The metadata will be
+extracted from the entire document if `page_range` is not provided.
+
+The original documents will be returned updated with the extracted metadata.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of documents to extract metadata from.
+- **page_range** (list\[str | int\] | None) – A range of pages to extract metadata from. For example, page_range=['1', '3'] will extract
+ metadata from the first and third pages of each document. It also accepts printable range
+ strings, e.g.: ['1-3', '5', '8', '10-12'] will extract metadata from pages 1, 2, 3, 5, 8, 10,
+ 11, 12.
+ If None, metadata will be extracted from the entire document for each document in the
+ documents list.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the keys:
+- "documents": A list of documents that were successfully updated with the extracted metadata.
+- "failed_documents": A list of documents that failed to extract metadata. These documents will have
+ "metadata_extraction_error" and "metadata_extraction_response" in their metadata. These documents can be
+ re-run with the extractor to extract metadata.
+
+#### run_async
+
+```python
+run_async(
+ documents: list[Document], page_range: list[str | int] | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously extract metadata from documents using a Large Language Model.
+
+If `page_range` is provided, the metadata will be extracted from the specified range of pages. This component
+will split the documents into pages and extract metadata from the specified range of pages. The metadata will be
+extracted from the entire document if `page_range` is not provided.
+
+The original documents will be returned updated with the extracted metadata.
+
+This is the asynchronous version of the `run` method. It has the same parameters
+and return values but can be used with `await` in an async code.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of documents to extract metadata from.
+- **page_range** (list\[str | int\] | None) – A range of pages to extract metadata from. For example, page_range=['1', '3'] will extract
+ metadata from the first and third pages of each document. It also accepts printable range
+ strings, e.g.: ['1-3', '5', '8', '10-12'] will extract metadata from pages 1, 2, 3, 5, 8, 10,
+ 11, 12.
+ If None, metadata will be extracted from the entire document for each document in the
+ documents list.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the keys:
+- "documents": A list of documents that were successfully updated with the extracted metadata.
+- "failed_documents": A list of documents that failed to extract metadata. These documents will have
+ "metadata_extraction_error" and "metadata_extraction_response" in their metadata. These documents can be
+ re-run with the extractor to extract metadata.
+
+## named_entity_extractor
+
+### NamedEntityExtractorBackend
+
+Bases: Enum
+
+NLP backend to use for Named Entity Recognition.
+
+#### from_str
+
+```python
+from_str(string: str) -> NamedEntityExtractorBackend
+```
+
+Convert a string to a NamedEntityExtractorBackend enum.
+
+### NamedEntityAnnotation
+
+Describes a single NER annotation.
+
+**Parameters:**
+
+- **entity** (str) – Entity label.
+- **start** (int) – Start index of the entity in the document.
+- **end** (int) – End index of the entity in the document.
+- **score** (float | None) – Score calculated by the model.
+
+### NamedEntityExtractor
+
+Annotates named entities in a collection of documents.
+
+The component supports two backends: Hugging Face and spaCy. The
+former can be used with any sequence classification model from the
+[Hugging Face model hub](https://huggingface.co/models), while the
+latter can be used with any [spaCy model](https://spacy.io/models)
+that contains an NER component. Annotations are stored as metadata
+in the documents.
+
+Usage example:
+
+
+
+```python
+from haystack import Document
+from haystack.components.extractors.named_entity_extractor import NamedEntityExtractor
+
+documents = [
+ Document(content="I'm Merlin, the happy pig!"),
+ Document(content="My name is Clara and I live in Berkeley, California."),
+]
+extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
+results = extractor.run(documents=documents)["documents"]
+annotations = [NamedEntityExtractor.get_stored_annotations(doc) for doc in results]
+print(annotations)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ backend: str | NamedEntityExtractorBackend,
+ model: str,
+ pipeline_kwargs: dict[str, Any] | None = None,
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ )
+) -> None
+```
+
+Create a Named Entity extractor component.
+
+**Parameters:**
+
+- **backend** (str | NamedEntityExtractorBackend) – Backend to use for NER.
+- **model** (str) – Name of the model or a path to the model on
+ the local disk. Dependent on the backend.
+- **pipeline_kwargs** (dict\[str, Any\] | None) – Keyword arguments passed to the pipeline. The
+ pipeline can override these arguments. Dependent on the backend.
+- **device** (ComponentDevice | None) – The device on which the model is loaded. If `None`,
+ the default device is automatically selected. If a
+ device/device map is specified in `pipeline_kwargs`,
+ it overrides this parameter (only applicable to the
+ HuggingFace backend).
+- **token** (Secret | None) – The API token to download private models from Hugging Face.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the component.
+
+**Raises:**
+
+- ComponentError – If the backend fails to initialize successfully.
+
+#### run
+
+```python
+run(documents: list[Document], batch_size: int = 1) -> dict[str, Any]
+```
+
+Annotate named entities in each document and store the annotations in the document's metadata.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to process.
+- **batch_size** (int) – Batch size used for processing the documents.
+
+**Returns:**
+
+- dict\[str, Any\] – Processed documents.
+
+**Raises:**
+
+- ComponentError – If the backend fails to process a document.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NamedEntityExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- NamedEntityExtractor – Deserialized component.
+
+#### initialized
+
+```python
+initialized: bool
+```
+
+Returns if the extractor is ready to annotate text.
+
+#### get_stored_annotations
+
+```python
+get_stored_annotations(
+ document: Document,
+) -> list[NamedEntityAnnotation] | None
+```
+
+Returns the document's named entity annotations stored in its metadata, if any.
+
+**Parameters:**
+
+- **document** (Document) – Document whose annotations are to be fetched.
+
+**Returns:**
+
+- list\[NamedEntityAnnotation\] | None – The stored annotations.
+
+## regex_text_extractor
+
+### RegexTextExtractor
+
+Extracts text from chat message or string input using a regex pattern.
+
+RegexTextExtractor parses input text or ChatMessages using a provided regular expression pattern.
+It can be configured to search through all messages or only the last message in a list of ChatMessages.
+
+### Usage example
+
+```python
+from haystack.components.extractors import RegexTextExtractor
+from haystack.dataclasses import ChatMessage
+
+# Using with a string
+parser = RegexTextExtractor(regex_pattern='str) – The regular expression pattern used to extract text.
+ The pattern should include a capture group to extract the desired text.
+ Example: `'dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> RegexTextExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- RegexTextExtractor – The deserialized component.
+
+#### run
+
+```python
+run(text_or_messages: str | list[ChatMessage]) -> dict[str, str]
+```
+
+Extracts text from input using the configured regex pattern.
+
+**Parameters:**
+
+- **text_or_messages** (str | list\[ChatMessage\]) – Either a string or a list of ChatMessage objects to search through.
+
+**Returns:**
+
+- dict\[str, str\] – - `{"captured_text": "matched text"}` if a match is found
+- `{"captured_text": ""}` if no match is found
+
+**Raises:**
+
+- TypeError – if receiving a list the last element is not a ChatMessage instance.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/fetchers_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/fetchers_api.md
new file mode 100644
index 0000000000..7bdc315442
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/fetchers_api.md
@@ -0,0 +1,121 @@
+---
+title: "Fetchers"
+id: fetchers-api
+description: "Fetches content from a list of URLs and returns a list of extracted content streams."
+slug: "/fetchers-api"
+---
+
+
+## link_content
+
+### LinkContentFetcher
+
+Fetches and extracts content from URLs.
+
+It supports various content types, retries on failures, and automatic user-agent rotation for failed web
+requests. Use it as the data-fetching step in your pipelines.
+
+You may need to convert LinkContentFetcher's output into a list of documents. Use HTMLToDocument
+converter to do this.
+
+### Usage example
+
+```python
+from haystack.components.fetchers.link_content import LinkContentFetcher
+
+fetcher = LinkContentFetcher()
+streams = fetcher.run(urls=["https://www.google.com"])["streams"]
+
+assert len(streams) == 1
+assert streams[0].meta == {'content_type': 'text/html', 'url': 'https://www.google.com'}
+assert streams[0].data
+```
+
+For async usage:
+
+```python
+import asyncio
+from haystack.components.fetchers import LinkContentFetcher
+
+async def fetch_async():
+ fetcher = LinkContentFetcher()
+ result = await fetcher.run_async(urls=["https://www.google.com"])
+ return result["streams"]
+
+streams = asyncio.run(fetch_async())
+```
+
+#### __init__
+
+```python
+__init__(
+ raise_on_failure: bool = True,
+ user_agents: list[str] | None = None,
+ retry_attempts: int = 2,
+ timeout: int = 3,
+ http2: bool = False,
+ client_kwargs: dict | None = None,
+ request_headers: dict[str, str] | None = None,
+) -> None
+```
+
+Initializes the component.
+
+**Parameters:**
+
+- **raise_on_failure** (bool) – If `True`, raises an exception if it fails to fetch a single URL.
+ For multiple URLs, it logs errors and returns the content it successfully fetched.
+- **user_agents** (list\[str\] | None) – [User agents](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)
+ for fetching content. If `None`, a default user agent is used.
+- **retry_attempts** (int) – The number of times to retry to fetch the URL's content.
+- **timeout** (int) – Timeout in seconds for the request.
+- **http2** (bool) – Whether to enable HTTP/2 support for requests. Defaults to False.
+ Requires the 'h2' package to be installed (via `pip install httpx[http2]`).
+- **client_kwargs** (dict | None) – Additional keyword arguments to pass to the httpx client.
+ If `None`, default values are used.
+
+#### run
+
+```python
+run(urls: list[str]) -> dict[str, Any]
+```
+
+Fetches content from a list of URLs and returns a list of extracted content streams.
+
+Each content stream is a `ByteStream` object containing the extracted content as binary data.
+Each ByteStream object in the returned list corresponds to the contents of a single URL.
+The content type of each stream is stored in the metadata of the ByteStream object under
+the key "content_type". The URL of the fetched content is stored under the key "url".
+
+**Parameters:**
+
+- **urls** (list\[str\]) – A list of URLs to fetch content from.
+
+**Returns:**
+
+- dict\[str, Any\] – `ByteStream` objects representing the extracted content.
+
+**Raises:**
+
+- Exception – If the provided list of URLs contains only a single URL, and `raise_on_failure` is set to
+ `True`, an exception will be raised in case of an error during content retrieval.
+ In all other scenarios, any retrieval errors are logged, and a list of successfully retrieved `ByteStream`
+ objects is returned.
+
+#### run_async
+
+```python
+run_async(urls: list[str]) -> dict[str, Any]
+```
+
+Asynchronously fetches content from a list of URLs and returns a list of extracted content streams.
+
+This is the asynchronous version of the `run` method with the same parameters and return values.
+
+**Parameters:**
+
+- **urls** (list\[str\]) – A list of URLs to fetch content from.
+
+**Returns:**
+
+- dict\[str, Any\] – `ByteStream` objects representing the extracted content.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/generators_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/generators_api.md
new file mode 100644
index 0000000000..651a692d4d
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/generators_api.md
@@ -0,0 +1,2439 @@
+---
+title: "Generators"
+id: generators-api
+description: "Enables text generation using LLMs."
+slug: "/generators-api"
+---
+
+
+## azure
+
+### AzureOpenAIGenerator
+
+Bases: OpenAIGenerator
+
+Generates text using OpenAI's large language models (LLMs).
+
+It works with the gpt-4 - type models and supports streaming responses
+from OpenAI API.
+
+You can customize how the text is generated by passing parameters to the
+OpenAI API. Use the `**generation_kwargs` argument when you initialize
+the component or when you run it. Any parameter that works with
+`openai.ChatCompletion.create` will work here too.
+
+For details on OpenAI API parameters, see
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
+
+### Usage example
+
+
+
+```python
+from haystack.components.generators import AzureOpenAIGenerator
+from haystack.utils import Secret
+client = AzureOpenAIGenerator(
+ azure_endpoint="str | None) – The endpoint of the deployed model, for example `https://example-resource.azure.openai.com/`.
+- **api_version** (str | None) – The version of the API to use. Defaults to 2024-12-01-preview.
+- **azure_deployment** (str | None) – The deployment of the model, usually the model name.
+- **api_key** (Secret | None) – The API key to use for authentication.
+- **azure_ad_token** (Secret | None) – [Azure Active Directory token](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id).
+- **organization** (str | None) – Your organization ID, defaults to `None`. For help, see
+ [Setting up your organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization).
+- **streaming_callback** (StreamingCallbackT | None) – A callback function called when a new token is received from the stream.
+ It accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk)
+ as an argument.
+- **system_prompt** (str | None) – The system prompt to use for text generation. If not provided, the Generator
+ omits the system prompt and uses the default system prompt.
+- **timeout** (float | None) – Timeout for AzureOpenAI client. If not set, it is inferred from the
+ `OPENAI_TIMEOUT` environment variable or set to 30.
+- **max_retries** (int | None) – Maximum retries to establish contact with AzureOpenAI if it returns an internal error.
+ If not set, it is inferred from the `OPENAI_MAX_RETRIES` environment variable or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model, sent directly to
+ the OpenAI endpoint. See [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat) for
+ more details.
+ Some of the supported parameters:
+- `max_completion_tokens`: An upper bound for the number of tokens that can be generated for a completion,
+ including visible output tokens and reasoning tokens.
+- `temperature`: The sampling temperature to use. Higher values mean the model takes more risks.
+ Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+ considers the results of the tokens with top_p probability mass. For example, 0.1 means only the tokens
+ comprising the top 10% probability mass are considered.
+- `n`: The number of completions to generate for each prompt. For example, with 3 prompts and n=2,
+ the LLM will generate two completions per prompt, resulting in 6 completions total.
+- `stop`: One or more sequences after which the LLM should stop generating tokens.
+- `presence_penalty`: The penalty applied if a token is already present.
+ Higher values make the model less likely to repeat the token.
+- `frequency_penalty`: Penalty applied if a token has already been generated.
+ Higher values make the model less likely to repeat the token.
+- `logit_bias`: Adds a logit bias to specific tokens. The keys of the dictionary are tokens, and the
+ values are the bias to add to that token.
+- **default_headers** (dict\[str, str\] | None) – Default headers to use for the AzureOpenAI client.
+- **azure_ad_token_provider** (AzureADTokenProvider | None) – A function that returns an Azure Active Directory token, will be invoked on
+ every request.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureOpenAIGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- AzureOpenAIGenerator – The deserialized component instance.
+
+## chat/azure
+
+### AzureOpenAIChatGenerator
+
+Bases: OpenAIChatGenerator
+
+Generates text using OpenAI's models on Azure.
+
+It works with the gpt-4 - type models and supports streaming responses
+from OpenAI API. It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage)
+format in input and output.
+
+You can customize how the text is generated by passing parameters to the
+OpenAI API. Use the `**generation_kwargs` argument when you initialize
+the component or when you run it. Any parameter that works with
+`openai.ChatCompletion.create` will work here too.
+
+For details on OpenAI API parameters, see
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
+
+### Usage example
+
+
+
+```python
+from haystack.components.generators.chat import AzureOpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = AzureOpenAIChatGenerator(
+ azure_endpoint="str | None) – The endpoint of the deployed model, for example `"https://example-resource.azure.openai.com/"`.
+- **api_version** (str | None) – The version of the API to use. Defaults to 2024-12-01-preview.
+- **azure_deployment** (str | None) – The deployment of the model, usually the model name.
+- **api_key** (Secret | None) – The API key to use for authentication.
+- **azure_ad_token** (Secret | None) – [Azure Active Directory token](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id).
+- **organization** (str | None) – Your organization ID, defaults to `None`. For help, see
+ [Setting up your organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization).
+- **streaming_callback** (StreamingCallbackT | None) – A callback function called when a new token is received from the stream.
+ It accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk)
+ as an argument.
+- **timeout** (float | None) – Timeout for OpenAI client calls. If not set, it defaults to either the
+ `OPENAI_TIMEOUT` environment variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact OpenAI after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are sent directly to
+ the OpenAI endpoint. For details, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
+ Some of the supported parameters:
+- `max_completion_tokens`: An upper bound for the number of tokens that can be generated for a completion,
+ including visible output tokens and reasoning tokens.
+- `temperature`: The sampling temperature to use. Higher values mean the model takes more risks.
+ Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: Nucleus sampling is an alternative to sampling with temperature, where the model considers
+ tokens with a top_p probability mass. For example, 0.1 means only the tokens comprising
+ the top 10% probability mass are considered.
+- `n`: The number of completions to generate for each prompt. For example, with 3 prompts and n=2,
+ the LLM will generate two completions per prompt, resulting in 6 completions total.
+- `stop`: One or more sequences after which the LLM should stop generating tokens.
+- `presence_penalty`: The penalty applied if a token is already present.
+ Higher values make the model less likely to repeat the token.
+- `frequency_penalty`: Penalty applied if a token has already been generated.
+ Higher values make the model less likely to repeat the token.
+- `logit_bias`: Adds a logit bias to specific tokens. The keys of the dictionary are tokens, and the
+ values are the bias to add to that token.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+ If provided, the output will always be validated against this
+ format (unless the model returns a tool call).
+ For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+ Notes:
+ - This parameter accepts Pydantic models and JSON schemas for latest models starting from GPT-4o.
+ Older models only support basic version of structured outputs through `{"type": "json_object"}`.
+ For detailed information on JSON mode, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs#json-mode).
+ - For structured outputs with streaming,
+ the `response_format` must be a JSON schema and not a Pydantic model.
+- **default_headers** (dict\[str, str\] | None) – Default headers to use for the AzureOpenAI client.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+- **tools_strict** (bool) – Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly
+ the schema provided in the `parameters` field of the tool definition, but this may increase latency.
+- **azure_ad_token_provider** (AzureADTokenProvider | AsyncAzureADTokenProvider | None) – A function that returns an Azure Active Directory token, will be invoked on
+ every request.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Azure OpenAI chat generator.
+
+This will warm up the tools registered in the chat generator.
+This method is idempotent and will only warm up the tools once.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureOpenAIChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- AzureOpenAIChatGenerator – The deserialized component instance.
+
+## chat/azure_responses
+
+### AzureOpenAIResponsesChatGenerator
+
+Bases: OpenAIResponsesChatGenerator
+
+Completes chats using OpenAI's Responses API on Azure.
+
+It works with the gpt-5 and o-series models and supports streaming responses
+from OpenAI API. It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage)
+format in input and output.
+
+You can customize how the text is generated by passing parameters to the
+OpenAI API. Use the `**generation_kwargs` argument when you initialize
+the component or when you run it. Any parameter that works with
+`openai.Responses.create` will work here too.
+
+For details on OpenAI API parameters, see
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/responses).
+
+### Usage example
+
+
+
+```python
+from haystack.components.generators.chat import AzureOpenAIResponsesChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = AzureOpenAIResponsesChatGenerator(
+ azure_endpoint="https://example-resource.azure.openai.com/",
+ generation_kwargs={"reasoning": {"effort": "low", "summary": "auto"}}
+)
+response = client.run(messages)
+print(response)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "gpt-5.4-pro",
+ "gpt-5.4",
+ "gpt-5.3-chat",
+ "gpt-5.3-codex",
+ "gpt-5.2-codex",
+ "gpt-5.2",
+ "gpt-5.2-chat",
+ "gpt-5.1-codex-max",
+ "gpt-5.1",
+ "gpt-5.1-chat",
+ "gpt-5.1-codex",
+ "gpt-5.1-codex-mini",
+ "gpt-5-pro",
+ "gpt-5-codex",
+ "gpt-5",
+ "gpt-5-mini",
+ "gpt-5-nano",
+ "gpt-5-chat",
+ "gpt-4o",
+ "gpt-4o-mini",
+ "computer-use-preview",
+ "gpt-4.1",
+ "gpt-4.1-nano",
+ "gpt-4.1-mini",
+ "gpt-image-1",
+ "gpt-image-1-mini",
+ "gpt-image-1.5",
+ "o1",
+ "o3-mini",
+ "o3",
+ "o4-mini",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+See https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/responses#model-support for the full list.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: (
+ Secret | Callable[[], str] | Callable[[], Awaitable[str]]
+ ) = Secret.from_env_var("AZURE_OPENAI_API_KEY", strict=False),
+ azure_endpoint: str | None = None,
+ azure_deployment: str = "gpt-5-mini",
+ streaming_callback: StreamingCallbackT | None = None,
+ organization: str | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ tools: ToolsType | None = None,
+ tools_strict: bool = False,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Initialize the AzureOpenAIResponsesChatGenerator component.
+
+**Parameters:**
+
+- **api_key** (Secret | Callable\[[], str\] | Callable\[[], Awaitable\[str\]\]) – The API key to use for authentication. Can be:
+- A `Secret` object containing the API key.
+- A `Secret` object containing the [Azure Active Directory token](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id).
+- A function that returns an Azure Active Directory token.
+- **azure_endpoint** (str | None) – The endpoint of the deployed model, for example `"https://example-resource.azure.openai.com/"`.
+- **azure_deployment** (str) – The deployment of the model, usually the model name.
+- **organization** (str | None) – Your organization ID, defaults to `None`. For help, see
+ [Setting up your organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization).
+- **streaming_callback** (StreamingCallbackT | None) – A callback function called when a new token is received from the stream.
+ It accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk)
+ as an argument.
+- **timeout** (float | None) – Timeout for OpenAI client calls. If not set, it defaults to either the
+ `OPENAI_TIMEOUT` environment variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact OpenAI after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are sent
+ directly to the OpenAI endpoint.
+ See OpenAI [documentation](https://platform.openai.com/docs/api-reference/responses) for
+ more details.
+ Some of the supported parameters:
+- `temperature`: What sampling temperature to use. Higher values like 0.8 will make the output more random,
+ while lower values like 0.2 will make it more focused and deterministic.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+ considers the results of the tokens with top_p probability mass. For example, 0.1 means only the tokens
+ comprising the top 10% probability mass are considered.
+- `previous_response_id`: The ID of the previous response.
+ Use this to create multi-turn conversations.
+- `text_format`: A Pydantic model that enforces the structure of the model's response.
+ If provided, the output will always be validated against this
+ format (unless the model returns a tool call).
+ For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+- `text`: A JSON schema that enforces the structure of the model's response.
+ If provided, the output will always be validated against this
+ format (unless the model returns a tool call).
+ Notes:
+ - Both JSON Schema and Pydantic models are supported for latest models starting from GPT-4o.
+ - If both are provided, `text_format` takes precedence and json schema passed to `text` is ignored.
+ - Currently, this component doesn't support streaming for structured outputs.
+ - Older models only support basic version of structured outputs through `{"type": "json_object"}`.
+ For detailed information on JSON mode, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs#json-mode).
+- `reasoning`: A dictionary of parameters for reasoning. For example:
+ - `summary`: The summary of the reasoning.
+ - `effort`: The level of effort to put into the reasoning. Can be `low`, `medium` or `high`.
+ - `generate_summary`: Whether to generate a summary of the reasoning.
+ Note: OpenAI does not return the reasoning tokens, but we can view summary if its enabled.
+ For details, see the [OpenAI Reasoning documentation](https://platform.openai.com/docs/guides/reasoning).
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+- **tools_strict** (bool) – Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly
+ the schema provided in the `parameters` field of the tool definition, but this may increase latency.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureOpenAIResponsesChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- AzureOpenAIResponsesChatGenerator – The deserialized component instance.
+
+## chat/fallback
+
+### FallbackChatGenerator
+
+A chat generator wrapper that tries multiple chat generators sequentially.
+
+It forwards all parameters transparently to the underlying chat generators and returns the first successful result.
+Calls chat generators sequentially until one succeeds. Falls back on any exception raised by a generator.
+If all chat generators fail, it raises a RuntimeError with details.
+
+Timeout enforcement is fully delegated to the underlying chat generators. The fallback mechanism will only
+work correctly if the underlying chat generators implement proper timeout handling and raise exceptions
+when timeouts occur. For predictable latency guarantees, ensure your chat generators:
+
+- Support a `timeout` parameter in their initialization
+- Implement timeout as total wall-clock time (shared deadline for both streaming and non-streaming)
+- Raise timeout exceptions (e.g., TimeoutError, asyncio.TimeoutError, httpx.TimeoutException) when exceeded
+
+Note: Most well-implemented chat generators (OpenAI, Anthropic, Cohere, etc.) support timeout parameters
+with consistent semantics. For HTTP-based LLM providers, a single timeout value (e.g., `timeout=30`)
+typically applies to all connection phases: connection setup, read, write, and pool. For streaming
+responses, read timeout is the maximum gap between chunks. For non-streaming, it's the time limit for
+receiving the complete response.
+
+Fail over is automatically triggered when a generator raises any exception, including:
+
+- Timeout errors (if the generator implements and raises them)
+- Rate limit errors (429)
+- Authentication errors (401)
+- Context length errors (400)
+- Server errors (500+)
+- Any other exception
+
+#### __init__
+
+```python
+__init__(chat_generators: list[ChatGenerator]) -> None
+```
+
+Creates an instance of FallbackChatGenerator.
+
+**Parameters:**
+
+- **chat_generators** (list\[ChatGenerator\]) – A non-empty list of chat generator components to try in order.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component, including nested chat generators when they support serialization.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FallbackChatGenerator
+```
+
+Rebuild the component from a serialized representation, restoring nested chat generators.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up all underlying chat generators.
+
+This method calls warm_up() on each underlying generator that supports it.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+) -> dict[str, list[ChatMessage] | dict[str, Any]]
+```
+
+Execute chat generators sequentially until one succeeds.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The conversation history as a list of ChatMessage instances.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional parameters for the chat generator (e.g., temperature, max_tokens).
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for function calling capabilities.
+- **streaming_callback** (StreamingCallbackT | None) – Optional callable for handling streaming responses.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\] | dict\[str, Any\]\] – A dictionary with:
+- "replies": Generated ChatMessage instances from the first successful generator.
+- "meta": Execution metadata including successful_chat_generator_index, successful_chat_generator_class,
+ total_attempts, failed_chat_generators, plus any metadata from the successful generator.
+
+**Raises:**
+
+- RuntimeError – If all chat generators fail.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+) -> dict[str, list[ChatMessage] | dict[str, Any]]
+```
+
+Asynchronously execute chat generators sequentially until one succeeds.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The conversation history as a list of ChatMessage instances.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional parameters for the chat generator (e.g., temperature, max_tokens).
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for function calling capabilities.
+- **streaming_callback** (StreamingCallbackT | None) – Optional callable for handling streaming responses.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\] | dict\[str, Any\]\] – A dictionary with:
+- "replies": Generated ChatMessage instances from the first successful generator.
+- "meta": Execution metadata including successful_chat_generator_index, successful_chat_generator_class,
+ total_attempts, failed_chat_generators, plus any metadata from the successful generator.
+
+**Raises:**
+
+- RuntimeError – If all chat generators fail.
+
+## chat/hugging_face_api
+
+### HuggingFaceAPIChatGenerator
+
+Completes chats using Hugging Face APIs.
+
+HuggingFaceAPIChatGenerator uses the [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage)
+format for input and output. Use it to generate text with Hugging Face APIs:
+
+- [Serverless Inference API (Inference Providers)](https://huggingface.co/docs/inference-providers)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
+
+### Usage examples
+
+#### With the serverless inference API (Inference Providers) - free tier available
+
+
+
+```python
+from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack.utils.hf import HFGenerationAPIType
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
+ ChatMessage.from_user("What's Natural Language Processing?")]
+
+# the api_type can be expressed using the HFGenerationAPIType enum or as a string
+api_type = HFGenerationAPIType.SERVERLESS_INFERENCE_API
+api_type = "serverless_inference_api" # this is equivalent to the above
+
+generator = HuggingFaceAPIChatGenerator(api_type=api_type,
+ api_params={"model": "Qwen/Qwen2.5-7B-Instruct",
+ "provider": "together"},
+ token=Secret.from_token("HFGenerationAPIType | str) – The type of Hugging Face API to use. Available types:
+- `text_generation_inference`: See [TGI](https://github.com/huggingface/text-generation-inference).
+- `inference_endpoints`: See [Inference Endpoints](https://huggingface.co/inference-endpoints).
+- `serverless_inference_api`: See
+ [Serverless Inference API - Inference Providers](https://huggingface.co/docs/inference-providers).
+- **api_params** (dict\[str, str\]) – A dictionary with the following keys:
+- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.
+- `provider`: Provider name. Recommended when `api_type` is `SERVERLESS_INFERENCE_API`.
+- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or
+ `TEXT_GENERATION_INFERENCE`.
+- Other parameters specific to the chosen API type, such as `timeout`, `headers`, etc.
+- **token** (Secret | None) – The Hugging Face token to use as HTTP bearer authorization.
+ Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **generation_kwargs** (dict\[str, Any\] | None) – A dictionary with keyword arguments to customize text generation.
+ Some examples: `max_tokens`, `temperature`, `top_p`.
+ For details, see [Hugging Face chat_completion documentation](https://huggingface.co/docs/huggingface_hub/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion).
+- **stop_words** (list\[str\] | None) – An optional list of strings representing the stop words.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callable for handling streaming responses.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ The chosen model should support tool/function calling, according to the model card.
+ Support for tools in the Hugging Face API and TGI is not yet fully refined and you may experience
+ unexpected behavior.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Hugging Face API chat generator.
+
+This will warm up the tools registered in the chat generator.
+This method is idempotent and will only warm up the tools once.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the serialized component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPIChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Invoke the text generation inference based on the provided messages and generation parameters.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage objects representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation.
+- **tools** (ToolsType | None) – A list of tools or a Toolset for which the model can prepare calls. If set, it will override
+ the `tools` parameter set during component initialization. This parameter can accept either a
+ list of `Tool` objects or a `Toolset` instance.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
+ parameter set during component initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: A list containing the generated responses as ChatMessage objects.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Asynchronously invokes the text generation inference based on the provided messages and generation parameters.
+
+This is the asynchronous version of the `run` method. It has the same parameters
+and return values but can be used with `await` in an async code.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage objects representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation.
+- **tools** (ToolsType | None) – A list of tools or a Toolset for which the model can prepare calls. If set, it will override the `tools`
+ parameter set during component initialization. This parameter can accept either a list of `Tool` objects
+ or a `Toolset` instance.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
+ parameter set during component initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: A list containing the generated responses as ChatMessage objects.
+
+## chat/hugging_face_local
+
+### default_tool_parser
+
+```python
+default_tool_parser(text: str) -> list[ToolCall] | None
+```
+
+Default implementation for parsing tool calls from model output text.
+
+Uses DEFAULT_TOOL_PATTERN to extract tool calls.
+
+**Parameters:**
+
+- **text** (str) – The text to parse for tool calls.
+
+**Returns:**
+
+- list\[ToolCall\] | None – A list containing a single ToolCall if a valid tool call is found, None otherwise.
+
+### HuggingFaceLocalChatGenerator
+
+Generates chat responses using models from Hugging Face that run locally.
+
+Use this component with chat-based models,
+such as `Qwen/Qwen3-0.6B` or `meta-llama/Llama-2-7b-chat-hf`.
+LLMs running locally may need powerful hardware.
+
+### Usage example
+
+
+
+```python
+from haystack.components.generators.chat import HuggingFaceLocalChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = HuggingFaceLocalChatGenerator(model="Qwen/Qwen3-0.6B")
+messages = [ChatMessage.from_user("What's Natural Language Processing? Be brief.")]
+print(generator.run(messages))
+```
+
+```
+{'replies':
+ [ChatMessage(_role=str) – The Hugging Face text generation model name or path,
+ for example, `mistralai/Mistral-7B-Instruct-v0.2` or `TheBloke/OpenHermes-2.5-Mistral-7B-16k-AWQ`.
+ The model must be a chat model supporting the ChatML messaging
+ format.
+ If the model is specified in `huggingface_pipeline_kwargs`, this parameter is ignored.
+- **task** (Literal['text-generation', 'text2text-generation', 'image-text-to-text'] | None) – The task for the Hugging Face pipeline. Possible options:
+- `text-generation`: Supported by decoder models, like GPT.
+- `text2text-generation`: Deprecated as of Transformers v5; use `text-generation` instead.
+ Previously supported by encoder–decoder models such as T5.
+- `image-text-to-text`: Supported by vision-language models.
+ If the task is specified in `huggingface_pipeline_kwargs`, this parameter is ignored.
+ If not specified, the component calls the Hugging Face API to infer the task from the model name.
+- **device** (ComponentDevice | None) – The device for loading the model. If `None`, automatically selects the default device.
+ If a device or device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter.
+- **token** (Secret | None) – The token to use as HTTP bearer authorization for remote files.
+ If the token is specified in `huggingface_pipeline_kwargs`, this parameter is ignored.
+- **chat_template** (str | None) – Specifies an optional Jinja template for formatting chat
+ messages. Most high-quality chat models have their own templates, but for models without this
+ feature or if you prefer a custom template, use this parameter.
+- **generation_kwargs** (dict\[str, Any\] | None) – A dictionary with keyword arguments to customize text generation.
+ Some examples: `max_length`, `max_new_tokens`, `temperature`, `top_k`, `top_p`.
+ See Hugging Face's documentation for more information:
+- - [customize-text-generation](https://huggingface.co/docs/transformers/main/en/generation_strategies#customize-text-generation)
+- - [GenerationConfig](https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationConfig)
+ The only `generation_kwargs` set by default is `max_new_tokens`, which is set to 512 tokens.
+- **huggingface_pipeline_kwargs** (dict\[str, Any\] | None) – Dictionary with keyword arguments to initialize the
+ Hugging Face pipeline for text generation.
+ These keyword arguments provide fine-grained control over the Hugging Face pipeline.
+ In case of duplication, these kwargs override `model`, `task`, `device`, and `token` init parameters.
+ For kwargs, see [Hugging Face documentation](https://huggingface.co/docs/transformers/en/main_classes/pipelines#transformers.pipeline.task).
+ In this dictionary, you can also include `model_kwargs` to specify the kwargs for [model initialization](https://huggingface.co/docs/transformers/en/main_classes/model#transformers.PreTrainedModel.from_pretrained)
+- **stop_words** (list\[str\] | None) – A list of stop words. If the model generates a stop word, the generation stops.
+ If you provide this parameter, don't specify the `stopping_criteria` in `generation_kwargs`.
+ For some chat models, the output includes both the new text and the original prompt.
+ In these cases, make sure your prompt has no stop words.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callable for handling streaming responses.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+- **tool_parsing_function** (Callable\\[[str\], list\[ToolCall\] | None\] | None) – A callable that takes a string and returns a list of ToolCall objects or None.
+ If None, the default_tool_parser will be used which extracts tool calls using a predefined pattern.
+- **async_executor** (ThreadPoolExecutor | None) – Optional ThreadPoolExecutor to use for async calls. If not provided, a single-threaded executor will be
+ initialized and used
+- **enable_thinking** (bool) – Whether to enable thinking mode in the chat template for thinking-capable models.
+ When enabled, the model generates intermediate reasoning before the final response. Defaults to False.
+
+#### shutdown
+
+```python
+shutdown() -> None
+```
+
+Explicitly shutdown the executor if we own it.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component and warms up tools if provided.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceLocalChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- HuggingFaceLocalChatGenerator – The deserialized component.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ tools: ToolsType | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Invoke text generation inference based on the provided messages and generation parameters.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage objects representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callable for handling streaming responses.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+#### create_message
+
+```python
+create_message(
+ text: str,
+ index: int,
+ tokenizer: Union[PreTrainedTokenizer, PreTrainedTokenizerFast],
+ prompt: str,
+ generation_kwargs: dict[str, Any],
+ parse_tool_calls: bool = False,
+) -> ChatMessage
+```
+
+Create a ChatMessage instance from the provided text, populated with metadata.
+
+**Parameters:**
+
+- **text** (str) – The generated text.
+- **index** (int) – The index of the generated text.
+- **tokenizer** (Union\[PreTrainedTokenizer, PreTrainedTokenizerFast\]) – The tokenizer used for generation.
+- **prompt** (str) – The prompt used for generation.
+- **generation_kwargs** (dict\[str, Any\]) – The generation parameters.
+- **parse_tool_calls** (bool) – Whether to attempt parsing tool calls from the text.
+
+**Returns:**
+
+- ChatMessage – A ChatMessage instance.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ tools: ToolsType | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Asynchronously invokes text generation inference based on the provided messages and generation parameters.
+
+This is the asynchronous version of the `run` method. It has the same parameters
+and return values but can be used with `await` in an async code.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage objects representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callable for handling streaming responses.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+## chat/llm
+
+### LLM
+
+Bases: Agent
+
+A text generation component powered by a large language model.
+
+The LLM component is a simplified version of the Agent that focuses solely on text generation
+without tool usage. It processes messages and returns a single response from the language model.
+
+### Usage examples
+
+```python
+from haystack.components.generators.chat import LLM
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+llm = LLM(
+ chat_generator=OpenAIChatGenerator(),
+ system_prompt="You are a helpful translation assistant.",
+ user_prompt="""{% message role="user"%}
+Summarize the following document: {{ document }}
+{% endmessage %}""",
+ required_variables=["document"],
+)
+
+result = llm.run(document="The weather is lovely today and the sun is shining. ")
+print(result["last_message"].text)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ chat_generator: ChatGenerator,
+ system_prompt: str | None = None,
+ user_prompt: str,
+ required_variables: list[str] | Literal["*"] = "*",
+ streaming_callback: StreamingCallbackT | None = None
+) -> None
+```
+
+Initialize the LLM component.
+
+**Parameters:**
+
+- **chat_generator** (ChatGenerator) – An instance of the chat generator that the LLM should use.
+- **system_prompt** (str | None) – System prompt for the LLM.
+- **user_prompt** (str) – User prompt for the LLM. Must contain at least one Jinja2 template variable
+ (e.g., `{{ variable_name }}`). This prompt is appended to the messages provided at runtime.
+- **required_variables** (list\[str\] | Literal['\*']) – Variables that must be provided as input to user_prompt.
+ If a variable listed as required is not provided, an exception is raised.
+ If set to `"*"`, all variables found in the prompt are required. Defaults to `"*"`.
+- **streaming_callback** (StreamingCallbackT | None) – A callback that will be invoked when a response is streamed from the LLM.
+
+**Raises:**
+
+- ValueError – If user_prompt contains no template variables.
+- ValueError – If required_variables is an empty list.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the LLM component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LLM
+```
+
+Deserialize the LLM from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- LLM – Deserialized LLM instance.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ *,
+ generation_kwargs: dict[str, Any] | None = None,
+ system_prompt: str | None = None,
+ user_prompt: str | None = None,
+ **kwargs: Any
+) -> dict[str, Any]
+```
+
+Process messages and generate a response from the language model.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | None) – List of Haystack ChatMessage objects to process.
+- **streaming_callback** (StreamingCallbackT | None) – A callback that will be invoked when a response is streamed from the LLM.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for the underlying chat generator. These parameters
+ will override the parameters passed during component initialization.
+- **system_prompt** (str | None) – System prompt for the LLM. If provided, it overrides the default system prompt.
+- **user_prompt** (str | None) – User prompt for the LLM. If provided, it overrides the default user prompt and is
+ appended to the messages provided at runtime.
+- **kwargs** (Any) – Additional keyword arguments. These are used to fill template variables in the `user_prompt`
+ (the keys must match template variable names).
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- "messages": List of all messages exchanged during the LLM's run.
+- "last_message": The last message exchanged during the LLM's run.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ *,
+ generation_kwargs: dict[str, Any] | None = None,
+ system_prompt: str | None = None,
+ user_prompt: str | None = None,
+ **kwargs: Any
+) -> dict[str, Any]
+```
+
+Asynchronously process messages and generate a response from the language model.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | None) – List of Haystack ChatMessage objects to process.
+- **streaming_callback** (StreamingCallbackT | None) – An asynchronous callback that will be invoked when a response is streamed
+ from the LLM.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for the underlying chat generator. These parameters
+ will override the parameters passed during component initialization.
+- **system_prompt** (str | None) – System prompt for the LLM. If provided, it overrides the default system prompt.
+- **user_prompt** (str | None) – User prompt for the LLM. If provided, it overrides the default user prompt and is
+ appended to the messages provided at runtime.
+- **kwargs** (Any) – Additional keyword arguments. These are used to fill template variables in the `user_prompt`
+ (the keys must match template variable names).
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- "messages": List of all messages exchanged during the LLM's run.
+- "last_message": The last message exchanged during the LLM's run.
+
+## chat/openai
+
+### OpenAIChatGenerator
+
+Completes chats using OpenAI's large language models (LLMs).
+
+It works with the gpt-4 and gpt-5 series models and supports streaming responses
+from OpenAI API. It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage)
+format in input and output.
+
+You can customize how the text is generated by passing parameters to the
+OpenAI API. Use the `**generation_kwargs` argument when you initialize
+the component or when you run it. Any parameter that works with
+`openai.ChatCompletion.create` will work here too.
+
+For details on OpenAI API parameters, see
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
+
+### Usage example
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = OpenAIChatGenerator()
+response = client.run(messages)
+print(response)
+```
+
+Output:
+
+```
+{'replies':
+ [ChatMessage(_role=Secret) – The OpenAI API key.
+ You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter
+ during initialization.
+- **model** (str) – The name of the model to use.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk)
+ as an argument.
+- **api_base_url** (str | None) – An optional base URL.
+- **organization** (str | None) – Your organization ID, defaults to `None`. See
+ [production best practices](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization).
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are sent directly to
+ the OpenAI endpoint. See OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat) for
+ more details.
+ Some of the supported parameters:
+- `max_completion_tokens`: An upper bound for the number of tokens that can be generated for a completion,
+ including visible output tokens and reasoning tokens.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+ Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+ considers the results of the tokens with top_p probability mass. For example, 0.1 means only the tokens
+ comprising the top 10% probability mass are considered.
+- `n`: How many completions to generate for each prompt. For example, if the LLM gets 3 prompts and n is 2,
+ it will generate two completions for each of the three prompts, ending up with 6 completions in total.
+- `stop`: One or more sequences after which the LLM should stop generating tokens.
+- `presence_penalty`: What penalty to apply if a token is already present at all. Bigger values mean
+ the model will be less likely to repeat the same token in the text.
+- `frequency_penalty`: What penalty to apply if a token has already been generated in the text.
+ Bigger values mean the model will be less likely to repeat the same token in the text.
+- `logit_bias`: Add a logit bias to specific tokens. The keys of the dictionary are tokens, and the
+ values are the bias to add to that token.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+ If provided, the output will always be validated against this
+ format (unless the model returns a tool call).
+ For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+ Notes:
+ - This parameter accepts Pydantic models and JSON schemas for latest models starting from GPT-4o.
+ Older models only support basic version of structured outputs through `{"type": "json_object"}`.
+ For detailed information on JSON mode, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs#json-mode).
+ - For structured outputs with streaming,
+ the `response_format` must be a JSON schema and not a Pydantic model.
+- **timeout** (float | None) – Timeout for OpenAI client calls. If not set, it defaults to either the
+ `OPENAI_TIMEOUT` environment variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact OpenAI after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+- **tools_strict** (bool) – Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly
+ the schema provided in the `parameters` field of the tool definition, but this may increase latency.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the OpenAI chat generator.
+
+This will warm up the tools registered in the chat generator.
+This method is idempotent and will only warm up the tools once.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAIChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- OpenAIChatGenerator – The deserialized component instance.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ *,
+ tools: ToolsType | None = None,
+ tools_strict: bool | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Invokes chat completion based on the provided messages and generation parameters.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will
+ override the parameters passed during component initialization.
+ For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create).
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter provided during initialization.
+- **tools_strict** (bool | None) – Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly
+ the schema provided in the `parameters` field of the tool definition, but this may increase latency.
+ If set, it will override the `tools_strict` parameter set during component initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ *,
+ tools: ToolsType | None = None,
+ tools_strict: bool | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Asynchronously invokes chat completion based on the provided messages and generation parameters.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ Must be a coroutine.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will
+ override the parameters passed during component initialization.
+ For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create).
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter provided during initialization.
+- **tools_strict** (bool | None) – Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly
+ the schema provided in the `parameters` field of the tool definition, but this may increase latency.
+ If set, it will override the `tools_strict` parameter set during component initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+## chat/openai_responses
+
+### OpenAIResponsesChatGenerator
+
+Completes chats using OpenAI's Responses API.
+
+It works with the gpt-4 and o-series models and supports streaming responses
+from OpenAI API. It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage)
+format in input and output.
+
+You can customize how the text is generated by passing parameters to the
+OpenAI API. Use the `**generation_kwargs` argument when you initialize
+the component or when you run it. Any parameter that works with
+`openai.Responses.create` will work here too.
+
+For details on OpenAI API parameters, see
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/responses).
+
+### Usage example
+
+```python
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = OpenAIResponsesChatGenerator(generation_kwargs={"reasoning": {"effort": "low", "summary": "auto"}})
+response = client.run(messages)
+print(response)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "gpt-5-mini",
+ "gpt-5-nano",
+ "gpt-5",
+ "gpt-5.1",
+ "gpt-5.2",
+ "gpt-5.2-pro",
+ "gpt-5.4",
+ "gpt-5-pro",
+ "gpt-4.1",
+ "gpt-4.1-mini",
+ "gpt-4.1-nano",
+ "gpt-4o",
+ "gpt-4o-mini",
+ "o1",
+ "o1-mini",
+ "o1-pro",
+ "o3",
+ "o3-mini",
+ "o3-pro",
+ "o4-mini",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+See https://platform.openai.com/docs/models for the full list and snapshot IDs.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
+ model: str = "gpt-5-mini",
+ streaming_callback: StreamingCallbackT | None = None,
+ api_base_url: str | None = None,
+ organization: str | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ tools: ToolsType | list[dict] | None = None,
+ tools_strict: bool = False,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of OpenAIResponsesChatGenerator. Uses OpenAI's gpt-5-mini by default.
+
+Before initializing the component, you can set the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES'
+environment variables to override the `timeout` and `max_retries` parameters respectively
+in the OpenAI client.
+
+**Parameters:**
+
+- **api_key** (Secret) – The OpenAI API key.
+ You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter
+ during initialization.
+- **model** (str) – The name of the model to use.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk)
+ as an argument.
+- **api_base_url** (str | None) – An optional base URL.
+- **organization** (str | None) – Your organization ID, defaults to `None`. See
+ [production best practices](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization).
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are sent
+ directly to the OpenAI endpoint.
+ See OpenAI [documentation](https://platform.openai.com/docs/api-reference/responses) for
+ more details.
+ Some of the supported parameters:
+- `temperature`: What sampling temperature to use. Higher values like 0.8 will make the output more random,
+ while lower values like 0.2 will make it more focused and deterministic.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+ considers the results of the tokens with top_p probability mass. For example, 0.1 means only the tokens
+ comprising the top 10% probability mass are considered.
+- `previous_response_id`: The ID of the previous response.
+ Use this to create multi-turn conversations.
+- `text_format`: A Pydantic model that enforces the structure of the model's response.
+ If provided, the output will always be validated against this
+ format (unless the model returns a tool call).
+ For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+- `text`: A JSON schema that enforces the structure of the model's response.
+ If provided, the output will always be validated against this
+ format (unless the model returns a tool call).
+ Notes:
+ - Both JSON Schema and Pydantic models are supported for latest models starting from GPT-4o.
+ - If both are provided, `text_format` takes precedence and json schema passed to `text` is ignored.
+ - Currently, this component doesn't support streaming for structured outputs.
+ - Older models only support basic version of structured outputs through `{"type": "json_object"}`.
+ For detailed information on JSON mode, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs#json-mode).
+- `reasoning`: A dictionary of parameters for reasoning. For example:
+ - `summary`: The summary of the reasoning.
+ - `effort`: The level of effort to put into the reasoning. Can be `low`, `medium` or `high`.
+ - `generate_summary`: Whether to generate a summary of the reasoning.
+ Note: OpenAI does not return the reasoning tokens, but we can view summary if its enabled.
+ For details, see the [OpenAI Reasoning documentation](https://platform.openai.com/docs/guides/reasoning).
+- **timeout** (float | None) – Timeout for OpenAI client calls. If not set, it defaults to either the
+ `OPENAI_TIMEOUT` environment variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact OpenAI after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **tools** (ToolsType | list\[dict\] | None) – The tools that the model can use to prepare calls. This parameter can accept either a
+ mixed list of Haystack `Tool` objects and Haystack `Toolset`. Or you can pass a dictionary of
+ OpenAI/MCP tool definitions.
+ Note: You cannot pass OpenAI/MCP tools and Haystack tools together.
+ For details on tool support, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create#responses-create-tools).
+- **tools_strict** (bool) – Whether to enable strict schema adherence for tool calls. If set to `False`, the model may not exactly
+ follow the schema provided in the `parameters` field of the tool definition. In Response API, tool calls
+ are strict by default.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the OpenAI responses chat generator.
+
+This will warm up the tools registered in the chat generator.
+This method is idempotent and will only warm up the tools once.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAIResponsesChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- OpenAIResponsesChatGenerator – The deserialized component instance.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ *,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | list[dict] | None = None,
+ tools_strict: bool | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Invokes response generation based on the provided messages and generation parameters.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will
+ override the parameters passed during component initialization.
+ For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create).
+- **tools** (ToolsType | list\[dict\] | None) – The tools that the model can use to prepare calls. If set, it will override the
+ `tools` parameter set during component initialization. This parameter can accept either a
+ mixed list of Haystack `Tool` objects and Haystack `Toolset`. Or you can pass a dictionary of
+ OpenAI/MCP tool definitions.
+ Note: You cannot pass OpenAI/MCP tools and Haystack tools together.
+ For details on tool support, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create#responses-create-tools).
+- **tools_strict** (bool | None) – Whether to enable strict schema adherence for tool calls. If set to `False`, the model may not exactly
+ follow the schema provided in the `parameters` field of the tool definition. In Response API, tool calls
+ are strict by default.
+ If set, it will override the `tools_strict` parameter set during component initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ *,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | list[dict] | None = None,
+ tools_strict: bool | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Asynchronously invokes response generation based on the provided messages and generation parameters.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ Must be a coroutine.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will
+ override the parameters passed during component initialization.
+ For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create).
+- **tools** (ToolsType | list\[dict\] | None) – A list of tools or a Toolset for which the model can prepare calls. If set, it will override the
+ `tools` parameter set during component initialization. This parameter can accept either a list of
+ mixed list of Haystack `Tool` objects and Haystack `Toolset`. Or you can pass a dictionary of
+ OpenAI/MCP tool definitions.
+ Note: You cannot pass OpenAI/MCP tools and Haystack tools together.
+- **tools_strict** (bool | None) – Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly
+ the schema provided in the `parameters` field of the tool definition, but this may increase latency.
+ If set, it will override the `tools_strict` parameter set during component initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+## hugging_face_api
+
+### HuggingFaceAPIGenerator
+
+Generates text using Hugging Face APIs.
+
+Use it with the following Hugging Face APIs:
+
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
+
+**Note:** As of July 2025, the Hugging Face Inference API no longer offers generative models through the
+`text_generation` endpoint. Generative models are now only available through providers supporting the
+`chat_completion` endpoint. As a result, this component might no longer work with the Hugging Face Inference API.
+Use the `HuggingFaceAPIChatGenerator` component, which supports the `chat_completion` endpoint.
+
+### Usage examples
+
+#### With Hugging Face Inference Endpoints
+
+
+
+```python
+from haystack.components.generators import HuggingFaceAPIGenerator
+from haystack.utils import Secret
+
+generator = HuggingFaceAPIGenerator(api_type="inference_endpoints",
+ api_params={"url": "HFGenerationAPIType | str) – The type of Hugging Face API to use. Available types:
+- `text_generation_inference`: See [TGI](https://github.com/huggingface/text-generation-inference).
+- `inference_endpoints`: See [Inference Endpoints](https://huggingface.co/inference-endpoints).
+- `serverless_inference_api`: See [Serverless Inference API](https://huggingface.co/inference-api).
+ This might no longer work due to changes in the models offered in the Hugging Face Inference API.
+ Please use the `HuggingFaceAPIChatGenerator` component instead.
+- **api_params** (dict\[str, str\]) – A dictionary with the following keys:
+- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.
+- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or
+ `TEXT_GENERATION_INFERENCE`.
+- Other parameters specific to the chosen API type, such as `timeout`, `headers`, `provider` etc.
+- **token** (Secret | None) – The Hugging Face token to use as HTTP bearer authorization.
+ Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **generation_kwargs** (dict\[str, Any\] | None) – A dictionary with keyword arguments to customize text generation. Some examples: `max_new_tokens`,
+ `temperature`, `top_k`, `top_p`.
+ For details, see [Hugging Face documentation](https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client#huggingface_hub.InferenceClient.text_generation)
+ for more information.
+- **stop_words** (list\[str\] | None) – An optional list of strings representing the stop words.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callable for handling streaming responses.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the serialized component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPIGenerator
+```
+
+Deserialize this component from a dictionary.
+
+#### run
+
+```python
+run(
+ prompt: str,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+) -> dict[str, Any]
+```
+
+Invoke the text generation inference for the given prompt and generation parameters.
+
+**Parameters:**
+
+- **prompt** (str) – A string representing the prompt.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the generated replies and metadata. Both are lists of length n.
+- replies: A list of strings representing the generated replies.
+
+## hugging_face_local
+
+### HuggingFaceLocalGenerator
+
+Generates text using models from Hugging Face that run locally.
+
+LLMs running locally may need powerful hardware.
+
+### Usage example
+
+```python
+from haystack.components.generators import HuggingFaceLocalGenerator
+
+generator = HuggingFaceLocalGenerator(
+ model="Qwen/Qwen3-0.6B",
+ task="text-generation",
+ generation_kwargs={"max_new_tokens": 100, "temperature": 0.9}
+)
+
+print(generator.run("Who is the best American actor?"))
+# >> {'replies': ['John Cusack']}
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "Qwen/Qwen3-0.6B",
+ task: Literal["text-generation", "text2text-generation"] | None = None,
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ generation_kwargs: dict[str, Any] | None = None,
+ huggingface_pipeline_kwargs: dict[str, Any] | None = None,
+ stop_words: list[str] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+) -> None
+```
+
+Creates an instance of a HuggingFaceLocalGenerator.
+
+**Parameters:**
+
+- **model** (str) – The Hugging Face text generation model name or path.
+- **task** (Literal['text-generation', 'text2text-generation'] | None) – The task for the Hugging Face pipeline. Possible options:
+- `text-generation`: Supported by decoder models, like GPT.
+- `text2text-generation`: Deprecated as of Transformers v5; use `text-generation` instead.
+ Previously supported by encoder–decoder models such as T5.
+ If the task is specified in `huggingface_pipeline_kwargs`, this parameter is ignored.
+ If not specified, the component calls the Hugging Face API to infer the task from the model name.
+- **device** (ComponentDevice | None) – The device for loading the model. If `None`, automatically selects the default device.
+ If a device or device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter.
+- **token** (Secret | None) – The token to use as HTTP bearer authorization for remote files.
+ If the token is specified in `huggingface_pipeline_kwargs`, this parameter is ignored.
+- **generation_kwargs** (dict\[str, Any\] | None) – A dictionary with keyword arguments to customize text generation.
+ Some examples: `max_length`, `max_new_tokens`, `temperature`, `top_k`, `top_p`.
+ See Hugging Face's documentation for more information:
+- [customize-text-generation](https://huggingface.co/docs/transformers/main/en/generation_strategies#customize-text-generation)
+- [transformers.GenerationConfig](https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationConfig)
+- **huggingface_pipeline_kwargs** (dict\[str, Any\] | None) – Dictionary with keyword arguments to initialize the
+ Hugging Face pipeline for text generation.
+ These keyword arguments provide fine-grained control over the Hugging Face pipeline.
+ In case of duplication, these kwargs override `model`, `task`, `device`, and `token` init parameters.
+ For available kwargs, see [Hugging Face documentation](https://huggingface.co/docs/transformers/en/main_classes/pipelines#transformers.pipeline.task).
+ In this dictionary, you can also include `model_kwargs` to specify the kwargs for model initialization:
+ [transformers.PreTrainedModel.from_pretrained](https://huggingface.co/docs/transformers/en/main_classes/model#transformers.PreTrainedModel.from_pretrained)
+- **stop_words** (list\[str\] | None) – If the model generates a stop word, the generation stops.
+ If you provide this parameter, don't specify the `stopping_criteria` in `generation_kwargs`.
+ For some chat models, the output includes both the new text and the original prompt.
+ In these cases, make sure your prompt has no stop words.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callable for handling streaming responses.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceLocalGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- HuggingFaceLocalGenerator – The deserialized component.
+
+#### run
+
+```python
+run(
+ prompt: str,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+) -> dict[str, Any]
+```
+
+Run the text generation model on the given prompt.
+
+**Parameters:**
+
+- **prompt** (str) – A string representing the prompt.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the generated replies.
+- replies: A list of strings representing the generated replies.
+
+## openai
+
+### OpenAIGenerator
+
+Generates text using OpenAI's large language models (LLMs).
+
+It works with the gpt-4 and gpt-5 series models and supports streaming responses
+from OpenAI API. It uses strings as input and output.
+
+You can customize how the text is generated by passing parameters to the
+OpenAI API. Use the `**generation_kwargs` argument when you initialize
+the component or when you run it. Any parameter that works with
+`openai.ChatCompletion.create` will work here too.
+
+For details on OpenAI API parameters, see
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
+
+### Usage example
+
+```python
+from haystack.components.generators import OpenAIGenerator
+client = OpenAIGenerator()
+response = client.run("What's Natural Language Processing? Be brief.")
+print(response)
+
+# >> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on
+# >> the interaction between computers and human language. It involves enabling computers to understand, interpret,
+# >> and respond to natural human language in a way that is both meaningful and useful.'], 'meta': [{'model':
+# >> 'gpt-5-mini', 'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 16,
+# >> 'completion_tokens': 49, 'total_tokens': 65}}]}
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
+ model: str = "gpt-5-mini",
+ streaming_callback: StreamingCallbackT | None = None,
+ api_base_url: str | None = None,
+ organization: str | None = None,
+ system_prompt: str | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Creates an instance of OpenAIGenerator. Unless specified otherwise in `model`, uses OpenAI's gpt-5-mini
+
+By setting the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES' you can change the timeout and max_retries parameters
+in the OpenAI client.
+
+**Parameters:**
+
+- **api_key** (Secret) – The OpenAI API key to connect to OpenAI.
+- **model** (str) – The name of the model to use.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **api_base_url** (str | None) – An optional base URL.
+- **organization** (str | None) – The Organization ID, defaults to `None`.
+- **system_prompt** (str | None) – The system prompt to use for text generation. If not provided, the system prompt is
+ omitted, and the default system prompt of the model is used.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the OpenAI endpoint. See OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat) for
+ more details.
+ Some of the supported parameters:
+- `max_completion_tokens`: An upper bound for the number of tokens that can be generated for a completion,
+ including visible output tokens and reasoning tokens.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+ Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+ considers the results of the tokens with top_p probability mass. So, 0.1 means only the tokens
+ comprising the top 10% probability mass are considered.
+- `n`: How many completions to generate for each prompt. For example, if the LLM gets 3 prompts and n is 2,
+ it will generate two completions for each of the three prompts, ending up with 6 completions in total.
+- `stop`: One or more sequences after which the LLM should stop generating tokens.
+- `presence_penalty`: What penalty to apply if a token is already present at all. Bigger values mean
+ the model will be less likely to repeat the same token in the text.
+- `frequency_penalty`: What penalty to apply if a token has already been generated in the text.
+ Bigger values mean the model will be less likely to repeat the same token in the text.
+- `logit_bias`: Add a logit bias to specific tokens. The keys of the dictionary are tokens, and the
+ values are the bias to add to that token.
+- **timeout** (float | None) – Timeout for OpenAI Client calls, if not set it is inferred from the `OPENAI_TIMEOUT` environment variable
+ or set to 30.
+- **max_retries** (int | None) – Maximum retries to establish contact with OpenAI if it returns an internal error, if not set it is inferred
+ from the `OPENAI_MAX_RETRIES` environment variable or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAIGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- OpenAIGenerator – The deserialized component instance.
+
+#### run
+
+```python
+run(
+ prompt: str,
+ system_prompt: str | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Invoke the text generation inference based on the provided messages and generation parameters.
+
+**Parameters:**
+
+- **prompt** (str) – The string prompt to use for text generation.
+- **system_prompt** (str | None) – The system prompt to use for text generation. If this run time system prompt is omitted, the system
+ prompt, if defined at initialisation time, is used.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+ passed in the `__init__` method. For more details on the parameters supported by the OpenAI API, refer to
+ the OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat/create).
+
+**Returns:**
+
+- dict\[str, list\[str\] | list\[dict\[str, Any\]\]\] – A list of strings containing the generated responses and a list of dictionaries containing the metadata
+ for each response.
+
+## openai_dalle
+
+### DALLEImageGenerator
+
+Generates images using OpenAI's DALL-E model.
+
+For details on OpenAI API parameters, see
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/images/create).
+
+### Usage example
+
+```python
+from haystack.components.generators import DALLEImageGenerator
+image_generator = DALLEImageGenerator()
+response = image_generator.run("Show me a picture of a black cat.")
+print(response)
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "dall-e-3",
+ quality: Literal["standard", "hd"] = "standard",
+ size: Literal[
+ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792"
+ ] = "1024x1024",
+ response_format: Literal["url", "b64_json"] = "url",
+ api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
+ api_base_url: str | None = None,
+ organization: str | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Creates an instance of DALLEImageGenerator. Unless specified otherwise in `model`, uses OpenAI's dall-e-3.
+
+**Parameters:**
+
+- **model** (str) – The model to use for image generation. Can be "dall-e-2" or "dall-e-3".
+- **quality** (Literal['standard', 'hd']) – The quality of the generated image. Can be "standard" or "hd".
+- **size** (Literal['256x256', '512x512', '1024x1024', '1792x1024', '1024x1792']) – The size of the generated images.
+ Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2.
+ Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models.
+- **response_format** (Literal['url', 'b64_json']) – The format of the response. Can be "url" or "b64_json".
+- **api_key** (Secret) – The OpenAI API key to connect to OpenAI.
+- **api_base_url** (str | None) – An optional base URL.
+- **organization** (str | None) – The Organization ID, defaults to `None`.
+- **timeout** (float | None) – Timeout for OpenAI Client calls. If not set, it is inferred from the `OPENAI_TIMEOUT` environment variable
+ or set to 30.
+- **max_retries** (int | None) – Maximum retries to establish contact with OpenAI if it returns an internal error. If not set, it is inferred
+ from the `OPENAI_MAX_RETRIES` environment variable or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the OpenAI client.
+
+#### run
+
+```python
+run(
+ prompt: str,
+ size: (
+ Literal["256x256", "512x512", "1024x1024", "1792x1024", "1024x1792"]
+ | None
+ ) = None,
+ quality: Literal["standard", "hd"] | None = None,
+ response_format: Literal["url", "b64_json"] | None = None,
+) -> dict[str, Any]
+```
+
+Invokes the image generation inference based on the provided prompt and generation parameters.
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to generate the image.
+- **size** (Literal['256x256', '512x512', '1024x1024', '1792x1024', '1024x1792'] | None) – If provided, overrides the size provided during initialization.
+- **quality** (Literal['standard', 'hd'] | None) – If provided, overrides the quality provided during initialization.
+- **response_format** (Literal['url', 'b64_json'] | None) – If provided, overrides the response format provided during initialization.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the generated list of images and the revised prompt.
+ Depending on the `response_format` parameter, the list of images can be URLs or base64 encoded JSON strings.
+ The revised prompt is the prompt that was used to generate the image, if there was any revision
+ to the prompt made by OpenAI.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DALLEImageGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- DALLEImageGenerator – The deserialized component instance.
+
+## utils
+
+### print_streaming_chunk
+
+```python
+print_streaming_chunk(chunk: StreamingChunk) -> None
+```
+
+Callback function to handle and display streaming output chunks.
+
+This function processes a `StreamingChunk` object by:
+
+- Printing tool call metadata (if any), including function names and arguments, as they arrive.
+- Printing tool call results when available.
+- Printing the main content (e.g., text tokens) of the chunk as it is received.
+
+The function outputs data directly to stdout and flushes output buffers to ensure immediate display during
+streaming.
+
+**Parameters:**
+
+- **chunk** (StreamingChunk) – A chunk of streaming data containing content and optional metadata, such as tool calls and
+ tool results.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/human_in_the_loop_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/human_in_the_loop_api.md
new file mode 100644
index 0000000000..0dfddd4adb
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/human_in_the_loop_api.md
@@ -0,0 +1,362 @@
+---
+title: "Human-in-the-Loop"
+id: human-in-the-loop-api
+description: "Abstractions for integrating human feedback and interaction into Agent workflows."
+slug: "/human-in-the-loop-api"
+---
+
+
+## dataclasses
+
+### ConfirmationUIResult
+
+Result of the confirmation UI interaction.
+
+**Parameters:**
+
+- **action** (str) – The action taken by the user such as "confirm", "reject", or "modify".
+ This action type is not enforced to allow for custom actions to be implemented.
+- **feedback** (str | None) – Optional feedback message from the user. For example, if the user rejects the tool execution,
+ they might provide a reason for the rejection.
+- **new_tool_params** (dict\[str, Any\] | None) – Optional set of new parameters for the tool. For example, if the user chooses to modify the tool parameters,
+ they can provide a new set of parameters here.
+
+### ToolExecutionDecision
+
+Decision made regarding tool execution.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool to be executed.
+- **execute** (bool) – A boolean indicating whether to execute the tool with the provided parameters.
+- **tool_call_id** (str | None) – Optional unique identifier for the tool call. This can be used to track and correlate the decision with a
+ specific tool invocation.
+- **feedback** (str | None) – Optional feedback message.
+ For example, if the tool execution is rejected, this can contain the reason. Or if the tool parameters were
+ modified, this can contain the modification details.
+- **final_tool_params** (dict\[str, Any\] | None) – Optional final parameters for the tool if execution is confirmed or modified.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the ToolExecutionDecision to a dictionary representation.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the tool execution decision details.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ToolExecutionDecision
+```
+
+Populate the ToolExecutionDecision from a dictionary representation.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – A dictionary containing the tool execution decision details.
+
+**Returns:**
+
+- ToolExecutionDecision – An instance of ToolExecutionDecision.
+
+## policies
+
+### AlwaysAskPolicy
+
+Bases: ConfirmationPolicy
+
+Always ask for confirmation.
+
+#### should_ask
+
+```python
+should_ask(
+ tool_name: str, tool_description: str, tool_params: dict[str, Any]
+) -> bool
+```
+
+Always ask for confirmation before executing the tool.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool to be executed.
+- **tool_description** (str) – The description of the tool.
+- **tool_params** (dict\[str, Any\]) – The parameters to be passed to the tool.
+
+**Returns:**
+
+- bool – Always returns True, indicating confirmation is needed.
+
+### NeverAskPolicy
+
+Bases: ConfirmationPolicy
+
+Never ask for confirmation.
+
+#### should_ask
+
+```python
+should_ask(
+ tool_name: str, tool_description: str, tool_params: dict[str, Any]
+) -> bool
+```
+
+Never ask for confirmation, always proceed with tool execution.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool to be executed.
+- **tool_description** (str) – The description of the tool.
+- **tool_params** (dict\[str, Any\]) – The parameters to be passed to the tool.
+
+**Returns:**
+
+- bool – Always returns False, indicating no confirmation is needed.
+
+### AskOncePolicy
+
+Bases: ConfirmationPolicy
+
+Ask only once per tool with specific parameters.
+
+#### __init__
+
+```python
+__init__() -> None
+```
+
+Creates an instance of AskOncePolicy.
+
+#### should_ask
+
+```python
+should_ask(
+ tool_name: str, tool_description: str, tool_params: dict[str, Any]
+) -> bool
+```
+
+Ask for confirmation only once per tool with specific parameters.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool to be executed.
+- **tool_description** (str) – The description of the tool.
+- **tool_params** (dict\[str, Any\]) – The parameters to be passed to the tool.
+
+**Returns:**
+
+- bool – True if confirmation is needed, False if already asked with the same parameters.
+
+#### update_after_confirmation
+
+```python
+update_after_confirmation(
+ tool_name: str,
+ tool_description: str,
+ tool_params: dict[str, Any],
+ confirmation_result: ConfirmationUIResult,
+) -> None
+```
+
+Store the tool and parameters if the action was "confirm" to avoid asking again.
+
+This method updates the internal state to remember that the user has already confirmed the execution of the
+tool with the given parameters.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool that was executed.
+- **tool_description** (str) – The description of the tool.
+- **tool_params** (dict\[str, Any\]) – The parameters that were passed to the tool.
+- **confirmation_result** (ConfirmationUIResult) – The result from the confirmation UI.
+
+## strategies
+
+### BlockingConfirmationStrategy
+
+Confirmation strategy that blocks execution to gather user feedback.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ confirmation_policy: ConfirmationPolicy,
+ confirmation_ui: ConfirmationUI,
+ reject_template: str = REJECTION_FEEDBACK_TEMPLATE,
+ modify_template: str = MODIFICATION_FEEDBACK_TEMPLATE,
+ user_feedback_template: str = USER_FEEDBACK_TEMPLATE
+) -> None
+```
+
+Initialize the BlockingConfirmationStrategy with a confirmation policy and UI.
+
+**Parameters:**
+
+- **confirmation_policy** (ConfirmationPolicy) – The confirmation policy to determine when to ask for user confirmation.
+- **confirmation_ui** (ConfirmationUI) – The user interface to interact with the user for confirmation.
+- **reject_template** (str) – Template for rejection feedback messages. It should include a `{tool_name}` placeholder.
+- **modify_template** (str) – Template for modification feedback messages. It should include `{tool_name}` and `{final_tool_params}`
+ placeholders.
+- **user_feedback_template** (str) – Template for user feedback messages. It should include a `{feedback}` placeholder.
+
+#### run
+
+```python
+run(
+ *,
+ tool_name: str,
+ tool_description: str,
+ tool_params: dict[str, Any],
+ tool_call_id: str | None = None,
+ confirmation_strategy_context: dict[str, Any] | None = None
+) -> ToolExecutionDecision
+```
+
+Run the human-in-the-loop strategy for a given tool and its parameters.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool to be executed.
+- **tool_description** (str) – The description of the tool.
+- **tool_params** (dict\[str, Any\]) – The parameters to be passed to the tool.
+- **tool_call_id** (str | None) – Optional unique identifier for the tool call. This can be used to track and correlate the decision with a
+ specific tool invocation.
+- **confirmation_strategy_context** (dict\[str, Any\] | None) – Optional dictionary for passing request-scoped resources. Useful in web/server environments
+ to provide per-request objects (e.g., WebSocket connections, async queues, Redis pub/sub clients)
+ that strategies can use for non-blocking user interaction.
+
+**Returns:**
+
+- ToolExecutionDecision – A ToolExecutionDecision indicating whether to execute the tool with the given parameters, or a
+ feedback message if rejected.
+
+#### run_async
+
+```python
+run_async(
+ *,
+ tool_name: str,
+ tool_description: str,
+ tool_params: dict[str, Any],
+ tool_call_id: str | None = None,
+ confirmation_strategy_context: dict[str, Any] | None = None
+) -> ToolExecutionDecision
+```
+
+Async version of run. Calls the sync run() method by default.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool to be executed.
+- **tool_description** (str) – The description of the tool.
+- **tool_params** (dict\[str, Any\]) – The parameters to be passed to the tool.
+- **tool_call_id** (str | None) – Optional unique identifier for the tool call.
+- **confirmation_strategy_context** (dict\[str, Any\] | None) – Optional dictionary for passing request-scoped resources.
+
+**Returns:**
+
+- ToolExecutionDecision – A ToolExecutionDecision indicating whether to execute the tool with the given parameters.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the BlockingConfirmationStrategy to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> BlockingConfirmationStrategy
+```
+
+Deserializes the BlockingConfirmationStrategy from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- BlockingConfirmationStrategy – Deserialized BlockingConfirmationStrategy.
+
+## user_interfaces
+
+### RichConsoleUI
+
+Bases: ConfirmationUI
+
+Rich console interface for user interaction.
+
+#### __init__
+
+```python
+__init__(console: Console | None = None) -> None
+```
+
+Creates an instance of RichConsoleUI.
+
+#### get_user_confirmation
+
+```python
+get_user_confirmation(
+ tool_name: str, tool_description: str, tool_params: dict[str, Any]
+) -> ConfirmationUIResult
+```
+
+Get user confirmation for tool execution via rich console prompts.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool to be executed.
+- **tool_description** (str) – The description of the tool.
+- **tool_params** (dict\[str, Any\]) – The parameters to be passed to the tool.
+
+**Returns:**
+
+- ConfirmationUIResult – ConfirmationUIResult based on user input.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the RichConsoleConfirmationUI to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+### SimpleConsoleUI
+
+Bases: ConfirmationUI
+
+Simple console interface using standard input/output.
+
+#### get_user_confirmation
+
+```python
+get_user_confirmation(
+ tool_name: str, tool_description: str, tool_params: dict[str, Any]
+) -> ConfirmationUIResult
+```
+
+Get user confirmation for tool execution via simple console prompts.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool to be executed.
+- **tool_description** (str) – The description of the tool.
+- **tool_params** (dict\[str, Any\]) – The parameters to be passed to the tool.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/image_converters_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/image_converters_api.md
new file mode 100644
index 0000000000..eb4415f7c6
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/image_converters_api.md
@@ -0,0 +1,353 @@
+---
+title: "Image Converters"
+id: image-converters-api
+description: "Various converters to transform image data from one format to another."
+slug: "/image-converters-api"
+---
+
+
+## document_to_image
+
+### DocumentToImageContent
+
+Converts documents sourced from PDF and image files into ImageContents.
+
+This component processes a list of documents and extracts visual content from supported file formats, converting
+them into ImageContents that can be used for multimodal AI tasks. It handles both direct image files and PDF
+documents by extracting specific pages as images.
+
+Documents are expected to have metadata containing:
+
+- The `file_path_meta_field` key with a valid file path that exists when combined with `root_path`
+- A supported image format (MIME type must be one of the supported image types)
+- For PDF files, a `page_number` key specifying which page to extract
+
+### Usage example
+
+
+
+```python
+from haystack import Document
+from haystack.components.converters.image.document_to_image import DocumentToImageContent
+
+converter = DocumentToImageContent(
+ file_path_meta_field="file_path",
+ root_path="/data/files",
+ detail="high",
+ size=(800, 600)
+)
+
+documents = [
+ Document(content="Optional description of image.jpg", meta={"file_path": "image.jpg"}),
+ Document(content="Text content of page 1 of doc.pdf", meta={"file_path": "doc.pdf", "page_number": 1})
+]
+
+result = converter.run(documents)
+image_contents = result["image_contents"]
+# [ImageContent(
+# base64_image='/9j/4A...', mime_type='image/jpeg', detail='high', meta={'file_path': 'image.jpg'}
+# ),
+# ImageContent(
+# base64_image='/9j/4A...', mime_type='image/jpeg', detail='high',
+# meta={'page_number': 1, 'file_path': 'doc.pdf'}
+# )]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ file_path_meta_field: str = "file_path",
+ root_path: str | None = None,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None
+) -> None
+```
+
+Initialize the DocumentToImageContent component.
+
+**Parameters:**
+
+- **file_path_meta_field** (str) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (str | None) – The root directory path where document files are located. If provided, file paths in
+ document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low".
+ This will be passed to the created ImageContent objects.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[ImageContent | None]]
+```
+
+Convert documents with image or PDF sources into ImageContent objects.
+
+This method processes the input documents, extracting images from supported file formats and converting them
+into ImageContent objects.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to process. Each document should have metadata containing at minimum
+ a 'file_path_meta_field' key. PDF documents additionally require a 'page_number' key to specify which
+ page to convert.
+
+**Returns:**
+
+- dict\[str, list\[ImageContent | None\]\] – Dictionary containing one key:
+- "image_contents": ImageContents created from the processed documents. These contain base64-encoded image
+ data and metadata. The order corresponds to order of input documents.
+
+**Raises:**
+
+- ValueError – If any document is missing the required metadata keys, has an invalid file path, or has an unsupported
+ MIME type. The error message will specify which document and what information is missing or incorrect.
+
+## file_to_document
+
+### ImageFileToDocument
+
+Converts image file references into empty Document objects with associated metadata.
+
+This component is useful in pipelines where image file paths need to be wrapped in `Document` objects to be
+processed by downstream components such as the `SentenceTransformersImageDocumentEmbedder`.
+
+It does **not** extract any content from the image files, instead it creates `Document` objects with `None` as
+their content and attaches metadata such as file path and any user-provided values.
+
+### Usage example
+
+```python
+from haystack.components.converters.image import ImageFileToDocument
+
+converter = ImageFileToDocument()
+
+sources = ["image.jpg", "another_image.png"]
+
+result = converter.run(sources=sources)
+documents = result["documents"]
+
+print(documents)
+
+# [Document(id=..., meta: {'file_path': 'image.jpg'}),
+# Document(id=..., meta: {'file_path': 'another_image.png'})]
+```
+
+#### __init__
+
+```python
+__init__(*, store_full_path: bool = False) -> None
+```
+
+Initialize the ImageFileToDocument component.
+
+**Parameters:**
+
+- **store_full_path** (bool) – If True, the full path of the file is stored in the metadata of the document.
+ If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+ *,
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, list[Document]]
+```
+
+Convert image files into empty Document objects with metadata.
+
+This method accepts image file references (as file paths or ByteStreams) and creates `Document` objects
+without content. These documents are enriched with metadata derived from the input source and optional
+user-provided metadata.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects to convert.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the documents.
+ This value can be a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced documents.
+ If it's a list, its length must match the number of sources, as they are zipped together.
+ For ByteStream objects, their `meta` is added to the output documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing:
+- `documents`: A list of `Document` objects with empty content and associated metadata.
+
+## file_to_image
+
+### ImageFileToImageContent
+
+Converts image files to ImageContent objects.
+
+### Usage example
+
+```python
+from haystack.components.converters.image import ImageFileToImageContent
+
+converter = ImageFileToImageContent()
+
+sources = ["image.jpg", "another_image.png"]
+
+image_contents = converter.run(sources=sources)["image_contents"]
+print(image_contents)
+
+# [ImageContent(base64_image='...',
+# mime_type='image/jpeg',
+# detail=None,
+# meta={'file_path': 'image.jpg'}),
+# ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None
+) -> None
+```
+
+Create the ImageFileToImageContent component.
+
+**Parameters:**
+
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+ This will be passed to the created ImageContent objects.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+ *,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None
+) -> dict[str, list[ImageContent]]
+```
+
+Converts files to ImageContent objects.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects to convert.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the ImageContent objects.
+ This value can be a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced ImageContent objects.
+ If it's a list, its length must match the number of sources as they're zipped together.
+ For ByteStream objects, their `meta` is added to the output ImageContent objects.
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+ This will be passed to the created ImageContent objects.
+ If not provided, the detail level will be the one set in the constructor.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+ If not provided, the size value will be the one set in the constructor.
+
+**Returns:**
+
+- dict\[str, list\[ImageContent\]\] – A dictionary with the following keys:
+- `image_contents`: A list of ImageContent objects.
+
+## pdf_to_image
+
+### PDFToImageContent
+
+Converts PDF files to ImageContent objects.
+
+### Usage example
+
+```python
+from haystack.components.converters.image import PDFToImageContent
+
+converter = PDFToImageContent()
+
+sources = ["file.pdf", "another_file.pdf"]
+
+image_contents = converter.run(sources=sources)["image_contents"]
+print(image_contents)
+
+# [ImageContent(base64_image='...',
+# mime_type='application/pdf',
+# detail=None,
+# meta={'file_path': 'file.pdf', 'page_number': 1}),
+# ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None,
+ page_range: list[str | int] | None = None
+) -> None
+```
+
+Create the PDFToImageContent component.
+
+**Parameters:**
+
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+ This will be passed to the created ImageContent objects.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+- **page_range** (list\[str | int\] | None) – List of page numbers and/or page ranges to convert to images. Page numbers start at 1.
+ If None, all pages in the PDF will be converted. Pages outside the valid range (1 to number of pages)
+ will be skipped with a warning. For example, page_range=[1, 3] will convert only the first and third
+ pages of the document. It also accepts printable range strings, e.g.: ['1-3', '5', '8', '10-12']
+ will convert pages 1, 2, 3, 5, 8, 10, 11, 12.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+ *,
+ detail: Literal["auto", "high", "low"] | None = None,
+ size: tuple[int, int] | None = None,
+ page_range: list[str | int] | None = None
+) -> dict[str, list[ImageContent]]
+```
+
+Converts files to ImageContent objects.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects to convert.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the ImageContent objects.
+ This value can be a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced ImageContent objects.
+ If it's a list, its length must match the number of sources as they're zipped together.
+ For ByteStream objects, their `meta` is added to the output ImageContent objects.
+- **detail** (Literal['auto', 'high', 'low'] | None) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+ This will be passed to the created ImageContent objects.
+ If not provided, the detail level will be the one set in the constructor.
+- **size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+ If not provided, the size value will be the one set in the constructor.
+- **page_range** (list\[str | int\] | None) – List of page numbers and/or page ranges to convert to images. Page numbers start at 1.
+ If None, all pages in the PDF will be converted. Pages outside the valid range (1 to number of pages)
+ will be skipped with a warning. For example, page_range=[1, 3] will convert only the first and third
+ pages of the document. It also accepts printable range strings, e.g.: ['1-3', '5', '8', '10-12']
+ will convert pages 1, 2, 3, 5, 8, 10, 11, 12.
+ If not provided, the page_range value will be the one set in the constructor.
+
+**Returns:**
+
+- dict\[str, list\[ImageContent\]\] – A dictionary with the following keys:
+- `image_contents`: A list of ImageContent objects.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/joiners_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/joiners_api.md
new file mode 100644
index 0000000000..26a98dd893
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/joiners_api.md
@@ -0,0 +1,566 @@
+---
+title: "Joiners"
+id: joiners-api
+description: "Components that join list of different objects"
+slug: "/joiners-api"
+---
+
+
+## answer_joiner
+
+### JoinMode
+
+Bases: Enum
+
+Enum for AnswerJoiner join modes.
+
+#### from_str
+
+```python
+from_str(string: str) -> JoinMode
+```
+
+Convert a string to a JoinMode enum.
+
+### AnswerJoiner
+
+Merges multiple lists of `Answer` objects into a single list.
+
+Use this component to combine answers from different Generators into a single list.
+Currently, the component supports only one join mode: `CONCATENATE`.
+This mode concatenates multiple lists of answers into a single list.
+
+### Usage example
+
+In this example, AnswerJoiner merges answers from two different Generators:
+
+```python
+from haystack.components.builders import AnswerBuilder
+from haystack.components.joiners import AnswerJoiner
+
+from haystack.core.pipeline import Pipeline
+
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+
+query = "What's Natural Language Processing?"
+messages = [ChatMessage.from_system("You are a helpful, respectful and honest assistant. Be super concise."),
+ ChatMessage.from_user(query)]
+
+pipe = Pipeline()
+pipe.add_component("llm_1", OpenAIChatGenerator())
+pipe.add_component("llm_2", OpenAIChatGenerator())
+pipe.add_component("aba", AnswerBuilder())
+pipe.add_component("abb", AnswerBuilder())
+pipe.add_component("joiner", AnswerJoiner())
+
+pipe.connect("llm_1.replies", "aba")
+pipe.connect("llm_2.replies", "abb")
+pipe.connect("aba.answers", "joiner")
+pipe.connect("abb.answers", "joiner")
+
+results = pipe.run(data={"llm_1": {"messages": messages},
+ "llm_2": {"messages": messages},
+ "aba": {"query": query},
+ "abb": {"query": query}})
+```
+
+#### __init__
+
+```python
+__init__(
+ join_mode: str | JoinMode = JoinMode.CONCATENATE,
+ top_k: int | None = None,
+ sort_by_score: bool = False,
+) -> None
+```
+
+Creates an AnswerJoiner component.
+
+**Parameters:**
+
+- **join_mode** (str | JoinMode) – Specifies the join mode to use. Available modes:
+- `concatenate`: Concatenates multiple lists of Answers into a single list.
+- **top_k** (int | None) – The maximum number of Answers to return.
+- **sort_by_score** (bool) – If `True`, sorts the documents by score in descending order.
+ If a document has no score, it is handled as if its score is -infinity.
+
+#### run
+
+```python
+run(
+ answers: Variadic[list[AnswerType]], top_k: int | None = None
+) -> dict[str, Any]
+```
+
+Joins multiple lists of Answers into a single list depending on the `join_mode` parameter.
+
+**Parameters:**
+
+- **answers** (Variadic\[list\[AnswerType\]\]) – Nested list of Answers to be merged.
+- **top_k** (int | None) – The maximum number of Answers to return. Overrides the instance's `top_k` if provided.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `answers`: Merged list of Answers
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnswerJoiner
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- AnswerJoiner – The deserialized component.
+
+## branch
+
+### BranchJoiner
+
+A component that merges multiple input branches of a pipeline into a single output stream.
+
+`BranchJoiner` receives multiple inputs of the same data type and forwards the first received value
+to its output. This is useful for scenarios where multiple branches need to converge before proceeding.
+
+### Common Use Cases:
+
+- **Loop Handling:** `BranchJoiner` helps close loops in pipelines. For example, if a pipeline component validates
+ or modifies incoming data and produces an error-handling branch, `BranchJoiner` can merge both branches and send
+ (or resend in the case of a loop) the data to the component that evaluates errors. See "Usage example" below.
+
+- **Decision-Based Merging:** `BranchJoiner` reconciles branches coming from Router components (such as
+ `ConditionalRouter`, `TextLanguageRouter`). Suppose a `TextLanguageRouter` directs user queries to different
+ Retrievers based on the detected language. Each Retriever processes its assigned query and passes the results
+ to `BranchJoiner`, which consolidates them into a single output before passing them to the next component, such
+ as a `PromptBuilder`.
+
+### Example Usage:
+
+```python
+import json
+
+from haystack import Pipeline
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.joiners import BranchJoiner
+from haystack.components.validators import JsonSchemaValidator
+from haystack.dataclasses import ChatMessage
+
+# Define a schema for validation
+person_schema = {
+ "type": "object",
+ "properties": {
+ "first_name": {"type": "string", "pattern": "^[A-Z][a-z]+$"},
+ "last_name": {"type": "string", "pattern": "^[A-Z][a-z]+$"},
+ "nationality": {"type": "string", "enum": ["Italian", "Portuguese", "American"]},
+ },
+ "required": ["first_name", "last_name", "nationality"]
+}
+
+# Initialize a pipeline
+pipe = Pipeline()
+
+# Add components to the pipeline
+pipe.add_component("joiner", BranchJoiner(list[ChatMessage]))
+pipe.add_component("generator", OpenAIChatGenerator(model="gpt-4.1-mini"))
+pipe.add_component("validator", JsonSchemaValidator(json_schema=person_schema))
+
+# And connect them
+pipe.connect("joiner", "generator")
+pipe.connect("generator.replies", "validator.messages")
+pipe.connect("validator.validation_error", "joiner")
+
+result = pipe.run(
+ data={
+ "generator": {"generation_kwargs": {"response_format": {"type": "json_object"}}},
+ "joiner": {"value": [ChatMessage.from_user("Create json from Peter Parker")]}}
+)
+
+print(json.loads(result["validator"]["validated"][0].text))
+
+
+# >> {'first_name': 'Peter', 'last_name': 'Parker', 'nationality': 'American', 'name': 'Spider-Man', 'occupation':
+# >> 'Superhero', 'age': 23, 'location': 'New York City'}
+```
+
+Note that `BranchJoiner` can manage only one data type at a time. In this case, `BranchJoiner` is created for
+passing `list[ChatMessage]`. This determines the type of data that `BranchJoiner` will receive from the upstream
+connected components and also the type of data that `BranchJoiner` will send through its output.
+
+In the code example, `BranchJoiner` receives a looped back `list[ChatMessage]` from the `JsonSchemaValidator` and
+sends it down to the `OpenAIChatGenerator` for re-generation. We can have multiple loopback connections in the
+pipeline. In this instance, the downstream component is only one (the `OpenAIChatGenerator`), but the pipeline could
+have more than one downstream component.
+
+#### __init__
+
+```python
+__init__(type_: type) -> None
+```
+
+Creates a `BranchJoiner` component.
+
+**Parameters:**
+
+- **type\_** (type) – The expected data type of inputs and outputs.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component into a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> BranchJoiner
+```
+
+Deserializes a `BranchJoiner` instance from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary containing serialized component data.
+
+**Returns:**
+
+- BranchJoiner – A deserialized `BranchJoiner` instance.
+
+#### run
+
+```python
+run(**kwargs: Any) -> dict[str, Any]
+```
+
+Executes the `BranchJoiner`, selecting the first available input value and passing it downstream.
+
+**Parameters:**
+
+- \*\***kwargs** (Any) – The input data. Must be of the type declared by `type_` during initialization.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with a single key `value`, containing the first input received.
+
+## document_joiner
+
+### JoinMode
+
+Bases: Enum
+
+Enum for join mode.
+
+#### from_str
+
+```python
+from_str(string: str) -> JoinMode
+```
+
+Convert a string to a JoinMode enum.
+
+### DocumentJoiner
+
+Joins multiple lists of documents into a single list.
+
+It supports different join modes:
+
+- concatenate: Keeps the highest-scored document in case of duplicates.
+- merge: Calculates a weighted sum of scores for duplicates and merges them.
+- reciprocal_rank_fusion: Merges and assigns scores based on reciprocal rank fusion.
+- distribution_based_rank_fusion: Merges and assigns scores based on scores distribution in each Retriever.
+
+### Usage example:
+
+```python
+from haystack import Pipeline, Document
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack.components.joiners import DocumentJoiner
+from haystack.components.retrievers import InMemoryBM25Retriever
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+docs = [Document(content="Paris"), Document(content="Berlin"), Document(content="London")]
+embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+docs_embeddings = embedder.run(docs)
+document_store.write_documents(docs_embeddings['documents'])
+
+p = Pipeline()
+p.add_component(instance=InMemoryBM25Retriever(document_store=document_store), name="bm25_retriever")
+p.add_component(
+ instance=SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"),
+ name="text_embedder",
+ )
+p.add_component(instance=InMemoryEmbeddingRetriever(document_store=document_store), name="embedding_retriever")
+p.add_component(instance=DocumentJoiner(), name="joiner")
+p.connect("bm25_retriever", "joiner")
+p.connect("embedding_retriever", "joiner")
+p.connect("text_embedder", "embedding_retriever")
+query = "What is the capital of France?"
+p.run(data={"query": query, "text": query, "top_k": 1})
+```
+
+#### __init__
+
+```python
+__init__(
+ join_mode: str | JoinMode = JoinMode.CONCATENATE,
+ weights: list[float] | None = None,
+ top_k: int | None = None,
+ sort_by_score: bool = True,
+) -> None
+```
+
+Creates a DocumentJoiner component.
+
+**Parameters:**
+
+- **join_mode** (str | JoinMode) – Specifies the join mode to use. Available modes:
+- `concatenate`: Keeps the highest-scored document in case of duplicates.
+- `merge`: Calculates a weighted sum of scores for duplicates and merges them.
+- `reciprocal_rank_fusion`: Merges and assigns scores based on reciprocal rank fusion.
+- `distribution_based_rank_fusion`: Merges and assigns scores based on scores
+ distribution in each Retriever.
+- **weights** (list\[float\] | None) – Assign importance to each list of documents to influence how they're joined.
+ This parameter is ignored for
+ `concatenate` or `distribution_based_rank_fusion` join modes.
+ Weight for each list of documents must match the number of inputs.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **sort_by_score** (bool) – If `True`, sorts the documents by score in descending order.
+ If a document has no score, it is handled as if its score is -infinity.
+
+#### run
+
+```python
+run(
+ documents: Variadic[list[Document]], top_k: int | None = None
+) -> dict[str, Any]
+```
+
+Joins multiple lists of Documents into a single list depending on the `join_mode` parameter.
+
+**Parameters:**
+
+- **documents** (Variadic\[list\[Document\]\]) – List of list of documents to be merged.
+- **top_k** (int | None) – The maximum number of documents to return. Overrides the instance's `top_k` if provided.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: Merged list of Documents
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DocumentJoiner
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- DocumentJoiner – The deserialized component.
+
+## list_joiner
+
+### ListJoiner
+
+A component that joins multiple lists into a single flat list.
+
+The ListJoiner receives multiple lists of the same type and concatenates them into a single flat list.
+The output order respects the pipeline's execution sequence, with earlier inputs being added first.
+
+Usage example:
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+from haystack.components.joiners import ListJoiner
+
+
+user_message = [ChatMessage.from_user("Give a brief answer the following question: {{query}}")]
+
+feedback_prompt = """
+ You are given a question and an answer.
+ Your task is to provide a score and a brief feedback on the answer.
+ Question: {{query}}
+ Answer: {{response}}
+ """
+feedback_message = [ChatMessage.from_system(feedback_prompt)]
+
+prompt_builder = ChatPromptBuilder(template=user_message)
+feedback_prompt_builder = ChatPromptBuilder(template=feedback_message)
+llm = OpenAIChatGenerator()
+feedback_llm = OpenAIChatGenerator()
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.add_component("feedback_prompt_builder", feedback_prompt_builder)
+pipe.add_component("feedback_llm", feedback_llm)
+pipe.add_component("list_joiner", ListJoiner(list[ChatMessage]))
+
+pipe.connect("prompt_builder.prompt", "llm.messages")
+pipe.connect("prompt_builder.prompt", "list_joiner")
+pipe.connect("llm.replies", "list_joiner")
+pipe.connect("llm.replies", "feedback_prompt_builder.response")
+pipe.connect("feedback_prompt_builder.prompt", "feedback_llm.messages")
+pipe.connect("feedback_llm.replies", "list_joiner")
+
+query = "What is nuclear physics?"
+ans = pipe.run(data={"prompt_builder": {"template_variables":{"query": query}},
+ "feedback_prompt_builder": {"template_variables":{"query": query}}})
+
+print(ans["list_joiner"]["values"])
+```
+
+#### __init__
+
+```python
+__init__(list_type_: type | None = None) -> None
+```
+
+Creates a ListJoiner component.
+
+**Parameters:**
+
+- **list_type\_** (type | None) – The expected type of the lists this component will join (e.g., list[ChatMessage]).
+ If specified, all input lists must conform to this type. If None, the component defaults to handling
+ lists of any type including mixed types.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ListJoiner
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ListJoiner – Deserialized component.
+
+#### run
+
+```python
+run(values: Variadic[list[Any]]) -> dict[str, list[Any]]
+```
+
+Joins multiple lists into a single flat list.
+
+**Parameters:**
+
+- **values** (Variadic\[list\[Any\]\]) – The list to be joined.
+
+**Returns:**
+
+- dict\[str, list\[Any\]\] – Dictionary with 'values' key containing the joined list.
+
+## string_joiner
+
+### StringJoiner
+
+Component to join strings from different components to a list of strings.
+
+### Usage example
+
+```python
+from haystack.components.joiners import StringJoiner
+from haystack.components.builders import PromptBuilder
+from haystack.core.pipeline import Pipeline
+
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+string_1 = "What's Natural Language Processing?"
+string_2 = "What is life?"
+
+pipeline = Pipeline()
+pipeline.add_component("prompt_builder_1", PromptBuilder("Builder 1: {{query}}"))
+pipeline.add_component("prompt_builder_2", PromptBuilder("Builder 2: {{query}}"))
+pipeline.add_component("string_joiner", StringJoiner())
+
+pipeline.connect("prompt_builder_1.prompt", "string_joiner.strings")
+pipeline.connect("prompt_builder_2.prompt", "string_joiner.strings")
+
+print(pipeline.run(data={"prompt_builder_1": {"query": string_1}, "prompt_builder_2": {"query": string_2}}))
+
+# >> {"string_joiner": {"strings": ["Builder 1: What's Natural Language Processing?", "Builder 2: What is life?"]}}
+```
+
+#### run
+
+```python
+run(strings: Variadic[str]) -> dict[str, list[str]]
+```
+
+Joins strings into a list of strings
+
+**Parameters:**
+
+- **strings** (Variadic\[str\]) – strings from different components
+
+**Returns:**
+
+- dict\[str, list\[str\]\] – A dictionary with the following keys:
+- `strings`: Merged list of strings
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/pipeline_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/pipeline_api.md
new file mode 100644
index 0000000000..51bc892464
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/pipeline_api.md
@@ -0,0 +1,497 @@
+---
+title: "Pipeline"
+id: pipeline-api
+description: "Arranges components and integrations in flow."
+slug: "/pipeline-api"
+---
+
+
+## async_pipeline
+
+### AsyncPipeline
+
+Bases: PipelineBase
+
+Asynchronous version of the Pipeline orchestration engine.
+
+Manages components in a pipeline allowing for concurrent processing when the pipeline's execution graph permits.
+This enables efficient processing of components by minimizing idle time and maximizing resource utilization.
+
+#### run_async_generator
+
+```python
+run_async_generator(
+ data: dict[str, Any],
+ include_outputs_from: set[str] | None = None,
+ concurrency_limit: int = 4,
+) -> AsyncIterator[dict[str, Any]]
+```
+
+Executes the pipeline step by step asynchronously, yielding partial outputs when any component finishes.
+
+Usage:
+
+```python
+from haystack import Document
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack import AsyncPipeline
+import asyncio
+
+# Write documents to InMemoryDocumentStore
+document_store = InMemoryDocumentStore()
+document_store.write_documents([
+ Document(content="My name is Jean and I live in Paris."),
+ Document(content="My name is Mark and I live in Berlin."),
+ Document(content="My name is Giorgio and I live in Rome.")
+])
+
+prompt_template = [
+ ChatMessage.from_user(
+ '''
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+ Question: {{question}}
+ Answer:
+ ''')
+]
+
+# Create and connect pipeline components
+retriever = InMemoryBM25Retriever(document_store=document_store)
+prompt_builder = ChatPromptBuilder(template=prompt_template)
+llm = OpenAIChatGenerator()
+
+rag_pipeline = AsyncPipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+# Prepare input data
+question = "Who lives in Paris?"
+data = {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+}
+
+
+# Process results as they become available
+async def process_results():
+ async for partial_output in rag_pipeline.run_async_generator(
+ data=data,
+ include_outputs_from={"retriever", "llm"}
+ ):
+ # Each partial_output contains the results from a completed component
+ if "retriever" in partial_output:
+ print("Retrieved documents:", len(partial_output["retriever"]["documents"]))
+ if "llm" in partial_output:
+ print("Generated answer:", partial_output["llm"]["replies"][0])
+
+
+asyncio.run(process_results())
+```
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Initial input data to the pipeline.
+- **concurrency_limit** (int) – The maximum number of components that are allowed to run concurrently.
+- **include_outputs_from** (set\[str\] | None) – Set of component names whose individual outputs are to be
+ included in the pipeline's output. For components that are
+ invoked multiple times (in a loop), only the last-produced
+ output is included.
+
+**Returns:**
+
+- AsyncIterator\[dict\[str, Any\]\] – An async iterator containing partial (and final) outputs.
+
+**Raises:**
+
+- ValueError – If invalid inputs are provided to the pipeline.
+- PipelineMaxComponentRuns – If a component exceeds the maximum number of allowed executions within the pipeline.
+- PipelineRuntimeError – If the Pipeline contains cycles with unsupported connections that would cause
+ it to get stuck and fail running.
+ Or if a Component fails or returns output in an unsupported type.
+
+#### run_async
+
+```python
+run_async(
+ data: dict[str, Any],
+ include_outputs_from: set[str] | None = None,
+ concurrency_limit: int = 4,
+) -> dict[str, Any]
+```
+
+Provides an asynchronous interface to run the pipeline with provided input data.
+
+This method allows the pipeline to be integrated into an asynchronous workflow, enabling non-blocking
+execution of pipeline components.
+
+Usage:
+
+```python
+import asyncio
+
+from haystack import Document
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.core.pipeline import AsyncPipeline
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+# Write documents to InMemoryDocumentStore
+document_store = InMemoryDocumentStore()
+document_store.write_documents([
+ Document(content="My name is Jean and I live in Paris."),
+ Document(content="My name is Mark and I live in Berlin."),
+ Document(content="My name is Giorgio and I live in Rome.")
+])
+
+prompt_template = [
+ ChatMessage.from_user(
+ '''
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+ Question: {{question}}
+ Answer:
+ ''')
+]
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+prompt_builder = ChatPromptBuilder(template=prompt_template)
+llm = OpenAIChatGenerator()
+
+rag_pipeline = AsyncPipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+# Ask a question
+question = "Who lives in Paris?"
+
+async def run_inner(data, include_outputs_from):
+ return await rag_pipeline.run_async(data=data, include_outputs_from=include_outputs_from)
+
+data = {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+}
+
+results = asyncio.run(run_inner(data, include_outputs_from={"retriever", "llm"}))
+
+print(results["llm"]["replies"])
+# [ChatMessage(_role=dict\[str, Any\]) – A dictionary of inputs for the pipeline's components. Each key is a component name
+ and its value is a dictionary of that component's input parameters:
+
+```
+data = {
+ "comp1": {"input1": 1, "input2": 2},
+}
+```
+
+For convenience, this format is also supported when input names are unique:
+
+```
+data = {
+ "input1": 1, "input2": 2,
+}
+```
+
+- **include_outputs_from** (set\[str\] | None) – Set of component names whose individual outputs are to be
+ included in the pipeline's output. For components that are
+ invoked multiple times (in a loop), only the last-produced
+ output is included.
+- **concurrency_limit** (int) – The maximum number of components that should be allowed to run concurrently.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary where each entry corresponds to a component name
+ and its output. If `include_outputs_from` is `None`, this dictionary
+ will only contain the outputs of leaf components, i.e., components
+ without outgoing connections.
+
+**Raises:**
+
+- ValueError – If invalid inputs are provided to the pipeline.
+- PipelineRuntimeError – If the Pipeline contains cycles with unsupported connections that would cause
+ it to get stuck and fail running.
+ Or if a Component fails or returns output in an unsupported type.
+- PipelineMaxComponentRuns – If a Component reaches the maximum number of times it can be run in this Pipeline.
+
+#### run
+
+```python
+run(
+ data: dict[str, Any],
+ include_outputs_from: set[str] | None = None,
+ concurrency_limit: int = 4,
+) -> dict[str, Any]
+```
+
+Provides a synchronous interface to run the pipeline with given input data.
+
+Internally, the pipeline components are executed asynchronously, but the method itself
+will block until the entire pipeline execution is complete.
+
+In case you need asynchronous methods, consider using `run_async` or `run_async_generator`.
+
+Usage:
+
+```python
+from haystack import Document
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.core.pipeline import AsyncPipeline
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+# Write documents to InMemoryDocumentStore
+document_store = InMemoryDocumentStore()
+document_store.write_documents([
+ Document(content="My name is Jean and I live in Paris."),
+ Document(content="My name is Mark and I live in Berlin."),
+ Document(content="My name is Giorgio and I live in Rome.")
+])
+
+prompt_template = [
+ ChatMessage.from_user(
+ '''
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+ Question: {{question}}
+ Answer:
+ ''')
+]
+
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+prompt_builder = ChatPromptBuilder(template=prompt_template)
+llm = OpenAIChatGenerator()
+
+rag_pipeline = AsyncPipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+# Ask a question
+question = "Who lives in Paris?"
+
+data = {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+}
+
+results = rag_pipeline.run(data)
+
+print(results["llm"]["replies"])
+# [ChatMessage(_role=dict\[str, Any\]) – A dictionary of inputs for the pipeline's components. Each key is a component name
+ and its value is a dictionary of that component's input parameters:
+
+```
+data = {
+ "comp1": {"input1": 1, "input2": 2},
+}
+```
+
+For convenience, this format is also supported when input names are unique:
+
+```
+data = {
+ "input1": 1, "input2": 2,
+}
+```
+
+- **include_outputs_from** (set\[str\] | None) – Set of component names whose individual outputs are to be
+ included in the pipeline's output. For components that are
+ invoked multiple times (in a loop), only the last-produced
+ output is included.
+- **concurrency_limit** (int) – The maximum number of components that should be allowed to run concurrently.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary where each entry corresponds to a component name
+ and its output. If `include_outputs_from` is `None`, this dictionary
+ will only contain the outputs of leaf components, i.e., components
+ without outgoing connections.
+
+**Raises:**
+
+- ValueError – If invalid inputs are provided to the pipeline.
+- PipelineRuntimeError – If the Pipeline contains cycles with unsupported connections that would cause
+ it to get stuck and fail running.
+ Or if a Component fails or returns output in an unsupported type.
+- PipelineMaxComponentRuns – If a Component reaches the maximum number of times it can be run in this Pipeline.
+- RuntimeError – If called from within an async context. Use `run_async` instead.
+
+## pipeline
+
+### Pipeline
+
+Bases: PipelineBase
+
+Synchronous version of the orchestration engine.
+
+Orchestrates component execution according to the execution graph, one after the other.
+
+#### run
+
+```python
+run(
+ data: dict[str, Any],
+ include_outputs_from: set[str] | None = None,
+ *,
+ break_point: Breakpoint | AgentBreakpoint | None = None,
+ pipeline_snapshot: PipelineSnapshot | None = None,
+ snapshot_callback: SnapshotCallback | None = None
+) -> dict[str, Any]
+```
+
+Runs the Pipeline with given input data.
+
+Usage:
+
+```python
+from haystack import Pipeline, Document
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.utils import Secret
+
+# Write documents to InMemoryDocumentStore
+document_store = InMemoryDocumentStore()
+document_store.write_documents([
+ Document(content="My name is Jean and I live in Paris."),
+ Document(content="My name is Mark and I live in Berlin."),
+ Document(content="My name is Giorgio and I live in Rome.")
+])
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+
+prompt_template = """
+Given these documents, answer the question.
+Documents:
+{% for doc in documents %}
+ {{ doc.content }}
+{% endfor %}
+Question: {{question}}
+Answer:
+"""
+
+template = [ChatMessage.from_user(prompt_template)]
+prompt_builder = ChatPromptBuilder(
+ template=template,
+ required_variables=["question", "documents"],
+ variables=["question", "documents"]
+)
+
+llm = OpenAIChatGenerator()
+rag_pipeline = Pipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+question = "Who lives in Paris?"
+results = rag_pipeline.run(
+ {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ }
+)
+
+print(results["llm"]["replies"][0].text)
+# Jean lives in Paris
+```
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – A dictionary of inputs for the pipeline's components. Each key is a component name
+ and its value is a dictionary of that component's input parameters:
+
+```
+data = {
+ "comp1": {"input1": 1, "input2": 2},
+}
+```
+
+For convenience, this format is also supported when input names are unique:
+
+```
+data = {
+ "input1": 1, "input2": 2,
+}
+```
+
+- **include_outputs_from** (set\[str\] | None) – Set of component names whose individual outputs are to be
+ included in the pipeline's output. For components that are
+ invoked multiple times (in a loop), only the last-produced
+ output is included.
+- **break_point** (Breakpoint | AgentBreakpoint | None) – A set of breakpoints that can be used to debug the pipeline execution.
+- **pipeline_snapshot** (PipelineSnapshot | None) – A dictionary containing a snapshot of a previously saved pipeline execution.
+- **snapshot_callback** (SnapshotCallback | None) – Optional callback function that is invoked when a pipeline snapshot is created.
+ The callback receives a `PipelineSnapshot` object and can return an optional string
+ (e.g., a file path or identifier).
+ If provided, the callback is used instead of the default file-saving behavior,
+ allowing custom handling of snapshots (e.g., saving to a database, sending to a remote service).
+ If not provided, the default behavior saves snapshots to a JSON file.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary where each entry corresponds to a component name
+ and its output. If `include_outputs_from` is `None`, this dictionary
+ will only contain the outputs of leaf components, i.e., components
+ without outgoing connections.
+
+**Raises:**
+
+- ValueError – If invalid inputs are provided to the pipeline.
+- PipelineRuntimeError – If the Pipeline contains cycles with unsupported connections that would cause
+ it to get stuck and fail running.
+ Or if a Component fails or returns output in an unsupported type.
+- PipelineMaxComponentRuns – If a Component reaches the maximum number of times it can be run in this Pipeline.
+- PipelineBreakpointException – When a pipeline_breakpoint is triggered. Contains the component name, state, and partial results.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/preprocessors_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/preprocessors_api.md
new file mode 100644
index 0000000000..4086475706
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/preprocessors_api.md
@@ -0,0 +1,992 @@
+---
+title: "PreProcessors"
+id: preprocessors-api
+description: "Preprocess your Documents and texts. Clean, split, and more."
+slug: "/preprocessors-api"
+---
+
+
+## csv_document_cleaner
+
+### CSVDocumentCleaner
+
+A component for cleaning CSV documents by removing empty rows and columns.
+
+This component processes CSV content stored in Documents, allowing
+for the optional ignoring of a specified number of rows and columns before performing
+the cleaning operation. Additionally, it provides options to keep document IDs and
+control whether empty rows and columns should be removed.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ ignore_rows: int = 0,
+ ignore_columns: int = 0,
+ remove_empty_rows: bool = True,
+ remove_empty_columns: bool = True,
+ keep_id: bool = False
+) -> None
+```
+
+Initializes the CSVDocumentCleaner component.
+
+**Parameters:**
+
+- **ignore_rows** (int) – Number of rows to ignore from the top of the CSV table before processing.
+- **ignore_columns** (int) – Number of columns to ignore from the left of the CSV table before processing.
+- **remove_empty_rows** (bool) – Whether to remove rows that are entirely empty.
+- **remove_empty_columns** (bool) – Whether to remove columns that are entirely empty.
+- **keep_id** (bool) – Whether to retain the original document ID in the output document.
+
+Rows and columns ignored using these parameters are preserved in the final output, meaning
+they are not considered when removing empty rows and columns.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Cleans CSV documents by removing empty rows and columns while preserving specified ignored rows and columns.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents containing CSV-formatted content.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with a list of cleaned Documents under the key "documents".
+
+Processing steps:
+
+1. Reads each document's content as a CSV table.
+1. Retains the specified number of `ignore_rows` from the top and `ignore_columns` from the left.
+1. Drops any rows and columns that are entirely empty (if enabled by `remove_empty_rows` and
+ `remove_empty_columns`).
+1. Reattaches the ignored rows and columns to maintain their original positions.
+1. Returns the cleaned CSV content as a new `Document` object, with an option to retain the original
+ document ID.
+
+## csv_document_splitter
+
+### CSVDocumentSplitter
+
+A component for splitting CSV documents into sub-tables based on split arguments.
+
+The splitter supports two modes of operation:
+
+- identify consecutive empty rows or columns that exceed a given threshold
+ and uses them as delimiters to segment the document into smaller tables.
+- split each row into a separate sub-table, represented as a Document.
+
+#### __init__
+
+```python
+__init__(
+ row_split_threshold: int | None = 2,
+ column_split_threshold: int | None = 2,
+ read_csv_kwargs: dict[str, Any] | None = None,
+ split_mode: SplitMode = "threshold",
+) -> None
+```
+
+Initializes the CSVDocumentSplitter component.
+
+**Parameters:**
+
+- **row_split_threshold** (int | None) – The minimum number of consecutive empty rows required to trigger a split.
+- **column_split_threshold** (int | None) – The minimum number of consecutive empty columns required to trigger a split.
+- **read_csv_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments to pass to `pandas.read_csv`.
+ By default, the component with options:
+- `header=None`
+- `skip_blank_lines=False` to preserve blank lines
+- `dtype=object` to prevent type inference (e.g., converting numbers to floats).
+ See https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html for more information.
+- **split_mode** (SplitMode) – If `threshold`, the component will split the document based on the number of
+ consecutive empty rows or columns that exceed the `row_split_threshold` or `column_split_threshold`.
+ If `row-wise`, the component will split each row into a separate sub-table.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Processes and splits a list of CSV documents into multiple sub-tables.
+
+**Splitting Process:**
+
+1. Applies a row-based split if `row_split_threshold` is provided.
+1. Applies a column-based split if `column_split_threshold` is provided.
+1. If both thresholds are specified, performs a recursive split by rows first, then columns, ensuring
+ further fragmentation of any sub-tables that still contain empty sections.
+1. Sorts the resulting sub-tables based on their original positions within the document.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents containing CSV-formatted content.
+ Each document is assumed to contain one or more tables separated by empty rows or columns.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with a key `"documents"`, mapping to a list of new `Document` objects,
+ each representing an extracted sub-table from the original CSV.
+ The metadata of each document includes:
+ \- A field `source_id` to track the original document.
+ \- A field `row_idx_start` to indicate the starting row index of the sub-table in the original table.
+ \- A field `col_idx_start` to indicate the starting column index of the sub-table in the original table.
+ \- A field `split_id` to indicate the order of the split in the original document.
+ \- All other metadata copied from the original document.
+
+- If a document cannot be processed, it is returned unchanged.
+
+- The `meta` field from the original document is preserved in the split documents.
+
+## document_cleaner
+
+### DocumentCleaner
+
+Cleans the text in the documents.
+
+It removes extra whitespaces,
+empty lines, specified substrings, regexes,
+page headers and footers (in this order).
+
+### Usage example:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentCleaner
+
+doc = Document(content="This is a document to clean\n\n\nsubstring to remove")
+
+cleaner = DocumentCleaner(remove_substrings = ["substring to remove"])
+result = cleaner.run(documents=[doc])
+
+assert result["documents"][0].content == "This is a document to clean "
+```
+
+#### __init__
+
+```python
+__init__(
+ remove_empty_lines: bool = True,
+ remove_extra_whitespaces: bool = True,
+ remove_repeated_substrings: bool = False,
+ keep_id: bool = False,
+ remove_substrings: list[str] | None = None,
+ remove_regex: str | None = None,
+ unicode_normalization: Literal["NFC", "NFKC", "NFD", "NFKD"] | None = None,
+ ascii_only: bool = False,
+ strip_whitespaces: bool = False,
+ replace_regexes: dict[str, str] | None = None,
+) -> None
+```
+
+Initialize DocumentCleaner.
+
+**Parameters:**
+
+- **remove_empty_lines** (bool) – If `True`, removes empty lines.
+- **remove_extra_whitespaces** (bool) – If `True`, removes extra whitespaces.
+- **remove_repeated_substrings** (bool) – If `True`, removes repeated substrings (headers and footers) from pages.
+ Pages must be separated by a form feed character "\\f",
+ which is supported by `TextFileToDocument` and `AzureOCRDocumentConverter`.
+- **remove_substrings** (list\[str\] | None) – List of substrings to remove from the text.
+- **remove_regex** (str | None) – Regex to match and replace substrings by "".
+- **keep_id** (bool) – If `True`, keeps the IDs of the original documents.
+- **unicode_normalization** (Literal['NFC', 'NFKC', 'NFD', 'NFKD'] | None) – Unicode normalization form to apply to the text.
+ Note: This will run before any other steps.
+- **ascii_only** (bool) – Whether to convert the text to ASCII only.
+ Will remove accents from characters and replace them with ASCII characters.
+ Other non-ASCII characters will be removed.
+ Note: This will run before any pattern matching or removal.
+- **strip_whitespaces** (bool) – If `True`, removes leading and trailing whitespace from the document content
+ using Python's `str.strip()`. Unlike `remove_extra_whitespaces`, this only affects the beginning
+ and end of the text, preserving internal whitespace (useful for markdown formatting).
+- **replace_regexes** (dict\[str, str\] | None) – A dictionary mapping regex patterns to their replacement strings.
+ For example, `{r'\n\n+': '\n'}` replaces multiple consecutive newlines with a single newline.
+ This is applied after `remove_regex` and allows custom replacements instead of just removal.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Cleans up the documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents to clean.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following key:
+- `documents`: List of cleaned Documents.
+
+**Raises:**
+
+- TypeError – if documents is not a list of Documents.
+
+## document_preprocessor
+
+### DocumentPreprocessor
+
+A SuperComponent that first splits and then cleans documents.
+
+This component consists of a DocumentSplitter followed by a DocumentCleaner in a single pipeline.
+It takes a list of documents as input and returns a processed list of documents.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentPreprocessor
+
+doc = Document(content="I love pizza!")
+preprocessor = DocumentPreprocessor()
+result = preprocessor.run(documents=[doc])
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ split_by: Literal[
+ "function", "page", "passage", "period", "word", "line", "sentence"
+ ] = "word",
+ split_length: int = 250,
+ split_overlap: int = 0,
+ split_threshold: int = 0,
+ splitting_function: Callable[[str], list[str]] | None = None,
+ respect_sentence_boundary: bool = False,
+ language: Language = "en",
+ use_split_rules: bool = True,
+ extend_abbreviations: bool = True,
+ remove_empty_lines: bool = True,
+ remove_extra_whitespaces: bool = True,
+ remove_repeated_substrings: bool = False,
+ keep_id: bool = False,
+ remove_substrings: list[str] | None = None,
+ remove_regex: str | None = None,
+ unicode_normalization: Literal["NFC", "NFKC", "NFD", "NFKD"] | None = None,
+ ascii_only: bool = False
+) -> None
+```
+
+Initialize a DocumentPreProcessor that first splits and then cleans documents.
+
+**Splitter Parameters**:
+
+**Parameters:**
+
+- **split_by** (Literal['function', 'page', 'passage', 'period', 'word', 'line', 'sentence']) – The unit of splitting: "function", "page", "passage", "period", "word", "line", or "sentence".
+- **split_length** (int) – The maximum number of units (words, lines, pages, and so on) in each split.
+- **split_overlap** (int) – The number of overlapping units between consecutive splits.
+- **split_threshold** (int) – The minimum number of units per split. If a split is smaller than this, it's merged
+ with the previous split.
+- **splitting_function** (Callable\\[[str\], list\[str\]\] | None) – A custom function for splitting if `split_by="function"`.
+- **respect_sentence_boundary** (bool) – If `True`, splits by words but tries not to break inside a sentence.
+- **language** (Language) – Language used by the sentence tokenizer if `split_by="sentence"` or
+ `respect_sentence_boundary=True`.
+- **use_split_rules** (bool) – Whether to apply additional splitting heuristics for the sentence splitter.
+- **extend_abbreviations** (bool) – Whether to extend the sentence splitter with curated abbreviations for certain
+ languages.
+
+**Cleaner Parameters**:
+
+- **remove_empty_lines** (bool) – If `True`, removes empty lines.
+- **remove_extra_whitespaces** (bool) – If `True`, removes extra whitespaces.
+- **remove_repeated_substrings** (bool) – If `True`, removes repeated substrings like headers/footers across pages.
+- **keep_id** (bool) – If `True`, keeps the original document IDs.
+- **remove_substrings** (list\[str\] | None) – A list of strings to remove from the document content.
+- **remove_regex** (str | None) – A regex pattern whose matches will be removed from the document content.
+- **unicode_normalization** (Literal['NFC', 'NFKC', 'NFD', 'NFKD'] | None) – Unicode normalization form to apply to the text, for example `"NFC"`.
+- **ascii_only** (bool) – If `True`, converts text to ASCII only.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize SuperComponent to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DocumentPreprocessor
+```
+
+Deserializes the SuperComponent from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- DocumentPreprocessor – Deserialized SuperComponent.
+
+## document_splitter
+
+### DocumentSplitter
+
+Splits long documents into smaller chunks.
+
+This is a common preprocessing step during indexing. It helps Embedders create meaningful semantic representations
+and prevents exceeding language model context limits.
+
+The DocumentSplitter is compatible with the following DocumentStores:
+
+- [Astra](https://docs.haystack.deepset.ai/docs/astradocumentstore)
+- [Chroma](https://docs.haystack.deepset.ai/docs/chromadocumentstore) limited support, overlapping information is
+ not stored
+- [Elasticsearch](https://docs.haystack.deepset.ai/docs/elasticsearch-document-store)
+- [OpenSearch](https://docs.haystack.deepset.ai/docs/opensearch-document-store)
+- [Pgvector](https://docs.haystack.deepset.ai/docs/pgvectordocumentstore)
+- [Pinecone](https://docs.haystack.deepset.ai/docs/pinecone-document-store) limited support, overlapping
+ information is not stored
+- [Qdrant](https://docs.haystack.deepset.ai/docs/qdrant-document-store)
+- [Weaviate](https://docs.haystack.deepset.ai/docs/weaviatedocumentstore)
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentSplitter
+
+doc = Document(content="Moonlight shimmered softly, wolves howled nearby, night enveloped everything.")
+
+splitter = DocumentSplitter(split_by="word", split_length=3, split_overlap=0)
+result = splitter.run(documents=[doc])
+```
+
+#### __init__
+
+```python
+__init__(
+ split_by: Literal[
+ "function", "page", "passage", "period", "word", "line", "sentence"
+ ] = "word",
+ split_length: int = 200,
+ split_overlap: int = 0,
+ split_threshold: int = 0,
+ splitting_function: Callable[[str], list[str]] | None = None,
+ respect_sentence_boundary: bool = False,
+ language: Language = "en",
+ use_split_rules: bool = True,
+ extend_abbreviations: bool = True,
+ *,
+ skip_empty_documents: bool = True
+) -> None
+```
+
+Initialize DocumentSplitter.
+
+**Parameters:**
+
+- **split_by** (Literal['function', 'page', 'passage', 'period', 'word', 'line', 'sentence']) – The unit for splitting your documents. Choose from:
+- `word` for splitting by spaces (" ")
+- `period` for splitting by periods (".")
+- `page` for splitting by form feed ("\\f")
+- `passage` for splitting by double line breaks ("\\n\\n")
+- `line` for splitting each line ("\\n")
+- `sentence` for splitting by NLTK sentence tokenizer
+- **split_length** (int) – The maximum number of units in each split.
+- **split_overlap** (int) – The number of overlapping units for each split.
+- **split_threshold** (int) – The minimum number of units per split. If a split has fewer units
+ than the threshold, it's attached to the previous split.
+- **splitting_function** (Callable\\[[str\], list\[str\]\] | None) – Necessary when `split_by` is set to "function".
+ This is a function which must accept a single `str` as input and return a `list` of `str` as output,
+ representing the chunks after splitting.
+- **respect_sentence_boundary** (bool) – Choose whether to respect sentence boundaries when splitting by "word".
+ If True, uses NLTK to detect sentence boundaries, ensuring splits occur only between sentences.
+- **language** (Language) – Choose the language for the NLTK tokenizer. The default is English ("en").
+- **use_split_rules** (bool) – Choose whether to use additional split rules when splitting by `sentence`.
+- **extend_abbreviations** (bool) – Choose whether to extend NLTK's PunktTokenizer abbreviations with a list
+ of curated abbreviations, if available. This is currently supported for English ("en") and German ("de").
+- **skip_empty_documents** (bool) – Choose whether to skip documents with empty content. Default is True.
+ Set to False when downstream components in the Pipeline (like LLMDocumentContentExtractor) can extract text
+ from non-textual documents.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the DocumentSplitter by loading the sentence tokenizer.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Split documents into smaller parts.
+
+Splits documents by the unit expressed in `split_by`, with a length of `split_length`
+and an overlap of `split_overlap`.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The documents to split.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following key:
+- `documents`: List of documents with the split texts. Each document includes:
+ - A metadata field `source_id` to track the original document.
+ - A metadata field `page_number` to track the original page number.
+ - All other metadata copied from the original document.
+
+**Raises:**
+
+- TypeError – if the input is not a list of Documents.
+- ValueError – if the content of a document is None.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+## embedding_based_document_splitter
+
+### EmbeddingBasedDocumentSplitter
+
+Splits documents based on embedding similarity using cosine distances between sequential sentence groups.
+
+This component first splits text into sentences, optionally groups them, calculates embeddings for each group,
+and then uses cosine distance between sequential embeddings to determine split points. Any distance above
+the specified percentile is treated as a break point. The component also tracks page numbers based on form feed
+characters (` `) in the original document.
+
+This component is inspired by [5 Levels of Text Splitting](https://github.com/FullStackRetrieval-com/RetrievalTutorials/blob/main/tutorials/LevelsOfTextSplitting/5_Levels_Of_Text_Splitting.ipynb) by Greg Kamradt.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+from haystack.components.preprocessors import EmbeddingBasedDocumentSplitter
+
+# Create a document with content that has a clear topic shift
+doc = Document(
+ content="This is a first sentence. This is a second sentence. This is a third sentence. "
+ "Completely different topic. The same completely different topic."
+)
+
+# Initialize the embedder to calculate semantic similarities
+embedder = SentenceTransformersDocumentEmbedder()
+
+# Configure the splitter with parameters that control splitting behavior
+splitter = EmbeddingBasedDocumentSplitter(
+ document_embedder=embedder,
+ sentences_per_group=2, # Group 2 sentences before calculating embeddings
+ percentile=0.95, # Split when cosine distance exceeds 95th percentile
+ min_length=50, # Merge splits shorter than 50 characters
+ max_length=1000 # Further split chunks longer than 1000 characters
+)
+result = splitter.run(documents=[doc])
+
+# The result contains a list of Document objects, each representing a semantic chunk
+# Each split document includes metadata: source_id, split_id, and page_number
+print(f"Original document split into {len(result['documents'])} chunks")
+for i, split_doc in enumerate(result['documents']):
+ print(f"Chunk {i}: {split_doc.content[:50]}...")
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_embedder: DocumentEmbedder,
+ sentences_per_group: int = 3,
+ percentile: float = 0.95,
+ min_length: int = 50,
+ max_length: int = 1000,
+ language: Language = "en",
+ use_split_rules: bool = True,
+ extend_abbreviations: bool = True
+) -> None
+```
+
+Initialize EmbeddingBasedDocumentSplitter.
+
+**Parameters:**
+
+- **document_embedder** (DocumentEmbedder) – The DocumentEmbedder to use for calculating embeddings.
+- **sentences_per_group** (int) – Number of sentences to group together before embedding.
+- **percentile** (float) – Percentile threshold for cosine distance. Distances above this percentile
+ are treated as break points.
+- **min_length** (int) – Minimum length of splits in characters. Splits below this length will be merged.
+- **max_length** (int) – Maximum length of splits in characters. Splits above this length will be recursively split.
+- **language** (Language) – Language for sentence tokenization.
+- **use_split_rules** (bool) – Whether to use additional split rules for sentence tokenization. Applies additional
+ split rules from SentenceSplitter to the sentence spans.
+- **extend_abbreviations** (bool) – If True, the abbreviations used by NLTK's PunktTokenizer are extended by a list
+ of curated abbreviations. Currently supported languages are: en, de.
+ If False, the default abbreviations are used.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the component by initializing the sentence splitter.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Split documents based on embedding similarity.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The documents to split.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following key:
+- `documents`: List of documents with the split texts. Each document includes:
+ - A metadata field `source_id` to track the original document.
+ - A metadata field `split_id` to track the split number.
+ - A metadata field `page_number` to track the original page number.
+ - All other metadata copied from the original document.
+
+**Raises:**
+
+- RuntimeError – If the component wasn't warmed up.
+- TypeError – If the input is not a list of Documents.
+- ValueError – If the document content is None or empty.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Asynchronously split documents based on embedding similarity.
+
+This is the asynchronous version of the `run` method with the same parameters and return values.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The documents to split.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following key:
+- `documents`: List of documents with the split texts. Each document includes:
+ - A metadata field `source_id` to track the original document.
+ - A metadata field `split_id` to track the split number.
+ - A metadata field `page_number` to track the original page number.
+ - All other metadata copied from the original document.
+
+**Raises:**
+
+- RuntimeError – If the component wasn't warmed up.
+- TypeError – If the input is not a list of Documents.
+- ValueError – If the document content is None or empty.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized dictionary representation of the component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> EmbeddingBasedDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize and create the component.
+
+**Returns:**
+
+- EmbeddingBasedDocumentSplitter – The deserialized component.
+
+## hierarchical_document_splitter
+
+### HierarchicalDocumentSplitter
+
+Splits a documents into different block sizes building a hierarchical tree structure of blocks of different sizes.
+
+The root node of the tree is the original document, the leaf nodes are the smallest blocks. The blocks in between
+are connected such that the smaller blocks are children of the parent-larger blocks.
+
+## Usage example
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import HierarchicalDocumentSplitter
+
+doc = Document(content="This is a simple test document")
+splitter = HierarchicalDocumentSplitter(block_sizes={3, 2}, split_overlap=0, split_by="word")
+splitter.run([doc])
+# >> {'documents': [Document(id=3f7..., content: 'This is a simple test document', meta: {'block_size': 0, 'parent_id': None, 'children_ids': ['5ff..', '8dc..'], 'level': 0}),
+# >> Document(id=5ff.., content: 'This is a ', meta: {'block_size': 3, 'parent_id': '3f7..', 'children_ids': ['f19..', '52c..'], 'level': 1, 'source_id': '3f7..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+# >> Document(id=8dc.., content: 'simple test document', meta: {'block_size': 3, 'parent_id': '3f7..', 'children_ids': ['39d..', 'e23..'], 'level': 1, 'source_id': '3f7..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 10}),
+# >> Document(id=f19.., content: 'This is ', meta: {'block_size': 2, 'parent_id': '5ff..', 'children_ids': [], 'level': 2, 'source_id': '5ff..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+# >> Document(id=52c.., content: 'a ', meta: {'block_size': 2, 'parent_id': '5ff..', 'children_ids': [], 'level': 2, 'source_id': '5ff..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 8}),
+# >> Document(id=39d.., content: 'simple test ', meta: {'block_size': 2, 'parent_id': '8dc..', 'children_ids': [], 'level': 2, 'source_id': '8dc..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+# >> Document(id=e23.., content: 'document', meta: {'block_size': 2, 'parent_id': '8dc..', 'children_ids': [], 'level': 2, 'source_id': '8dc..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 12})]}
+```
+
+#### __init__
+
+```python
+__init__(
+ block_sizes: set[int],
+ split_overlap: int = 0,
+ split_by: Literal["word", "sentence", "page", "passage"] = "word",
+) -> None
+```
+
+Initialize HierarchicalDocumentSplitter.
+
+**Parameters:**
+
+- **block_sizes** (set\[int\]) – Set of block sizes to split the document into. The blocks are split in descending order.
+- **split_overlap** (int) – The number of overlapping units for each split.
+- **split_by** (Literal['word', 'sentence', 'page', 'passage']) – The unit for splitting your documents.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Builds a hierarchical document structure for each document in a list of documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents to split into hierarchical blocks.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – List of HierarchicalDocument
+
+#### build_hierarchy_from_doc
+
+```python
+build_hierarchy_from_doc(document: Document) -> list[Document]
+```
+
+Build a hierarchical tree document structure from a single document.
+
+Given a document, this function splits the document into hierarchical blocks of different sizes represented
+as HierarchicalDocument objects.
+
+**Parameters:**
+
+- **document** (Document) – Document to split into hierarchical blocks.
+
+**Returns:**
+
+- list\[Document\] – List of HierarchicalDocument
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the component.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized dictionary representation of the component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HierarchicalDocumentSplitter
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize and create the component.
+
+**Returns:**
+
+- HierarchicalDocumentSplitter – The deserialized component.
+
+## markdown_header_splitter
+
+### MarkdownHeaderSplitter
+
+Split documents at ATX-style Markdown headers (#), with optional secondary splitting.
+
+This component processes text documents by:
+
+- Splitting them into chunks at Markdown headers (e.g., '#', '##', etc.), preserving header hierarchy as metadata.
+- Optionally applying a secondary split (by word, passage, period, or line) to each chunk
+ (using haystack's DocumentSplitter).
+- Preserving and propagating metadata such as parent headers, page numbers, and split IDs.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ page_break_character: str = "\x0c",
+ keep_headers: bool = True,
+ header_split_levels: list[int] | None = None,
+ secondary_split: Literal["word", "passage", "period", "line"] | None = None,
+ split_length: int = 200,
+ split_overlap: int = 0,
+ split_threshold: int = 0,
+ skip_empty_documents: bool = True
+) -> None
+```
+
+Initialize the MarkdownHeaderSplitter.
+
+**Parameters:**
+
+- **page_break_character** (str) – Character used to identify page breaks. Defaults to form feed (" ").
+- **keep_headers** (bool) – If True, headers are kept in the content. If False, headers are moved to metadata.
+ Defaults to True.
+- **header_split_levels** (list\[int\] | None) – List of header levels (1–6) to split on. For example, `[1, 2]` splits only
+ on `#` and `##` headers, merging content under deeper headers into the preceding chunk. Defaults to
+ all levels `[1, 2, 3, 4, 5, 6]`.
+- **secondary_split** (Literal['word', 'passage', 'period', 'line'] | None) – Optional secondary split condition after header splitting.
+ Options are None, "word", "passage", "period", "line". Defaults to None.
+- **split_length** (int) – The maximum number of units in each split when using secondary splitting. Defaults to 200.
+- **split_overlap** (int) – The number of overlapping units for each split when using secondary splitting.
+ Defaults to 0.
+- **split_threshold** (int) – The minimum number of units per split when using secondary splitting. Defaults to 0.
+- **skip_empty_documents** (bool) – Choose whether to skip documents with empty content. Default is True.
+ Set to False when downstream components in the Pipeline (like LLMDocumentContentExtractor) can extract text
+ from non-textual documents.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the MarkdownHeaderSplitter.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Run the markdown header splitter with optional secondary splitting.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of documents to split
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following key:
+- `documents`: List of documents with the split texts. Each document includes:
+ - A metadata field `source_id` to track the original document.
+ - A metadata field `page_number` to track the original page number.
+ - A metadata field `split_id` to identify the split chunk index within its parent document.
+ - All other metadata copied from the original document.
+
+**Raises:**
+
+- ValueError – If a document has `None` content.
+- TypeError – If a document's content is not a string.
+
+## recursive_splitter
+
+### RecursiveDocumentSplitter
+
+Recursively chunk text into smaller chunks.
+
+This component is used to split text into smaller chunks, it does so by recursively applying a list of separators
+to the text.
+
+The separators are applied in the order they are provided, typically this is a list of separators that are
+applied in a specific order, being the last separator the most specific one.
+
+Each separator is applied to the text, it then checks each of the resulting chunks, it keeps the chunks that
+are within the split_length, for the ones that are larger than the split_length, it applies the next separator in the
+list to the remaining text.
+
+This is done until all chunks are smaller than the split_length parameter.
+
+Example:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import RecursiveDocumentSplitter
+
+chunker = RecursiveDocumentSplitter(split_length=260, split_overlap=0, separators=["\n\n", "\n", ".", " "])
+text = ('''Artificial intelligence (AI) - Introduction
+
+AI, in its broadest sense, is intelligence exhibited by machines, particularly computer systems.
+AI technology is widely used throughout industry, government, and science. Some high-profile applications include advanced web search engines; recommendation systems; interacting via human speech; autonomous vehicles; generative and creative tools; and superhuman play and analysis in strategy games.''')
+doc = Document(content=text)
+doc_chunks = chunker.run([doc])
+print(doc_chunks["documents"])
+# [
+# Document(id=..., content: 'Artificial intelligence (AI) - Introduction\n\n', meta: {'original_id': '...', 'split_id': 0, 'split_idx_start': 0, '_split_overlap': []})
+# Document(id=..., content: 'AI, in its broadest sense, is intelligence exhibited by machines, particularly computer systems.\n', meta: {'original_id': '...', 'split_id': 1, 'split_idx_start': 45, '_split_overlap': []})
+# Document(id=..., content: 'AI technology is widely used throughout industry, government, and science.', meta: {'original_id': '...', 'split_id': 2, 'split_idx_start': 142, '_split_overlap': []})
+# Document(id=..., content: ' Some high-profile applications include advanced web search engines; recommendation systems; interac...', meta: {'original_id': '...', 'split_id': 3, 'split_idx_start': 216, '_split_overlap': []})
+# ]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ split_length: int = 200,
+ split_overlap: int = 0,
+ split_unit: Literal["word", "char", "token"] = "word",
+ separators: list[str] | None = None,
+ sentence_splitter_params: dict[str, Any] | None = None
+) -> None
+```
+
+Initializes a RecursiveDocumentSplitter.
+
+**Parameters:**
+
+- **split_length** (int) – The maximum length of each chunk by default in words, but can be in characters or tokens.
+ See the `split_units` parameter.
+- **split_overlap** (int) – The number of characters to overlap between consecutive chunks.
+- **split_unit** (Literal['word', 'char', 'token']) – The unit of the split_length parameter. It can be either "word", "char", or "token".
+ If "token" is selected, the text will be split into tokens using the tiktoken tokenizer (o200k_base).
+- **separators** (list\[str\] | None) – An optional list of separator strings to use for splitting the text. The string
+ separators will be treated as regular expressions unless the separator is "sentence", in that case the
+ text will be split into sentences using a custom sentence tokenizer based on NLTK.
+ See: haystack.components.preprocessors.sentence_tokenizer.SentenceSplitter.
+ If no separators are provided, the default separators ["\\n\\n", "sentence", "\\n", " "] are used.
+- **sentence_splitter_params** (dict\[str, Any\] | None) – Optional parameters to pass to the sentence tokenizer.
+ See: haystack.components.preprocessors.sentence_tokenizer.SentenceSplitter for more information.
+
+**Raises:**
+
+- ValueError – If the overlap is greater than or equal to the chunk size or if the overlap is negative, or
+ if any separator is not a string.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the sentence tokenizer and tiktoken tokenizer if needed.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Split a list of documents into documents with smaller chunks of text.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents to split.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing a key "documents" with a List of Documents with smaller chunks of text corresponding
+ to the input documents.
+
+## text_cleaner
+
+### TextCleaner
+
+Cleans text strings.
+
+It can remove substrings matching a list of regular expressions, convert text to lowercase,
+remove punctuation, and remove numbers.
+Use it to clean up text data before evaluation.
+
+### Usage example
+
+```python
+from haystack.components.preprocessors import TextCleaner
+
+text_to_clean = "1Moonlight shimmered softly, 300 Wolves howled nearby, Night enveloped everything."
+
+cleaner = TextCleaner(convert_to_lowercase=True, remove_punctuation=False, remove_numbers=True)
+result = cleaner.run(texts=[text_to_clean])
+```
+
+#### __init__
+
+```python
+__init__(
+ remove_regexps: list[str] | None = None,
+ convert_to_lowercase: bool = False,
+ remove_punctuation: bool = False,
+ remove_numbers: bool = False,
+) -> None
+```
+
+Initializes the TextCleaner component.
+
+**Parameters:**
+
+- **remove_regexps** (list\[str\] | None) – A list of regex patterns to remove matching substrings from the text.
+- **convert_to_lowercase** (bool) – If `True`, converts all characters to lowercase.
+- **remove_punctuation** (bool) – If `True`, removes punctuation from the text.
+- **remove_numbers** (bool) – If `True`, removes numerical digits from the text.
+
+#### run
+
+```python
+run(texts: list[str]) -> dict[str, Any]
+```
+
+Cleans up the given list of strings.
+
+**Parameters:**
+
+- **texts** (list\[str\]) – List of strings to clean.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following key:
+- `texts`: the cleaned list of strings.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/query_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/query_api.md
new file mode 100644
index 0000000000..8021c22cd0
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/query_api.md
@@ -0,0 +1,129 @@
+---
+title: "Query"
+id: query-api
+description: "Components for query processing and expansion."
+slug: "/query-api"
+---
+
+
+## query_expander
+
+### QueryExpander
+
+A component that returns a list of semantically similar queries to improve retrieval recall in RAG systems.
+
+The component uses a chat generator to expand queries. The chat generator is expected to return a JSON response
+with the following structure:
+
+```json
+{"queries": ["expanded query 1", "expanded query 2", "expanded query 3"]}
+```
+
+### Usage example
+
+```python
+from haystack.components.generators.chat.openai import OpenAIChatGenerator
+from haystack.components.query import QueryExpander
+
+expander = QueryExpander(
+ chat_generator=OpenAIChatGenerator(model="gpt-4.1-mini"),
+ n_expansions=3
+)
+
+result = expander.run(query="green energy sources")
+print(result["queries"])
+# Output: ['alternative query 1', 'alternative query 2', 'alternative query 3', 'green energy sources']
+# Note: Up to 3 additional queries + 1 original query (if include_original_query=True)
+
+# To control total number of queries:
+expander = QueryExpander(n_expansions=2, include_original_query=True) # Up to 3 total
+# or
+expander = QueryExpander(n_expansions=3, include_original_query=False) # Exactly 3 total
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ chat_generator: ChatGenerator | None = None,
+ prompt_template: str | None = None,
+ n_expansions: int = 4,
+ include_original_query: bool = True
+) -> None
+```
+
+Initialize the QueryExpander component.
+
+**Parameters:**
+
+- **chat_generator** (ChatGenerator | None) – The chat generator component to use for query expansion.
+ If None, a default OpenAIChatGenerator with gpt-4.1-mini model is used.
+- **prompt_template** (str | None) – Custom [PromptBuilder](https://docs.haystack.deepset.ai/docs/promptbuilder)
+ template for query expansion. The template should instruct the LLM to return a JSON response with the
+ structure: `{"queries": ["query1", "query2", "query3"]}`. The template should include 'query' and
+ 'n_expansions' variables.
+- **n_expansions** (int) – Number of alternative queries to generate (default: 4).
+- **include_original_query** (bool) – Whether to include the original query in the output.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> QueryExpander
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary with serialized data.
+
+**Returns:**
+
+- QueryExpander – Deserialized component.
+
+#### run
+
+```python
+run(query: str, n_expansions: int | None = None) -> dict[str, list[str]]
+```
+
+Expand the input query into multiple semantically similar queries.
+
+The language of the original query is preserved in the expanded queries.
+
+**Parameters:**
+
+- **query** (str) – The original query to expand.
+- **n_expansions** (int | None) – Number of additional queries to generate (not including the original).
+ If None, uses the value from initialization. Can be 0 to generate no additional queries.
+
+**Returns:**
+
+- dict\[str, list\[str\]\] – Dictionary with "queries" key containing the list of expanded queries.
+ If include_original_query=True, the original query will be included in addition
+ to the n_expansions alternative queries.
+
+**Raises:**
+
+- ValueError – If n_expansions is not positive (less than or equal to 0).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the LLM provider component.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/rankers_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/rankers_api.md
new file mode 100644
index 0000000000..f656899d2f
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/rankers_api.md
@@ -0,0 +1,1158 @@
+---
+title: "Rankers"
+id: rankers-api
+description: "Reorders a set of Documents based on their relevance to the query."
+slug: "/rankers-api"
+---
+
+
+## hugging_face_tei
+
+### TruncationDirection
+
+Bases: str, Enum
+
+Defines the direction to truncate text when input length exceeds the model's limit.
+
+Attributes:
+LEFT: Truncate text from the left side (start of text).
+RIGHT: Truncate text from the right side (end of text).
+
+### HuggingFaceTEIRanker
+
+Ranks documents based on their semantic similarity to the query.
+
+It can be used with a Text Embeddings Inference (TEI) API endpoint:
+
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+- [Hugging Face Inference Endpoints](https://huggingface.co/inference-endpoints)
+
+Usage example:
+
+
+
+```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)]}
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ url: str,
+ top_k: int = 10,
+ raw_scores: bool = False,
+ timeout: int | None = 30,
+ max_retries: int = 3,
+ retry_status_codes: list[int] | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ )
+) -> None
+```
+
+Initializes the TEI reranker component.
+
+**Parameters:**
+
+- **url** (str) – Base URL of the TEI reranking service (for example, "https://api.example.com").
+- **top_k** (int) – Maximum number of top documents to return.
+- **raw_scores** (bool) – If True, include raw relevance scores in the API payload.
+- **timeout** (int | None) – Request timeout in seconds.
+- **max_retries** (int) – Maximum number of retry attempts for failed requests.
+- **retry_status_codes** (list\[int\] | None) – List of HTTP status codes that will trigger a retry.
+ When None, HTTP 408, 418, 429 and 503 will be retried (default: None).
+- **token** (Secret | None) – The Hugging Face token to use as HTTP bearer authorization. Not always required
+ depending on your TEI server configuration.
+ Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceTEIRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- HuggingFaceTEIRanker – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ documents: list[Document],
+ top_k: int | None = None,
+ truncation_direction: TruncationDirection | None = None,
+) -> dict[str, list[Document]]
+```
+
+Reranks the provided documents by relevance to the query using the TEI API.
+
+Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+if a score is present.
+
+**Parameters:**
+
+- **query** (str) – The user query string to guide reranking.
+- **documents** (list\[Document\]) – List of `Document` objects to rerank.
+- **top_k** (int | None) – Optional override for the maximum number of documents to return.
+- **truncation_direction** (TruncationDirection | None) – If set, enables text truncation in the specified direction.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: A list of reranked documents.
+
+**Raises:**
+
+- RuntimeError – - If the API request fails.
+- RuntimeError – - If the API returns an error response.
+- TypeError – - If the API response is not in the expected list format.
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ documents: list[Document],
+ top_k: int | None = None,
+ truncation_direction: TruncationDirection | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously reranks the provided documents by relevance to the query using the TEI API.
+
+Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+if a score is present.
+
+**Parameters:**
+
+- **query** (str) – The user query string to guide reranking.
+- **documents** (list\[Document\]) – List of `Document` objects to rerank.
+- **top_k** (int | None) – Optional override for the maximum number of documents to return.
+- **truncation_direction** (TruncationDirection | None) – If set, enables text truncation in the specified direction.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: A list of reranked documents.
+
+**Raises:**
+
+- httpx.RequestError – - If the API request fails.
+- RuntimeError – - If the API returns an error response.
+- TypeError – - If the API response is not in the expected list format.
+
+## llm_ranker
+
+### LLMRanker
+
+Ranks documents for a query using a Large Language Model.
+
+The LLM is expected to return a JSON object containing ranked document indices.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.rankers import LLMRanker
+
+chat_generator = OpenAIChatGenerator(
+ model="gpt-4.1-mini",
+ generation_kwargs={
+ "temperature": 0.0,
+ "response_format": {
+ "type": "json_schema",
+ "json_schema": {
+ "name": "document_ranking",
+ "schema": {
+ "type": "object",
+ "properties": {
+ "documents": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {"index": {"type": "integer"}},
+ "required": ["index"],
+ "additionalProperties": False,
+ },
+ }
+ },
+ "required": ["documents"],
+ "additionalProperties": False,
+ },
+ },
+ },
+ },
+)
+
+ranker = LLMRanker(chat_generator=chat_generator)
+
+documents = [
+ Document(id="paris", content="Paris is the capital of France."),
+ Document(id="berlin", content="Berlin is the capital of Germany."),
+]
+
+result = ranker.run(query="capital of Germany", documents=documents)
+print(result["documents"][0].id)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ chat_generator: ChatGenerator | None = None,
+ prompt: str = DEFAULT_PROMPT_TEMPLATE,
+ top_k: int = 10,
+ raise_on_failure: bool = False
+) -> None
+```
+
+Initialize the LLMRanker component.
+
+**Parameters:**
+
+- **chat_generator** (ChatGenerator | None) – The chat generator to use for reranking. If `None`, a default `OpenAIChatGenerator` configured for JSON
+ output is used.
+- **prompt** (str) – Custom prompt template for reranking. The prompt must include exactly the variables `query` and
+ `documents` and instruct the LLM to return ranked 1-based document indices as JSON.
+- **top_k** (int) – The maximum number of documents to return.
+- **raise_on_failure** (bool) – If `True`, raise when generation or response parsing fails. If `False`, log the failure and return the
+ input documents in fallback order.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the underlying chat generator.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LLMRanker
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of the component.
+
+**Returns:**
+
+- LLMRanker – The deserialized component instance.
+
+#### run
+
+```python
+run(
+ query: str, documents: list[Document], top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Rank documents for a query using an LLM.
+
+Before ranking, duplicate documents are removed.
+
+**Parameters:**
+
+- **query** (str) – The query used for reranking.
+- **documents** (list\[Document\]) – Candidate documents to rerank.
+- **top_k** (int | None) – The maximum number of documents to return. Overrides the instance's `top_k` if provided.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the ranked documents under the `documents` key.
+
+## lost_in_the_middle
+
+### LostInTheMiddleRanker
+
+A LostInTheMiddle Ranker.
+
+Ranks documents based on the 'lost in the middle' order so that the most relevant documents are either at the
+beginning or end, while the least relevant are in the middle.
+
+LostInTheMiddleRanker assumes that some prior component in the pipeline has already ranked documents by relevance
+and requires no query as input but only documents. It is typically used as the last component before building a
+prompt for an LLM to prepare the input context for the LLM.
+
+Lost in the Middle ranking lays out document contents into LLM context so that the most relevant contents are at
+the beginning or end of the input context, while the least relevant is in the middle of the context. See the
+paper ["Lost in the Middle: How Language Models Use Long Contexts"](https://arxiv.org/abs/2307.03172) for more
+details.
+
+Usage example:
+
+```python
+from haystack.components.rankers import LostInTheMiddleRanker
+from haystack import Document
+
+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)
+```
+
+#### __init__
+
+```python
+__init__(
+ word_count_threshold: int | None = None, top_k: int | None = None
+) -> None
+```
+
+Initialize the LostInTheMiddleRanker.
+
+If 'word_count_threshold' is specified, this ranker includes all documents up until the point where adding
+another document would exceed the 'word_count_threshold'. The last document that causes the threshold to
+be breached will be included in the resulting list of documents, but all subsequent documents will be
+discarded.
+
+**Parameters:**
+
+- **word_count_threshold** (int | None) – The maximum total number of words across all documents selected by the ranker.
+- **top_k** (int | None) – The maximum number of documents to return.
+
+#### run
+
+```python
+run(
+ documents: list[Document],
+ top_k: int | None = None,
+ word_count_threshold: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Reranks documents based on the "lost in the middle" order.
+
+Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+if a score is present.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents to reorder.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **word_count_threshold** (int | None) – The maximum total number of words across all documents selected by the ranker.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Reranked list of Documents
+
+**Raises:**
+
+- ValueError – If any of the documents is not textual.
+
+## meta_field
+
+### MetaFieldRanker
+
+Ranks Documents based on the value of their specific meta field.
+
+The ranking can be performed in descending order or ascending order.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.rankers import MetaFieldRanker
+
+ranker = MetaFieldRanker(meta_field="rating")
+docs = [
+ Document(content="Paris", meta={"rating": 1.3}),
+ Document(content="Berlin", meta={"rating": 0.7}),
+ Document(content="Barcelona", meta={"rating": 2.1}),
+]
+
+output = ranker.run(documents=docs)
+docs = output["documents"]
+assert docs[0].content == "Barcelona"
+```
+
+#### __init__
+
+```python
+__init__(
+ meta_field: str,
+ weight: float = 1.0,
+ top_k: int | None = None,
+ ranking_mode: Literal[
+ "reciprocal_rank_fusion", "linear_score"
+ ] = "reciprocal_rank_fusion",
+ sort_order: Literal["ascending", "descending"] = "descending",
+ missing_meta: Literal["drop", "top", "bottom"] = "bottom",
+ meta_value_type: Literal["float", "int", "date"] | None = None,
+) -> None
+```
+
+Creates an instance of MetaFieldRanker.
+
+**Parameters:**
+
+- **meta_field** (str) – The name of the meta field to rank by.
+- **weight** (float) – In range [0,1].
+ 0 disables ranking by a meta field.
+ 0.5 ranking from previous component and based on meta field have the same weight.
+ 1 ranking by a meta field only.
+- **top_k** (int | None) – The maximum number of Documents to return per query.
+ If not provided, the Ranker returns all documents it receives in the new ranking order.
+- **ranking_mode** (Literal['reciprocal_rank_fusion', 'linear_score']) – The mode used to combine the Retriever's and Ranker's scores.
+ Possible values are 'reciprocal_rank_fusion' (default) and 'linear_score'.
+ Use the 'linear_score' mode only with Retrievers or Rankers that return a score in range [0,1].
+- **sort_order** (Literal['ascending', 'descending']) – Whether to sort the meta field by ascending or descending order.
+ Possible values are `descending` (default) and `ascending`.
+- **missing_meta** (Literal['drop', 'top', 'bottom']) – What to do with documents that are missing the sorting metadata field.
+ Possible values are:
+ - 'drop' will drop the documents entirely.
+ - 'top' will place the documents at the top of the metadata-sorted list
+ (regardless of 'ascending' or 'descending').
+ - 'bottom' will place the documents at the bottom of metadata-sorted list
+ (regardless of 'ascending' or 'descending').
+- **meta_value_type** (Literal['float', 'int', 'date'] | None) – Parse the meta value into the data type specified before sorting.
+ This will only work if all meta values stored under `meta_field` in the provided documents are strings.
+ For example, if we specified `meta_value_type="date"` then for the meta value `"date": "2015-02-01"`
+ we would parse the string into a datetime object and then sort the documents by date.
+ The available options are:
+- 'float' will parse the meta values into floats.
+- 'int' will parse the meta values into integers.
+- 'date' will parse the meta values into datetime objects.
+- 'None' (default) will do no parsing.
+
+#### run
+
+```python
+run(
+ documents: list[Document],
+ top_k: int | None = None,
+ weight: float | None = None,
+ ranking_mode: (
+ Literal["reciprocal_rank_fusion", "linear_score"] | None
+ ) = None,
+ sort_order: Literal["ascending", "descending"] | None = None,
+ missing_meta: Literal["drop", "top", "bottom"] | None = None,
+ meta_value_type: Literal["float", "int", "date"] | None = None,
+) -> dict[str, Any]
+```
+
+Ranks a list of Documents based on the selected meta field by:
+
+1. Sorting the Documents by the meta field in descending or ascending order.
+1. Merging the rankings from the previous component and based on the meta field according to ranking mode and
+ weight.
+1. Returning the top-k documents.
+
+Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+if a score is present.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to be ranked.
+- **top_k** (int | None) – The maximum number of Documents to return per query.
+ If not provided, the top_k provided at initialization time is used.
+- **weight** (float | None) – In range [0,1].
+ 0 disables ranking by a meta field.
+ 0.5 ranking from previous component and based on meta field have the same weight.
+ 1 ranking by a meta field only.
+ If not provided, the weight provided at initialization time is used.
+- **ranking_mode** (Literal['reciprocal_rank_fusion', 'linear_score'] | None) – (optional) The mode used to combine the Retriever's and Ranker's scores.
+ Possible values are 'reciprocal_rank_fusion' (default) and 'linear_score'.
+ Use the 'score' mode only with Retrievers or Rankers that return a score in range [0,1].
+ If not provided, the ranking_mode provided at initialization time is used.
+- **sort_order** (Literal['ascending', 'descending'] | None) – Whether to sort the meta field by ascending or descending order.
+ Possible values are `descending` (default) and `ascending`.
+ If not provided, the sort_order provided at initialization time is used.
+- **missing_meta** (Literal['drop', 'top', 'bottom'] | None) – What to do with documents that are missing the sorting metadata field.
+ Possible values are:
+- 'drop' will drop the documents entirely.
+- 'top' will place the documents at the top of the metadata-sorted list
+ (regardless of 'ascending' or 'descending').
+- 'bottom' will place the documents at the bottom of metadata-sorted list
+ (regardless of 'ascending' or 'descending').
+ If not provided, the missing_meta provided at initialization time is used.
+- **meta_value_type** (Literal['float', 'int', 'date'] | None) – Parse the meta value into the data type specified before sorting.
+ This will only work if all meta values stored under `meta_field` in the provided documents are strings.
+ For example, if we specified `meta_value_type="date"` then for the meta value `"date": "2015-02-01"`
+ we would parse the string into a datetime object and then sort the documents by date.
+ The available options are:
+ -'float' will parse the meta values into floats.
+ -'int' will parse the meta values into integers.
+ -'date' will parse the meta values into datetime objects.
+ -'None' (default) will do no parsing.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of Documents sorted by the specified meta field.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+ If `weight` is not in range [0,1].
+ If `ranking_mode` is not 'reciprocal_rank_fusion' or 'linear_score'.
+ If `sort_order` is not 'ascending' or 'descending'.
+ If `meta_value_type` is not 'float', 'int', 'date' or `None`.
+
+## meta_field_grouping_ranker
+
+### MetaFieldGroupingRanker
+
+Reorders the documents by grouping them based on metadata keys.
+
+The MetaFieldGroupingRanker can group documents by a primary metadata key `group_by`, and subgroup them with an optional
+secondary key, `subgroup_by`.
+Within each group or subgroup, it 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 proper organization of documents helps improve the efficiency and performance of subsequent processing by an LLM.
+
+### Usage example
+
+```python
+from haystack.components.rankers import MetaFieldGroupingRanker
+from haystack.dataclasses import Document
+
+
+docs = [
+ Document(content="Javascript is a popular programming language", meta={"group": "42", "split_id": 7, "subgroup": "subB"}),
+ Document(content="Python is a popular programming language",meta={"group": "42", "split_id": 4, "subgroup": "subB"}),
+ Document(content="A chromosome is a package of 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 a popular programming language", 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"])
+
+# >>
+# >> Document(id=d665bbc83e52c08c3d8275bccf4f22bf2bfee21c6e77d78794627637355b8ebc,
+# >> content: 'Java is a popular programming language', meta: {'group': '42', 'split_id': 3, 'subgroup': 'subB'}),
+# >> Document(id=a20b326f07382b3cbf2ce156092f7c93e8788df5d48f2986957dce2adb5fe3c2,
+# >> content: 'Python is a popular programming language', meta: {'group': '42', 'split_id': 4, 'subgroup': 'subB'}),
+# >> Document(id=ce12919795d22f6ca214d0f161cf870993889dcb146f3bb1b3e1ffdc95be960f,
+# >> content: 'Javascript is a popular programming language', meta: {'group': '42', 'split_id': 7, 'subgroup': 'subB'}),
+# >> Document(id=d9fc857046c904e5cf790b3969b971b1bbdb1b3037d50a20728fdbf82991aa94,
+# >> content: 'A chromosome is a package of DNA', meta: {'group': '314', 'split_id': 2, 'subgroup': 'subC'}),
+# >> Document(id=6d3b7bdc13d09aa01216471eb5fb0bfdc53c5f2f3e98ad125ff6b85d3106c9a3,
+# >> content: 'An octopus has three hearts', meta: {'group': '11', 'split_id': 2, 'subgroup': 'subD'})
+```
+
+#### __init__
+
+```python
+__init__(
+ group_by: str,
+ subgroup_by: str | None = None,
+ sort_docs_by: str | None = None,
+) -> None
+```
+
+Creates an instance of MetaFieldGroupingRanker.
+
+**Parameters:**
+
+- **group_by** ([str) – The metadata key to aggregate the documents by.
+- **subgroup_by** (str | None) – The metadata key to aggregate the documents within a group that was created by the
+ `group_by` key.
+- **sort_docs_by** (str | None) – Determines which metadata key is used to sort the documents. If not provided, the
+ documents within the groups or subgroups are not sorted and are kept in the same order as
+ they were inserted in the subgroups.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Groups the provided list of documents based on the `group_by` parameter and optionally the `subgroup_by`.
+
+Before grouping, documents are deduplicated by their id, retaining only the document with the highest score
+if a score is present.
+
+The output is a list of documents reordered based on how they were grouped.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The list of documents to group.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- documents: The list of documents ordered by the `group_by` and `subgroup_by` metadata values.
+
+## sentence_transformers_diversity
+
+### DiversityRankingStrategy
+
+Bases: Enum
+
+The strategy to use for diversity ranking.
+
+#### from_str
+
+```python
+from_str(string: str) -> DiversityRankingStrategy
+```
+
+Convert a string to a Strategy enum.
+
+### DiversityRankingSimilarity
+
+Bases: Enum
+
+The similarity metric to use for comparing embeddings.
+
+#### from_str
+
+```python
+from_str(string: str) -> DiversityRankingSimilarity
+```
+
+Convert a string to a Similarity enum.
+
+### SentenceTransformersDiversityRanker
+
+A Diversity Ranker based on Sentence Transformers.
+
+Applies a document ranking algorithm based on one of the two strategies:
+
+1. Greedy Diversity Order:
+
+ Implements a document ranking algorithm that orders documents in a way that maximizes the overall diversity
+ of the documents based on their similarity to the query.
+
+ It uses a pre-trained Sentence Transformers model to embed the query and
+ the documents.
+
+1. Maximum Margin Relevance:
+
+ Implements a document ranking algorithm that orders documents based on their Maximum Margin Relevance (MMR)
+ scores.
+
+ MMR scores are calculated for each document based on their relevance to the query and diversity from already
+ selected documents. The algorithm iteratively selects documents based on their MMR scores, balancing between
+ relevance to the query and diversity from already selected documents. The 'lambda_threshold' controls the
+ trade-off between relevance and diversity.
+
+Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+if a score is present.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.rankers import SentenceTransformersDiversityRanker
+
+ranker = SentenceTransformersDiversityRanker(
+ model="sentence-transformers/all-MiniLM-L6-v2", similarity="cosine", strategy="greedy_diversity_order"
+)
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "What is the capital of germany?"
+output = ranker.run(query=query, documents=docs)
+docs = output["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "sentence-transformers/all-MiniLM-L6-v2",
+ top_k: int = 10,
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ similarity: str | DiversityRankingSimilarity = "cosine",
+ query_prefix: str = "",
+ query_suffix: str = "",
+ document_prefix: str = "",
+ document_suffix: str = "",
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ strategy: str | DiversityRankingStrategy = "greedy_diversity_order",
+ lambda_threshold: float = 0.5,
+ model_kwargs: dict[str, Any] | None = None,
+ tokenizer_kwargs: dict[str, Any] | None = None,
+ config_kwargs: dict[str, Any] | None = None,
+ backend: Literal["torch", "onnx", "openvino"] = "torch",
+) -> None
+```
+
+Initialize a SentenceTransformersDiversityRanker.
+
+**Parameters:**
+
+- **model** (str) – Local path or name of the model in Hugging Face's model hub,
+ such as `'sentence-transformers/all-MiniLM-L6-v2'`.
+- **top_k** (int) – The maximum number of Documents to return per query.
+- **device** (ComponentDevice | None) – The device on which the model is loaded. If `None`, the default device is automatically
+ selected.
+- **token** (Secret | None) – The API token used to download private models from Hugging Face.
+- **similarity** (str | DiversityRankingSimilarity) – Similarity metric for comparing embeddings. Can be set to "dot_product" (default) or
+ "cosine".
+- **query_prefix** (str) – A string to add to the beginning of the query text before ranking.
+ Can be used to prepend the text with an instruction, as required by some embedding models,
+ such as E5 and BGE.
+- **query_suffix** (str) – A string to add to the end of the query text before ranking.
+- **document_prefix** (str) – A string to add to the beginning of each Document text before ranking.
+ Can be used to prepend the text with an instruction, as required by some embedding models,
+ such as E5 and BGE.
+- **document_suffix** (str) – A string to add to the end of each Document text before ranking.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be embedded along with the Document content.
+- **embedding_separator** (str) – Separator used to concatenate the meta fields to the Document content.
+- **strategy** (str | DiversityRankingStrategy) – The strategy to use for diversity ranking. Can be either "greedy_diversity_order" or
+ "maximum_margin_relevance".
+- **lambda_threshold** (float) – The trade-off parameter between relevance and diversity. Only used when strategy is
+ "maximum_margin_relevance".
+- **model_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
+ when loading the model. Refer to specific model documentation for available kwargs.
+- **tokenizer_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
+ Refer to specific model documentation for available kwargs.
+- **config_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration.
+- **backend** (Literal['torch', 'onnx', 'openvino']) – The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino".
+ Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html)
+ for more information on acceleration and quantization options.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SentenceTransformersDiversityRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- SentenceTransformersDiversityRanker – The deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ documents: list[Document],
+ top_k: int | None = None,
+ lambda_threshold: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Rank the documents based on their diversity.
+
+**Parameters:**
+
+- **query** (str) – The search query.
+- **documents** (list\[Document\]) – List of Document objects to be ranker.
+- **top_k** (int | None) – Optional. An integer to override the top_k set during initialization.
+- **lambda_threshold** (float | None) – Override the trade-off parameter between relevance and diversity. Only used when
+ strategy is "maximum_margin_relevance".
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following key:
+- `documents`: List of Document objects that have been selected based on the diversity ranking.
+
+**Raises:**
+
+- ValueError – If the top_k value is less than or equal to 0.
+
+## sentence_transformers_similarity
+
+### SentenceTransformersSimilarityRanker
+
+Ranks documents based on their semantic similarity to the query.
+
+It uses a pre-trained cross-encoder model from Hugging Face to embed the query and the documents.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.rankers import SentenceTransformersSimilarityRanker
+
+ranker = SentenceTransformersSimilarityRanker()
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "City in Germany"
+result = ranker.run(query=query, documents=docs)
+docs = result["documents"]
+print(docs[0].content)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str | Path = "cross-encoder/ms-marco-MiniLM-L-6-v2",
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ top_k: int = 10,
+ query_prefix: str = "",
+ query_suffix: str = "",
+ document_prefix: str = "",
+ document_suffix: str = "",
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ scale_score: bool = True,
+ score_threshold: float | None = None,
+ trust_remote_code: bool = False,
+ model_kwargs: dict[str, Any] | None = None,
+ tokenizer_kwargs: dict[str, Any] | None = None,
+ config_kwargs: dict[str, Any] | None = None,
+ backend: Literal["torch", "onnx", "openvino"] = "torch",
+ batch_size: int = 16
+) -> None
+```
+
+Creates an instance of SentenceTransformersSimilarityRanker.
+
+**Parameters:**
+
+- **model** (str | Path) – The ranking model. Pass a local path or the Hugging Face model name of a cross-encoder model.
+- **device** (ComponentDevice | None) – The device on which the model is loaded. If `None`, the default device is automatically selected.
+- **token** (Secret | None) – The API token to download private models from Hugging Face.
+- **top_k** (int) – The maximum number of documents to return per query.
+- **query_prefix** (str) – A string to add at the beginning of the query text before ranking.
+ Use it to prepend the text with an instruction, as required by reranking models like `bge`.
+- **query_suffix** (str) – A string to add at the end of the query text before ranking.
+ Use it to append the text with an instruction, as required by reranking models like `qwen`.
+- **document_prefix** (str) – A string to add at the beginning of each document before ranking. You can use it to prepend the document
+ with an instruction, as required by embedding models like `bge`.
+- **document_suffix** (str) – A string to add at the end of each document before ranking. You can use it to append the document
+ with an instruction, as required by embedding models like `qwen`.
+- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed with the document.
+- **embedding_separator** (str) – Separator to concatenate metadata fields to the document.
+- **scale_score** (bool) – If `True`, scales the raw logit predictions using a Sigmoid activation function.
+ If `False`, disables scaling of the raw logit predictions.
+- **score_threshold** (float | None) – Use it to return documents with a score above this threshold only.
+- **trust_remote_code** (bool) – If `False`, allows only Hugging Face verified model architectures.
+ If `True`, allows custom models and scripts.
+- **model_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
+ when loading the model. Refer to specific model documentation for available kwargs.
+- **tokenizer_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
+ Refer to specific model documentation for available kwargs.
+- **config_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration.
+- **backend** (Literal['torch', 'onnx', 'openvino']) – The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino".
+ Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html)
+ for more information on acceleration and quantization options.
+- **batch_size** (int) – The batch size to use for inference. The higher the batch size, the more memory is required.
+ If you run into memory issues, reduce the batch size.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SentenceTransformersSimilarityRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SentenceTransformersSimilarityRanker – Deserialized component.
+
+#### run
+
+```python
+run(
+ *,
+ query: str,
+ documents: list[Document],
+ top_k: int | None = None,
+ scale_score: bool | None = None,
+ score_threshold: float | None = None
+) -> dict[str, list[Document]]
+```
+
+Returns a list of documents ranked by their similarity to the given query.
+
+Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+if a score is present.
+
+**Parameters:**
+
+- **query** (str) – The input query to compare the documents to.
+- **documents** (list\[Document\]) – A list of documents to be ranked.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **scale_score** (bool | None) – If `True`, scales the raw logit predictions using a Sigmoid activation function.
+ If `False`, disables scaling of the raw logit predictions.
+ If set, overrides the value set at initialization.
+- **score_threshold** (float | None) – Use it to return documents only with a score above this threshold.
+ If set, overrides the value set at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: A list of documents closest to the query, sorted from most similar to least similar.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+
+## transformers_similarity
+
+### TransformersSimilarityRanker
+
+Ranks documents based on their semantic similarity to the query.
+
+It uses a pre-trained cross-encoder model from Hugging Face to embed the query and the documents.
+
+Note:
+This component is considered legacy and will no longer receive updates. It may be deprecated in a future release,
+with removal following after a deprecation period.
+Consider using SentenceTransformersSimilarityRanker instead, which provides the same functionality along with
+additional features.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.rankers import TransformersSimilarityRanker
+
+ranker = TransformersSimilarityRanker()
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "City in Germany"
+result = ranker.run(query=query, documents=docs)
+docs = result["documents"]
+print(docs[0].content)
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str | Path = "cross-encoder/ms-marco-MiniLM-L-6-v2",
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ top_k: int = 10,
+ query_prefix: str = "",
+ document_prefix: str = "",
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ scale_score: bool = True,
+ calibration_factor: float | None = 1.0,
+ score_threshold: float | None = None,
+ model_kwargs: dict[str, Any] | None = None,
+ tokenizer_kwargs: dict[str, Any] | None = None,
+ batch_size: int = 16,
+) -> None
+```
+
+Creates an instance of TransformersSimilarityRanker.
+
+**Parameters:**
+
+- **model** (str | Path) – The ranking model. Pass a local path or the Hugging Face model name of a cross-encoder model.
+- **device** (ComponentDevice | None) – The device on which the model is loaded. If `None`, overrides the default device.
+- **token** (Secret | None) – The API token to download private models from Hugging Face.
+- **top_k** (int) – The maximum number of documents to return per query.
+- **query_prefix** (str) – A string to add at the beginning of the query text before ranking.
+ Use it to prepend the text with an instruction, as required by reranking models like `bge`.
+- **document_prefix** (str) – A string to add at the beginning of each document before ranking. You can use it to prepend the document
+ with an instruction, as required by embedding models like `bge`.
+- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed with the document.
+- **embedding_separator** (str) – Separator to concatenate metadata fields to the document.
+- **scale_score** (bool) – If `True`, scales the raw logit predictions using a Sigmoid activation function.
+ If `False`, disables scaling of the raw logit predictions.
+- **calibration_factor** (float | None) – Use this factor to calibrate probabilities with `sigmoid(logits * calibration_factor)`.
+ Used only if `scale_score` is `True`.
+- **score_threshold** (float | None) – Use it to return documents with a score above this threshold only.
+- **model_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
+ when loading the model. Refer to specific model documentation for available kwargs.
+- **tokenizer_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
+ Refer to specific model documentation for available kwargs.
+- **batch_size** (int) – The batch size to use for inference. The higher the batch size, the more memory is required.
+ If you run into memory issues, reduce the batch size.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+ If `scale_score` is True and `calibration_factor` is not provided.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TransformersSimilarityRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- TransformersSimilarityRanker – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ documents: list[Document],
+ top_k: int | None = None,
+ scale_score: bool | None = None,
+ calibration_factor: float | None = None,
+ score_threshold: float | None = None,
+) -> dict[str, Any]
+```
+
+Returns a list of documents ranked by their similarity to the given query.
+
+Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+if a score is present.
+
+**Parameters:**
+
+- **query** (str) – The input query to compare the documents to.
+- **documents** (list\[Document\]) – A list of documents to be ranked.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **scale_score** (bool | None) – If `True`, scales the raw logit predictions using a Sigmoid activation function.
+ If `False`, disables scaling of the raw logit predictions.
+- **calibration_factor** (float | None) – Use this factor to calibrate probabilities with `sigmoid(logits * calibration_factor)`.
+ Used only if `scale_score` is `True`.
+- **score_threshold** (float | None) – Use it to return documents only with a score above this threshold.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of documents closest to the query, sorted from most similar to least similar.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+ If `scale_score` is True and `calibration_factor` is not provided.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/readers_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/readers_api.md
new file mode 100644
index 0000000000..16e7c1a94b
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/readers_api.md
@@ -0,0 +1,193 @@
+---
+title: "Readers"
+id: readers-api
+description: "Takes a query and a set of Documents as input and returns ExtractedAnswers by selecting a text span within the Documents."
+slug: "/readers-api"
+---
+
+
+## extractive
+
+### ExtractiveReader
+
+Locates and extracts answers to a given query from Documents.
+
+The ExtractiveReader component performs extractive question answering.
+It assigns a score to every possible answer span independently of other answer spans.
+This fixes a common issue of other implementations which make comparisons across documents harder by normalizing
+each document's answers independently.
+
+Example usage:
+
+```python
+from haystack import Document
+from haystack.components.readers import ExtractiveReader
+
+docs = [
+ Document(content="Python is a popular programming language"),
+ Document(content="python ist eine beliebte Programmiersprache"),
+]
+
+reader = ExtractiveReader()
+
+question = "What is a popular programming language?"
+result = reader.run(query=question, documents=docs)
+assert "Python" in result["answers"][0].data
+```
+
+#### __init__
+
+```python
+__init__(
+ model: Path | str = "deepset/roberta-base-squad2-distilled",
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ top_k: int = 20,
+ score_threshold: float | None = None,
+ max_seq_length: int = 384,
+ stride: int = 128,
+ max_batch_size: int | None = None,
+ answers_per_seq: int | None = None,
+ no_answer: bool = True,
+ calibration_factor: float = 0.1,
+ overlap_threshold: float | None = 0.01,
+ model_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Creates an instance of ExtractiveReader.
+
+**Parameters:**
+
+- **model** (Path | str) – A Hugging Face transformers question answering model.
+ Can either be a path to a folder containing the model files or an identifier for the Hugging Face hub.
+- **device** (ComponentDevice | None) – The device on which the model is loaded. If `None`, the default device is automatically selected.
+- **token** (Secret | None) – The API token used to download private models from Hugging Face.
+- **top_k** (int) – Number of answers to return per query. It is required even if score_threshold is set.
+ An additional answer with no text is returned if no_answer is set to True (default).
+- **score_threshold** (float | None) – Returns only answers with the probability score above this threshold.
+- **max_seq_length** (int) – Maximum number of tokens. If a sequence exceeds it, the sequence is split.
+- **stride** (int) – Number of tokens that overlap when sequence is split because it exceeds max_seq_length.
+- **max_batch_size** (int | None) – Maximum number of samples that are fed through the model at the same time.
+- **answers_per_seq** (int | None) – Number of answer candidates to consider per sequence.
+ This is relevant when a Document was split into multiple sequences because of max_seq_length.
+- **no_answer** (bool) – Whether to return an additional `no answer` with an empty text and a score representing the
+ probability that the other top_k answers are incorrect.
+- **calibration_factor** (float) – Factor used for calibrating probabilities.
+- **overlap_threshold** (float | None) – If set this will remove duplicate answers if they have an overlap larger than the
+ supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove
+ one of these answers since the second answer has a 100% (1.0) overlap with the first answer.
+ However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so
+ both of these answers could be kept if this variable is set to 0.24 or lower.
+ If None is provided then all answers are kept.
+- **model_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments passed to `AutoModelForQuestionAnswering.from_pretrained`
+ when loading the model specified in `model`. For details on what kwargs you can pass,
+ see the model's documentation.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ExtractiveReader
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ExtractiveReader – Deserialized component.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### deduplicate_by_overlap
+
+```python
+deduplicate_by_overlap(
+ answers: list[ExtractedAnswer], overlap_threshold: float | None
+) -> list[ExtractedAnswer]
+```
+
+De-duplicates overlapping Extractive Answers.
+
+De-duplicates overlapping Extractive Answers from the same document based on how much the spans of the
+answers overlap.
+
+**Parameters:**
+
+- **answers** (list\[ExtractedAnswer\]) – List of answers to be deduplicated.
+- **overlap_threshold** (float | None) – If set this will remove duplicate answers if they have an overlap larger than the
+ supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove
+ one of these answers since the second answer has a 100% (1.0) overlap with the first answer.
+ However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so
+ both of these answers could be kept if this variable is set to 0.24 or lower.
+ If None is provided then all answers are kept.
+
+**Returns:**
+
+- list\[ExtractedAnswer\] – List of deduplicated answers.
+
+#### run
+
+```python
+run(
+ query: str,
+ documents: list[Document],
+ top_k: int | None = None,
+ score_threshold: float | None = None,
+ max_seq_length: int | None = None,
+ stride: int | None = None,
+ max_batch_size: int | None = None,
+ answers_per_seq: int | None = None,
+ no_answer: bool | None = None,
+ overlap_threshold: float | None = None,
+) -> dict[str, Any]
+```
+
+Locates and extracts answers from the given Documents using the given query.
+
+**Parameters:**
+
+- **query** (str) – Query string.
+- **documents** (list\[Document\]) – List of Documents in which you want to search for an answer to the query.
+- **top_k** (int | None) – The maximum number of answers to return.
+ An additional answer is returned if no_answer is set to True (default).
+- **score_threshold** (float | None) – Returns only answers with the score above this threshold.
+- **max_seq_length** (int | None) – Maximum number of tokens. If a sequence exceeds it, the sequence is split.
+- **stride** (int | None) – Number of tokens that overlap when sequence is split because it exceeds max_seq_length.
+- **max_batch_size** (int | None) – Maximum number of samples that are fed through the model at the same time.
+- **answers_per_seq** (int | None) – Number of answer candidates to consider per sequence.
+ This is relevant when a Document was split into multiple sequences because of max_seq_length.
+- **no_answer** (bool | None) – Whether to return no answer scores.
+- **overlap_threshold** (float | None) – If set this will remove duplicate answers if they have an overlap larger than the
+ supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove
+ one of these answers since the second answer has a 100% (1.0) overlap with the first answer.
+ However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so
+ both of these answers could be kept if this variable is set to 0.24 or lower.
+ If None is provided then all answers are kept.
+
+**Returns:**
+
+- dict\[str, Any\] – List of answers sorted by (desc.) answer score.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/retrievers_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/retrievers_api.md
new file mode 100644
index 0000000000..59dc6a3286
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/retrievers_api.md
@@ -0,0 +1,1305 @@
+---
+title: "Retrievers"
+id: retrievers-api
+description: "Sweeps through a Document Store and returns a set of candidate Documents that are relevant to the query."
+slug: "/retrievers-api"
+---
+
+
+## auto_merging_retriever
+
+### AutoMergingRetriever
+
+A retriever which returns parent documents of the matched leaf nodes documents, based on a threshold setting.
+
+The AutoMergingRetriever assumes you have a hierarchical tree structure of documents, where the leaf nodes
+are indexed in a document store. See the HierarchicalDocumentSplitter for more information on how to create
+such a structure. During retrieval, if the number of matched leaf documents below the same parent is
+higher than a defined threshold, the retriever will return the parent document instead of the individual leaf
+documents.
+
+The rational is, given that a paragraph is split into multiple chunks represented as leaf documents, and if for
+a given query, multiple chunks are matched, the whole paragraph might be more informative than the individual
+chunks alone.
+
+Currently the AutoMergingRetriever can only be used by the following DocumentStores:
+
+- [AstraDB](https://haystack.deepset.ai/integrations/astradb)
+- [ElasticSearch](https://haystack.deepset.ai/docs/latest/documentstore/elasticsearch)
+- [OpenSearch](https://haystack.deepset.ai/docs/latest/documentstore/opensearch)
+- [PGVector](https://haystack.deepset.ai/docs/latest/documentstore/pgvector)
+- [Qdrant](https://haystack.deepset.ai/docs/latest/documentstore/qdrant)
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import HierarchicalDocumentSplitter
+from haystack.components.retrievers.auto_merging_retriever import AutoMergingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+# create a hierarchical document structure with 3 levels, where the parent document has 3 children
+text = "The sun rose early in the morning. It cast a warm glow over the trees. Birds began to sing."
+original_document = Document(content=text)
+builder = HierarchicalDocumentSplitter(block_sizes={10, 3}, split_overlap=0, split_by="word")
+docs = builder.run([original_document])["documents"]
+
+# store level-1 parent documents and initialize the retriever
+doc_store_parents = InMemoryDocumentStore()
+for doc in docs:
+ if doc.meta["__children_ids"] and doc.meta["__level"] in [0,1]: # store the root document and level 1 documents
+ doc_store_parents.write_documents([doc])
+
+retriever = AutoMergingRetriever(doc_store_parents, threshold=0.5)
+
+# assume we retrieved 2 leaf docs from the same parent, the parent document should be returned,
+# since it has 3 children and the threshold=0.5, and we retrieved 2 children (2/3 > 0.66(6))
+leaf_docs = [doc for doc in docs if not doc.meta["__children_ids"]]
+retrieved_docs = retriever.run(leaf_docs[4:6])
+print(retrieved_docs["documents"])
+# [Document(id=538..),
+# content: 'warm glow over the trees. Birds began to sing.',
+# meta: {'block_size': 10, 'parent_id': '835..', 'children_ids': ['c17...', '3ff...', '352...'], 'level': 1, 'source_id': '835...',
+# 'page_number': 1, 'split_id': 1, 'split_idx_start': 45})]}
+```
+
+#### __init__
+
+```python
+__init__(document_store: DocumentStore, threshold: float = 0.5) -> None
+```
+
+Initialize the AutoMergingRetriever.
+
+**Parameters:**
+
+- **document_store** (DocumentStore) – DocumentStore from which to retrieve the parent documents
+- **threshold** (float) – Threshold to decide whether the parent instead of the individual documents is returned
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AutoMergingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary with serialized data.
+
+**Returns:**
+
+- AutoMergingRetriever – An instance of the component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Run the AutoMergingRetriever.
+
+Recursively groups documents by their parents and merges them if they meet the threshold,
+continuing up the hierarchy until no more merges are possible.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of leaf documents that were matched by a retriever
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – List of documents (could be a mix of different hierarchy levels)
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Asynchronously run the AutoMergingRetriever.
+
+Recursively groups documents by their parents and merges them if they meet the threshold,
+continuing up the hierarchy until no more merges are possible.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of leaf documents that were matched by a retriever
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – List of documents (could be a mix of different hierarchy levels)
+
+## filter_retriever
+
+### FilterRetriever
+
+Retrieves documents that match the provided filters.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.retrievers import FilterRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+docs = [
+ Document(content="Python is a popular programming language", meta={"lang": "en"}),
+ Document(content="python ist eine beliebte Programmiersprache", meta={"lang": "de"}),
+]
+
+doc_store = InMemoryDocumentStore()
+doc_store.write_documents(docs)
+retriever = FilterRetriever(doc_store, filters={"field": "lang", "operator": "==", "value": "en"})
+
+# if passed in the run method, filters override those provided at initialization
+result = retriever.run(filters={"field": "lang", "operator": "==", "value": "de"})
+
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: DocumentStore, filters: dict[str, Any] | None = None
+) -> None
+```
+
+Create the FilterRetriever component.
+
+**Parameters:**
+
+- **document_store** (DocumentStore) – An instance of a Document Store to use with the Retriever.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FilterRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- FilterRetriever – The deserialized component.
+
+#### run
+
+```python
+run(filters: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Run the FilterRetriever on the given input data.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space.
+ If not specified, the FilterRetriever uses the values provided at initialization.
+
+**Returns:**
+
+- dict\[str, Any\] – A list of retrieved documents.
+
+#### run_async
+
+```python
+run_async(filters: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Asynchronously run the FilterRetriever on the given input data.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space.
+ If not specified, the FilterRetriever uses the values provided at initialization.
+
+**Returns:**
+
+- dict\[str, Any\] – A list of retrieved documents.
+
+## in_memory/bm25_retriever
+
+### InMemoryBM25Retriever
+
+Retrieves documents that are most similar to the query using keyword-based algorithm.
+
+Use this retriever with the InMemoryDocumentStore.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+docs = [
+ Document(content="Python is a popular programming language"),
+ Document(content="python ist eine beliebte Programmiersprache"),
+]
+
+doc_store = InMemoryDocumentStore()
+doc_store.write_documents(docs)
+retriever = InMemoryBM25Retriever(doc_store)
+
+result = retriever.run(query="Programmiersprache")
+
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: InMemoryDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ scale_score: bool = False,
+ filter_policy: FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Create the InMemoryBM25Retriever component.
+
+**Parameters:**
+
+- **document_store** (InMemoryDocumentStore) – An instance of InMemoryDocumentStore where the retriever should search for relevant documents.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the retriever's search space in the document store.
+- **top_k** (int) – The maximum number of documents to retrieve.
+- **scale_score** (bool) – When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant.
+ When `False`, uses raw similarity scores.
+- **filter_policy** (FilterPolicy) – The filter policy to apply during retrieval.
+ Filter policy determines how filters are applied when retrieving documents. You can choose:
+- `REPLACE` (default): Overrides the initialization filters with the filters specified at runtime.
+ Use this policy to dynamically change filtering for specific queries.
+- `MERGE`: Combines runtime filters with initialization filters to narrow down the search.
+
+**Raises:**
+
+- TypeError – If the document_store is not an instance of InMemoryDocumentStore.
+- ValueError – If the specified `top_k` is not > 0.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> InMemoryBM25Retriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- InMemoryBM25Retriever – The deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ scale_score: bool | None = None,
+) -> dict[str, list[Document]]
+```
+
+Run the InMemoryBM25Retriever on the given input data.
+
+**Parameters:**
+
+- **query** (str) – The query string for the Retriever.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space when retrieving documents.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **scale_score** (bool | None) – When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant.
+ When `False`, uses raw similarity scores.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The retrieved documents.
+
+**Raises:**
+
+- ValueError – If the specified DocumentStore is not found or is not a InMemoryDocumentStore instance.
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ scale_score: bool | None = None,
+) -> dict[str, list[Document]]
+```
+
+Run the InMemoryBM25Retriever on the given input data.
+
+**Parameters:**
+
+- **query** (str) – The query string for the Retriever.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space when retrieving documents.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **scale_score** (bool | None) – When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant.
+ When `False`, uses raw similarity scores.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The retrieved documents.
+
+**Raises:**
+
+- ValueError – If the specified DocumentStore is not found or is not a InMemoryDocumentStore instance.
+
+## in_memory/embedding_retriever
+
+### InMemoryEmbeddingRetriever
+
+Retrieves documents that are most semantically similar to the query.
+
+Use this retriever with the InMemoryDocumentStore.
+
+When using this retriever, make sure it has query and document embeddings available.
+In indexing pipelines, use a DocumentEmbedder to embed documents.
+In query pipelines, use a TextEmbedder to embed queries and send them to the retriever.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+docs = [
+ Document(content="Python is a popular programming language"),
+ Document(content="python ist eine beliebte Programmiersprache"),
+]
+doc_embedder = SentenceTransformersDocumentEmbedder()
+docs_with_embeddings = doc_embedder.run(docs)["documents"]
+
+doc_store = InMemoryDocumentStore()
+doc_store.write_documents(docs_with_embeddings)
+retriever = InMemoryEmbeddingRetriever(doc_store)
+
+query="Programmiersprache"
+text_embedder = SentenceTransformersTextEmbedder()
+query_embedding = text_embedder.run(query)["embedding"]
+
+result = retriever.run(query_embedding=query_embedding)
+
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: InMemoryDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ scale_score: bool = False,
+ return_embedding: bool = False,
+ filter_policy: FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Create the InMemoryEmbeddingRetriever component.
+
+**Parameters:**
+
+- **document_store** (InMemoryDocumentStore) – An instance of InMemoryDocumentStore where the retriever should search for relevant documents.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the retriever's search space in the document store.
+- **top_k** (int) – The maximum number of documents to retrieve.
+- **scale_score** (bool) – When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant.
+ When `False`, uses raw similarity scores.
+- **return_embedding** (bool) – When `True`, returns the embedding of the retrieved documents.
+ When `False`, returns just the documents, without their embeddings.
+- **filter_policy** (FilterPolicy) – The filter policy to apply during retrieval.
+ Filter policy determines how filters are applied when retrieving documents. You can choose:
+- `REPLACE` (default): Overrides the initialization filters with the filters specified at runtime.
+ Use this policy to dynamically change filtering for specific queries.
+- `MERGE`: Combines runtime filters with initialization filters to narrow down the search.
+
+**Raises:**
+
+- TypeError – If the document_store is not an instance of InMemoryDocumentStore.
+- ValueError – If the specified top_k is not > 0.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> InMemoryEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- InMemoryEmbeddingRetriever – The deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ scale_score: bool | None = None,
+ return_embedding: bool | None = None,
+) -> dict[str, list[Document]]
+```
+
+Run the InMemoryEmbeddingRetriever on the given input data.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space when retrieving documents.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **scale_score** (bool | None) – When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant.
+ When `False`, uses raw similarity scores.
+- **return_embedding** (bool | None) – When `True`, returns the embedding of the retrieved documents.
+ When `False`, returns just the documents, without their embeddings.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The retrieved documents.
+
+**Raises:**
+
+- ValueError – If the specified DocumentStore is not found or is not an InMemoryDocumentStore instance.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ scale_score: bool | None = None,
+ return_embedding: bool | None = None,
+) -> dict[str, list[Document]]
+```
+
+Run the InMemoryEmbeddingRetriever on the given input data.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – A dictionary with filters to narrow down the search space when retrieving documents.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **scale_score** (bool | None) – When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant.
+ When `False`, uses raw similarity scores.
+- **return_embedding** (bool | None) – When `True`, returns the embedding of the retrieved documents.
+ When `False`, returns just the documents, without their embeddings.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The retrieved documents.
+
+**Raises:**
+
+- ValueError – If the specified DocumentStore is not found or is not an InMemoryDocumentStore instance.
+
+## multi_query_embedding_retriever
+
+### MultiQueryEmbeddingRetriever
+
+A component that retrieves documents using multiple queries in parallel with an embedding-based retriever.
+
+This component takes a list of text queries, converts them to embeddings using a query embedder,
+and then uses an embedding-based retriever to find relevant documents for each query in parallel.
+The results are combined and sorted by relevance score.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+from haystack.components.writers import DocumentWriter
+from haystack.components.retrievers import MultiQueryEmbeddingRetriever
+
+documents = [
+ Document(content="Renewable energy is energy that is collected from renewable resources."),
+ Document(content="Solar energy is a type of green energy that is harnessed from the sun."),
+ Document(content="Wind energy is another type of green energy that is generated by wind turbines."),
+ Document(content="Geothermal energy is heat that comes from the sub-surface of the earth."),
+ Document(content="Biomass energy is produced from organic materials, such as plant and animal waste."),
+ Document(content="Fossil fuels, such as coal, oil, and natural gas, are non-renewable energy sources."),
+]
+
+# Populate the document store
+doc_store = InMemoryDocumentStore()
+doc_embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+doc_writer = DocumentWriter(document_store=doc_store, policy=DuplicatePolicy.SKIP)
+documents = doc_embedder.run(documents)["documents"]
+doc_writer.run(documents=documents)
+
+# Run the multi-query retriever
+in_memory_retriever = InMemoryEmbeddingRetriever(document_store=doc_store, top_k=1)
+query_embedder = SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+
+multi_query_retriever = MultiQueryEmbeddingRetriever(
+ retriever=in_memory_retriever,
+ query_embedder=query_embedder,
+ max_workers=3
+)
+
+queries = ["Geothermal energy", "natural gas", "turbines"]
+result = multi_query_retriever.run(queries=queries)
+for doc in result["documents"]:
+ print(f"Content: {doc.content}, Score: {doc.score}")
+# >> Content: Geothermal energy is heat that comes from the sub-surface of the earth., Score: 0.8509603046266574
+# >> Content: Renewable energy is energy that is collected from renewable resources., Score: 0.42763211298893034
+# >> Content: Solar energy is a type of green energy that is harnessed from the sun., Score: 0.40077417016494354
+# >> Content: Fossil fuels, such as coal, oil, and natural gas, are non-renewable energy sources., Score: 0.3774863680
+# >> Content: Wind energy is another type of green energy that is generated by wind turbines., Score: 0.30914239725622
+# >> Content: Biomass energy is produced from organic materials, such as plant and animal waste., Score: 0.25173074243
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ retriever: EmbeddingRetriever,
+ query_embedder: TextEmbedder,
+ max_workers: int = 3
+) -> None
+```
+
+Initialize MultiQueryEmbeddingRetriever.
+
+**Parameters:**
+
+- **retriever** (EmbeddingRetriever) – The embedding-based retriever to use for document retrieval.
+- **query_embedder** (TextEmbedder) – The query embedder to convert text queries to embeddings.
+- **max_workers** (int) – Maximum number of worker threads for parallel processing.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the query embedder and the retriever if any has a warm_up method.
+
+#### run
+
+```python
+run(
+ queries: list[str], retriever_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents using multiple queries in parallel.
+
+**Parameters:**
+
+- **queries** (list\[str\]) – List of text queries to process.
+- **retriever_kwargs** (dict\[str, Any\] | None) – Optional dictionary of arguments to pass to the retriever's run method.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing:
+ - `documents`: List of retrieved documents sorted by relevance score.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representing the serialized component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MultiQueryEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- MultiQueryEmbeddingRetriever – The deserialized component.
+
+## multi_query_text_retriever
+
+### MultiQueryTextRetriever
+
+A component that retrieves documents using multiple queries in parallel with a text-based retriever.
+
+This component takes a list of text queries and uses a text-based retriever to find relevant documents for each
+query in parallel, using a thread pool to manage concurrent execution. The results are combined and sorted by
+relevance score.
+
+You can use this component in combination with QueryExpander component to enhance the retrieval process.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.components.retrievers import InMemoryBM25Retriever
+from haystack.components.query import QueryExpander
+from haystack.components.retrievers.multi_query_text_retriever import MultiQueryTextRetriever
+
+documents = [
+ Document(content="Renewable energy is energy that is collected from renewable resources."),
+ Document(content="Solar energy is a type of green energy that is harnessed from the sun."),
+ Document(content="Wind energy is another type of green energy that is generated by wind turbines."),
+ Document(content="Hydropower is a form of renewable energy using the flow of water to generate electricity."),
+ Document(content="Geothermal energy is heat that comes from the sub-surface of the earth.")
+]
+
+document_store = InMemoryDocumentStore()
+doc_writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.SKIP)
+doc_writer.run(documents=documents)
+
+in_memory_retriever = InMemoryBM25Retriever(document_store=document_store, top_k=1)
+multiquery_retriever = MultiQueryTextRetriever(retriever=in_memory_retriever)
+results = multiquery_retriever.run(queries=["renewable energy?", "Geothermal", "Hydropower"])
+for doc in results["documents"]:
+ print(f"Content: {doc.content}, Score: {doc.score}")
+# >>
+# >> Content: Geothermal energy is heat that comes from the sub-surface of the earth., Score: 1.6474448833731097
+# >> Content: Hydropower is a form of renewable energy using the flow of water to generate electricity., Score: 1.615
+# >> Content: Renewable energy is energy that is collected from renewable resources., Score: 1.5255309812344944
+```
+
+#### __init__
+
+```python
+__init__(*, retriever: TextRetriever, max_workers: int = 3) -> None
+```
+
+Initialize MultiQueryTextRetriever.
+
+**Parameters:**
+
+- **retriever** (TextRetriever) – The text-based retriever to use for document retrieval.
+- **max_workers** (int) – Maximum number of worker threads for parallel processing. Default is 3.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the retriever if it has a warm_up method.
+
+#### run
+
+```python
+run(
+ queries: list[str], retriever_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents using multiple queries in parallel.
+
+**Parameters:**
+
+- **queries** (list\[str\]) – List of text queries to process.
+- **retriever_kwargs** (dict\[str, Any\] | None) – Optional dictionary of arguments to pass to the retriever's run method.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing:
+ `documents`: List of retrieved documents sorted by relevance score.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MultiQueryTextRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- MultiQueryTextRetriever – The deserialized component.
+
+## multi_retriever
+
+### MultiRetriever
+
+A component that accepts text retrievers and runs them in parallel, combining their results.
+
+> **Note:** This component is experimental and may change or be removed in future releases without prior
+> deprecation notice.
+
+All retrievers must implement the `TextRetriever` protocol. Use `TextEmbeddingRetriever` to wrap an
+embedding-based retriever before passing it to this component.
+
+Each retriever is queried concurrently using a thread pool.
+The results are deduplicated and returned as a single list of documents.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.components.retrievers import InMemoryBM25Retriever, InMemoryEmbeddingRetriever
+from haystack.components.retrievers import TextEmbeddingRetriever, MultiRetriever
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack.components.writers import DocumentWriter
+
+documents = [
+ Document(content="Renewable energy is energy that is collected from renewable resources."),
+ Document(content="Solar energy is a type of green energy that is harnessed from the sun."),
+ Document(content="Wind energy is another type of green energy that is generated by wind turbines."),
+]
+
+# Populate the document store
+doc_store = InMemoryDocumentStore()
+doc_embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+doc_writer = DocumentWriter(document_store=doc_store, policy=DuplicatePolicy.SKIP)
+doc_writer.run(documents=doc_embedder.run(documents)["documents"])
+
+# Run the multi-retriever with all retrievers
+retriever = MultiRetriever(
+ retrievers={
+ "bm25": InMemoryBM25Retriever(document_store=doc_store),
+ "embedding": TextEmbeddingRetriever(
+ retriever=InMemoryEmbeddingRetriever(document_store=doc_store),
+ text_embedder=SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"),
+ ),
+ },
+ top_k=3,
+)
+
+# Run all retrievers
+result = retriever.run(query="green energy sources")
+
+# Run only the BM25 retriever
+result = retriever.run(query="green energy sources", active_retrievers=["bm25"])
+
+for doc in result["documents"]:
+ print(doc.content)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ retrievers: dict[str, TextRetriever],
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ max_workers: int = 4,
+ join_mode: Literal[
+ "concatenate", "reciprocal_rank_fusion"
+ ] = "reciprocal_rank_fusion"
+) -> None
+```
+
+Create the MultiRetriever component.
+
+**Parameters:**
+
+- **retrievers** (dict\[str, TextRetriever\]) – A dictionary mapping names to text retrievers (implementing the `TextRetriever` protocol) to run in
+ parallel.
+- **filters** (dict\[str, Any\] | None) – A dictionary of filters to apply when retrieving documents.
+- **top_k** (int) – The maximum number of documents to return per retriever.
+- **max_workers** (int) – The maximum number of threads to use for parallel retrieval.
+- **join_mode** (Literal['concatenate', 'reciprocal_rank_fusion']) – How to merge results from multiple retrievers. Available modes:
+- `concatenate`: Combines all results into a single list and deduplicates.
+- `reciprocal_rank_fusion`: Deduplicates and assigns scores based on reciprocal rank fusion.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the retrievers if any has a warm_up method.
+
+#### run
+
+```python
+run(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ *,
+ active_retrievers: list[str] | None = None
+) -> dict[str, list[Document]]
+```
+
+Runs retrievers in parallel on the given query and returns deduplicated results.
+
+**Parameters:**
+
+- **query** (str) – The query to run the retrievers on.
+- **filters** (dict\[str, Any\] | None) – Filters to apply. Defaults to the value set at initialization.
+- **top_k** (int | None) – Maximum documents to return per retriever. Defaults to the value set at initialization.
+- **active_retrievers** (list\[str\] | None) – Names of retrievers to run. Defaults to all. Must match keys in the `retrievers` dictionary.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the keys:
+ - "documents": A deduplicated list of retrieved documents.
+
+**Raises:**
+
+- ValueError – If any name in `active_retrievers` does not match a retriever name.
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ *,
+ active_retrievers: list[str] | None = None
+) -> dict[str, list[Document]]
+```
+
+Runs retrievers concurrently on the given query and returns deduplicated results.
+
+Uses each retriever's `run_async` method if available, otherwise runs `run` in a thread executor.
+
+**Parameters:**
+
+- **query** (str) – The query to run the retrievers on.
+- **filters** (dict\[str, Any\] | None) – Filters to apply. Defaults to the value set at initialization.
+- **top_k** (int | None) – Maximum documents to return per retriever. Defaults to the value set at initialization.
+- **active_retrievers** (list\[str\] | None) – Names of retrievers to run. Defaults to all. Must match keys in the `retrievers` dictionary.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the keys:
+ - "documents": A deduplicated list of retrieved documents.
+
+**Raises:**
+
+- ValueError – If any name in `active_retrievers` does not match a retriever name.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MultiRetriever
+```
+
+Creates an instance of the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary with the data to create the component.
+
+## sentence_window_retriever
+
+### SentenceWindowRetriever
+
+Retrieves neighboring documents from a DocumentStore to provide context for query results.
+
+This component is intended to be used after a Retriever (e.g., BM25Retriever, EmbeddingRetriever).
+It enhances retrieved results by fetching adjacent document chunks to give
+additional context for the user.
+
+The documents must include metadata indicating their origin and position:
+
+- `source_id` is used to group sentence chunks belonging to the same original document.
+- `split_id` represents the position/order of the chunk within the document.
+
+The number of adjacent documents to include on each side of the retrieved document can be configured using the
+`window_size` parameter. You can also specify which metadata fields to use for source and split ID
+via `source_id_meta_field` and `split_id_meta_field`.
+
+The SentenceWindowRetriever is compatible with the following DocumentStores:
+
+- [Astra](https://docs.haystack.deepset.ai/docs/astradocumentstore)
+- [Elasticsearch](https://docs.haystack.deepset.ai/docs/elasticsearch-document-store)
+- [OpenSearch](https://docs.haystack.deepset.ai/docs/opensearch-document-store)
+- [Pgvector](https://docs.haystack.deepset.ai/docs/pgvectordocumentstore)
+- [Pinecone](https://docs.haystack.deepset.ai/docs/pinecone-document-store)
+- [Qdrant](https://docs.haystack.deepset.ai/docs/qdrant-document-store)
+
+### Usage example
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.retrievers import SentenceWindowRetriever
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+splitter = DocumentSplitter(split_length=10, split_overlap=5, split_by="word")
+text = (
+ "This is a text with some words. There is a second sentence. And there is also a third sentence. "
+ "It also contains a fourth sentence. And a fifth sentence. And a sixth sentence. And a seventh sentence"
+)
+doc = Document(content=text)
+docs = splitter.run([doc])
+doc_store = InMemoryDocumentStore()
+doc_store.write_documents(docs["documents"])
+
+
+rag = Pipeline()
+rag.add_component("bm25_retriever", InMemoryBM25Retriever(doc_store, top_k=1))
+rag.add_component("sentence_window_retriever", SentenceWindowRetriever(document_store=doc_store, window_size=2))
+rag.connect("bm25_retriever", "sentence_window_retriever")
+
+rag.run({'bm25_retriever': {"query":"third"}})
+
+# >> {'sentence_window_retriever': {'context_windows': ['some words. There is a second sentence.
+# >> And there is also a third sentence. It also contains a fourth sentence. And a fifth sentence. And a sixth
+# >> sentence. And a'], 'context_documents': [[Document(id=..., content: 'some words. There is a second sentence.
+# >> And there is ', meta: {'source_id': '...', 'page_number': 1, 'split_id': 1, 'split_idx_start': 20,
+# >> '_split_overlap': [{'doc_id': '...', 'range': (20, 43)}, {'doc_id': '...', 'range': (0, 30)}]}),
+# >> Document(id=..., content: 'second sentence. And there is also a third sentence. It ',
+# >> meta: {'source_id': '74ea87deb38012873cf8c07e...f19d01a26a098447113e1d7b83efd30c02987114', 'page_number': 1,
+# >> 'split_id': 2, 'split_idx_start': 43, '_split_overlap': [{'doc_id': '...', 'range': (23, 53)}, {'doc_id': '.',
+# >> 'range': (0, 26)}]}), Document(id=..., content: 'also a third sentence. It also contains a fourth sentence. ',
+# >> meta: {'source_id': '...', 'page_number': 1, 'split_id': 3, 'split_idx_start': 73, '_split_overlap':
+# >> [{'doc_id': '...', 'range': (30, 56)}, {'doc_id': '...', 'range': (0, 33)}]}), Document(id=..., content:
+# >> 'also contains a fourth sentence. And a fifth sentence. And ', meta: {'source_id': '...', 'page_number': 1,
+# >> 'split_id': 4, 'split_idx_start': 99, '_split_overlap': [{'doc_id': '...', 'range': (26, 59)},
+# >> {'doc_id': '...', 'range': (0, 26)}]}), Document(id=..., content: 'And a fifth sentence. And a sixth sentence.
+# >> And a ', meta: {'source_id': '...', 'page_number': 1, 'split_id': 5, 'split_idx_start': 132,
+# >> '_split_overlap': [{'doc_id': '...', 'range': (33, 59)}, {'doc_id': '...', 'range': (0, 24)}]})]]}}}}
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: DocumentStore,
+ window_size: int = 3,
+ *,
+ source_id_meta_field: str | list[str] = "source_id",
+ split_id_meta_field: str = "split_id",
+ raise_on_missing_meta_fields: bool = True
+) -> None
+```
+
+Creates a new SentenceWindowRetriever component.
+
+**Parameters:**
+
+- **document_store** (DocumentStore) – The Document Store to retrieve the surrounding documents from.
+- **window_size** (int) – The number of documents to retrieve before and after the relevant one.
+ For example, `window_size: 2` fetches 2 preceding and 2 following documents.
+- **source_id_meta_field** (str | list\[str\]) – The metadata field that contains the source ID of the document.
+ This can be a single field or a list of fields. If multiple fields are provided, the retriever will
+ consider the document as part of the same source if all the fields match.
+- **split_id_meta_field** (str) – The metadata field that contains the split ID of the document.
+- **raise_on_missing_meta_fields** (bool) – If True, raises an error if the documents do not contain the required
+ metadata fields. If False, it will skip retrieving the context for documents that are missing
+ the required metadata fields, but will still include the original document in the results.
+
+#### merge_documents_text
+
+```python
+merge_documents_text(documents: list[Document]) -> str
+```
+
+Merge a list of document text into a single string.
+
+This functions concatenates the textual content of a list of documents into a single string, eliminating any
+overlapping content.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents to merge.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SentenceWindowRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Returns:**
+
+- SentenceWindowRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ retrieved_documents: list[Document], window_size: int | None = None
+) -> dict[str, Any]
+```
+
+Based on the `source_id` and on the `doc.meta['split_id']` get surrounding documents from the document store.
+
+Implements the logic behind the sentence-window technique, retrieving the surrounding documents of a given
+document from the document store.
+
+**Parameters:**
+
+- **retrieved_documents** (list\[Document\]) – List of retrieved documents from the previous retriever.
+- **window_size** (int | None) – The number of documents to retrieve before and after the relevant one. This will overwrite
+ the `window_size` parameter set in the constructor.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+ - `context_windows`: A list of strings, where each string represents the concatenated text from the
+ context window of the corresponding document in `retrieved_documents`.
+ - `context_documents`: A list `Document` objects, containing the retrieved documents plus the context
+ document surrounding them. The documents are sorted by the `split_idx_start`
+ meta field.
+
+#### run_async
+
+```python
+run_async(
+ retrieved_documents: list[Document], window_size: int | None = None
+) -> dict[str, Any]
+```
+
+Based on the `source_id` and on the `doc.meta['split_id']` get surrounding documents from the document store.
+
+Implements the logic behind the sentence-window technique, retrieving the surrounding documents of a given
+document from the document store.
+
+**Parameters:**
+
+- **retrieved_documents** (list\[Document\]) – List of retrieved documents from the previous retriever.
+- **window_size** (int | None) – The number of documents to retrieve before and after the relevant one. This will overwrite
+ the `window_size` parameter set in the constructor.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+ - `context_windows`: A list of strings, where each string represents the concatenated text from the
+ context window of the corresponding document in `retrieved_documents`.
+ - `context_documents`: A list `Document` objects, containing the retrieved documents plus the context
+ document surrounding them. The documents are sorted by the `split_idx_start`
+ meta field.
+
+## text_embedding_retriever
+
+### TextEmbeddingRetriever
+
+A component that retrieves documents using a query with an embedding-based retriever.
+
+This component takes a text query, converts it to an embedding using a text embedder, and then uses an
+embedding-based retriever to find relevant documents.
+The results are sorted by relevance score.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack.components.retrievers import InMemoryEmbeddingRetriever, TextEmbeddingRetriever
+from haystack.components.writers import DocumentWriter
+
+documents = [
+ Document(content="Renewable energy is energy that is collected from renewable resources."),
+ Document(content="Solar energy is a type of green energy that is harnessed from the sun."),
+ Document(content="Wind energy is another type of green energy that is generated by wind turbines."),
+ Document(content="Geothermal energy is heat that comes from the sub-surface of the earth."),
+ Document(content="Biomass energy is produced from organic materials, such as plant and animal waste."),
+ Document(content="Fossil fuels, such as coal, oil, and natural gas, are non-renewable energy sources."),
+]
+
+# Populate the document store
+doc_store = InMemoryDocumentStore()
+doc_embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+doc_writer = DocumentWriter(document_store=doc_store, policy=DuplicatePolicy.SKIP)
+documents = doc_embedder.run(documents)["documents"]
+doc_writer.run(documents=documents)
+
+# Run the retriever
+in_memory_retriever = InMemoryEmbeddingRetriever(document_store=doc_store, top_k=1)
+text_embedder = SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+retriever = TextEmbeddingRetriever(retriever=in_memory_retriever, text_embedder=text_embedder)
+result = retriever.run(query="Geothermal energy")
+
+for doc in result["documents"]:
+ print(f"Content: {doc.content}, Score: {doc.score}")
+# >> Content: Geothermal energy is heat that comes from the sub-surface of the earth., Score: 0.8509603046266574
+```
+
+#### __init__
+
+```python
+__init__(*, retriever: EmbeddingRetriever, text_embedder: TextEmbedder) -> None
+```
+
+Initialize TextEmbeddingRetriever.
+
+**Parameters:**
+
+- **retriever** (EmbeddingRetriever) – The embedding-based retriever to use for document retrieval.
+- **text_embedder** (TextEmbedder) – The text embedder to convert a text query to an embedding.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the text embedder and the retriever if any has a warm_up method.
+
+#### run
+
+```python
+run(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents using a single query.
+
+**Parameters:**
+
+- **query** (str) – The query to retrieve documents for.
+- **filters** (dict\[str, Any\] | None) – A dictionary of filters to apply when retrieving documents.
+- **top_k** (int | None) – The maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing:
+ - `documents`: List of retrieved documents sorted by relevance score.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representing the serialized component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TextEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- TextEmbeddingRetriever – The deserialized component.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/routers_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/routers_api.md
new file mode 100644
index 0000000000..476c3668b8
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/routers_api.md
@@ -0,0 +1,1158 @@
+---
+title: "Routers"
+id: routers-api
+description: "Routers is a group of components that route queries or Documents to other components that can handle them best."
+slug: "/routers-api"
+---
+
+
+## conditional_router
+
+### NoRouteSelectedException
+
+Bases: Exception
+
+Exception raised when no route is selected in ConditionalRouter.
+
+### RouteConditionException
+
+Bases: Exception
+
+Exception raised when there is an error parsing or evaluating the condition expression in ConditionalRouter.
+
+### ConditionalRouter
+
+Routes data based on specific conditions.
+
+You define these conditions in a list of dictionaries called `routes`.
+Each dictionary in this list represents a single route. Each route has these four elements:
+
+- `condition`: A Jinja2 string expression that determines if the route is selected.
+- `output`: A Jinja2 expression defining the route's output value.
+- `output_type`: The type of the output data (for example, `str`, `list[int]`).
+- `output_name`: The name you want to use to publish `output`. This name is used to connect
+ the router to other components in the pipeline.
+
+### Usage example
+
+```python
+from haystack.components.routers import ConditionalRouter
+
+routes = [
+ {
+ "condition": "{{streams|length > 2}}",
+ "output": "{{streams}}",
+ "output_name": "enough_streams",
+ "output_type": list[int],
+ },
+ {
+ "condition": "{{streams|length <= 2}}",
+ "output": "{{streams}}",
+ "output_name": "insufficient_streams",
+ "output_type": list[int],
+ },
+]
+router = ConditionalRouter(routes)
+# When 'streams' has more than 2 items, 'enough_streams' output will activate, emitting the list [1, 2, 3]
+kwargs = {"streams": [1, 2, 3], "query": "Haystack"}
+result = router.run(**kwargs)
+assert result == {"enough_streams": [1, 2, 3]}
+```
+
+In this example, we configure two routes. The first route sends the 'streams' value to 'enough_streams' if the
+stream count exceeds two. The second route directs 'streams' to 'insufficient_streams' if there
+are two or fewer streams.
+
+In the pipeline setup, the Router connects to other components using the output names. For example,
+'enough_streams' might connect to a component that processes streams, while
+'insufficient_streams' might connect to a component that fetches more streams.
+
+Here is a pipeline that uses `ConditionalRouter` and routes the fetched `ByteStreams` to
+different components depending on the number of streams fetched:
+
+```python
+from haystack import Pipeline
+from haystack.dataclasses import ByteStream
+from haystack.components.routers import ConditionalRouter
+
+routes = [
+ {"condition": "{{count > 5}}",
+ "output": "Processing many items",
+ "output_name": "many_items",
+ "output_type": str,
+ },
+ {"condition": "{{count <= 5}}",
+ "output": "Processing few items",
+ "output_name": "few_items",
+ "output_type": str,
+ },
+]
+
+pipe = Pipeline()
+pipe.add_component("router", ConditionalRouter(routes))
+
+# Run with count > 5
+result = pipe.run({"router": {"count": 10}})
+print(result)
+# >> {'router': {'many_items': 'Processing many items'}}
+
+# Run with count <= 5
+result = pipe.run({"router": {"count": 3}})
+print(result)
+# >> {'router': {'few_items': 'Processing few items'}}
+```
+
+#### __init__
+
+```python
+__init__(
+ routes: list[Route],
+ custom_filters: dict[str, Callable] | None = None,
+ unsafe: bool = False,
+ validate_output_type: bool = False,
+ optional_variables: list[str] | None = None,
+) -> None
+```
+
+Initializes the `ConditionalRouter` with a list of routes detailing the conditions for routing.
+
+**Parameters:**
+
+- **routes** (list\[Route\]) – A list of dictionaries, each defining a route.
+ Each route has these four elements:
+- `condition`: A Jinja2 string expression that determines if the route is selected.
+- `output`: A Jinja2 expression defining the route's output value.
+- `output_type`: The type of the output data (for example, `str`, `list[int]`).
+- `output_name`: The name you want to use to publish `output`. This name is used to connect
+ the router to other components in the pipeline.
+- **custom_filters** (dict\[str, Callable\] | None) – A dictionary of custom Jinja2 filters used in the condition expressions.
+ For example, passing `{"my_filter": my_filter_fcn}` where:
+- `my_filter` is the name of the custom filter.
+- `my_filter_fcn` is a callable that takes `my_var:str` and returns `my_var[:3]`.
+ `{{ my_var|my_filter }}` can then be used inside a route condition expression:
+ `"condition": "{{ my_var|my_filter == 'foo' }}"`.
+- **unsafe** (bool) – Enable execution of arbitrary code in the Jinja template.
+ This should only be used if you trust the source of the template as it can be lead to remote code execution.
+- **validate_output_type** (bool) – Enable validation of routes' output.
+ If a route output doesn't match the declared type a ValueError is raised running.
+- **optional_variables** (list\[str\] | None) – A list of variable names that are optional in your route conditions and outputs.
+ If these variables are not provided at runtime, they will be set to `None`.
+ This allows you to write routes that can handle missing inputs gracefully without raising errors.
+
+Example usage with a default fallback route in a Pipeline:
+
+```python
+from haystack import Pipeline
+from haystack.components.routers import ConditionalRouter
+
+routes = [
+ {
+ "condition": '{{ path == "rag" }}',
+ "output": "{{ question }}",
+ "output_name": "rag_route",
+ "output_type": str
+ },
+ {
+ "condition": "{{ True }}", # fallback route
+ "output": "{{ question }}",
+ "output_name": "default_route",
+ "output_type": str
+ }
+]
+
+router = ConditionalRouter(routes, optional_variables=["path"])
+pipe = Pipeline()
+pipe.add_component("router", router)
+
+# When 'path' is provided in the pipeline:
+result = pipe.run(data={"router": {"question": "What?", "path": "rag"}})
+assert result["router"] == {"rag_route": "What?"}
+
+# When 'path' is not provided, fallback route is taken:
+result = pipe.run(data={"router": {"question": "What?"}})
+assert result["router"] == {"default_route": "What?"}
+```
+
+This pattern is particularly useful when:
+
+- You want to provide default/fallback behavior when certain inputs are missing
+- Some variables are only needed for specific routing conditions
+- You're building flexible pipelines where not all inputs are guaranteed to be present
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ConditionalRouter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- ConditionalRouter – The deserialized component.
+
+#### run
+
+```python
+run(**kwargs: Any) -> dict[str, Any]
+```
+
+Executes the routing logic.
+
+Executes the routing logic by evaluating the specified boolean condition expressions for each route in the
+order they are listed. The method directs the flow of data to the output specified in the first route whose
+`condition` is True.
+
+**Parameters:**
+
+- **kwargs** (Any) – All variables used in the `condition` expressed in the routes. When the component is used in a
+ pipeline, these variables are passed from the previous component's output.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary where the key is the `output_name` of the selected route and the value is the `output`
+ of the selected route.
+
+**Raises:**
+
+- NoRouteSelectedException – If no `condition' in the routes is `True\`.
+- RouteConditionException – If there is an error parsing or evaluating the `condition` expression in the routes.
+- ValueError – If type validation is enabled and route type doesn't match actual value type.
+
+## document_length_router
+
+### DocumentLengthRouter
+
+Categorizes documents based on the length of the `content` field and routes them to the appropriate output.
+
+A common use case for DocumentLengthRouter is handling documents obtained from PDFs that contain non-text
+content, such as scanned pages or images. This component can detect empty or low-content documents and route them to
+components that perform OCR, generate captions, or compute image embeddings.
+
+### Usage example
+
+```python
+from haystack.components.routers import DocumentLengthRouter
+from haystack.dataclasses import Document
+
+docs = [
+ Document(content="Short"),
+ Document(content="Long document "*20),
+]
+
+router = DocumentLengthRouter(threshold=10)
+
+result = router.run(documents=docs)
+print(result)
+
+# {
+# "short_documents": [Document(content="Short", ...)],
+# "long_documents": [Document(content="Long document ...", ...)],
+# }
+```
+
+#### __init__
+
+```python
+__init__(*, threshold: int = 10) -> None
+```
+
+Initialize the DocumentLengthRouter component.
+
+**Parameters:**
+
+- **threshold** (int) – The threshold for the number of characters in the document `content` field. Documents where `content` is
+ None or whose character count is less than or equal to the threshold will be routed to the `short_documents`
+ output. Otherwise, they will be routed to the `long_documents` output.
+ To route only documents with None content to `short_documents`, set the threshold to a negative number.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Categorize input documents into groups based on the length of the `content` field.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to be categorized.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `short_documents`: A list of documents where `content` is None or the length of `content` is less than or
+ equal to the threshold.
+- `long_documents`: A list of documents where the length of `content` is greater than the threshold.
+
+## document_type_router
+
+### DocumentTypeRouter
+
+Routes documents by their MIME types.
+
+DocumentTypeRouter is used to dynamically route documents within a pipeline based on their MIME types.
+It supports exact MIME type matches and regex patterns.
+
+MIME types can be extracted directly from document metadata or inferred from file paths using standard or
+user-supplied MIME type mappings.
+
+### Usage example
+
+```python
+from haystack.components.routers import DocumentTypeRouter
+from haystack.dataclasses import Document
+
+docs = [
+ Document(content="Example text", meta={"file_path": "example.txt"}),
+ Document(content="Another document", meta={"mime_type": "application/pdf"}),
+ Document(content="Unknown type")
+]
+
+router = DocumentTypeRouter(
+ mime_type_meta_field="mime_type",
+ file_path_meta_field="file_path",
+ mime_types=["text/plain", "application/pdf"]
+)
+
+result = router.run(documents=docs)
+print(result)
+```
+
+Expected output:
+
+```python
+{
+ "text/plain": [Document(...)],
+ "application/pdf": [Document(...)],
+ "unclassified": [Document(...)]
+}
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ mime_types: list[str],
+ mime_type_meta_field: str | None = None,
+ file_path_meta_field: str | None = None,
+ additional_mimetypes: dict[str, str] | None = None
+) -> None
+```
+
+Initialize the DocumentTypeRouter component.
+
+**Parameters:**
+
+- **mime_types** (list\[str\]) – A list of MIME types or regex patterns to classify the input documents.
+ (for example: `["text/plain", "audio/x-wav", "image/jpeg"]`).
+- **mime_type_meta_field** (str | None) – Optional name of the metadata field that holds the MIME type.
+- **file_path_meta_field** (str | None) – Optional name of the metadata field that holds the file path. Used to infer the MIME type if
+ `mime_type_meta_field` is not provided or missing in a document.
+- **additional_mimetypes** (dict\[str, str\] | None) – Optional dictionary mapping MIME types to file extensions to enhance or override the standard
+ `mimetypes` module. Useful when working with uncommon or custom file types.
+ For example: `{"application/vnd.custom-type": ".custom"}`.
+
+**Raises:**
+
+- ValueError – If `mime_types` is empty or if both `mime_type_meta_field` and `file_path_meta_field` are
+ not provided.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Categorize input documents into groups based on their MIME type.
+
+MIME types can either be directly available in document metadata or derived from file paths using the
+standard Python `mimetypes` module and custom mappings.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to be categorized.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary where the keys are MIME types (or `"unclassified"`) and the values are lists of documents.
+
+## file_type_router
+
+### FileTypeRouter
+
+Categorizes files or byte streams by their MIME types, helping in context-based routing.
+
+FileTypeRouter supports both exact MIME type matching and regex patterns.
+
+For file paths, MIME types come from extensions, while byte streams use metadata.
+You can use regex patterns in the `mime_types` parameter to set broad categories
+(such as 'audio/*' or 'text/*') or specific types.
+MIME types without regex patterns are treated as exact matches.
+
+### Usage example
+
+```python
+from haystack.components.routers import FileTypeRouter
+from pathlib import Path
+
+# For exact MIME type matching
+router = FileTypeRouter(mime_types=["text/plain", "application/pdf"])
+
+# For flexible matching using regex, to handle all audio types
+router_with_regex = FileTypeRouter(mime_types=[r"audio/.*", r"text/plain"])
+
+sources = [Path("file.txt"), Path("document.pdf"), Path("song.mp3")]
+print(router.run(sources=sources))
+print(router_with_regex.run(sources=sources))
+
+# Expected output:
+# {'text/plain': [
+# PosixPath('file.txt')], 'application/pdf': [PosixPath('document.pdf')], 'unclassified': [PosixPath('song.mp3')
+# ]}
+# {'audio/.*': [
+# PosixPath('song.mp3')], 'text/plain': [PosixPath('file.txt')], 'unclassified': [PosixPath('document.pdf')
+# ]}
+```
+
+#### __init__
+
+```python
+__init__(
+ mime_types: list[str],
+ additional_mimetypes: dict[str, str] | None = None,
+ raise_on_failure: bool = False,
+) -> None
+```
+
+Initialize the FileTypeRouter component.
+
+**Parameters:**
+
+- **mime_types** (list\[str\]) – A list of MIME types or regex patterns to classify the input files or byte streams.
+ (for example: `["text/plain", "audio/x-wav", "image/jpeg"]`).
+- **additional_mimetypes** (dict\[str, str\] | None) – A dictionary containing the MIME type to add to the mimetypes package to prevent unsupported or non-native
+ packages from being unclassified.
+ (for example: `{"application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx"}`).
+- **raise_on_failure** (bool) – If True, raises FileNotFoundError when a file path doesn't exist.
+ If False (default), only emits a warning when a file path doesn't exist.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FileTypeRouter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- FileTypeRouter – The deserialized component.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[ByteStream | Path]]
+```
+
+Categorize files or byte streams according to their MIME types.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – A list of file paths or byte streams to categorize.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the sources.
+ When provided, the sources are internally converted to ByteStream objects and the metadata is added.
+ This value can be a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all ByteStream objects.
+ If it's a list, its length must match the number of sources, as they are zipped together.
+
+**Returns:**
+
+- dict\[str, list\[ByteStream | Path\]\] – A dictionary where the keys are MIME types and the values are lists of data sources.
+ Two extra keys may be returned: `"unclassified"` when a source's MIME type doesn't match any pattern
+ and `"failed"` when a source cannot be processed (for example, a file path that doesn't exist).
+
+**Raises:**
+
+- TypeError – If a source is not a Path, str, or ByteStream.
+
+## llm_messages_router
+
+### LLMMessagesRouter
+
+Routes Chat Messages to different connections using a generative Language Model to perform classification.
+
+This component can be used with general-purpose LLMs and with specialized LLMs for moderation like Llama Guard.
+
+### Usage example
+
+```python
+from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.components.routers.llm_messages_router import LLMMessagesRouter
+from haystack.dataclasses import ChatMessage
+
+# initialize a Chat Generator with a generative model for moderation
+chat_generator = HuggingFaceAPIChatGenerator(
+ api_type="serverless_inference_api",
+ api_params={"model": "openai/gpt-oss-safeguard-20b", "provider": "groq"},
+)
+
+router = LLMMessagesRouter(chat_generator=chat_generator,
+ output_names=["unsafe", "safe"],
+ output_patterns=["unsafe", "safe"])
+
+
+print(router.run([ChatMessage.from_user("How to rob a bank?")]))
+
+# {
+# 'chat_generator_text': 'unsafe\nS2',
+# 'unsafe': [
+# ChatMessage(
+# _role=ChatGenerator) – A ChatGenerator instance which represents the LLM.
+- **output_names** (list\[str\]) – A list of output connection names. These can be used to connect the router to other
+ components.
+- **output_patterns** (list\[str\]) – A list of regular expressions to be matched against the output of the LLM. Each pattern
+ corresponds to an output name. Patterns are evaluated in order.
+ When using moderation models, refer to the model card to understand the expected outputs.
+- **system_prompt** (str | None) – An optional system prompt to customize the behavior of the LLM.
+ For moderation models, refer to the model card for supported customization options.
+
+**Raises:**
+
+- ValueError – If output_names and output_patterns are not non-empty lists of the same length.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the underlying LLM.
+
+#### run
+
+```python
+run(messages: list[ChatMessage]) -> dict[str, str | list[ChatMessage]]
+```
+
+Classify the messages based on LLM output and route them to the appropriate output connection.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessages to be routed. Only user and assistant messages are supported.
+
+**Returns:**
+
+- dict\[str, str | list\[ChatMessage\]\] – A dictionary with the following keys:
+- "chat_generator_text": The text output of the LLM, useful for debugging.
+- "output_names": Each contains the list of messages that matched the corresponding pattern.
+- "unmatched": The messages that did not match any of the output patterns.
+
+**Raises:**
+
+- ValueError – If messages is an empty list or contains messages with unsupported roles.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LLMMessagesRouter
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- LLMMessagesRouter – The deserialized component instance.
+
+## metadata_router
+
+### MetadataRouter
+
+Routes documents or byte streams to different connections based on their metadata fields.
+
+Specify the routing rules in the `init` method.
+If a document or byte stream does not match any of the rules, it's routed to a connection named "unmatched".
+
+### Usage examples
+
+**Routing Documents by metadata:**
+
+```python
+from haystack import Document
+from haystack.components.routers import MetadataRouter
+
+docs = [Document(content="Paris is the capital of France.", meta={"language": "en"}),
+ Document(content="Berlin ist die Haupststadt von Deutschland.", meta={"language": "de"})]
+
+router = MetadataRouter(rules={"en": {"field": "meta.language", "operator": "==", "value": "en"}})
+
+print(router.run(documents=docs))
+# {'en': [Document(id=..., content: 'Paris is the capital of France.', meta: {'language': 'en'})],
+# 'unmatched': [Document(id=..., content: 'Berlin ist die Haupststadt von Deutschland.', meta: {'language': 'de'})]}
+```
+
+**Routing ByteStreams by metadata:**
+
+```python
+from haystack.dataclasses import ByteStream
+from haystack.components.routers import MetadataRouter
+
+streams = [
+ ByteStream.from_string("Hello world", meta={"language": "en"}),
+ ByteStream.from_string("Bonjour le monde", meta={"language": "fr"})
+]
+
+router = MetadataRouter(
+ rules={"english": {"field": "meta.language", "operator": "==", "value": "en"}},
+ output_type=list[ByteStream]
+)
+
+result = router.run(documents=streams)
+# {'english': [ByteStream(...)], 'unmatched': [ByteStream(...)]}
+```
+
+#### __init__
+
+```python
+__init__(rules: dict[str, dict], output_type: type = list[Document]) -> None
+```
+
+Initializes the MetadataRouter component.
+
+**Parameters:**
+
+- **rules** (dict\[str, dict\]) – A dictionary defining how to route documents or byte streams to output connections based on their
+ metadata. Keys are output connection names, and values are dictionaries of
+ [filtering expressions](https://docs.haystack.deepset.ai/docs/metadata-filtering) in Haystack.
+ For example:
+
+```python
+{
+"edge_1": {
+ "operator": "AND",
+ "conditions": [
+ {"field": "meta.created_at", "operator": ">=", "value": "2023-01-01"},
+ {"field": "meta.created_at", "operator": "<", "value": "2023-04-01"},
+ ],
+},
+"edge_2": {
+ "operator": "AND",
+ "conditions": [
+ {"field": "meta.created_at", "operator": ">=", "value": "2023-04-01"},
+ {"field": "meta.created_at", "operator": "<", "value": "2023-07-01"},
+ ],
+},
+"edge_3": {
+ "operator": "AND",
+ "conditions": [
+ {"field": "meta.created_at", "operator": ">=", "value": "2023-07-01"},
+ {"field": "meta.created_at", "operator": "<", "value": "2023-10-01"},
+ ],
+},
+"edge_4": {
+ "operator": "AND",
+ "conditions": [
+ {"field": "meta.created_at", "operator": ">=", "value": "2023-10-01"},
+ {"field": "meta.created_at", "operator": "<", "value": "2024-01-01"},
+ ],
+},
+}
+```
+
+:param output_type: The type of the output produced. Lists of Documents or ByteStreams can be specified.
+
+#### run
+
+```python
+run(
+ documents: list[Document] | list[ByteStream],
+) -> dict[str, list[Document] | list[ByteStream]]
+```
+
+Routes documents or byte streams to different connections based on their metadata fields.
+
+If a document or byte stream does not match any of the rules, it's routed to a connection named "unmatched".
+
+**Parameters:**
+
+- **documents** (list\[Document\] | list\[ByteStream\]) – A list of `Document` or `ByteStream` objects to be routed based on their metadata.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | list\[ByteStream\]\] – A dictionary where the keys are the names of the output connections (including `"unmatched"`)
+ and the values are lists of `Document` or `ByteStream` objects that matched the corresponding rules.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MetadataRouter
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- MetadataRouter – The deserialized component instance.
+
+## text_language_router
+
+### TextLanguageRouter
+
+Routes text strings to different output connections based on their language.
+
+Provide a list of languages during initialization. If the document's text doesn't match any of the
+specified languages, the metadata value is set to "unmatched".
+For routing documents based on their language, use the DocumentLanguageClassifier component,
+followed by the MetaDataRouter.
+
+### Usage example
+
+```python
+from haystack import Pipeline, Document
+from haystack.components.routers import TextLanguageRouter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+
+document_store = InMemoryDocumentStore()
+document_store.write_documents([Document(content="Elvis Presley was an American singer and actor.")])
+
+p = Pipeline()
+p.add_component(instance=TextLanguageRouter(languages=["en"]), name="text_language_router")
+p.add_component(instance=InMemoryBM25Retriever(document_store=document_store), name="retriever")
+p.connect("text_language_router.en", "retriever.query")
+
+result = p.run({"text_language_router": {"text": "Who was Elvis Presley?"}})
+assert result["retriever"]["documents"][0].content == "Elvis Presley was an American singer and actor."
+
+result = p.run({"text_language_router": {"text": "ένα ελληνικό κείμενο"}})
+assert result["text_language_router"]["unmatched"] == "ένα ελληνικό κείμενο"
+```
+
+#### __init__
+
+```python
+__init__(languages: list[str] | None = None) -> None
+```
+
+Initialize the TextLanguageRouter component.
+
+**Parameters:**
+
+- **languages** (list\[str\] | None) – A list of ISO language codes.
+ See the supported languages in [`langdetect` documentation](https://github.com/Mimino666/langdetect#languages).
+ If not specified, defaults to ["en"].
+
+#### run
+
+```python
+run(text: str) -> dict[str, str]
+```
+
+Routes the text strings to different output connections based on their language.
+
+If the document's text doesn't match any of the specified languages, the metadata value is set to "unmatched".
+
+**Parameters:**
+
+- **text** (str) – A text string to route.
+
+**Returns:**
+
+- dict\[str, str\] – A dictionary in which the key is the language (or `"unmatched"`),
+ and the value is the text.
+
+**Raises:**
+
+- TypeError – If the input is not a string.
+
+## transformers_text_router
+
+### TransformersTextRouter
+
+Routes the text strings to different connections based on a category label.
+
+The labels are specific to each model and can be found it its description on Hugging Face.
+
+### Usage example
+
+
+
+```python
+from haystack.core.pipeline import Pipeline
+from haystack.components.routers import TransformersTextRouter
+from haystack.components.builders import PromptBuilder
+from haystack.components.generators import HuggingFaceLocalGenerator
+
+p = Pipeline()
+p.add_component(
+ instance=TransformersTextRouter(model="papluca/xlm-roberta-base-language-detection"),
+ name="text_router"
+)
+p.add_component(
+ instance=PromptBuilder(template="Answer the question: {{query}}\nAnswer:"),
+ name="english_prompt_builder"
+)
+p.add_component(
+ instance=PromptBuilder(template="Beantworte die Frage: {{query}}\nAntwort:"),
+ name="german_prompt_builder"
+)
+
+p.add_component(
+ instance=HuggingFaceLocalGenerator(model="DiscoResearch/Llama3-DiscoLeo-Instruct-8B-v0.1"),
+ name="german_llm"
+)
+p.add_component(
+ instance=HuggingFaceLocalGenerator(model="microsoft/Phi-3-mini-4k-instruct"),
+ name="english_llm"
+)
+
+p.connect("text_router.en", "english_prompt_builder.query")
+p.connect("text_router.de", "german_prompt_builder.query")
+p.connect("english_prompt_builder.prompt", "english_llm.prompt")
+p.connect("german_prompt_builder.prompt", "german_llm.prompt")
+
+# English Example
+print(p.run({"text_router": {"text": "What is the capital of Germany?"}}))
+
+# German Example
+print(p.run({"text_router": {"text": "Was ist die Hauptstadt von Deutschland?"}}))
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ labels: list[str] | None = None,
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ huggingface_pipeline_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Initializes the TransformersTextRouter component.
+
+**Parameters:**
+
+- **model** (str) – The name or path of a Hugging Face model for text classification.
+- **labels** (list\[str\] | None) – The list of labels. If not provided, the component fetches the labels
+ from the model configuration file hosted on the Hugging Face Hub using
+ `transformers.AutoConfig.from_pretrained`.
+- **device** (ComponentDevice | None) – The device for loading the model. If `None`, automatically selects the default device.
+ If a device or device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter.
+- **token** (Secret | None) – The API token used to download private models from Hugging Face.
+ If `True`, uses either `HF_API_TOKEN` or `HF_TOKEN` environment variables.
+ To generate these tokens, run `transformers-cli login`.
+- **huggingface_pipeline_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments for initializing the Hugging Face
+ text classification pipeline.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TransformersTextRouter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- TransformersTextRouter – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, str]
+```
+
+Routes the text strings to different connections based on a category label.
+
+**Parameters:**
+
+- **text** (str) – A string of text to route.
+
+**Returns:**
+
+- dict\[str, str\] – A dictionary with the label as key and the text as value.
+
+**Raises:**
+
+- TypeError – If the input is not a str.
+
+## zero_shot_text_router
+
+### TransformersZeroShotTextRouter
+
+Routes the text strings to different connections based on a category label.
+
+Specify the set of labels for categorization when initializing the component.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.core.pipeline import Pipeline
+from haystack.components.routers import TransformersZeroShotTextRouter
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore()
+doc_embedder = SentenceTransformersDocumentEmbedder(model="intfloat/e5-base-v2")
+docs = [
+ Document(
+ content="Germany, officially the Federal Republic of Germany, is a country in the western region of "
+ "Central Europe. The nation's capital and most populous city is Berlin and its main financial centre "
+ "is Frankfurt; the largest urban area is the Ruhr."
+ ),
+ Document(
+ content="France, officially the French Republic, is a country located primarily in Western Europe. "
+ "France is a unitary semi-presidential republic with its capital in Paris, the country's largest city "
+ "and main cultural and commercial centre; other major urban areas include Marseille, Lyon, Toulouse, "
+ "Lille, Bordeaux, Strasbourg, Nantes and Nice."
+ )
+]
+docs_with_embeddings = doc_embedder.run(docs)
+document_store.write_documents(docs_with_embeddings["documents"])
+
+p = Pipeline()
+p.add_component(instance=TransformersZeroShotTextRouter(labels=["passage", "query"]), name="text_router")
+p.add_component(
+ instance=SentenceTransformersTextEmbedder(model="intfloat/e5-base-v2", prefix="passage: "),
+ name="passage_embedder"
+)
+p.add_component(
+ instance=SentenceTransformersTextEmbedder(model="intfloat/e5-base-v2", prefix="query: "),
+ name="query_embedder"
+)
+p.add_component(
+ instance=InMemoryEmbeddingRetriever(document_store=document_store),
+ name="query_retriever"
+)
+p.add_component(
+ instance=InMemoryEmbeddingRetriever(document_store=document_store),
+ name="passage_retriever"
+)
+
+p.connect("text_router.passage", "passage_embedder.text")
+p.connect("passage_embedder.embedding", "passage_retriever.query_embedding")
+p.connect("text_router.query", "query_embedder.text")
+p.connect("query_embedder.embedding", "query_retriever.query_embedding")
+
+# Query Example
+p.run({"text_router": {"text": "What is the capital of Germany?"}})
+
+# Passage Example
+p.run({
+ "text_router":{
+ "text": "The United Kingdom of Great Britain and Northern Ireland, commonly known as the " "United Kingdom (UK) or Britain, is a country in Northwestern Europe, off the north-western coast of " "the continental mainland."
+ }
+})
+```
+
+#### __init__
+
+```python
+__init__(
+ labels: list[str],
+ multi_label: bool = False,
+ model: str = "MoritzLaurer/deberta-v3-base-zeroshot-v1.1-all-33",
+ device: ComponentDevice | None = None,
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ huggingface_pipeline_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Initializes the TransformersZeroShotTextRouter component.
+
+**Parameters:**
+
+- **labels** (list\[str\]) – The set of labels to use for classification. Can be a single label,
+ a string of comma-separated labels, or a list of labels.
+- **multi_label** (bool) – Indicates if multiple labels can be true.
+ If `False`, label scores are normalized so their sum equals 1 for each sequence.
+ If `True`, the labels are considered independent and probabilities are normalized for each candidate by
+ doing a softmax of the entailment score vs. the contradiction score.
+- **model** (str) – The name or path of a Hugging Face model for zero-shot text classification.
+- **device** (ComponentDevice | None) – The device for loading the model. If `None`, automatically selects the default device.
+ If a device or device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter.
+- **token** (Secret | None) – The API token used to download private models from Hugging Face.
+ If `True`, uses either `HF_API_TOKEN` or `HF_TOKEN` environment variables.
+ To generate these tokens, run `transformers-cli login`.
+- **huggingface_pipeline_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments for initializing the Hugging Face
+ zero shot text classification.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TransformersZeroShotTextRouter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- TransformersZeroShotTextRouter – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, str]
+```
+
+Routes the text strings to different connections based on a category label.
+
+**Parameters:**
+
+- **text** (str) – A string of text to route.
+
+**Returns:**
+
+- dict\[str, str\] – A dictionary with the label as key and the text as value.
+
+**Raises:**
+
+- TypeError – If the input is not a str.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/samplers_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/samplers_api.md
new file mode 100644
index 0000000000..6b391535fe
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/samplers_api.md
@@ -0,0 +1,81 @@
+---
+title: "Samplers"
+id: samplers-api
+description: "Filters documents based on their similarity scores using top-p sampling."
+slug: "/samplers-api"
+---
+
+
+## top_p
+
+### TopPSampler
+
+Implements top-p (nucleus) sampling for document filtering based on cumulative probability scores.
+
+This component provides functionality to filter a list of documents by selecting those whose scores fall
+within the top 'p' percent of the cumulative distribution. It is useful for focusing on high-probability
+documents while filtering out less relevant ones based on their assigned scores.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.samplers import TopPSampler
+
+sampler = TopPSampler(top_p=0.95, score_field="similarity_score")
+docs = [
+ Document(content="Berlin", meta={"similarity_score": -10.6}),
+ Document(content="Belgrade", meta={"similarity_score": -8.9}),
+ Document(content="Sarajevo", meta={"similarity_score": -4.6}),
+]
+output = sampler.run(documents=docs)
+docs = output["documents"]
+assert len(docs) == 1
+assert docs[0].content == "Sarajevo"
+```
+
+#### __init__
+
+```python
+__init__(
+ top_p: float = 1.0,
+ score_field: str | None = None,
+ min_top_k: int | None = None,
+) -> None
+```
+
+Creates an instance of TopPSampler.
+
+**Parameters:**
+
+- **top_p** (float) – Float between 0 and 1 representing the cumulative probability threshold for document selection.
+ A value of 1.0 indicates no filtering (all documents are retained).
+- **score_field** (str | None) – Name of the field in each document's metadata that contains the score. If None, the default
+ document score field is used.
+- **min_top_k** (int | None) – If specified, the minimum number of documents to return. If the top_p selects
+ fewer documents, additional ones with the next highest scores are added to the selection.
+
+#### run
+
+```python
+run(documents: list[Document], top_p: float | None = None) -> dict[str, Any]
+```
+
+Filters documents using top-p sampling based on their scores.
+
+If the specified top_p results in no documents being selected (especially in cases of a low top_p value), the
+method returns the document with the highest score.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Document objects to be filtered.
+- **top_p** (float | None) – If specified, a float to override the cumulative probability threshold set during initialization.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following key:
+- `documents`: List of Document objects that have been selected based on the top-p sampling.
+
+**Raises:**
+
+- ValueError – If the top_p value is not within the range [0, 1].
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/tool_components_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/tool_components_api.md
new file mode 100644
index 0000000000..59c9779883
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/tool_components_api.md
@@ -0,0 +1,314 @@
+---
+title: "Tool Components"
+id: tool-components-api
+description: "Components related to Tool Calling."
+slug: "/tool-components-api"
+---
+
+
+## tool_invoker
+
+### ToolInvokerError
+
+Bases: Exception
+
+Base exception class for ToolInvoker errors.
+
+### ToolNotFoundException
+
+Bases: ToolInvokerError
+
+Exception raised when a tool is not found in the list of available tools.
+
+### StringConversionError
+
+Bases: ToolInvokerError
+
+Exception raised when the conversion of a tool result to a string fails.
+
+### ResultConversionError
+
+Bases: ToolInvokerError
+
+Exception raised when the conversion of a tool output to a result fails.
+
+### ToolOutputMergeError
+
+Bases: ToolInvokerError
+
+Exception raised when merging tool outputs into state fails.
+
+#### from_exception
+
+```python
+from_exception(tool_name: str, error: Exception) -> ToolOutputMergeError
+```
+
+Create a ToolOutputMergeError from an exception.
+
+### ToolInvoker
+
+Invokes tools based on prepared tool calls and returns the results as a list of ChatMessage objects.
+
+Also handles reading/writing from a shared `State`.
+At initialization, the ToolInvoker component is provided with a list of available tools.
+At runtime, the component processes a list of ChatMessage object containing tool calls
+and invokes the corresponding tools.
+The results of the tool invocations are returned as a list of ChatMessage objects with tool role.
+
+Usage example:
+
+```python
+from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.tools import Tool
+from haystack.components.tools import ToolInvoker
+
+# Tool definition
+def dummy_weather_function(city: str):
+ return f"The weather in {city} is 20 degrees."
+
+parameters = {"type": "object",
+ "properties": {"city": {"type": "string"}},
+ "required": ["city"]}
+
+tool = Tool(name="weather_tool",
+ description="A tool to get the weather",
+ function=dummy_weather_function,
+ parameters=parameters)
+
+# Usually, the ChatMessage with tool_calls is generated by a Language Model
+# Here, we create it manually for demonstration purposes
+tool_call = ToolCall(
+ tool_name="weather_tool",
+ arguments={"city": "Berlin"}
+)
+message = ChatMessage.from_assistant(tool_calls=[tool_call])
+
+# ToolInvoker initialization and run
+invoker = ToolInvoker(tools=[tool])
+result = invoker.run(messages=[message])
+
+print(result)
+```
+
+```
+# >> {
+# >> 'tool_messages': [
+# >> ChatMessage(
+# >> _role=ToolsType) – A list of Tool and/or Toolset objects, or a Toolset instance that can resolve tools.
+- **raise_on_failure** (bool) – If True, the component will raise an exception in case of errors
+ (tool not found, tool invocation errors, tool result conversion errors).
+ If False, the component will return a ChatMessage object with `error=True`
+ and a description of the error in `result`.
+- **convert_result_to_json_string** (bool) – If True, the tool invocation result will be converted to a string using `json.dumps`.
+ If False, the tool invocation result will be converted to a string using `str`.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that will be called to emit tool results.
+ Note that the result is only emitted once it becomes available — it is not
+ streamed incrementally in real time.
+- **enable_streaming_callback_passthrough** (bool) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
+ This allows tools to stream their results back to the client.
+ Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
+ If False, the `streaming_callback` will not be passed to the tool invocation.
+- **max_workers** (int) – The maximum number of workers to use in the thread pool executor.
+ This also decides the maximum number of concurrent tool invocations.
+
+**Raises:**
+
+- ValueError – If no tools are provided or if duplicate tool names are found.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the tool invoker.
+
+This will warm up the tools registered in the tool invoker.
+This method is idempotent and will only warm up the tools once.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ state: State | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ *,
+ enable_streaming_callback_passthrough: bool | None = None,
+ tools: ToolsType | None = None
+) -> dict[str, Any]
+```
+
+Processes ChatMessage objects containing tool calls and invokes the corresponding tools, if available.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage objects.
+- **state** (State | None) – The runtime state that should be used by the tools.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that will be called to emit tool results.
+ Note that the result is only emitted once it becomes available — it is not
+ streamed incrementally in real time.
+- **enable_streaming_callback_passthrough** (bool | None) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
+ This allows tools to stream their results back to the client.
+ Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
+ If False, the `streaming_callback` will not be passed to the tool invocation.
+ If None, the value from the constructor will be used.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role.
+ Each ChatMessage objects wraps the result of a tool invocation.
+
+**Raises:**
+
+- ToolNotFoundException – If the tool is not found in the list of available tools and `raise_on_failure` is True.
+- ToolInvocationError – If the tool invocation fails and `raise_on_failure` is True.
+- StringConversionError – If the conversion of the tool result to a string fails and `raise_on_failure` is True.
+- ToolOutputMergeError – If merging tool outputs into state fails and `raise_on_failure` is True.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ state: State | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ *,
+ enable_streaming_callback_passthrough: bool | None = None,
+ tools: ToolsType | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously processes ChatMessage objects containing tool calls.
+
+Multiple tool calls are performed concurrently.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage objects.
+- **state** (State | None) – The runtime state that should be used by the tools.
+- **streaming_callback** (StreamingCallbackT | None) – An asynchronous callback function that will be called to emit tool results.
+ Note that the result is only emitted once it becomes available — it is not
+ streamed incrementally in real time.
+- **enable_streaming_callback_passthrough** (bool | None) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
+ This allows tools to stream their results back to the client.
+ Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
+ If False, the `streaming_callback` will not be passed to the tool invocation.
+ If None, the value from the constructor will be used.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role.
+ Each ChatMessage objects wraps the result of a tool invocation.
+
+**Raises:**
+
+- ToolNotFoundException – If the tool is not found in the list of available tools and `raise_on_failure` is True.
+- ToolInvocationError – If the tool invocation fails and `raise_on_failure` is True.
+- StringConversionError – If the conversion of the tool result to a string fails and `raise_on_failure` is True.
+- ToolOutputMergeError – If merging tool outputs into state fails and `raise_on_failure` is True.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ToolInvoker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- ToolInvoker – The deserialized component.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/tools_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/tools_api.md
new file mode 100644
index 0000000000..d71226ccfd
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/tools_api.md
@@ -0,0 +1,1130 @@
+---
+title: "Tools"
+id: tools-api
+description: "Unified abstractions to represent tools across the framework."
+slug: "/tools-api"
+---
+
+
+## component_tool
+
+### ComponentTool
+
+Bases: Tool
+
+A Tool that wraps Haystack components, allowing them to be used as tools by LLMs.
+
+ComponentTool automatically generates LLM-compatible tool schemas from component input sockets,
+which are derived from the component's `run` method signature and type hints.
+
+Key features:
+
+- Automatic LLM tool calling schema generation from component input sockets
+- Type conversion and validation for component inputs
+- Support for types:
+ - Dataclasses
+ - Lists of dataclasses
+ - Basic types (str, int, float, bool, dict)
+ - Lists of basic types
+- Automatic name generation from component class name
+- Description extraction from component docstrings
+
+To use ComponentTool, you first need a Haystack component - either an existing one or a new one you create.
+You can create a ComponentTool from the component by passing the component to the ComponentTool constructor.
+Below is an example of creating a ComponentTool from an existing SerperDevWebSearch component.
+
+## Usage Example:
+
+
+
+```python
+from haystack import component, Pipeline
+from haystack.tools import ComponentTool
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.utils import Secret
+from haystack.components.tools.tool_invoker import ToolInvoker
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+# Create a SerperDev search component
+search = SerperDevWebSearch(api_key=Secret.from_env_var("SERPERDEV_API_KEY"), top_k=3)
+
+# Create a tool from the component
+tool = ComponentTool(
+ component=search,
+ name="web_search", # Optional: defaults to "serper_dev_web_search"
+ description="Search the web for current information on any topic" # Optional: defaults to component docstring
+)
+
+# Create pipeline with OpenAIChatGenerator and ToolInvoker
+pipeline = Pipeline()
+pipeline.add_component("llm", OpenAIChatGenerator(tools=[tool]))
+pipeline.add_component("tool_invoker", ToolInvoker(tools=[tool]))
+
+# Connect components
+pipeline.connect("llm.replies", "tool_invoker.messages")
+
+message = ChatMessage.from_user("Use the web search tool to find information about Nikola Tesla")
+
+# Run pipeline
+result = pipeline.run({"llm": {"messages": [message]}})
+
+print(result)
+```
+
+#### __init__
+
+```python
+__init__(
+ component: Component,
+ name: str | None = None,
+ description: str | None = None,
+ parameters: dict[str, Any] | None = None,
+ *,
+ outputs_to_string: dict[str, str | Callable[[Any], str]] | None = None,
+ inputs_from_state: dict[str, str] | None = None,
+ outputs_to_state: dict[str, dict[str, str | Callable]] | None = None
+) -> None
+```
+
+Create a Tool instance from a Haystack component.
+
+**Parameters:**
+
+- **component** (Component) – The Haystack component to wrap as a tool.
+- **name** (str | None) – Optional name for the tool (defaults to snake_case of component class name).
+- **description** (str | None) – Optional description (defaults to component's docstring).
+- **parameters** (dict\[str, Any\] | None) – A JSON schema defining the parameters expected by the Tool.
+ Will fall back to the parameters defined in the component's run method signature if not provided.
+- **outputs_to_string** (dict\[str, str | Callable\\[[Any\], str\]\] | None) – Optional dictionary defining how tool outputs should be converted into string(s) or results.
+ If not provided, the tool result is converted to a string using a default handler.
+
+`outputs_to_string` supports two formats:
+
+1. Single output format - use "source", "handler", and/or "raw_result" at the root level:
+
+ ```python
+ {
+ "source": "docs", "handler": format_documents, "raw_result": False
+ }
+ ```
+
+ - `source`: If provided, only the specified output key is sent to the handler.
+ - `handler`: A function that takes the tool output (or the extracted source value) and returns the
+ final result.
+ - `raw_result`: If `True`, the result is returned raw without string conversion, but applying the
+ `handler` if provided. This is intended for tools that return images. In this mode, the Tool
+ function or the `handler` function must return a list of `TextContent`/`ImageContent` objects to
+ ensure compatibility with Chat Generators.
+
+1. Multiple output format - map keys to individual configurations:
+
+ ```python
+ {
+ "formatted_docs": {"source": "docs", "handler": format_documents},
+ "summary": {"source": "summary_text", "handler": str.upper}
+ }
+ ```
+
+ Each key maps to a dictionary that can contain "source" and/or "handler".
+ Note that `raw_result` is not supported in the multiple output format.
+
+- **inputs_from_state** (dict\[str, str\] | None) – Optional dictionary mapping state keys to tool parameter names.
+ Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- **outputs_to_state** (dict\[str, dict\[str, str | Callable\]\] | None) – Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
+ If the source is provided only the specified output key is sent to the handler.
+ Example:
+
+```python
+{
+ "documents": {"source": "docs", "handler": custom_handler}
+}
+```
+
+If the source is omitted the whole tool result is sent to the handler.
+Example:
+
+```python
+{
+ "documents": {"handler": custom_handler}
+}
+```
+
+**Raises:**
+
+- TypeError – If the object passed is not a Haystack Component instance.
+- ValueError – If the component has already been added to a pipeline, or if schema generation fails.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Prepare the ComponentTool for use.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the ComponentTool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ComponentTool
+```
+
+Deserializes the ComponentTool from a dictionary.
+
+## from_function
+
+### create_tool_from_function
+
+```python
+create_tool_from_function(
+ function: Callable,
+ name: str | None = None,
+ description: str | None = None,
+ inputs_from_state: dict[str, str] | None = None,
+ outputs_to_state: dict[str, dict[str, Any]] | None = None,
+ outputs_to_string: dict[str, Any] | None = None,
+) -> Tool
+```
+
+Create a Tool instance from a function.
+
+Allows customizing the Tool name and description.
+For simpler use cases, consider using the `@tool` decorator.
+
+### Usage example
+
+```python
+from typing import Annotated, Literal
+from haystack.tools import create_tool_from_function
+
+def get_weather(
+ city: Annotated[str, "the city for which to get the weather"] = "Munich",
+ unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
+ '''A simple function to get the current weather for a location.'''
+ return f"Weather report for {city}: 20 {unit}, sunny"
+
+tool = create_tool_from_function(get_weather)
+
+print(tool)
+# >> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
+# >> parameters={
+# >> 'type': 'object',
+# >> 'properties': {
+# >> 'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
+# >> 'unit': {
+# >> 'type': 'string',
+# >> 'enum': ['Celsius', 'Fahrenheit'],
+# >> 'description': 'the unit for the temperature',
+# >> 'default': 'Celsius',
+# >> },
+# >> }
+# >> },
+# >> function=Callable) – The function to be converted into a Tool.
+ The function must include type hints for all parameters.
+ The function is expected to have basic python input types (str, int, float, bool, list, dict, tuple).
+ Other input types may work but are not guaranteed.
+ If a parameter is annotated using `typing.Annotated`, its metadata will be used as parameter description.
+- **name** (str | None) – The name of the Tool. If not provided, the name of the function will be used.
+- **description** (str | None) – The description of the Tool. If not provided, the docstring of the function will be used.
+ To intentionally leave the description empty, pass an empty string.
+- **inputs_from_state** (dict\[str, str\] | None) – Optional dictionary mapping state keys to tool parameter names.
+ Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- **outputs_to_state** (dict\[str, dict\[str, Any\]\] | None) – Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
+ If the source is provided only the specified output key is sent to the handler.
+ Example:
+
+```python
+{
+ "documents": {"source": "docs", "handler": custom_handler}
+}
+```
+
+If the source is omitted the whole tool result is sent to the handler.
+Example:
+
+```python
+{
+ "documents": {"handler": custom_handler}
+}
+```
+
+- **outputs_to_string** (dict\[str, Any\] | None) – Optional dictionary defining how tool outputs should be converted into string(s) or results.
+ If not provided, the tool result is converted to a string using a default handler.
+
+`outputs_to_string` supports two formats:
+
+1. Single output format - use "source", "handler", and/or "raw_result" at the root level:
+
+ ```python
+ {
+ "source": "docs", "handler": format_documents, "raw_result": False
+ }
+ ```
+
+ - `source`: If provided, only the specified output key is sent to the handler. If not provided, the whole
+ tool result is sent to the handler.
+ - `handler`: A function that takes the tool output (or the extracted source value) and returns the
+ final result.
+ - `raw_result`: If `True`, the result is returned raw without string conversion, but applying the `handler`
+ if provided. This is intended for tools that return images. In this mode, the Tool function or the
+ `handler` must return a list of `TextContent`/`ImageContent` objects to ensure compatibility with Chat
+ Generators.
+
+1. Multiple output format - map keys to individual configurations:
+
+ ```python
+ {
+ "formatted_docs": {"source": "docs", "handler": format_documents},
+ "summary": {"source": "summary_text", "handler": str.upper}
+ }
+ ```
+
+ Each key maps to a dictionary that can contain "source" and/or "handler".
+ Note that `raw_result` is not supported in the multiple output format.
+
+**Returns:**
+
+- Tool – The Tool created from the function.
+
+**Raises:**
+
+- ValueError – If any parameter of the function lacks a type hint.
+- SchemaGenerationError – If there is an error generating the JSON schema for the Tool.
+
+### tool
+
+```python
+tool(
+ function: Callable | None = None,
+ *,
+ name: str | None = None,
+ description: str | None = None,
+ inputs_from_state: dict[str, str] | None = None,
+ outputs_to_state: dict[str, dict[str, Any]] | None = None,
+ outputs_to_string: dict[str, Any] | None = None
+) -> Tool | Callable[[Callable], Tool]
+```
+
+Decorator to convert a function into a Tool.
+
+Can be used with or without parameters:
+@tool # without parameters
+def my_function(): ...
+
+@tool(name="custom_name") # with parameters
+def my_function(): ...
+
+### Usage example
+
+```python
+from typing import Annotated, Literal
+from haystack.tools import tool
+
+@tool
+def get_weather(
+ city: Annotated[str, "the city for which to get the weather"] = "Munich",
+ unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
+ '''A simple function to get the current weather for a location.'''
+ return f"Weather report for {city}: 20 {unit}, sunny"
+
+print(get_weather)
+# >> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
+# >> parameters={
+# >> 'type': 'object',
+# >> 'properties': {
+# >> 'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
+# >> 'unit': {
+# >> 'type': 'string',
+# >> 'enum': ['Celsius', 'Fahrenheit'],
+# >> 'description': 'the unit for the temperature',
+# >> 'default': 'Celsius',
+# >> },
+# >> }
+# >> },
+# >> function=Callable | None) – The function to decorate (when used without parameters)
+- **name** (str | None) – Optional custom name for the tool
+- **description** (str | None) – Optional custom description
+- **inputs_from_state** (dict\[str, str\] | None) – Optional dictionary mapping state keys to tool parameter names.
+ Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- **outputs_to_state** (dict\[str, dict\[str, Any\]\] | None) – Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
+ If the source is provided only the specified output key is sent to the handler.
+ Example:
+
+```python
+{
+ "documents": {"source": "docs", "handler": custom_handler}
+}
+```
+
+If the source is omitted the whole tool result is sent to the handler.
+Example:
+
+```python
+{
+ "documents": {"handler": custom_handler}
+}
+```
+
+- **outputs_to_string** (dict\[str, Any\] | None) – Optional dictionary defining how tool outputs should be converted into string(s) or results.
+ If not provided, the tool result is converted to a string using a default handler.
+
+`outputs_to_string` supports two formats:
+
+1. Single output format - use "source", "handler", and/or "raw_result" at the root level:
+
+ ```python
+ {
+ "source": "docs", "handler": format_documents, "raw_result": False
+ }
+ ```
+
+ - `source`: If provided, only the specified output key is sent to the handler. If not provided, the whole
+ tool result is sent to the handler.
+ - `handler`: A function that takes the tool output (or the extracted source value) and returns the
+ final result.
+ - `raw_result`: If `True`, the result is returned raw without string conversion, but applying the `handler`
+ if provided. This is intended for tools that return images. In this mode, the Tool function or the
+ `handler` must return a list of `TextContent`/`ImageContent` objects to ensure compatibility with Chat
+ Generators.
+
+1. Multiple output format - map keys to individual configurations:
+
+ ```python
+ {
+ "formatted_docs": {"source": "docs", "handler": format_documents},
+ "summary": {"source": "summary_text", "handler": str.upper}
+ }
+ ```
+
+ Each key maps to a dictionary that can contain "source" and/or "handler".
+ Note that `raw_result` is not supported in the multiple output format.
+
+**Returns:**
+
+- Tool | Callable\\[[Callable\], Tool\] – Either a Tool instance or a decorator function that will create one
+
+## pipeline_tool
+
+### PipelineTool
+
+Bases: ComponentTool
+
+A Tool that wraps Haystack Pipelines, allowing them to be used as tools by LLMs.
+
+PipelineTool automatically generates LLM-compatible tool schemas from pipeline input sockets,
+which are derived from the underlying components in the pipeline.
+
+Key features:
+
+- Automatic LLM tool calling schema generation from pipeline inputs
+- Description extraction of pipeline inputs based on the underlying component docstrings
+
+To use PipelineTool, you first need a Haystack pipeline.
+Below is an example of creating a PipelineTool
+
+## Usage Example:
+
+```python
+from haystack import Document, Pipeline
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.embedders.sentence_transformers_text_embedder import SentenceTransformersTextEmbedder
+from haystack.components.embedders.sentence_transformers_document_embedder import (
+ SentenceTransformersDocumentEmbedder
+)
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+from haystack.components.agents import Agent
+from haystack.tools import PipelineTool
+
+# Initialize a document store and add some documents
+document_store = InMemoryDocumentStore()
+document_embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+documents = [
+ Document(content="Nikola Tesla was a Serbian-American inventor and electrical engineer."),
+ Document(
+ content="He is best known for his contributions to the design of the modern alternating current (AC) "
+ "electricity supply system."
+ ),
+]
+docs_with_embeddings = document_embedder.run(documents=documents)["documents"]
+document_store.write_documents(docs_with_embeddings)
+
+# Build a simple retrieval pipeline
+retrieval_pipeline = Pipeline()
+retrieval_pipeline.add_component(
+ "embedder", SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+)
+retrieval_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+
+retrieval_pipeline.connect("embedder.embedding", "retriever.query_embedding")
+
+# Wrap the pipeline as a tool
+retriever_tool = PipelineTool(
+ pipeline=retrieval_pipeline,
+ input_mapping={"query": ["embedder.text"]},
+ output_mapping={"retriever.documents": "documents"},
+ name="document_retriever",
+ description="For any questions about Nikola Tesla, always use this tool",
+)
+
+# Create an Agent with the tool
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-4.1-mini"),
+ tools=[retriever_tool]
+)
+
+# Let the Agent handle a query
+result = agent.run([ChatMessage.from_user("Who was Nikola Tesla?")])
+
+# Print result of the tool call
+print("Tool Call Result:")
+print(result["messages"][2].tool_call_result.result)
+print("")
+
+# Print answer
+print("Answer:")
+print(result["messages"][-1].text)
+```
+
+#### __init__
+
+```python
+__init__(
+ pipeline: Pipeline | AsyncPipeline,
+ *,
+ name: str,
+ description: str,
+ input_mapping: dict[str, list[str]] | None = None,
+ output_mapping: dict[str, str] | None = None,
+ parameters: dict[str, Any] | None = None,
+ outputs_to_string: dict[str, str | Callable[[Any], str]] | None = None,
+ inputs_from_state: dict[str, str] | None = None,
+ outputs_to_state: dict[str, dict[str, str | Callable]] | None = None
+) -> None
+```
+
+Create a Tool instance from a Haystack pipeline.
+
+**Parameters:**
+
+- **pipeline** (Pipeline | AsyncPipeline) – The Haystack pipeline to wrap as a tool.
+- **name** (str) – Name of the tool.
+- **description** (str) – Description of the tool.
+- **input_mapping** (dict\[str, list\[str\]\] | None) – A dictionary mapping component input names to pipeline input socket paths.
+ If not provided, a default input mapping will be created based on all pipeline inputs.
+ Example:
+
+```python
+input_mapping={
+ "query": ["retriever.query", "prompt_builder.query"],
+}
+```
+
+- **output_mapping** (dict\[str, str\] | None) – A dictionary mapping pipeline output socket paths to component output names.
+ If not provided, a default output mapping will be created based on all pipeline outputs.
+ Example:
+
+```python
+output_mapping={
+ "retriever.documents": "documents",
+ "generator.replies": "replies",
+}
+```
+
+- **parameters** (dict\[str, Any\] | None) – A JSON schema defining the parameters expected by the Tool.
+ Will fall back to the parameters defined in the component's run method signature if not provided.
+- **outputs_to_string** (dict\[str, str | Callable\\[[Any\], str\]\] | None) – Optional dictionary defining how tool outputs should be converted into string(s) or results.
+ If not provided, the tool result is converted to a string using a default handler.
+
+`outputs_to_string` supports two formats:
+
+1. Single output format - use "source", "handler", and/or "raw_result" at the root level:
+
+ ```python
+ {
+ "source": "docs", "handler": format_documents, "raw_result": False
+ }
+ ```
+
+ - `source`: If provided, only the specified output key is sent to the handler.
+ - `handler`: A function that takes the tool output (or the extracted source value) and returns the
+ final result.
+ - `raw_result`: If `True`, the result is returned raw without string conversion, but applying the
+ `handler` if provided. This is intended for tools that return images. In this mode, the Tool
+ function or the `handler` function must return a list of `TextContent`/`ImageContent` objects to
+ ensure compatibility with Chat Generators.
+
+1. Multiple output format - map keys to individual configurations:
+
+ ```python
+ {
+ "formatted_docs": {"source": "docs", "handler": format_documents},
+ "summary": {"source": "summary_text", "handler": str.upper}
+ }
+ ```
+
+ Each key maps to a dictionary that can contain "source" and/or "handler".
+ Note that `raw_result` is not supported in the multiple output format.
+
+- **inputs_from_state** (dict\[str, str\] | None) – Optional dictionary mapping state keys to tool parameter names.
+ Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- **outputs_to_state** (dict\[str, dict\[str, str | Callable\]\] | None) – Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
+ If the source is provided only the specified output key is sent to the handler.
+ Example:
+
+```python
+{
+ "documents": {"source": "docs", "handler": custom_handler}
+}
+```
+
+If the source is omitted the whole tool result is sent to the handler.
+Example:
+
+```python
+{
+ "documents": {"handler": custom_handler}
+}
+```
+
+**Raises:**
+
+- ValueError – If the provided pipeline is not a valid Haystack Pipeline instance.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the PipelineTool to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized dictionary representation of PipelineTool.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PipelineTool
+```
+
+Deserializes the PipelineTool from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of PipelineTool.
+
+**Returns:**
+
+- PipelineTool – The deserialized PipelineTool instance.
+
+## searchable_toolset
+
+### SearchableToolset
+
+Bases: Toolset
+
+Dynamic tool discovery from large catalogs using BM25 search.
+
+This Toolset enables LLMs to discover and use tools from large catalogs through
+BM25-based search. Instead of exposing all tools at once (which can overwhelm the
+LLM context), it provides a `search_tools` bootstrap tool that allows the LLM to
+find and load specific tools as needed.
+
+For very small catalogs (below `search_threshold`), acts as a simple passthrough
+exposing all tools directly without any discovery mechanism.
+
+### Usage Example
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import Tool, SearchableToolset
+
+# Create a catalog of tools
+catalog = [
+ Tool(name="get_weather", description="Get weather for a city",
+ parameters={}, function=lambda: None),
+ Tool(name="search_web", description="Search the web",
+ parameters={}, function=lambda: None),
+ # ... 100s more tools
+]
+toolset = SearchableToolset(catalog=catalog)
+
+agent = Agent(chat_generator=OpenAIChatGenerator(), tools=toolset)
+
+# The agent is initially provided only with the search_tools tool and will use it to find relevant tools.
+result = agent.run(messages=[ChatMessage.from_user("What's the weather in Milan?")])
+```
+
+#### __init__
+
+```python
+__init__(
+ catalog: ToolsType,
+ *,
+ top_k: int = 3,
+ search_threshold: int = 8,
+ search_tool_name: str = "search_tools",
+ search_tool_description: str | None = None,
+ search_tool_parameters_description: dict[str, str] | None = None
+) -> None
+```
+
+Initialize the SearchableToolset.
+
+**Parameters:**
+
+- **catalog** (ToolsType) – Source of tools - a list of Tools, list of Toolsets, or a single Toolset.
+- **top_k** (int) – Default number of results for search_tools.
+- **search_threshold** (int) – Minimum catalog size to activate search.
+ If catalog has fewer tools, acts as passthrough (all tools visible).
+ Default is 8.
+- **search_tool_name** (str) – Custom name for the bootstrap search tool. Default is "search_tools".
+- **search_tool_description** (str | None) – Custom description for the bootstrap search tool.
+ If not provided, uses a default description.
+- **search_tool_parameters_description** (dict\[str, str\] | None) – Custom descriptions for the bootstrap search tool's parameters.
+ Keys must be a subset of `{"tool_keywords", "k"}`.
+ Example: `{"tool_keywords": "Keywords to find tools, e.g. 'email send'"}`
+
+#### add
+
+```python
+add(tool: Tool | Toolset) -> None
+```
+
+Adding new tools after initialization is not supported for SearchableToolset.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Prepare the toolset for use.
+
+Warms up child toolsets first (so lazy toolsets like MCPToolset can connect),
+then flattens the catalog, indexes it, and creates the search_tools bootstrap tool.
+In passthrough mode, it warms up all catalog tools directly.
+Must be called before using the toolset with an Agent.
+
+#### clear
+
+```python
+clear() -> None
+```
+
+Clear all discovered tools.
+
+This method allows resetting the toolset's discovered tools between agent runs
+when the same toolset instance is reused. This can be useful for long-running
+applications to control memory usage or to start fresh searches.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the toolset to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary representation of the toolset.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SearchableToolset
+```
+
+Deserialize a toolset from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary representation of the toolset.
+
+**Returns:**
+
+- SearchableToolset – New SearchableToolset instance.
+
+## tool
+
+### Tool
+
+Data class representing a Tool that Language Models can prepare a call for.
+
+Accurate definitions of the textual attributes such as `name` and `description`
+are important for the Language Model to correctly prepare the call.
+
+For resource-intensive operations like establishing connections to remote services or
+loading models, override the `warm_up()` method. This method is called before the Tool
+is used and should be idempotent, as it may be called multiple times during
+pipeline/agent setup.
+
+**Parameters:**
+
+- **name** (str) – Name of the Tool.
+- **description** (str) – Description of the Tool.
+- **parameters** (dict\[str, Any\]) – A JSON schema defining the parameters expected by the Tool.
+- **function** (Callable) – The function that will be invoked when the Tool is called.
+ Must be a synchronous function; async functions are not supported.
+- **outputs_to_string** (dict\[str, Any\] | None) – Optional dictionary defining how tool outputs should be converted into string(s) or results.
+ If not provided, the tool result is converted to a string using a default handler.
+
+`outputs_to_string` supports two formats:
+
+1. Single output format - use "source", "handler", and/or "raw_result" at the root level:
+
+ ```python
+ {
+ "source": "docs", "handler": format_documents, "raw_result": False
+ }
+ ```
+
+ - `source`: If provided, only the specified output key is sent to the handler. If not provided, the whole
+ tool result is sent to the handler.
+ - `handler`: A function that takes the tool output (or the extracted source value) and returns the
+ final result.
+ - `raw_result`: If `True`, the result is returned raw without string conversion, but applying the `handler`
+ if provided. This is intended for tools that return images. In this mode, the Tool function or the
+ `handler` must return a list of `TextContent`/`ImageContent` objects to ensure compatibility with Chat
+ Generators.
+
+1. Multiple output format - map keys to individual configurations:
+
+ ```python
+ {
+ "formatted_docs": {"source": "docs", "handler": format_documents},
+ "summary": {"source": "summary_text", "handler": str.upper}
+ }
+ ```
+
+ Each key maps to a dictionary that can contain "source" and/or "handler".
+ Note that `raw_result` is not supported in the multiple output format.
+
+- **inputs_from_state** (dict\[str, str\] | None) – Optional dictionary mapping state keys to tool parameter names.
+ Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- **outputs_to_state** (dict\[str, dict\[str, Any\]\] | None) – Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
+ If the source is provided only the specified output key is sent to the handler.
+ Example:
+
+```python
+{
+ "documents": {"source": "docs", "handler": custom_handler}
+}
+```
+
+If the source is omitted the whole tool result is sent to the handler.
+Example:
+
+```python
+{
+ "documents": {"handler": custom_handler}
+}
+```
+
+**Raises:**
+
+- ValueError – If `function` is async, if `parameters` is not a valid JSON schema, or if the
+ `outputs_to_state`, `outputs_to_string`, or `inputs_from_state` configurations are invalid.
+- TypeError – If any configuration value in `outputs_to_state`, `outputs_to_string`, or
+ `inputs_from_state` has the wrong type.
+
+#### tool_spec
+
+```python
+tool_spec: dict[str, Any]
+```
+
+Return the Tool specification to be used by the Language Model.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Prepare the Tool for use.
+
+Override this method to establish connections to remote services, load models,
+or perform other resource-intensive initialization. This method should be idempotent,
+as it may be called multiple times.
+
+#### invoke
+
+```python
+invoke(**kwargs: Any) -> Any
+```
+
+Invoke the Tool with the provided keyword arguments.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the Tool to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Tool
+```
+
+Deserializes the Tool from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- Tool – Deserialized Tool.
+
+## toolset
+
+### Toolset
+
+A collection of related Tools that can be used and managed as a cohesive unit.
+
+Toolset serves two main purposes:
+
+1. Group related tools together:
+ Toolset allows you to organize related tools into a single collection, making it easier
+ to manage and use them as a unit in Haystack pipelines.
+
+ Example:
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack.components.tools import ToolInvoker
+
+# Define math functions
+def add_numbers(a: int, b: int) -> int:
+ return a + b
+
+def subtract_numbers(a: int, b: int) -> int:
+ return a - b
+
+# Create tools with proper schemas
+add_tool = Tool(
+ name="add",
+ description="Add two numbers",
+ parameters={
+ "type": "object",
+ "properties": {
+ "a": {"type": "integer"},
+ "b": {"type": "integer"}
+ },
+ "required": ["a", "b"]
+ },
+ function=add_numbers
+)
+
+subtract_tool = Tool(
+ name="subtract",
+ description="Subtract b from a",
+ parameters={
+ "type": "object",
+ "properties": {
+ "a": {"type": "integer"},
+ "b": {"type": "integer"}
+ },
+ "required": ["a", "b"]
+ },
+ function=subtract_numbers
+)
+
+# Create a toolset with the math tools
+math_toolset = Toolset([add_tool, subtract_tool])
+
+# Use the toolset with a ToolInvoker or ChatGenerator component
+invoker = ToolInvoker(tools=math_toolset)
+```
+
+2. Base class for dynamic tool loading:
+ By subclassing Toolset, you can create implementations that dynamically load tools
+ from external sources like OpenAPI URLs, MCP servers, or other resources.
+
+ Example:
+
+```python
+from haystack.core.serialization import generate_qualified_class_name
+from haystack.tools import Tool, Toolset
+from haystack.components.tools import ToolInvoker
+
+class CalculatorToolset(Toolset):
+ '''A toolset for calculator operations.'''
+
+ def __init__(self) -> None:
+ tools = self._create_tools()
+ super().__init__(tools)
+
+ def _create_tools(self):
+ # These Tool instances are obviously defined statically and for illustration purposes only.
+ # In a real-world scenario, you would dynamically load tools from an external source here.
+ tools = []
+ add_tool = Tool(
+ name="add",
+ description="Add two numbers",
+ parameters={
+ "type": "object",
+ "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
+ "required": ["a", "b"],
+ },
+ function=lambda a, b: a + b,
+ )
+
+ multiply_tool = Tool(
+ name="multiply",
+ description="Multiply two numbers",
+ parameters={
+ "type": "object",
+ "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
+ "required": ["a", "b"],
+ },
+ function=lambda a, b: a * b,
+ )
+
+ tools.append(add_tool)
+ tools.append(multiply_tool)
+
+ return tools
+
+ def to_dict(self):
+ return {
+ "type": generate_qualified_class_name(type(self)),
+ "data": {}, # no data to serialize as we define the tools dynamically
+ }
+
+ @classmethod
+ def from_dict(cls, data):
+ return cls() # Recreate the tools dynamically during deserialization
+
+# Create the dynamic toolset and use it with ToolInvoker
+calculator_toolset = CalculatorToolset()
+invoker = ToolInvoker(tools=calculator_toolset)
+```
+
+Toolset implements the collection interface (__iter__, __contains__, __len__, __getitem__),
+making it behave like a list of Tools. This makes it compatible with components that expect
+iterable tools, such as ToolInvoker or Haystack chat generators.
+
+When implementing a custom Toolset subclass for dynamic tool loading:
+
+- Perform the dynamic loading in the __init__ method
+- Override to_dict() and from_dict() methods if your tools are defined dynamically
+- Serialize endpoint descriptors rather than tool instances if your tools
+ are loaded from external sources
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Prepare the Toolset for use.
+
+By default, this method iterates through and warms up all tools in the Toolset.
+Subclasses can override this method to customize initialization behavior, such as:
+
+- Setting up shared resources (database connections, HTTP sessions) instead of
+ warming individual tools
+- Implementing custom initialization logic for dynamically loaded tools
+- Controlling when and how tools are initialized
+
+For example, a Toolset that manages tools from an external service (like MCPToolset)
+might override this to initialize a shared connection rather than warming up
+individual tools:
+
+```python
+class MCPToolset(Toolset):
+ def warm_up(self) -> None:
+ # Only warm up the shared MCP connection, not individual tools
+ self.mcp_connection = establish_connection(self.server_url)
+```
+
+This method should be idempotent, as it may be called multiple times.
+
+#### add
+
+```python
+add(tool: Union[Tool, Toolset]) -> None
+```
+
+Add a new Tool or merge another Toolset.
+
+**Parameters:**
+
+- **tool** (Union\[Tool, Toolset\]) – A Tool instance or another Toolset to add
+
+**Raises:**
+
+- ValueError – If adding the tool would result in duplicate tool names
+- TypeError – If the provided object is not a Tool or Toolset
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the Toolset to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the Toolset
+
+Note for subclass implementers:
+The default implementation is ideal for scenarios where Tool resolution is static. However, if your subclass
+of Toolset dynamically resolves Tool instances from external sources—such as an MCP server, OpenAPI URL, or
+a local OpenAPI specification—you should consider serializing the endpoint descriptor instead of the Tool
+instances themselves. This strategy preserves the dynamic nature of your Toolset and minimizes the overhead
+associated with serializing potentially large collections of Tool objects. Moreover, by serializing the
+descriptor, you ensure that the deserialization process can accurately reconstruct the Tool instances, even
+if they have been modified or removed since the last serialization. Failing to serialize the descriptor may
+lead to issues where outdated or incorrect Tool configurations are loaded, potentially causing errors or
+unexpected behavior.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Toolset
+```
+
+Deserialize a Toolset from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary representation of the Toolset
+
+**Returns:**
+
+- Toolset – A new Toolset instance
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/utils_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/utils_api.md
new file mode 100644
index 0000000000..78d731d7bc
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/utils_api.md
@@ -0,0 +1,1143 @@
+---
+title: "Utils"
+id: utils-api
+description: "Utility functions and classes used across the library."
+slug: "/utils-api"
+---
+
+
+## asynchronous
+
+### is_callable_async_compatible
+
+```python
+is_callable_async_compatible(func: Callable) -> bool
+```
+
+Returns if the given callable is usable inside a component's `run_async` method.
+
+**Parameters:**
+
+- **func** (Callable) – The callable to check.
+
+**Returns:**
+
+- bool – True if the callable is compatible, False otherwise.
+
+## auth
+
+### SecretType
+
+Bases: Enum
+
+Type of secret: token (API key) or environment variable.
+
+#### from_str
+
+```python
+from_str(string: str) -> SecretType
+```
+
+Convert a string to a SecretType.
+
+**Parameters:**
+
+- **string** (str) – The string to convert.
+
+### Secret
+
+Bases: ABC
+
+Encapsulates a secret used for authentication.
+
+Usage example:
+
+```python
+from haystack.components.generators import OpenAIGenerator
+from haystack.utils import Secret
+
+generator = OpenAIGenerator(api_key=Secret.from_token("str) – The token to use for authentication.
+
+#### from_env_var
+
+```python
+from_env_var(env_vars: str | list[str], *, strict: bool = True) -> Secret
+```
+
+Create an environment variable-based secret. Accepts one or more environment variables.
+
+Upon resolution, it returns a string token from the first environment variable that is set.
+
+**Parameters:**
+
+- **env_vars** (str | list\[str\]) – A single environment variable or an ordered list of
+ candidate environment variables.
+- **strict** (bool) – Whether to raise an exception if none of the environment
+ variables are set.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the secret to a JSON-serializable dictionary.
+
+Some secrets may not be serializable.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized policy.
+
+#### from_dict
+
+```python
+from_dict(dict: dict[str, Any]) -> Secret
+```
+
+Create a secret from a JSON-serializable dictionary.
+
+**Parameters:**
+
+- **dict** (dict\[str, Any\]) – The dictionary with the serialized data.
+
+**Returns:**
+
+- Secret – The deserialized secret.
+
+#### resolve_value
+
+```python
+resolve_value() -> Any | None
+```
+
+Resolve the secret to an atomic value. The semantics of the value is secret-dependent.
+
+**Returns:**
+
+- Any | None – The value of the secret, if any.
+
+#### type
+
+```python
+type: SecretType
+```
+
+The type of the secret.
+
+### TokenSecret
+
+Bases: Secret
+
+A secret that uses a string token/API key.
+
+Cannot be serialized.
+
+#### resolve_value
+
+```python
+resolve_value() -> Any | None
+```
+
+Return the token.
+
+#### type
+
+```python
+type: SecretType
+```
+
+The type of the secret.
+
+### EnvVarSecret
+
+Bases: Secret
+
+A secret that accepts one or more environment variables.
+
+Upon resolution, it returns a string token from the first environment variable that is set. Can be serialized.
+
+#### resolve_value
+
+```python
+resolve_value() -> Any | None
+```
+
+Resolve the secret to an atomic value. The semantics of the value is secret-dependent.
+
+#### type
+
+```python
+type: SecretType
+```
+
+The type of the secret.
+
+### deserialize_secrets_inplace
+
+```python
+deserialize_secrets_inplace(
+ data: dict[str, Any], keys: Iterable[str], *, recursive: bool = False
+) -> None
+```
+
+Deserialize secrets in a dictionary inplace.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary with the serialized data.
+- **keys** (Iterable\[str\]) – The keys of the secrets to deserialize.
+- **recursive** (bool) – Whether to recursively deserialize nested dictionaries.
+
+## azure
+
+### default_azure_ad_token_provider
+
+```python
+default_azure_ad_token_provider() -> str
+```
+
+Get a Azure AD token using the DefaultAzureCredential and the "https://cognitiveservices.azure.com/.default" scope.
+
+## base_serialization
+
+### serialize_class_instance
+
+```python
+serialize_class_instance(obj: Any) -> dict[str, Any]
+```
+
+Serializes an object that has a `to_dict` method into a dictionary.
+
+**Parameters:**
+
+- **obj** (Any) – The object to be serialized.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the object.
+
+**Raises:**
+
+- SerializationError – If the object does not have a `to_dict` method.
+
+### deserialize_class_instance
+
+```python
+deserialize_class_instance(data: dict[str, Any]) -> Any
+```
+
+Deserializes an object from a dictionary representation generated by `auto_serialize_class_instance`.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- Any – The deserialized object.
+
+**Raises:**
+
+- DeserializationError – If the serialization data is malformed, the class type cannot be imported, or the
+ class does not have a `from_dict` method.
+
+## callable_serialization
+
+### serialize_callable
+
+```python
+serialize_callable(callable_handle: Callable) -> str
+```
+
+Serializes a callable to its full path.
+
+**Parameters:**
+
+- **callable_handle** (Callable) – The callable to serialize
+
+**Returns:**
+
+- str – The full path of the callable
+
+### deserialize_callable
+
+```python
+deserialize_callable(callable_handle: str) -> Callable
+```
+
+Deserializes a callable given its full import path as a string.
+
+**Parameters:**
+
+- **callable_handle** (str) – The full path of the callable_handle
+
+**Returns:**
+
+- Callable – The callable
+
+**Raises:**
+
+- DeserializationError – If the callable cannot be found
+
+## deserialization
+
+### deserialize_chatgenerator_inplace
+
+```python
+deserialize_chatgenerator_inplace(
+ data: dict[str, Any], key: str = "chat_generator"
+) -> None
+```
+
+Deserialize a ChatGenerator in a dictionary inplace.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary with the serialized data.
+- **key** (str) – The key in the dictionary where the ChatGenerator is stored.
+
+**Raises:**
+
+- DeserializationError – If the key is missing in the serialized data, the value is not a dictionary,
+ the type key is missing, the class cannot be imported, or the class lacks a 'from_dict' method.
+
+### deserialize_component_inplace
+
+```python
+deserialize_component_inplace(
+ data: dict[str, Any], key: str = "chat_generator"
+) -> None
+```
+
+Deserialize a Component in a dictionary inplace.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary with the serialized data.
+- **key** (str) – The key in the dictionary where the Component is stored. Default is "chat_generator".
+
+**Raises:**
+
+- DeserializationError – If the key is missing in the serialized data, the value is not a dictionary,
+ the type key is missing, the class cannot be imported, or the class lacks a 'from_dict' method.
+
+## device
+
+### DeviceType
+
+Bases: Enum
+
+Represents device types supported by Haystack.
+
+This also includes devices that are not directly used by models - for example, the disk device is exclusively used
+in device maps for frameworks that support offloading model weights to disk.
+
+#### from_str
+
+```python
+from_str(string: str) -> DeviceType
+```
+
+Create a device type from a string.
+
+**Parameters:**
+
+- **string** (str) – The string to convert.
+
+**Returns:**
+
+- DeviceType – The device type.
+
+### Device
+
+A generic representation of a device.
+
+**Parameters:**
+
+- **type** (DeviceType) – The device type.
+- **id** (int | None) – The optional device id.
+
+#### __init__
+
+```python
+__init__(type: DeviceType, id: int | None = None) -> None
+```
+
+Create a generic device.
+
+**Parameters:**
+
+- **type** (DeviceType) – The device type.
+- **id** (int | None) – The device id.
+
+#### cpu
+
+```python
+cpu() -> Device
+```
+
+Create a generic CPU device.
+
+**Returns:**
+
+- Device – The CPU device.
+
+#### gpu
+
+```python
+gpu(id: int = 0) -> Device
+```
+
+Create a generic GPU device.
+
+**Parameters:**
+
+- **id** (int) – The GPU id.
+
+**Returns:**
+
+- Device – The GPU device.
+
+#### disk
+
+```python
+disk() -> Device
+```
+
+Create a generic disk device.
+
+**Returns:**
+
+- Device – The disk device.
+
+#### mps
+
+```python
+mps() -> Device
+```
+
+Create a generic Apple Metal Performance Shader device.
+
+**Returns:**
+
+- Device – The MPS device.
+
+#### xpu
+
+```python
+xpu() -> Device
+```
+
+Create a generic Intel GPU Optimization device.
+
+**Returns:**
+
+- Device – The XPU device.
+
+#### from_str
+
+```python
+from_str(string: str) -> Device
+```
+
+Create a generic device from a string.
+
+**Returns:**
+
+- Device – The device.
+
+### DeviceMap
+
+A generic mapping from strings to devices.
+
+The semantics of the strings are dependent on target framework. Primarily used to deploy HuggingFace models to
+multiple devices.
+
+**Parameters:**
+
+- **mapping** (dict\[str, Device\]) – Dictionary mapping strings to devices.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, str]
+```
+
+Serialize the mapping to a JSON-serializable dictionary.
+
+**Returns:**
+
+- dict\[str, str\] – The serialized mapping.
+
+#### first_device
+
+```python
+first_device: Device | None
+```
+
+Return the first device in the mapping, if any.
+
+**Returns:**
+
+- Device | None – The first device.
+
+#### from_dict
+
+```python
+from_dict(dict: dict[str, str]) -> DeviceMap
+```
+
+Create a generic device map from a JSON-serialized dictionary.
+
+**Parameters:**
+
+- **dict** (dict\[str, str\]) – The serialized mapping.
+
+**Returns:**
+
+- DeviceMap – The generic device map.
+
+#### from_hf
+
+```python
+from_hf(hf_device_map: dict[str, Union[int, str, torch.device]]) -> DeviceMap
+```
+
+Create a generic device map from a HuggingFace device map.
+
+**Parameters:**
+
+- **hf_device_map** (dict\[str, Union\[int, str, device\]\]) – The HuggingFace device map.
+
+**Returns:**
+
+- DeviceMap – The deserialized device map.
+
+**Raises:**
+
+- TypeError – If a device value in the map is not an int, str, or torch.device.
+
+### ComponentDevice
+
+A representation of a device for a component.
+
+This can be either a single device or a device map.
+
+#### from_str
+
+```python
+from_str(device_str: str) -> ComponentDevice
+```
+
+Create a component device representation from a device string.
+
+The device string can only represent a single device.
+
+**Parameters:**
+
+- **device_str** (str) – The device string.
+
+**Returns:**
+
+- ComponentDevice – The component device representation.
+
+#### from_single
+
+```python
+from_single(device: Device) -> ComponentDevice
+```
+
+Create a component device representation from a single device.
+
+Disks cannot be used as single devices.
+
+**Parameters:**
+
+- **device** (Device) – The device.
+
+**Returns:**
+
+- ComponentDevice – The component device representation.
+
+#### from_multiple
+
+```python
+from_multiple(device_map: DeviceMap) -> ComponentDevice
+```
+
+Create a component device representation from a device map.
+
+**Parameters:**
+
+- **device_map** (DeviceMap) – The device map.
+
+**Returns:**
+
+- ComponentDevice – The component device representation.
+
+#### to_torch
+
+```python
+to_torch() -> torch.device
+```
+
+Convert the component device representation to PyTorch format.
+
+Device maps are not supported.
+
+**Returns:**
+
+- device – The PyTorch device representation.
+
+#### to_torch_str
+
+```python
+to_torch_str() -> str
+```
+
+Convert the component device representation to PyTorch string format.
+
+Device maps are not supported.
+
+**Returns:**
+
+- str – The PyTorch device string representation.
+
+#### to_spacy
+
+```python
+to_spacy() -> int
+```
+
+Convert the component device representation to spaCy format.
+
+Device maps are not supported.
+
+**Returns:**
+
+- int – The spaCy device representation.
+
+#### to_hf
+
+```python
+to_hf() -> int | str | dict[str, int | str]
+```
+
+Convert the component device representation to HuggingFace format.
+
+**Returns:**
+
+- int | str | dict\[str, int | str\] – The HuggingFace device representation.
+
+#### update_hf_kwargs
+
+```python
+update_hf_kwargs(
+ hf_kwargs: dict[str, Any], *, overwrite: bool
+) -> dict[str, Any]
+```
+
+Convert the component device representation to HuggingFace format.
+
+Add them as canonical keyword arguments to the keyword arguments dictionary.
+
+**Parameters:**
+
+- **hf_kwargs** (dict\[str, Any\]) – The HuggingFace keyword arguments dictionary.
+- **overwrite** (bool) – Whether to overwrite existing device arguments.
+
+**Returns:**
+
+- dict\[str, Any\] – The HuggingFace keyword arguments dictionary.
+
+#### has_multiple_devices
+
+```python
+has_multiple_devices: bool
+```
+
+Whether this component device representation contains multiple devices.
+
+#### first_device
+
+```python
+first_device: Optional[ComponentDevice]
+```
+
+Return either the single device or the first device in the device map, if any.
+
+**Returns:**
+
+- Optional\[ComponentDevice\] – The first device.
+
+#### resolve_device
+
+```python
+resolve_device(device: Optional[ComponentDevice] = None) -> ComponentDevice
+```
+
+Select a device for a component. If a device is specified, it's used. Otherwise, the default device is used.
+
+**Parameters:**
+
+- **device** (Optional\[ComponentDevice\]) – The provided device, if any.
+
+**Returns:**
+
+- ComponentDevice – The resolved device.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the component device representation to a JSON-serializable dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The dictionary representation.
+
+#### from_dict
+
+```python
+from_dict(dict: dict[str, Any]) -> ComponentDevice
+```
+
+Create a component device representation from a JSON-serialized dictionary.
+
+**Parameters:**
+
+- **dict** (dict\[str, Any\]) – The serialized representation.
+
+**Returns:**
+
+- ComponentDevice – The deserialized component device.
+
+## filters
+
+### raise_on_invalid_filter_syntax
+
+```python
+raise_on_invalid_filter_syntax(filters: dict[str, Any] | None = None) -> None
+```
+
+Raise an error if the filter syntax is invalid.
+
+### document_matches_filter
+
+```python
+document_matches_filter(
+ filters: dict[str, Any], document: Document | ByteStream
+) -> bool
+```
+
+Return whether `filters` match the Document or the ByteStream.
+
+For a detailed specification of the filters, refer to the
+`DocumentStore.filter_documents()` protocol documentation.
+
+## http_client
+
+### init_http_client
+
+```python
+init_http_client(
+ http_client_kwargs: dict[str, Any] | None = None, async_client: bool = False
+) -> httpx.Client | httpx.AsyncClient | None
+```
+
+Initialize an httpx client based on the http_client_kwargs.
+
+**Parameters:**
+
+- **http_client_kwargs** (dict\[str, Any\] | None) – The kwargs to pass to the httpx client.
+- **async_client** (bool) – Whether to initialize an async client.
+
+**Returns:**
+
+- Client | AsyncClient | None – A httpx client or an async httpx client.
+
+## jinja2_chat_extension
+
+### ChatMessageExtension
+
+Bases: Extension
+
+A Jinja2 extension for creating structured chat messages with mixed content types.
+
+This extension provides a custom `{% message %}` tag that allows creating chat messages
+with different attributes (role, name, meta) and mixed content types (text, images, etc.).
+
+Inspired by [Banks](https://github.com/masci/banks).
+
+Example:
+
+```
+{% message role="system" %}
+You are a helpful assistant. You like to talk with {{user_name}}.
+{% endmessage %}
+
+{% message role="user" %}
+Hello! I am {{user_name}}. Please describe the images.
+{% for image in images %}
+{{ image | templatize_part }}
+{% endfor %}
+{% endmessage %}
+```
+
+### How it works
+
+1. The `{% message %}` tag is used to define a chat message.
+1. The message can contain text and other structured content parts.
+1. To include a structured content part in the message, the `| templatize_part` filter is used.
+ The filter serializes the content part into a JSON string and wraps it in a `Any) – The Jinja2 parser instance
+
+**Returns:**
+
+- Node | list\[Node\] – A CallBlock node containing the parsed message configuration
+
+**Raises:**
+
+- TemplateSyntaxError – If an invalid role is provided
+
+### templatize_part
+
+```python
+templatize_part(value: ChatMessageContentT) -> Markup
+```
+
+Jinja filter to convert an ChatMessageContentT object into JSON string wrapped in special XML content tags.
+
+**Parameters:**
+
+- **value** (ChatMessageContentT) – The ChatMessageContentT object to convert
+
+**Returns:**
+
+- Markup – A JSON string wrapped in special XML content tags marked as safe
+
+**Raises:**
+
+- ValueError – If the value is not an instance of ChatMessageContentT
+
+## jinja2_extensions
+
+### Jinja2TimeExtension
+
+Bases: Extension
+
+A Jinja2 extension for formatting dates and times.
+
+#### __init__
+
+```python
+__init__(environment: Environment) -> None
+```
+
+Initializes the JinjaTimeExtension object.
+
+**Parameters:**
+
+- **environment** (Environment) – The Jinja2 environment to initialize the extension with.
+ It provides the context where the extension will operate.
+
+#### parse
+
+```python
+parse(parser: Any) -> nodes.Node | list[nodes.Node]
+```
+
+Parse the template expression to determine how to handle the datetime formatting.
+
+**Parameters:**
+
+- **parser** (Any) – The parser object that processes the template expressions and manages the syntax tree.
+ It's used to interpret the template's structure.
+
+## jupyter
+
+### is_in_jupyter
+
+```python
+is_in_jupyter() -> bool
+```
+
+Returns `True` if in Jupyter or Google Colab, `False` otherwise.
+
+## misc
+
+### expand_page_range
+
+```python
+expand_page_range(page_range: list[str | int]) -> list[int]
+```
+
+Takes a list of page numbers and ranges and expands them into a list of page numbers.
+
+For example, given a page_range=['1-3', '5', '8', '10-12'] the function will return [1, 2, 3, 5, 8, 10, 11, 12]
+
+**Parameters:**
+
+- **page_range** (list\[str | int\]) – List of page numbers and ranges
+
+**Returns:**
+
+- list\[int\] – An expanded list of page integers
+
+### expit
+
+```python
+expit(x: float | ndarray[Any, Any]) -> float | ndarray[Any, Any]
+```
+
+Compute logistic sigmoid function. Maps input values to a range between 0 and 1
+
+**Parameters:**
+
+- **x** (float | ndarray\[Any, Any\]) – input value. Can be a scalar or a numpy array.
+
+## requests_utils
+
+### request_with_retry
+
+```python
+request_with_retry(
+ attempts: int = 3,
+ status_codes_to_retry: list[int] | None = None,
+ **kwargs: Any
+) -> httpx.Response
+```
+
+Executes an HTTP request with a configurable exponential backoff retry on failures.
+
+Usage example:
+
+
+
+```python
+from haystack.utils import request_with_retry
+
+# Sending an HTTP request with default retry configs
+res = request_with_retry(method="GET", url="https://example.com")
+
+# Sending an HTTP request with custom number of attempts
+res = request_with_retry(method="GET", url="https://example.com", attempts=10)
+
+# Sending an HTTP request with custom HTTP codes to retry
+res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=[408, 503])
+
+# Sending an HTTP request with custom timeout in seconds
+res = request_with_retry(method="GET", url="https://example.com", timeout=5)
+
+# Sending an HTTP request with custom headers
+res = request_with_retry(method="GET", url="https://example.com", headers={"Authorization": "Bearer int) – Maximum number of attempts to retry the request.
+- **status_codes_to_retry** (list\[int\] | None) – List of HTTP status codes that will trigger a retry.
+ When param is `None`, HTTP 408, 418, 429 and 503 will be retried.
+- **kwargs** (Any) – Optional arguments that `httpx.Client.request` accepts.
+
+**Returns:**
+
+- Response – The `httpx.Response` object.
+
+### async_request_with_retry
+
+```python
+async_request_with_retry(
+ attempts: int = 3,
+ status_codes_to_retry: list[int] | None = None,
+ **kwargs: Any
+) -> httpx.Response
+```
+
+Executes an asynchronous HTTP request with a configurable exponential backoff retry on failures.
+
+Usage example:
+
+```python
+import asyncio
+from haystack.utils import async_request_with_retry
+
+# Sending an async HTTP request with default retry configs
+async def example():
+ res = await async_request_with_retry(method="GET", url="https://example.com")
+ return res
+
+# Sending an async HTTP request with custom number of attempts
+async def example_with_attempts():
+ res = await async_request_with_retry(method="GET", url="https://example.com", attempts=10)
+ return res
+
+# Sending an async HTTP request with custom HTTP codes to retry
+async def example_with_status_codes():
+ res = await async_request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=[408, 503])
+ return res
+
+# Sending an async HTTP request with custom timeout in seconds
+async def example_with_timeout():
+ res = await async_request_with_retry(method="GET", url="https://example.com", timeout=5)
+ return res
+
+# Sending an async HTTP request with custom headers
+async def example_with_headers():
+ headers = {"Authorization": "Bearer int) – Maximum number of attempts to retry the request.
+- **status_codes_to_retry** (list\[int\] | None) – List of HTTP status codes that will trigger a retry.
+ When param is `None`, HTTP 408, 418, 429 and 503 will be retried.
+- **kwargs** (Any) – Optional arguments that `httpx.AsyncClient.request` accepts.
+
+**Returns:**
+
+- Response – The `httpx.Response` object.
+
+## type_serialization
+
+### serialize_type
+
+```python
+serialize_type(target: Any) -> str
+```
+
+Serializes a type or an instance to its string representation, including the module name.
+
+This function handles types, instances of types, and special typing objects.
+It assumes that non-typing objects will have a '__name__' attribute.
+
+**Parameters:**
+
+- **target** (Any) – The object to serialize, can be an instance or a type.
+
+**Returns:**
+
+- str – The string representation of the type.
+
+### deserialize_type
+
+```python
+deserialize_type(type_str: str) -> Any
+```
+
+Deserializes a type given its full import path as a string, including nested generic types.
+
+This function will dynamically import the module if it's not already imported
+and then retrieve the type object from it. It also handles nested generic types like
+`list[dict[int, str]]`.
+
+**Parameters:**
+
+- **type_str** (str) – The string representation of the type's full import path.
+
+**Returns:**
+
+- Any – The deserialized type object.
+
+**Raises:**
+
+- DeserializationError – If the type cannot be deserialized due to missing module or type.
+
+### thread_safe_import
+
+```python
+thread_safe_import(module_name: str) -> ModuleType
+```
+
+Import a module in a thread-safe manner.
+
+Importing modules in a multi-threaded environment can lead to race conditions.
+This function ensures that the module is imported in a thread-safe manner without having impact
+on the performance of the import for single-threaded environments.
+
+**Parameters:**
+
+- **module_name** (str) – the module to import
+
+## url_validation
+
+### is_valid_http_url
+
+```python
+is_valid_http_url(url: str) -> bool
+```
+
+Check if a URL is a valid HTTP/HTTPS URL.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/validators_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/validators_api.md
new file mode 100644
index 0000000000..5e5a2b0b17
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/validators_api.md
@@ -0,0 +1,135 @@
+---
+title: "Validators"
+id: validators-api
+description: "Validators validate LLM outputs"
+slug: "/validators-api"
+---
+
+
+## json_schema
+
+### is_valid_json
+
+```python
+is_valid_json(s: str) -> bool
+```
+
+Check if the provided string is a valid JSON.
+
+**Parameters:**
+
+- **s** (str) – The string to be checked.
+
+**Returns:**
+
+- bool – `True` if the string is a valid JSON; otherwise, `False`.
+
+### JsonSchemaValidator
+
+Validates JSON content of `ChatMessage` against a specified [JSON Schema](https://json-schema.org/).
+
+If JSON content of a message conforms to the provided schema, the message is passed along the "validated" output.
+If the JSON content does not conform to the schema, the message is passed along the "validation_error" output.
+In the latter case, the error message is constructed using the provided `error_template` or a default template.
+These error ChatMessages can be used by LLMs in Haystack 2.x recovery loops.
+
+Usage example:
+
+```python
+from haystack import Pipeline
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.joiners import BranchJoiner
+from haystack.components.validators import JsonSchemaValidator
+from haystack import component
+from haystack.dataclasses import ChatMessage
+
+
+@component
+class MessageProducer:
+
+ @component.output_types(messages=list[ChatMessage])
+ def run(self, messages: list[ChatMessage]) -> dict:
+ return {"messages": messages}
+
+
+p = Pipeline()
+p.add_component("llm", OpenAIChatGenerator(generation_kwargs={"response_format": {"type": "json_object"}}))
+p.add_component("schema_validator", JsonSchemaValidator())
+p.add_component("joiner_for_llm", BranchJoiner(list[ChatMessage]))
+p.add_component("message_producer", MessageProducer())
+
+p.connect("message_producer.messages", "joiner_for_llm")
+p.connect("joiner_for_llm", "llm")
+p.connect("llm.replies", "schema_validator.messages")
+p.connect("schema_validator.validation_error", "joiner_for_llm")
+
+result = p.run(data={
+ "message_producer": {
+ "messages":[ChatMessage.from_user("Generate JSON for person with name 'John' and age 30")]},
+ "schema_validator": {
+ "json_schema": {
+ "type": "object",
+ "properties": {"name": {"type": "string"},
+ "age": {"type": "integer"}
+ }
+ }
+ }
+})
+print(result)
+# >> {'schema_validator': {'validated': [ChatMessage(_role=dict\[str, Any\] | None) – A dictionary representing the [JSON schema](https://json-schema.org/) against which
+ the messages' content is validated.
+- **error_template** (str | None) – A custom template string for formatting the error message in case of validation failure.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ json_schema: dict[str, Any] | None = None,
+ error_template: str | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Validates the last of the provided messages against the specified json schema.
+
+If it does, the message is passed along the "validated" output. If it does not, the message is passed along
+the "validation_error" output.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances to be validated. The last message in this list is the one
+ that is validated.
+- **json_schema** (dict\[str, Any\] | None) – A dictionary representing the [JSON schema](https://json-schema.org/)
+ against which the messages' content is validated. If not provided, the schema from the component init
+ is used.
+- **error_template** (str | None) – A custom template string for formatting the error message in case of validation. If not
+ provided, the `error_template` from the component init is used.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- "validated": A list of messages if the last message is valid.
+- "validation_error": A list of messages if the last message is invalid.
+
+**Raises:**
+
+- ValueError – If no JSON schema is provided or if the message content is not a dictionary or a list of
+ dictionaries.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/websearch_api.md b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/websearch_api.md
new file mode 100644
index 0000000000..5aae72586b
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/haystack-api/websearch_api.md
@@ -0,0 +1,266 @@
+---
+title: "Websearch"
+id: websearch-api
+description: "Web search engine for Haystack."
+slug: "/websearch-api"
+---
+
+
+## searchapi
+
+### SearchApiWebSearch
+
+Uses [SearchApi](https://www.searchapi.io/) to search the web for relevant documents.
+
+Usage example:
+
+
+
+```python
+from haystack.components.websearch import SearchApiWebSearch
+from haystack.utils import Secret
+
+websearch = SearchApiWebSearch(top_k=10, api_key=Secret.from_env_var("SERPERDEV_API_KEY"))
+results = websearch.run(query="Who is the boyfriend of Olivia Wilde?")
+
+assert results["documents"]
+assert results["links"]
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("SEARCHAPI_API_KEY"),
+ top_k: int | None = 10,
+ allowed_domains: list[str] | None = None,
+ search_params: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the SearchApiWebSearch component.
+
+**Parameters:**
+
+- **api_key** (Secret) – API key for the SearchApi API
+- **top_k** (int | None) – Number of documents to return.
+- **allowed_domains** (list\[str\] | None) – List of domains to limit the search to.
+- **search_params** (dict\[str, Any\] | None) – Additional parameters passed to the SearchApi API.
+ For example, you can set 'num' to 100 to increase the number of search results.
+ See the [SearchApi website](https://www.searchapi.io/) for more details.
+
+The default search engine is Google, however, users can change it by setting the `engine`
+parameter in the `search_params`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SearchApiWebSearch
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- SearchApiWebSearch – The deserialized component.
+
+#### run
+
+```python
+run(query: str) -> dict[str, list[Document] | list[str]]
+```
+
+Uses [SearchApi](https://www.searchapi.io/) to search the web.
+
+**Parameters:**
+
+- **query** (str) – Search query.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | list\[str\]\] – A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+
+**Raises:**
+
+- TimeoutError – If the request to the SearchApi API times out.
+- SearchApiError – If an error occurs while querying the SearchApi API.
+
+#### run_async
+
+```python
+run_async(query: str) -> dict[str, list[Document] | list[str]]
+```
+
+Asynchronously uses [SearchApi](https://www.searchapi.io/) to search the web.
+
+This is the asynchronous version of the `run` method with the same parameters and return values.
+
+**Parameters:**
+
+- **query** (str) – Search query.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | list\[str\]\] – A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+
+**Raises:**
+
+- TimeoutError – If the request to the SearchApi API times out.
+- SearchApiError – If an error occurs while querying the SearchApi API.
+
+## serper_dev
+
+### SerperDevWebSearch
+
+Uses [Serper](https://serper.dev/) to search the web for relevant documents.
+
+See the [Serper Dev website](https://serper.dev/) for more details.
+
+Usage example:
+
+
+
+```python
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.utils import Secret
+
+serper_dev_api = Secret.from_env_var("SERPERDEV_API_KEY")
+
+websearch = SerperDevWebSearch(top_k=10, api_key=serper_dev_api)
+results = websearch.run(query="Who is the boyfriend of Olivia Wilde?")
+
+assert results["documents"]
+assert results["links"]
+
+# Example with domain filtering - exclude subdomains
+websearch_filtered = SerperDevWebSearch(
+ top_k=10,
+ allowed_domains=["example.com"],
+ exclude_subdomains=True, # Only results from example.com, not blog.example.com
+ api_key=serper_dev_api
+)
+results_filtered = websearch_filtered.run(query="search query")
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("SERPERDEV_API_KEY"),
+ top_k: int | None = 10,
+ allowed_domains: list[str] | None = None,
+ search_params: dict[str, Any] | None = None,
+ *,
+ exclude_subdomains: bool = False
+) -> None
+```
+
+Initialize the SerperDevWebSearch component.
+
+**Parameters:**
+
+- **api_key** (Secret) – API key for the Serper API.
+- **top_k** (int | None) – Number of documents to return.
+- **allowed_domains** (list\[str\] | None) – List of domains to limit the search to.
+- **exclude_subdomains** (bool) – Whether to exclude subdomains when filtering by allowed_domains.
+ If True, only results from the exact domains in allowed_domains will be returned.
+ If False, results from subdomains will also be included. Defaults to False.
+- **search_params** (dict\[str, Any\] | None) – Additional parameters passed to the Serper API.
+ For example, you can set 'num' to 20 to increase the number of search results.
+ See the [Serper website](https://serper.dev/) for more details.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SerperDevWebSearch
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- SerperDevWebSearch – The deserialized component.
+
+#### run
+
+```python
+run(query: str) -> dict[str, list[Document] | list[str]]
+```
+
+Use [Serper](https://serper.dev/) to search the web.
+
+**Parameters:**
+
+- **query** (str) – Search query.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | list\[str\]\] – A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+
+**Raises:**
+
+- SerperDevError – If an error occurs while querying the SerperDev API.
+- TimeoutError – If the request to the SerperDev API times out.
+
+#### run_async
+
+```python
+run_async(query: str) -> dict[str, list[Document] | list[str]]
+```
+
+Asynchronously uses [Serper](https://serper.dev/) to search the web.
+
+This is the asynchronous version of the `run` method with the same parameters and return values.
+
+**Parameters:**
+
+- **query** (str) – Search query.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | list\[str\]\] – A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+
+**Raises:**
+
+- SerperDevError – If an error occurs while querying the SerperDev API.
+- TimeoutError – If the request to the SerperDev API times out.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/index.mdx b/docs-website/reference_versioned_docs/version-2.29-unstable/index.mdx
new file mode 100644
index 0000000000..c00b968ea5
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/index.mdx
@@ -0,0 +1,21 @@
+---
+id: api-index
+title: API Documentation
+sidebar_position: 1
+---
+
+# API Reference
+
+Complete technical reference for Haystack classes, functions, and modules.
+
+## Haystack API
+
+Core framework API for the `haystack-ai` package. This includes all base components, pipelines, document stores, data classes, and utilities that make up the Haystack framework.
+
+## Integrations API
+
+API reference for official Haystack integrations distributed as separate packages (for example, `AlloyDBDocumentStore) – An instance of `AlloyDBDocumentStore` to use as the document store.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved documents.
+- **top_k** (int) – Maximum number of documents to return.
+- **vector_function** (Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None) – The similarity function to use when searching for similar embeddings.
+ Overrides the `vector_function` set in the `AlloyDBDocumentStore`.
+ `"cosine_similarity"` and `"inner_product"` are similarity functions and
+ higher scores indicate greater similarity between the documents.
+ `"l2_distance"` returns the straight-line distance between vectors,
+ and the most similar documents are the ones with the smallest score.
+ **Important**: when using the `"hnsw"` search strategy, make sure to use the same
+ vector function as the one used when the HNSW index was created.
+ If not specified, the `vector_function` of the `AlloyDBDocumentStore` is used.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied at query time.
+ `FilterPolicy.REPLACE` (default) replaces the init filters with the run-time filters.
+ `FilterPolicy.MERGE` merges the init filters with the run-time filters.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `AlloyDBDocumentStore`.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ vector_function: (
+ Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+ ) = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `AlloyDBDocumentStore` by embedding similarity.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – A vector representation of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved documents.
+ The `filter_policy` set at initialization determines how these are combined with the init filters.
+- **top_k** (int | None) – Maximum number of documents to return. Overrides the `top_k` set at initialization.
+- **vector_function** (Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None) – The similarity function to use when searching for similar embeddings.
+ Overrides the `vector_function` set at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing the `documents` retrieved from the document store.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AlloyDBEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AlloyDBEmbeddingRetriever – Deserialized component.
+
+## haystack_integrations.components.retrievers.alloydb.keyword_retriever
+
+### AlloyDBKeywordRetriever
+
+Retrieves documents from the `AlloyDBDocumentStore` by keyword search.
+
+Uses PostgreSQL full-text search (`to_tsvector` / `plainto_tsquery`) to find documents.
+Must be connected to the `AlloyDBDocumentStore`.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: AlloyDBDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create the `AlloyDBKeywordRetriever` component.
+
+**Parameters:**
+
+- **document_store** (AlloyDBDocumentStore) – An instance of `AlloyDBDocumentStore` to use as the document store.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved documents.
+- **top_k** (int) – Maximum number of documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied at query time.
+ `FilterPolicy.REPLACE` (default) replaces the init filters with the run-time filters.
+ `FilterPolicy.MERGE` merges the init filters with the run-time filters.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `AlloyDBDocumentStore`.
+
+#### run
+
+```python
+run(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `AlloyDBDocumentStore` by keyword search.
+
+**Parameters:**
+
+- **query** (str) – A keyword query to search for.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved documents.
+ The `filter_policy` set at initialization determines how these are combined with the init filters.
+- **top_k** (int | None) – Maximum number of documents to return. Overrides the `top_k` set at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing the `documents` retrieved from the document store.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AlloyDBKeywordRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AlloyDBKeywordRetriever – Deserialized component.
+
+## haystack_integrations.document_stores.alloydb.document_store
+
+### AlloyDBDocumentStore
+
+Bases: DocumentStore
+
+A Document Store backed by [Google Cloud AlloyDB](https://cloud.google.com/alloydb).
+
+Uses the [pgvector extension](https://cloud.google.com/alloydb/docs/ai/work-with-embeddings) for vector search.
+
+AlloyDB is a fully managed, PostgreSQL-compatible database service on Google Cloud.
+Connection is handled securely via the
+[AlloyDB Python Connector](https://github.com/GoogleCloudPlatform/alloydb-python-connector),
+which provides TLS encryption and IAM-based authorization without requiring manual SSL certificate
+management, firewall rules, or IP allowlisting.
+
+**Filter limitations**: the `NOT` logical operator is not supported. Use `!=` or `not in`
+comparison operators to express negation.
+
+Usage example:
+
+```python
+import os
+from haystack_integrations.document_stores.alloydb import AlloyDBDocumentStore
+
+# Set required environment variables:
+# ALLOYDB_INSTANCE_URI = "projects/MY_PROJECT/locations/MY_REGION/clusters/MY_CLUSTER/instances/MY_INSTANCE"
+# ALLOYDB_USER = "my-db-user"
+# ALLOYDB_PASSWORD = "my-db-password"
+
+document_store = AlloyDBDocumentStore(
+ db="my-database",
+ embedding_dimension=768,
+ recreate_table=True,
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ instance_uri: Secret = Secret.from_env_var("ALLOYDB_INSTANCE_URI"),
+ user: Secret = Secret.from_env_var("ALLOYDB_USER"),
+ password: Secret = Secret.from_env_var("ALLOYDB_PASSWORD", strict=False),
+ db: str = "postgres",
+ enable_iam_auth: bool = False,
+ ip_type: Literal["PRIVATE", "PUBLIC", "PSC"] = "PRIVATE",
+ create_extension: bool = True,
+ schema_name: str = "public",
+ table_name: str = "haystack_documents",
+ language: str = "english",
+ embedding_dimension: int = 768,
+ vector_function: Literal[
+ "cosine_similarity", "inner_product", "l2_distance"
+ ] = "cosine_similarity",
+ recreate_table: bool = False,
+ search_strategy: Literal[
+ "exact_nearest_neighbor", "hnsw"
+ ] = "exact_nearest_neighbor",
+ hnsw_recreate_index_if_exists: bool = False,
+ hnsw_index_creation_kwargs: dict[str, int] | None = None,
+ hnsw_index_name: str = "haystack_hnsw_index",
+ hnsw_ef_search: int | None = None,
+ keyword_index_name: str = "haystack_keyword_index"
+) -> None
+```
+
+Creates a new AlloyDBDocumentStore instance.
+
+Connection to AlloyDB is established lazily on first use via the AlloyDB Python Connector.
+A specific table to store Haystack documents will be created if it doesn't exist yet.
+
+**Parameters:**
+
+- **instance_uri** (Secret) – The AlloyDB instance URI in the format
+ `"projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE"`.
+ Read from the `ALLOYDB_INSTANCE_URI` environment variable by default.
+- **user** (Secret) – The database user. Read from the `ALLOYDB_USER` environment variable by default.
+ When using IAM database authentication, use the service account email (omitting
+ `.gserviceaccount.com`) or the full IAM user email.
+- **password** (Secret) – The database password. Read from the `ALLOYDB_PASSWORD` environment variable by default.
+ Not required when `enable_iam_auth=True`.
+- **db** (str) – The name of the database to connect to. Defaults to `"postgres"`.
+- **enable_iam_auth** (bool) – Whether to use IAM database authentication instead of a password.
+ When `True`, `password` is ignored. The IAM principal must be granted the
+ AlloyDB Client role and have an IAM database user created.
+ See the [AlloyDB documentation](https://cloud.google.com/alloydb/docs/manage-iam-authn) for details.
+- **ip_type** (Literal['PRIVATE', 'PUBLIC', 'PSC']) – The IP address type to use for the connection.
+ `"PRIVATE"` (default) connects over a private VPC IP.
+ `"PUBLIC"` connects over a public IP.
+ `"PSC"` connects via Private Service Connect.
+- **create_extension** (bool) – Whether to create the pgvector extension if it doesn't exist.
+ Set this to `True` (default) to automatically create the extension if it is missing.
+ Creating the extension may require superuser privileges.
+ If set to `False`, ensure the extension is already installed; otherwise, an error will be raised.
+- **schema_name** (str) – The name of the schema the table is created in. The schema must already exist.
+- **table_name** (str) – The name of the table to use to store Haystack documents.
+- **language** (str) – The language to be used to parse query and document content in keyword retrieval.
+ To see the list of available languages, you can run the following SQL query in your PostgreSQL database:
+ `SELECT cfgname FROM pg_ts_config;`.
+- **embedding_dimension** (int) – The dimension of the embedding.
+- **vector_function** (Literal['cosine_similarity', 'inner_product', 'l2_distance']) – The similarity function to use when searching for similar embeddings.
+ `"cosine_similarity"` and `"inner_product"` are similarity functions and
+ higher scores indicate greater similarity between the documents.
+ `"l2_distance"` returns the straight-line distance between vectors,
+ and the most similar documents are the ones with the smallest score.
+ **Important**: when using the `"hnsw"` search strategy, an index will be created that depends on the
+ `vector_function` passed here. Make sure subsequent queries will keep using the same
+ vector similarity function in order to take advantage of the index.
+- **recreate_table** (bool) – Whether to recreate the table if it already exists.
+- **search_strategy** (Literal['exact_nearest_neighbor', 'hnsw']) – The search strategy to use when searching for similar embeddings.
+ `"exact_nearest_neighbor"` provides perfect recall but can be slow for large numbers of documents.
+ `"hnsw"` is an approximate nearest neighbor search strategy,
+ which trades off some accuracy for speed; it is recommended for large numbers of documents.
+ **Important**: when using the `"hnsw"` search strategy, an index will be created that depends on the
+ `vector_function` passed here. Make sure subsequent queries will keep using the same
+ vector similarity function in order to take advantage of the index.
+- **hnsw_recreate_index_if_exists** (bool) – Whether to recreate the HNSW index if it already exists.
+ Only used if search_strategy is set to `"hnsw"`.
+- **hnsw_index_creation_kwargs** (dict\[str, int\] | None) – Additional keyword arguments to pass to the HNSW index creation.
+ Only used if search_strategy is set to `"hnsw"`. Valid arguments are `m` and `ef_construction`.
+ See the [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw) for details.
+- **hnsw_index_name** (str) – Index name for the HNSW index.
+- **hnsw_ef_search** (int | None) – The `ef_search` parameter to use at query time. Only used if search_strategy is set to
+ `"hnsw"`. See the [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw).
+- **keyword_index_name** (str) – Index name for the keyword GIN index.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AlloyDBDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AlloyDBDocumentStore – Deserialized component.
+
+#### close
+
+```python
+close() -> None
+```
+
+Closes the database connection and the AlloyDB connector.
+
+Call this when you are done using the document store to release resources.
+For long-lived applications the connector runs a background refresh thread;
+calling `close()` ensures that thread is stopped cleanly.
+
+#### delete_table
+
+```python
+delete_table() -> None
+```
+
+Deletes the table used to store Haystack documents.
+
+The name of the schema (`schema_name`) and the name of the table (`table_name`)
+are defined when initializing the `AlloyDBDocumentStore`.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are in the document store.
+
+**Returns:**
+
+- int – The number of documents in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Filter operator support**: comparison operators (`==`, `!=`, `>`, `>=`, `<`, `<=`, `in`,
+`not in`, `like`, `not like`) and logical operators `AND` and `OR` are fully supported.
+The `NOT` logical operator is **not** supported — use `!=` or `not in` comparison
+operators instead.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+**Raises:**
+
+- TypeError – If `filters` is not a dictionary.
+- ValueError – If `filters` syntax is invalid.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.FAIL
+) -> int
+```
+
+Writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+**Raises:**
+
+- ValueError – If `documents` contains objects that are not of type `Document`.
+- DuplicateDocumentError – If a document with the same id already exists in the document store
+ and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+- DocumentStoreError – If the write operation fails for any other reason.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents in the document store.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the count of unique values for each specified metadata field.
+
+Considers only documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of metadata field names to count unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping field names to their unique value counts.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns information about the metadata fields in the document store.
+
+Since metadata is stored in a JSONB field, this method analyzes actual data
+to infer field types.
+
+Example return:
+
+```python
+{
+ 'category': {'type': 'text'},
+ 'priority': {'type': 'integer'},
+}
+```
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary mapping field names to their type information.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for a metadata field.
+
+For numeric fields (integer, real), returns numeric min/max.
+For text and other non-numeric fields, returns lexicographic min/max
+using the `"C"` collation.
+
+**Parameters:**
+
+- **field** (str) – The metadata field name (with or without the "meta." prefix).
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with `min` and `max` keys. Returns
+ `{"min": None, "max": None}` when the field has no values or the
+ store is empty.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ field: str, filters: dict[str, Any] | None = None
+) -> list[Any]
+```
+
+Returns a list of unique values for a metadata field.
+
+**Parameters:**
+
+- **field** (str) – The metadata field name (with or without the "meta." prefix).
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- list\[Any\] – A list of unique values for the given field.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/amazon_bedrock.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/amazon_bedrock.md
new file mode 100644
index 0000000000..51b1b21dce
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/amazon_bedrock.md
@@ -0,0 +1,1679 @@
+---
+title: "Amazon Bedrock"
+id: integrations-amazon-bedrock
+description: "Amazon Bedrock integration for Haystack"
+slug: "/integrations-amazon-bedrock"
+---
+
+
+## haystack_integrations.common.amazon_bedrock.errors
+
+### AmazonBedrockError
+
+Bases: Exception
+
+Any error generated by the Amazon Bedrock integration.
+
+This error wraps its source transparently in such a way that its attributes
+can be accessed directly: for example, if the original error has a `message` attribute,
+`AmazonBedrockError.message` will exist and have the expected content.
+
+### AWSConfigurationError
+
+Bases: AmazonBedrockError
+
+Exception raised when AWS is not configured correctly
+
+### AmazonBedrockConfigurationError
+
+Bases: AmazonBedrockError
+
+Exception raised when AmazonBedrock node is not configured correctly
+
+### AmazonBedrockInferenceError
+
+Bases: AmazonBedrockError
+
+Exception for issues that occur in the Bedrock inference node
+
+## haystack_integrations.common.amazon_bedrock.errors
+
+### AmazonBedrockError
+
+Bases: Exception
+
+Any error generated by the Amazon Bedrock integration.
+
+This error wraps its source transparently in such a way that its attributes
+can be accessed directly: for example, if the original error has a `message` attribute,
+`AmazonBedrockError.message` will exist and have the expected content.
+
+### AWSConfigurationError
+
+Bases: AmazonBedrockError
+
+Exception raised when AWS is not configured correctly
+
+### AmazonBedrockConfigurationError
+
+Bases: AmazonBedrockError
+
+Exception raised when AmazonBedrock node is not configured correctly
+
+### AmazonBedrockInferenceError
+
+Bases: AmazonBedrockError
+
+Exception for issues that occur in the Bedrock inference node
+
+## haystack_integrations.common.s3.errors
+
+### S3Error
+
+Bases: Exception
+
+Exception for issues that occur in the S3 based components
+
+### S3ConfigurationError
+
+Bases: S3Error
+
+Exception raised when AmazonS3 node is not configured correctly
+
+### S3StorageError
+
+Bases: S3Error
+
+This exception is raised when an error occurs while interacting with a S3Storage object.
+
+## haystack_integrations.common.s3.utils
+
+### S3Storage
+
+This class provides a storage class for downloading files from an AWS S3 bucket.
+
+#### __init__
+
+```python
+__init__(
+ s3_bucket: str,
+ session: Session,
+ s3_prefix: str | None = None,
+ endpoint_url: str | None = None,
+ config: Config | None = None,
+) -> None
+```
+
+Initializes the S3Storage object with the provided parameters.
+
+**Parameters:**
+
+- **s3_bucket** (str) – The name of the S3 bucket to download files from.
+- **session** (Session) – The session to use for the S3 client.
+- **s3_prefix** (str | None) – The optional prefix of the files in the S3 bucket.
+ Can be used to specify folder or naming structure.
+ For example, if the file is in the folder "folder/subfolder/file.txt",
+ the s3_prefix should be "folder/subfolder/". If the file is in the root of the S3 bucket,
+ the s3_prefix should be None.
+- **endpoint_url** (str | None) – The endpoint URL of the S3 bucket to download files from.
+- **config** (Config | None) – The configuration to use for the S3 client.
+
+#### download
+
+```python
+download(key: str, local_file_path: Path) -> None
+```
+
+Download a file from S3.
+
+**Parameters:**
+
+- **key** (str) – The key of the file to download.
+- **local_file_path** (Path) – The folder path to download the file to.
+ It will be created if it does not exist. The file will be downloaded to
+ the folder with the same name as the key.
+
+**Raises:**
+
+- S3ConfigurationError – If the S3 session client cannot be created.
+- S3StorageError – If the file does not exist in the S3 bucket
+ or the file cannot be downloaded.
+
+#### from_env
+
+```python
+from_env(
+ *,
+ session: Session,
+ config: Config,
+ s3_bucket_name_env: str = "S3_DOWNLOADER_BUCKET"
+) -> S3Storage
+```
+
+Create a S3Storage object from environment variables.
+
+The following environment variables are read:
+
+- `S3_DOWNLOADER_BUCKET` (or the value of `s3_bucket_name_env`): The name of the S3 bucket
+ to download files from. Required — raises `ValueError` if not set.
+- `S3_DOWNLOADER_PREFIX`: Optional prefix to apply to all S3 keys (e.g. `"folder/subfolder/"`).
+- `AWS_ENDPOINT_URL`: Optional custom endpoint URL, useful for S3-compatible services
+ such as MinIO or LocalStack.
+
+**Parameters:**
+
+- **session** (Session) – The boto3 `Session` to use when creating the S3 client.
+- **config** (Config) – The botocore `Config` to apply to the S3 client.
+- **s3_bucket_name_env** (str) – The name of the environment variable of the S3 bucket to download files from.
+ By default, the value is `"S3_DOWNLOADER_BUCKET"`.
+
+**Returns:**
+
+- S3Storage – A fully initialized `S3Storage` instance.
+
+**Raises:**
+
+- ValueError – If the environment variable specified by `s3_bucket_name_env` is not set
+ or is empty.
+
+## haystack_integrations.components.downloaders.s3.s3_downloader
+
+### S3Downloader
+
+A component for downloading files from AWS S3 Buckets to local filesystem.
+
+Supports filtering by file extensions.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ aws_access_key_id: Secret | None = Secret.from_env_var(
+ "AWS_ACCESS_KEY_ID", strict=False
+ ),
+ aws_secret_access_key: Secret | None = Secret.from_env_var(
+ "AWS_SECRET_ACCESS_KEY", strict=False
+ ),
+ aws_session_token: Secret | None = Secret.from_env_var(
+ "AWS_SESSION_TOKEN", strict=False
+ ),
+ aws_region_name: Secret | None = Secret.from_env_var(
+ "AWS_DEFAULT_REGION", strict=False
+ ),
+ aws_profile_name: Secret | None = Secret.from_env_var(
+ "AWS_PROFILE", strict=False
+ ),
+ boto3_config: dict[str, Any] | None = None,
+ file_root_path: str | None = None,
+ file_extensions: list[str] | None = None,
+ file_name_meta_key: str = "file_name",
+ max_workers: int = 32,
+ max_cache_size: int = 100,
+ s3_key_generation_function: Callable[[Document], str] | None = None,
+ s3_bucket_name_env: str = "S3_DOWNLOADER_BUCKET"
+) -> None
+```
+
+Initializes the `S3Downloader` with the provided parameters.
+
+Note that the AWS credentials are not required if the AWS environment is configured correctly. These are loaded
+automatically from the environment or the AWS configuration file and do not need to be provided explicitly via
+the constructor. If the AWS environment is not configured users need to provide the AWS credentials via the
+constructor. Three required parameters are `aws_access_key_id`, `aws_secret_access_key`,
+and `aws_region_name`.
+
+**Parameters:**
+
+- **aws_access_key_id** (Secret | None) – AWS access key ID.
+- **aws_secret_access_key** (Secret | None) – AWS secret access key.
+- **aws_session_token** (Secret | None) – AWS session token.
+- **aws_region_name** (Secret | None) – AWS region name.
+- **aws_profile_name** (Secret | None) – AWS profile name.
+- **boto3_config** (dict\[str, Any\] | None) – Dictionary of configuration options for the underlying Boto3 client.
+ Can be used to tune [retry behavior](https://docs.aws.amazon.com/boto3/latest/guide/retries.html)
+ and other low-level settings like timeouts and connection management.
+- **file_root_path** (str | None) – The path where the file will be downloaded.
+ Can be set through this parameter or the `FILE_ROOT_PATH` environment variable.
+ If none of them is set, a `ValueError` is raised.
+- **file_extensions** (list\[str\] | None) – The file extensions that are permitted to be downloaded.
+ By default, all file extensions are allowed.
+- **max_workers** (int) – The maximum number of workers to use for concurrent downloads.
+- **max_cache_size** (int) – The maximum number of files to cache.
+- **file_name_meta_key** (str) – The name of the meta key that contains the file name to download. The file name
+ will also be used to create local file path for download.
+ By default, the `Document.meta["file_name"]` is used. If you want to use a
+ different key in `Document.meta`, you can set it here.
+- **s3_key_generation_function** (Callable\\[[Document\], str\] | None) – An optional function that generates the S3 key for the file to download.
+ If not provided, the default behavior is to use `Document.meta[file_name_meta_key]`.
+ The function must accept a `Document` object and return a string.
+ If the environment variable `S3_DOWNLOADER_PREFIX` is set, its value will be automatically
+ prefixed to the generated S3 key.
+- **s3_bucket_name_env** (str) – The name of the environment variable of the S3 bucket to download files from.
+ By default, the value is `"S3_DOWNLOADER_BUCKET"`.
+
+**Raises:**
+
+- ValueError – If the `file_root_path` is not set through
+ the constructor or the `FILE_ROOT_PATH` environment variable.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the component by initializing the settings and storage.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Download files from AWS S3 Buckets to local filesystem.
+
+Return enriched `Document`s with the path of the downloaded file.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Document containing the name of the file to download in the meta field.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with:
+- `documents`: The downloaded `Document`s; each has `meta['file_path']`.
+
+**Raises:**
+
+- S3Error – If a download attempt fails or the file does not exist in the S3 bucket.
+- ValueError – If the path where files will be downloaded is not set.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> S3Downloader
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- S3Downloader – Deserialized component.
+
+## haystack_integrations.components.embedders.amazon_bedrock.document_embedder
+
+### AmazonBedrockDocumentEmbedder
+
+A component for computing Document embeddings using Amazon Bedrock.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+import os
+from haystack.dataclasses import Document
+from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockDocumentEmbedder
+
+os.environ["AWS_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_SECRET_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_DEFAULT_REGION"] = "..."
+
+embedder = AmazonBedrockDocumentEmbedder(
+ model="cohere.embed-english-v3",
+ input_type="search_document",
+)
+
+doc = Document(content="I love Paris in the winter.", meta={"name": "doc1"})
+
+result = embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.002, 0.032, 0.504, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ aws_access_key_id: Secret | None = Secret.from_env_var(
+ "AWS_ACCESS_KEY_ID", strict=False
+ ),
+ aws_secret_access_key: Secret | None = Secret.from_env_var(
+ "AWS_SECRET_ACCESS_KEY", strict=False
+ ),
+ aws_session_token: Secret | None = Secret.from_env_var(
+ "AWS_SESSION_TOKEN", strict=False
+ ),
+ aws_region_name: Secret | None = Secret.from_env_var(
+ "AWS_DEFAULT_REGION", strict=False
+ ),
+ aws_profile_name: Secret | None = Secret.from_env_var(
+ "AWS_PROFILE", strict=False
+ ),
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ boto3_config: dict[str, Any] | None = None,
+ **kwargs: Any
+) -> None
+```
+
+Initializes the AmazonBedrockDocumentEmbedder with the provided parameters.
+
+The parameters are passed to the Amazon Bedrock client.
+
+Note that the AWS credentials are not required if the AWS environment is configured correctly. These are loaded
+automatically from the environment or the AWS configuration file and do not need to be provided explicitly via
+the constructor. If the AWS environment is not configured users need to provide the AWS credentials via the
+constructor. Aside from model, three required parameters are `aws_access_key_id`, `aws_secret_access_key`,
+and `aws_region_name`.
+
+**Parameters:**
+
+- **model** (str) – The embedding model to use.
+ Amazon Titan and Cohere embedding models are supported, for example:
+ "amazon.titan-embed-text-v1", "amazon.titan-embed-text-v2:0", "amazon.titan-embed-image-v1",
+ "cohere.embed-english-v3", "cohere.embed-multilingual-v3", "cohere.embed-v4:0".
+ To find all supported models, refer to the Amazon Bedrock
+ [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) and
+ filter for "embedding", then select models from the Amazon Titan and Cohere series.
+- **aws_access_key_id** (Secret | None) – AWS access key ID.
+- **aws_secret_access_key** (Secret | None) – AWS secret access key.
+- **aws_session_token** (Secret | None) – AWS session token.
+- **aws_region_name** (Secret | None) – AWS region name.
+- **aws_profile_name** (Secret | None) – AWS profile name.
+- **batch_size** (int) – Number of Documents to encode at once.
+ Only Cohere models support batch inference. This parameter is ignored for Amazon Titan models.
+- **progress_bar** (bool) – Whether to show a progress bar or not. Can be helpful to disable in production deployments
+ to keep the logs clean.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (str) – Separator used to concatenate the meta fields to the Document text.
+- **boto3_config** (dict\[str, Any\] | None) – Dictionary of configuration options for the underlying Boto3 client.
+ Can be used to tune [retry behavior](https://docs.aws.amazon.com/boto3/latest/guide/retries.html)
+ and other low-level settings like timeouts and connection management.
+- **kwargs** (Any) – Additional parameters to pass for model inference. For example, `input_type` and `truncate` for
+ Cohere models.
+
+**Raises:**
+
+- ValueError – If the model is not supported.
+- AmazonBedrockConfigurationError – If the AWS environment is not configured correctly.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed the provided `Document`s using the specified model.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The `Document`s to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: The `Document`s with the `embedding` field populated.
+
+**Raises:**
+
+- AmazonBedrockInferenceError – If the inference fails.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AmazonBedrockDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AmazonBedrockDocumentEmbedder – Deserialized component.
+
+## haystack_integrations.components.embedders.amazon_bedrock.document_image_embedder
+
+### AmazonBedrockDocumentImageEmbedder
+
+A component for computing Document embeddings based on images using Amazon Bedrock models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+### Usage example
+
+```python
+from haystack import Document
+rom haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockDocumentImageEmbedder
+
+os.environ["AWS_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_SECRET_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_DEFAULT_REGION"] = "..."
+
+embedder = AmazonBedrockDocumentImageEmbedder(model="amazon.titan-embed-image-v1")
+
+documents = [
+ Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
+ Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}),
+]
+
+result = embedder.run(documents=documents)
+documents_with_embeddings = result["documents"]
+print(documents_with_embeddings)
+
+# [Document(id=...,
+# content='A photo of a cat',
+# meta={'file_path': 'cat.jpg',
+# 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}},
+# embedding=vector of size 512),
+# ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str,
+ aws_access_key_id: Secret | None = Secret.from_env_var(
+ "AWS_ACCESS_KEY_ID", strict=False
+ ),
+ aws_secret_access_key: Secret | None = Secret.from_env_var(
+ "AWS_SECRET_ACCESS_KEY", strict=False
+ ),
+ aws_session_token: Secret | None = Secret.from_env_var(
+ "AWS_SESSION_TOKEN", strict=False
+ ),
+ aws_region_name: Secret | None = Secret.from_env_var(
+ "AWS_DEFAULT_REGION", strict=False
+ ),
+ aws_profile_name: Secret | None = Secret.from_env_var(
+ "AWS_PROFILE", strict=False
+ ),
+ file_path_meta_field: str = "file_path",
+ root_path: str | None = None,
+ image_size: tuple[int, int] | None = None,
+ progress_bar: bool = True,
+ boto3_config: dict[str, Any] | None = None,
+ **kwargs: Any
+) -> None
+```
+
+Creates a AmazonBedrockDocumentImageEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – The embedding model to use.
+ Amazon Titan and Cohere multimodal embedding models are supported, for example:
+ "amazon.titan-embed-image-v1", "cohere.embed-english-v3", "cohere.embed-multilingual-v3",
+ "cohere.embed-v4:0".
+ To find all supported models, refer to the Amazon Bedrock
+ [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) and
+ filter for "embedding", then select multimodal models from the Amazon Titan and Cohere series.
+- **aws_access_key_id** (Secret | None) – AWS access key ID.
+- **aws_secret_access_key** (Secret | None) – AWS secret access key.
+- **aws_session_token** (Secret | None) – AWS session token.
+- **aws_region_name** (Secret | None) – AWS region name.
+- **aws_profile_name** (Secret | None) – AWS profile name.
+- **file_path_meta_field** (str) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (str | None) – The root directory path where document files are located. If provided, file paths in
+ document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **image_size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+- **progress_bar** (bool) – If `True`, shows a progress bar when embedding documents.
+- **boto3_config** (dict\[str, Any\] | None) – Dictionary of configuration options for the underlying Boto3 client.
+ Can be used to tune [retry behavior](https://docs.aws.amazon.com/boto3/latest/guide/retries.html)
+ and other low-level settings like timeouts and connection management.
+- **kwargs** (Any) – Additional parameters to pass for model inference.
+ For example, `embeddingConfig` for Amazon Titan models and
+ `embedding_types` for Cohere models.
+
+**Raises:**
+
+- ValueError – If the model is not supported.
+- AmazonBedrockConfigurationError – If the AWS environment is not configured correctly.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AmazonBedrockDocumentImageEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AmazonBedrockDocumentImageEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of images.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Documents with embeddings.
+
+## haystack_integrations.components.embedders.amazon_bedrock.text_embedder
+
+### AmazonBedrockTextEmbedder
+
+A component for embedding strings using Amazon Bedrock.
+
+Usage example:
+
+```python
+import os
+from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockTextEmbedder
+
+os.environ["AWS_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_SECRET_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_DEFAULT_REGION"] = "..."
+
+embedder = AmazonBedrockTextEmbedder(
+ model="cohere.embed-english-v3",
+ input_type="search_query",
+)
+
+print(text_embedder.run("I love Paris in the summer."))
+
+# {'embedding': [0.002, 0.032, 0.504, ...]}
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ aws_access_key_id: Secret | None = Secret.from_env_var(
+ "AWS_ACCESS_KEY_ID", strict=False
+ ),
+ aws_secret_access_key: Secret | None = Secret.from_env_var(
+ "AWS_SECRET_ACCESS_KEY", strict=False
+ ),
+ aws_session_token: Secret | None = Secret.from_env_var(
+ "AWS_SESSION_TOKEN", strict=False
+ ),
+ aws_region_name: Secret | None = Secret.from_env_var(
+ "AWS_DEFAULT_REGION", strict=False
+ ),
+ aws_profile_name: Secret | None = Secret.from_env_var(
+ "AWS_PROFILE", strict=False
+ ),
+ boto3_config: dict[str, Any] | None = None,
+ **kwargs: Any
+) -> None
+```
+
+Initializes the AmazonBedrockTextEmbedder with the provided parameters.
+
+The parameters are passed to the Amazon Bedrock client.
+
+Note that the AWS credentials are not required if the AWS environment is configured correctly. These are loaded
+automatically from the environment or the AWS configuration file and do not need to be provided explicitly via
+the constructor. If the AWS environment is not configured users need to provide the AWS credentials via the
+constructor. Aside from model, three required parameters are `aws_access_key_id`, `aws_secret_access_key`,
+and `aws_region_name`.
+
+**Parameters:**
+
+- **model** (str) – The embedding model to use.
+ Amazon Titan and Cohere embedding models are supported, for example:
+ "amazon.titan-embed-text-v1", "amazon.titan-embed-text-v2:0", "amazon.titan-embed-image-v1",
+ "cohere.embed-english-v3", "cohere.embed-multilingual-v3", "cohere.embed-v4:0".
+ To find all supported models, refer to the Amazon Bedrock
+ [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) and
+ filter for "embedding", then select models from the Amazon Titan and Cohere series.
+- **aws_access_key_id** (Secret | None) – AWS access key ID.
+- **aws_secret_access_key** (Secret | None) – AWS secret access key.
+- **aws_session_token** (Secret | None) – AWS session token.
+- **aws_region_name** (Secret | None) – AWS region name.
+- **aws_profile_name** (Secret | None) – AWS profile name.
+- **boto3_config** (dict\[str, Any\] | None) – Dictionary of configuration options for the underlying Boto3 client.
+ Can be used to tune [retry behavior](https://docs.aws.amazon.com/boto3/latest/guide/retries.html)
+ and other low-level settings like timeouts and connection management.
+- **kwargs** (Any) – Additional parameters to pass for model inference. For example, `input_type` and `truncate` for
+ Cohere models.
+
+**Raises:**
+
+- ValueError – If the model is not supported.
+- AmazonBedrockConfigurationError – If the AWS environment is not configured correctly.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float]]
+```
+
+Embeds the input text using the Amazon Bedrock model.
+
+**Parameters:**
+
+- **text** (str) – The input text to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\]\] – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+
+**Raises:**
+
+- TypeError – If the input text is not a string.
+- AmazonBedrockInferenceError – If the model inference fails.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AmazonBedrockTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AmazonBedrockTextEmbedder – Deserialized component.
+
+## haystack_integrations.components.generators.amazon_bedrock.adapters
+
+### BedrockModelAdapter
+
+Bases: ABC
+
+Base class for Amazon Bedrock model adapters.
+
+Each subclass of this class is designed to address the unique specificities of a particular LLM it adapts,
+focusing on preparing the requests and extracting the responses from the Amazon Bedrock hosted LLMs.
+
+**Parameters:**
+
+- **model_kwargs** (dict\[str, Any\]) – Keyword arguments for the model. You can find the full list of parameters in the
+ Amazon Bedrock API [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html).
+- **max_length** (int | None) – Maximum length of generated text. This is mapped to the correct parameter for each model.
+ It will be overridden by the corresponding parameter in the `model_kwargs` if it is present.
+
+#### prepare_body
+
+```python
+prepare_body(prompt: str, **inference_kwargs: Any) -> dict[str, Any]
+```
+
+Prepares the body for the Amazon Bedrock request.
+
+Each subclass should implement this method to prepare the request body for the specific model.
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to be sent to the model.
+- **inference_kwargs** (Any) – Additional keyword arguments passed to the handler.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the body for the request.
+
+#### get_responses
+
+```python
+get_responses(response_body: dict[str, Any]) -> list[str]
+```
+
+Extracts the responses from the Amazon Bedrock response.
+
+**Parameters:**
+
+- **response_body** (dict\[str, Any\]) – The response body from the Amazon Bedrock request.
+
+**Returns:**
+
+- list\[str\] – A list of responses.
+
+#### get_stream_responses
+
+```python
+get_stream_responses(
+ stream: EventStream, streaming_callback: SyncStreamingCallbackT
+) -> list[str]
+```
+
+Extracts the responses from the Amazon Bedrock streaming response.
+
+**Parameters:**
+
+- **stream** (EventStream) – The streaming response from the Amazon Bedrock request.
+- **streaming_callback** (SyncStreamingCallbackT) – The handler for the streaming response.
+
+**Returns:**
+
+- list\[str\] – A list of string responses.
+
+### AnthropicClaudeAdapter
+
+Bases: BedrockModelAdapter
+
+Adapter for the Anthropic Claude models.
+
+**Parameters:**
+
+- **model_kwargs** (dict\[str, Any\]) – Keyword arguments for the model. You can find the full list of parameters in the
+ Amazon Bedrock API documentation for the Claude model
+ [here](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html).
+ Some example parameters are:
+- use_messages_api: Whether to use the messages API, default: True
+- include_thinking: Whether to include thinking output, default: True
+- thinking_tag: XML tag for thinking content, default: "thinking"
+- **max_length** (int | None) – Maximum length of generated text
+
+#### prepare_body
+
+```python
+prepare_body(prompt: str, **inference_kwargs: Any) -> dict[str, Any]
+```
+
+Prepares the body for the Claude model
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to be sent to the model.
+- **inference_kwargs** (Any) – Additional keyword arguments passed to the handler.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `prompt`: The prompt to be sent to the model.
+- specified inference parameters.
+
+### MistralAdapter
+
+Bases: BedrockModelAdapter
+
+Adapter for the Mistral models.
+
+#### prepare_body
+
+```python
+prepare_body(prompt: str, **inference_kwargs: Any) -> dict[str, Any]
+```
+
+Prepares the body for the Mistral model
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to be sent to the model.
+- **inference_kwargs** (Any) – Additional keyword arguments passed to the handler.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `prompt`: The prompt to be sent to the model.
+- specified inference parameters.
+
+### CohereCommandAdapter
+
+Bases: BedrockModelAdapter
+
+Adapter for the Cohere Command model.
+
+#### prepare_body
+
+```python
+prepare_body(prompt: str, **inference_kwargs: Any) -> dict[str, Any]
+```
+
+Prepares the body for the Command model
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to be sent to the model.
+- **inference_kwargs** (Any) – Additional keyword arguments passed to the handler.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `prompt`: The prompt to be sent to the model.
+- specified inference parameters.
+
+### CohereCommandRAdapter
+
+Bases: BedrockModelAdapter
+
+Adapter for the Cohere Command R models.
+
+#### prepare_body
+
+```python
+prepare_body(prompt: str, **inference_kwargs: Any) -> dict[str, Any]
+```
+
+Prepares the body for the Command model
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to be sent to the model.
+- **inference_kwargs** (Any) – Additional keyword arguments passed to the handler.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `prompt`: The prompt to be sent to the model.
+- specified inference parameters.
+
+### AI21LabsJurassic2Adapter
+
+Bases: BedrockModelAdapter
+
+Model adapter for AI21 Labs' Jurassic 2 models.
+
+#### prepare_body
+
+```python
+prepare_body(prompt: str, **inference_kwargs: Any) -> dict[str, Any]
+```
+
+Prepares the body for the Jurassic 2 model.
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to be sent to the model.
+- **inference_kwargs** (Any) – Additional keyword arguments passed to the handler.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `prompt`: The prompt to be sent to the model.
+- specified inference parameters.
+
+### AmazonTitanAdapter
+
+Bases: BedrockModelAdapter
+
+Adapter for Amazon's Titan models.
+
+#### prepare_body
+
+```python
+prepare_body(prompt: str, **inference_kwargs: Any) -> dict[str, Any]
+```
+
+Prepares the body for the Titan model
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to be sent to the model.
+- **inference_kwargs** (Any) – Additional keyword arguments passed to the handler.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys
+- `inputText`: The prompt to be sent to the model.
+- specified inference parameters.
+
+### MetaLlamaAdapter
+
+Bases: BedrockModelAdapter
+
+Adapter for Meta's Llama2 models.
+
+#### prepare_body
+
+```python
+prepare_body(prompt: str, **inference_kwargs: Any) -> dict[str, Any]
+```
+
+Prepares the body for the Llama2 model
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to be sent to the model.
+- **inference_kwargs** (Any) – Additional keyword arguments passed to the handler.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `prompt`: The prompt to be sent to the model.
+- specified inference parameters.
+
+## haystack_integrations.components.generators.amazon_bedrock.chat.chat_generator
+
+### AmazonBedrockChatGenerator
+
+Completes chats using LLMs hosted on Amazon Bedrock available via the Bedrock Converse API.
+
+For example, to use the Anthropic Claude 4.6 Sonnet model, initialize this component with the
+'global.anthropic.claude-sonnet-4-6' model name.
+
+**Usage example**
+
+```python
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.components.generators.utils import print_streaming_chunk
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant, answer in German only"),
+ ChatMessage.from_user("What's Natural Language Processing?")]
+
+
+client = AmazonBedrockChatGenerator(model="global.anthropic.claude-sonnet-4-6",
+ streaming_callback=print_streaming_chunk)
+client.run(messages, generation_kwargs={"max_tokens": 512})
+```
+
+**Multimodal example**
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator
+
+generator = AmazonBedrockChatGenerator(model="global.anthropic.claude-sonnet-4-6")
+
+image_content = ImageContent.from_file_path(file_path="apple.jpg")
+
+message = ChatMessage.from_user(content_parts=["Describe the image using 10 words at most.", image_content])
+
+response = generator.run(messages=[message])["replies"][0].text
+
+print(response)
+> The image shows a red apple.
+```
+
+**Tool usage example**
+
+AmazonBedrockChatGenerator supports Haystack's unified tool architecture, allowing tools to be used
+across different chat generators. The same tool definitions and usage patterns work consistently
+whether using Amazon Bedrock, OpenAI, Ollama, or any other supported LLM providers.
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.tools import Tool
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator
+
+def weather(city: str):
+ return f'The weather in {city} is sunny and 32°C'
+
+# Define tool parameters
+tool_parameters = {
+ "type": "object",
+ "properties": {"city": {"type": "string"}},
+ "required": ["city"]
+}
+
+# Create weather tool
+weather_tool = Tool(
+ name="weather",
+ description="useful to determine the weather in a given location",
+ parameters=tool_parameters,
+ function=weather
+)
+
+# Initialize generator with tool
+client = AmazonBedrockChatGenerator(
+ model="global.anthropic.claude-sonnet-4-6",
+ tools=[weather_tool]
+)
+
+# Run initial query
+messages = [ChatMessage.from_user("What's the weather like in Paris?")]
+results = client.run(messages=messages)
+
+# Get tool call from response
+tool_message = next(msg for msg in results["replies"] if msg.tool_call)
+tool_call = tool_message.tool_call
+
+# Execute tool and send result back
+weather_result = weather(**tool_call.arguments)
+new_messages = [
+ messages[0],
+ tool_message,
+ ChatMessage.from_tool(tool_result=weather_result, origin=tool_call)
+]
+
+# Get final response
+final_result = client.run(new_messages)
+print(final_result["replies"][0].text)
+
+> Based on the information I've received, I can tell you that the weather in Paris is
+> currently sunny with a temperature of 32°C (which is about 90°F).
+```
+
+**Prompt caching**
+
+This component supports prompt caching. You can use the `tools_cachepoint_config` parameter to configure the cache
+point for tools.
+To cache messages, you can use the `cachePoint` key in `ChatMessage.meta` attribute.
+
+```python
+ChatMessage.from_user("Long message...", meta={"cachePoint": {"type": "default"}})
+```
+
+For more information, see the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html).
+
+**Authentication**
+
+AmazonBedrockChatGenerator 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 [Amazon Bedrock documentation]
+(https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html).
+
+If the AWS environment is configured correctly, the AWS credentials are not required as they're loaded
+automatically from the environment or the AWS configuration file.
+If the AWS environment is not configured, set `aws_access_key_id`, `aws_secret_access_key`,
+and `aws_region_name` as environment variables or pass them as
+[Secret](https://docs.haystack.deepset.ai/docs/secret-management) arguments. Make sure the region you set
+supports Amazon Bedrock.
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ aws_access_key_id: Secret | None = Secret.from_env_var(
+ ["AWS_ACCESS_KEY_ID"], strict=False
+ ),
+ aws_secret_access_key: Secret | None = Secret.from_env_var(
+ ["AWS_SECRET_ACCESS_KEY"], strict=False
+ ),
+ aws_session_token: Secret | None = Secret.from_env_var(
+ ["AWS_SESSION_TOKEN"], strict=False
+ ),
+ aws_region_name: Secret | None = Secret.from_env_var(
+ ["AWS_DEFAULT_REGION"], strict=False
+ ),
+ aws_profile_name: Secret | None = Secret.from_env_var(
+ ["AWS_PROFILE"], strict=False
+ ),
+ generation_kwargs: dict[str, Any] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ boto3_config: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ *,
+ guardrail_config: dict[str, str] | None = None,
+ tools_cachepoint_config: dict[str, str] | None = None
+) -> None
+```
+
+Initializes the `AmazonBedrockChatGenerator` with the provided parameters.
+
+The parameters are passed to the Amazon Bedrock client.
+
+Note that the AWS credentials are not required if the AWS environment is configured correctly. These are loaded
+automatically from the environment or the AWS configuration file and do not need to be provided explicitly via
+the constructor. If the AWS environment is not configured users need to provide the AWS credentials via the
+constructor. Aside from model, three required parameters are `aws_access_key_id`, `aws_secret_access_key`,
+and `aws_region_name`.
+
+**Parameters:**
+
+- **model** (str) – The model to use for text generation. The model must be available in Amazon Bedrock and must
+ be specified in the format outlined in the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids-arns.html).
+
+- **aws_access_key_id** (Secret | None) – AWS access key ID.
+
+- **aws_secret_access_key** (Secret | None) – AWS secret access key.
+
+- **aws_session_token** (Secret | None) – AWS session token.
+
+- **aws_region_name** (Secret | None) – AWS region name. Make sure the region you set supports Amazon Bedrock.
+
+- **aws_profile_name** (Secret | None) – AWS profile name.
+
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional dictionary of generation parameters. Some common parameters are:
+
+- `maxTokens`: Maximum number of tokens to generate.
+
+- `stopSequences`: List of stop sequences to stop generation.
+
+- `temperature`: Sampling temperature.
+
+- `topP`: Nucleus sampling parameter.
+
+- `response_format`: Request structured JSON output validated against a schema. Provide a dict with:
+
+ - `schema` (required): a JSON Schema dict describing the expected output structure.
+ - `name` (optional): a name for the schema, defaults to `"response_schema"`.
+ - `description` (optional): a description of the schema.
+
+ Example::
+
+ ```
+ generation_kwargs={
+ "response_format": {
+ "name": "person",
+ "schema": {
+ "type": "object",
+ "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
+ "required": ["name", "age"],
+ "additionalProperties": False,
+ },
+ }
+ }
+ ```
+
+ When set, the parsed JSON object is stored in `reply.meta["structured_output"]`.
+ You can find the model specific arguments in the AWS Bedrock API[documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html).
+
+- **streaming_callback** (StreamingCallbackT | None) – A callback function called when a new token is received from the stream.
+ By default, the model is not set up for streaming. To enable streaming, set this parameter to a callback
+ function that handles the streaming chunks. The callback function receives a
+ [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk) object and switches
+ the streaming mode on.
+
+- **boto3_config** (dict\[str, Any\] | None) – Dictionary of configuration options for the underlying Boto3 client.
+ Can be used to tune [retry behavior](https://docs.aws.amazon.com/boto3/latest/guide/retries.html)
+ and other low-level settings like timeouts and connection management.
+
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ Each tool should have a unique name.
+
+- **guardrail_config** (dict\[str, str\] | None) – Optional configuration for a guardrail that has been created in Amazon Bedrock.
+ This must be provided as a dictionary matching either
+ [GuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_GuardrailConfiguration.html).
+ or, in streaming mode (when `streaming_callback` is set),
+ [GuardrailStreamConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailStreamConfiguration.html).
+ If `trace` is set to `enabled`, the guardrail trace will be included under the `trace` key in the `meta`
+ attribute of the resulting `ChatMessage`.
+ Note: Enabling guardrails in streaming mode may introduce additional latency.
+ To manage this, you can adjust the `streamProcessingMode` parameter.
+ See the
+ [Guardrails Streaming documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-streaming.html)
+ for more information.
+
+- **tools_cachepoint_config** (dict\[str, str\] | None) – Optional configuration to use prompt caching for tools.
+ The dictionary must match the
+ [CachePointBlock schema](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_CachePointBlock.html).
+ Example: `{"type": "default", "ttl": "5m"}`
+
+**Raises:**
+
+- ValueError – If the model name is empty or None.
+- AmazonBedrockConfigurationError – If the AWS environment is not configured correctly or the model is
+ not supported.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AmazonBedrockChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary with serialized data.
+
+**Returns:**
+
+- AmazonBedrockChatGenerator – Instance of `AmazonBedrockChatGenerator`.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Executes a synchronous inference call to the Amazon Bedrock model using the Converse API.
+
+Supports both standard and streaming responses depending on whether a streaming callback is provided.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of `ChatMessage` objects forming the chat history.
+- **streaming_callback** (StreamingCallbackT | None) – Optional callback for handling streaming outputs.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional dictionary of generation parameters. Some common parameters are:
+- `maxTokens`: Maximum number of tokens to generate.
+- `stopSequences`: List of stop sequences to stop generation.
+- `temperature`: Sampling temperature.
+- `topP`: Nucleus sampling parameter.
+- `response_format`: Request structured JSON output validated against a schema.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ Each tool should have a unique name.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary containing the model-generated replies under the `"replies"` key.
+
+**Raises:**
+
+- AmazonBedrockInferenceError – If the Bedrock inference API call fails.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Executes an asynchronous inference call to the Amazon Bedrock model using the Converse API.
+
+Designed for use cases where non-blocking or concurrent execution is desired.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of `ChatMessage` objects forming the chat history.
+- **streaming_callback** (StreamingCallbackT | None) – Optional async-compatible callback for handling streaming outputs.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional dictionary of generation parameters. Some common parameters are:
+- `maxTokens`: Maximum number of tokens to generate.
+- `stopSequences`: List of stop sequences to stop generation.
+- `temperature`: Sampling temperature.
+- `topP`: Nucleus sampling parameter.
+- `response_format`: Request structured JSON output validated against a schema.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ Each tool should have a unique name.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary containing the model-generated replies under the `"replies"` key.
+
+**Raises:**
+
+- AmazonBedrockInferenceError – If the Bedrock inference API call fails.
+
+## haystack_integrations.components.generators.amazon_bedrock.generator
+
+### AmazonBedrockGenerator
+
+Generates text using models hosted on Amazon Bedrock.
+
+For example, to use the Anthropic Claude model, pass 'anthropic.claude-v2' in the `model` parameter.
+Provide AWS credentials either through the local AWS profile or directly through
+`aws_access_key_id`, `aws_secret_access_key`, `aws_session_token`, and `aws_region_name` parameters.
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockGenerator
+
+generator = AmazonBedrockGenerator(
+ model="anthropic.claude-v2",
+ max_length=99
+)
+
+print(generator.run("Who is the best American actor?"))
+```
+
+AmazonBedrockGenerator 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 [Amazon Bedrock documentation]
+(https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html).
+If the AWS environment is configured correctly, the AWS credentials are not required as they're loaded
+automatically from the environment or the AWS configuration file.
+If the AWS environment is not configured, set `aws_access_key_id`, `aws_secret_access_key`,
+`aws_session_token`, and `aws_region_name` as environment variables or pass them as
+[Secret](https://docs.haystack.deepset.ai/docs/secret-management) arguments. Make sure the region you set
+supports Amazon Bedrock.
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ aws_access_key_id: Secret | None = Secret.from_env_var(
+ "AWS_ACCESS_KEY_ID", strict=False
+ ),
+ aws_secret_access_key: Secret | None = Secret.from_env_var(
+ "AWS_SECRET_ACCESS_KEY", strict=False
+ ),
+ aws_session_token: Secret | None = Secret.from_env_var(
+ "AWS_SESSION_TOKEN", strict=False
+ ),
+ aws_region_name: Secret | None = Secret.from_env_var(
+ "AWS_DEFAULT_REGION", strict=False
+ ),
+ aws_profile_name: Secret | None = Secret.from_env_var(
+ "AWS_PROFILE", strict=False
+ ),
+ max_length: int | None = None,
+ truncate: bool | None = None,
+ streaming_callback: Callable[[StreamingChunk], None] | None = None,
+ boto3_config: dict[str, Any] | None = None,
+ model_family: MODEL_FAMILIES | None = None,
+ **kwargs: Any
+) -> None
+```
+
+Create a new `AmazonBedrockGenerator` instance.
+
+**Parameters:**
+
+- **model** (str) – The name of the model to use.
+- **aws_access_key_id** (Secret | None) – The AWS access key ID.
+- **aws_secret_access_key** (Secret | None) – The AWS secret access key.
+- **aws_session_token** (Secret | None) – The AWS session token.
+- **aws_region_name** (Secret | None) – The AWS region name. Make sure the region you set supports Amazon Bedrock.
+- **aws_profile_name** (Secret | None) – The AWS profile name.
+- **max_length** (int | None) – The maximum length of the generated text. This can also be set in the `kwargs` parameter
+ by using the model specific parameter name.
+- **truncate** (bool | None) – Deprecated. This parameter no longer has any effect.
+- **streaming_callback** (Callable\\[[StreamingChunk\], None\] | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **boto3_config** (dict\[str, Any\] | None) – Dictionary of configuration options for the underlying Boto3 client.
+ Can be used to tune [retry behavior](https://docs.aws.amazon.com/boto3/latest/guide/retries.html)
+ and other low-level settings like timeouts and connection management.
+- **model_family** (MODEL_FAMILIES | None) – The model family to use. If not provided, the model adapter is selected based on the model
+ name.
+- **kwargs** (Any) – Additional keyword arguments to be passed to the model.
+ You can find the model specific arguments in AWS Bedrock's
+ [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html).
+ These arguments are specific to the model. You can find them in the model's documentation.
+
+**Raises:**
+
+- ValueError – If the model name is empty or None.
+- AmazonBedrockConfigurationError – If the AWS environment is not configured correctly or the model is
+ not supported.
+
+#### run
+
+```python
+run(
+ prompt: str,
+ streaming_callback: Callable[[StreamingChunk], None] | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+) -> dict[str, list[str] | dict[str, Any]]
+```
+
+Generates a list of string response to the given prompt.
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to generate a response for.
+- **streaming_callback** (Callable\\[[StreamingChunk\], None\] | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments passed to the generator.
+
+**Returns:**
+
+- dict\[str, list\[str\] | dict\[str, Any\]\] – A dictionary with the following keys:
+- `replies`: A list of generated responses.
+- `meta`: A dictionary containing response metadata.
+
+**Raises:**
+
+- ValueError – If the prompt is empty or None.
+- AmazonBedrockInferenceError – If the model cannot be invoked.
+
+#### get_model_adapter
+
+```python
+get_model_adapter(
+ model: str, model_family: str | None = None
+) -> type[BedrockModelAdapter]
+```
+
+Gets the model adapter for the given model.
+
+If `model_family` is provided, the adapter for the model family is returned.
+If `model_family` is not provided, the adapter is auto-detected based on the model name.
+
+**Parameters:**
+
+- **model** (str) – The model name.
+- **model_family** (str | None) – The model family.
+
+**Returns:**
+
+- type\[BedrockModelAdapter\] – The model adapter class, or None if no adapter is found.
+
+**Raises:**
+
+- AmazonBedrockConfigurationError – If the model family is not supported or the model cannot be
+ auto-detected.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AmazonBedrockGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AmazonBedrockGenerator – Deserialized component.
+
+## haystack_integrations.components.rankers.amazon_bedrock.ranker
+
+### AmazonBedrockRanker
+
+Ranks Documents based on their similarity to the query using Amazon Bedrock's Cohere Rerank model.
+
+Documents are indexed from most to least semantically relevant to the query.
+
+Supported Amazon Bedrock models:
+
+- cohere.rerank-v3-5:0
+- amazon.rerank-v1:0
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.utils import Secret
+from haystack_integrations.components.rankers.amazon_bedrock import AmazonBedrockRanker
+
+ranker = AmazonBedrockRanker(
+ model="cohere.rerank-v3-5:0",
+ top_k=2,
+ aws_region_name=Secret.from_token("eu-central-1")
+)
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "What is the capital of germany?"
+output = ranker.run(query=query, documents=docs)
+docs = output["documents"]
+```
+
+AmazonBedrockRanker 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 [Amazon Bedrock documentation]
+(https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html).
+
+If the AWS environment is configured correctly, the AWS credentials are not required as they're loaded
+automatically from the environment or the AWS configuration file.
+If the AWS environment is not configured, set `aws_access_key_id`, `aws_secret_access_key`,
+and `aws_region_name` as environment variables or pass them as
+[Secret](https://docs.haystack.deepset.ai/docs/secret-management) arguments. Make sure the region you set
+supports Amazon Bedrock.
+
+#### __init__
+
+```python
+__init__(
+ model: str = "cohere.rerank-v3-5:0",
+ top_k: int = 10,
+ aws_access_key_id: Secret | None = Secret.from_env_var(
+ ["AWS_ACCESS_KEY_ID"], strict=False
+ ),
+ aws_secret_access_key: Secret | None = Secret.from_env_var(
+ ["AWS_SECRET_ACCESS_KEY"], strict=False
+ ),
+ aws_session_token: Secret | None = Secret.from_env_var(
+ ["AWS_SESSION_TOKEN"], strict=False
+ ),
+ aws_region_name: Secret | None = Secret.from_env_var(
+ ["AWS_DEFAULT_REGION"], strict=False
+ ),
+ aws_profile_name: Secret | None = Secret.from_env_var(
+ ["AWS_PROFILE"], strict=False
+ ),
+ max_chunks_per_doc: int | None = None,
+ meta_fields_to_embed: list[str] | None = None,
+ meta_data_separator: str = "\n",
+) -> None
+```
+
+Creates an instance of the 'AmazonBedrockRanker'.
+
+**Parameters:**
+
+- **model** (str) – Amazon Bedrock model name for Cohere Rerank. Default is "cohere.rerank-v3-5:0".
+- **top_k** (int) – The maximum number of documents to return.
+- **aws_access_key_id** (Secret | None) – AWS access key ID.
+- **aws_secret_access_key** (Secret | None) – AWS secret access key.
+- **aws_session_token** (Secret | None) – AWS session token.
+- **aws_region_name** (Secret | None) – AWS region name.
+- **aws_profile_name** (Secret | None) – AWS profile name.
+- **max_chunks_per_doc** (int | None) – If your document exceeds 512 tokens, this determines the maximum number of
+ chunks a document can be split into. If `None`, the default of 10 is used.
+ Note: This parameter is not currently used in the implementation but is included for future compatibility.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be concatenated
+ with the document content for reranking.
+- **meta_data_separator** (str) – Separator used to concatenate the meta fields
+ to the Document content.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AmazonBedrockRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- AmazonBedrockRanker – The deserialized component.
+
+#### run
+
+```python
+run(
+ query: str, documents: list[Document], top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Use the Amazon Bedrock Reranker to re-rank the list of documents based on the query.
+
+**Parameters:**
+
+- **query** (str) – Query string.
+- **documents** (list\[Document\]) – List of Documents.
+- **top_k** (int | None) – The maximum number of Documents you want the Ranker to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/amazon_sagemaker.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/amazon_sagemaker.md
new file mode 100644
index 0000000000..836d7b8170
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/amazon_sagemaker.md
@@ -0,0 +1,150 @@
+---
+title: "Amazon Sagemaker"
+id: integrations-amazon-sagemaker
+description: "Amazon Sagemaker integration for Haystack"
+slug: "/integrations-amazon-sagemaker"
+---
+
+
+
+## Module haystack\_integrations.components.generators.amazon\_sagemaker.sagemaker
+
+
+
+### SagemakerGenerator
+
+Enables text generation using Amazon Sagemaker.
+
+SagemakerGenerator supports Large Language Models (LLMs) hosted and deployed on a SageMaker Inference Endpoint.
+For guidance on how to deploy a model to SageMaker, refer to the
+[SageMaker JumpStart foundation models documentation](https://docs.aws.amazon.com/sagemaker/latest/dg/jumpstart-foundation-models-use.html).
+
+Usage example:
+```python
+# Make sure your AWS credentials are set up correctly. You can use environment variables or a shared credentials
+# file. Then you can use the generator as follows:
+from haystack_integrations.components.generators.amazon_sagemaker import SagemakerGenerator
+
+generator = SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-bf16")
+response = generator.run("What's Natural Language Processing? Be brief.")
+print(response)
+>>> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on
+>>> the interaction between computers and human language. It involves enabling computers to understand, interpret,
+>>> and respond to natural human language in a way that is both meaningful and useful.'], 'meta': [{}]}
+```
+
+
+
+#### SagemakerGenerator.\_\_init\_\_
+
+```python
+def __init__(
+ model: str,
+ aws_access_key_id: Secret | None = Secret.from_env_var(
+ ["AWS_ACCESS_KEY_ID"], strict=False),
+ aws_secret_access_key: Secret
+ | None = Secret.from_env_var( # noqa: B008
+ ["AWS_SECRET_ACCESS_KEY"], strict=False),
+ aws_session_token: Secret | None = Secret.from_env_var(
+ ["AWS_SESSION_TOKEN"], strict=False),
+ aws_region_name: Secret | None = Secret.from_env_var(
+ ["AWS_DEFAULT_REGION"], strict=False),
+ aws_profile_name: Secret | None = Secret.from_env_var(["AWS_PROFILE"],
+ strict=False),
+ aws_custom_attributes: dict[str, Any] | None = None,
+ generation_kwargs: dict[str, Any] | None = None)
+```
+
+Instantiates the session with SageMaker.
+
+**Arguments**:
+
+- `aws_access_key_id`: The `Secret` for AWS access key ID.
+- `aws_secret_access_key`: The `Secret` for AWS secret access key.
+- `aws_session_token`: The `Secret` for AWS session token.
+- `aws_region_name`: The `Secret` for AWS region name. If not provided, the default region will be used.
+- `aws_profile_name`: The `Secret` for AWS profile name. If not provided, the default profile will be used.
+- `model`: The name for SageMaker Model Endpoint.
+- `aws_custom_attributes`: Custom attributes to be passed to SageMaker, for example `{"accept_eula": True}`
+in case of Llama-2 models.
+- `generation_kwargs`: Additional keyword arguments for text generation. For a list of supported parameters
+see your model's documentation page, for example here for HuggingFace models:
+https://huggingface.co/blog/sagemaker-huggingface-llm#4-run-inference-and-chat-with-our-model
+
+Specifically, Llama-2 models support the following inference payload parameters:
+
+- `max_new_tokens`: Model generates text until the output length (excluding the input context length)
+ reaches `max_new_tokens`. If specified, it must be a positive integer.
+- `temperature`: Controls the randomness in the output. Higher temperature results in output sequence with
+ low-probability words and lower temperature results in output sequence with high-probability words.
+ If `temperature=0`, it results in greedy decoding. If specified, it must be a positive float.
+- `top_p`: In each step of text generation, sample from the smallest possible set of words with cumulative
+ probability `top_p`. If specified, it must be a float between 0 and 1.
+- `return_full_text`: If `True`, input text will be part of the output generated text. If specified, it must
+ be boolean. The default value for it is `False`.
+
+
+
+#### SagemakerGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### SagemakerGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "SagemakerGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### SagemakerGenerator.run
+
+```python
+@component.output_types(replies=list[str], meta=list[dict[str, Any]])
+def run(
+ prompt: str,
+ generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Invoke the text generation inference based on the provided prompt and generation parameters.
+
+**Arguments**:
+
+- `prompt`: The string prompt to use for text generation.
+- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will
+potentially override the parameters passed in the `__init__` method.
+
+**Raises**:
+
+- `ValueError`: If the model response type is not a list of dictionaries or a single dictionary.
+- `SagemakerNotReadyError`: If the SageMaker model is not ready to accept requests.
+- `SagemakerInferenceError`: If the SageMaker Inference returns an error.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list of strings containing the generated responses
+- `meta`: A list of dictionaries containing the metadata for each response.
+
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/anthropic.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/anthropic.md
new file mode 100644
index 0000000000..cba0fccd3f
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/anthropic.md
@@ -0,0 +1,685 @@
+---
+title: "Anthropic"
+id: integrations-anthropic
+description: "Anthropic integration for Haystack"
+slug: "/integrations-anthropic"
+---
+
+
+## haystack_integrations.components.generators.anthropic.chat.chat_generator
+
+### AnthropicChatGenerator
+
+Completes chats using Anthropic's large language models (LLMs).
+
+It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage)
+format in input and output. Supports multimodal inputs including text and images.
+
+You can customize how the text is generated by passing parameters to the
+Anthropic API. Use the `**generation_kwargs` argument when you initialize
+the component or when you run it. Any parameter that works with
+`anthropic.Message.create` will work here too.
+
+For details on Anthropic API parameters, see
+[Anthropic documentation](https://docs.anthropic.com/en/api/messages).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.anthropic import (
+ AnthropicChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+
+generator = AnthropicChatGenerator(
+ generation_kwargs={
+ "max_tokens": 1000,
+ "temperature": 0.7,
+ },
+)
+
+messages = [
+ ChatMessage.from_system(
+ "You are a helpful, respectful and honest assistant"
+ ),
+ ChatMessage.from_user("What's Natural Language Processing?"),
+]
+print(generator.run(messages=messages))
+```
+
+Usage example with images:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+
+image_content = ImageContent.from_file_path("path/to/image.jpg")
+messages = [
+ ChatMessage.from_user(
+ content_parts=["What's in this image?", image_content]
+ )
+]
+generator = AnthropicChatGenerator()
+result = generator.run(messages)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "claude-opus-4-6",
+ "claude-sonnet-4-6",
+ "claude-haiku-4-5-20251001",
+ "claude-sonnet-4-5-20250929",
+ "claude-opus-4-5-20251101",
+ "claude-opus-4-1-20250805",
+ "claude-sonnet-4-20250514",
+ "claude-opus-4-20250514",
+ "claude-3-haiku-20240307",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component. See
+https://platform.claude.com/docs/en/about-claude/models/overview for the full list.
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("ANTHROPIC_API_KEY"),
+ model: str = "claude-sonnet-4-5",
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ ignore_tools_thinking_messages: bool = True,
+ tools: ToolsType | None = None,
+ *,
+ timeout: float | None = None,
+ max_retries: int | None = None
+) -> None
+```
+
+Creates an instance of AnthropicChatGenerator.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Anthropic API key
+- **model** (str) – The name of the model to use.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the Anthropic endpoint. See Anthropic [documentation](https://docs.anthropic.com/claude/reference/messages_post)
+ for more details.
+
+Supported generation_kwargs parameters are:
+
+- `system`: The system message to be passed to the model.
+- `max_tokens`: The maximum number of tokens to generate.
+- `metadata`: A dictionary of metadata to be passed to the model.
+- `stop_sequences`: A list of strings that the model should stop generating at.
+- `temperature`: The temperature to use for sampling.
+- `top_p`: The top_p value to use for nucleus sampling.
+- `top_k`: The top_k value to use for top-k sampling.
+- `extra_headers`: A dictionary of extra headers to be passed to the model (i.e. for beta features).
+- `thinking`: A dictionary of thinking parameters to be passed to the model.
+ The `budget_tokens` passed for thinking should be less than `max_tokens`.
+ For more details and supported models, see: [Anthropic Extended Thinking](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking)
+- `output_config`: A dictionary of output configuration options to be passed to the model.
+- **ignore_tools_thinking_messages** (bool) – Anthropic's approach to tools (function calling) resolution involves a
+ "chain of thought" messages before returning the actual function names and parameters in a message. If
+ `ignore_tools_thinking_messages` is `True`, the generator will drop so-called thinking messages when tool
+ use is detected. See the Anthropic [tools](https://docs.anthropic.com/en/docs/tool-use#chain-of-thought-tool-use)
+ for more details.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset, that the model can use.
+ Each tool should have a unique name.
+- **timeout** (float | None) – Timeout for Anthropic client calls. If not set, it defaults to the default set by the Anthropic client.
+- **max_retries** (int | None) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by
+ the Anthropic client.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnthropicChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- AnthropicChatGenerator – The deserialized component instance.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Invokes the Anthropic API with the given messages and generation kwargs.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Anthropic generation endpoint.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset, that the model can use.
+ Each tool should have a unique name. If set, it will override the `tools` parameter set during component
+ initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: The responses from the model
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Async version of the run method. Invokes the Anthropic API with the given messages and generation kwargs.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Anthropic generation endpoint.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset, that the model can use.
+ Each tool should have a unique name. If set, it will override the `tools` parameter set during component
+ initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: The responses from the model
+
+## haystack_integrations.components.generators.anthropic.chat.foundry_chat_generator
+
+### AnthropicFoundryChatGenerator
+
+Bases: AnthropicChatGenerator
+
+Enables text generation using Anthropic's Claude models via Azure Foundry.
+
+A variety of Claude models (Opus, Sonnet, Haiku, and others) are available through Azure Foundry.
+
+To use AnthropicFoundryChatGenerator, you must have an Azure subscription with Foundry enabled
+and the desired Anthropic model deployed in your Foundry resource.
+
+For more details, refer to the [Anthropic Foundry documentation](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/lib/foundry.md).
+
+Any valid text generation parameters for the Anthropic messaging API can be passed to
+the AnthropicFoundry API. Users can provide these parameters directly to the component via
+the `generation_kwargs` parameter in `__init__` or the `run` method.
+
+For more details on the parameters supported by the Anthropic API, refer to the
+Anthropic Message API [documentation](https://docs.anthropic.com/en/api/messages).
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicFoundryChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = AnthropicFoundryChatGenerator(
+ model="claude-sonnet-4-5",
+ api_key=Secret.from_env_var("ANTHROPIC_FOUNDRY_API_KEY"),
+ resource="my-resource",
+)
+
+response = client.run(messages)
+print(response)
+>> {'replies': [ChatMessage(_role=Secret | None) – The API key to use for authentication.
+ Defaults to the `ANTHROPIC_FOUNDRY_API_KEY` environment variable.
+ Can be `None` when using `azure_ad_token_provider` instead.
+- **resource** (str | None) – The Foundry resource name. Can also be set via the `ANTHROPIC_FOUNDRY_RESOURCE`
+ environment variable. Either `resource` or `endpoint` must be provided.
+- **endpoint** (str | None) – The full Foundry endpoint URL (e.g.,
+ "https://your-resource.openai.azure.com/anthropic").
+ Either `resource` or `endpoint` must be provided.
+- **model** (str) – The name of the model to use (deployment name in Foundry).
+- **streaming_callback** (Callable\\[[StreamingChunk\], None\] | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the AnthropicFoundry endpoint. See Anthropic [documentation](https://docs.anthropic.com/claude/reference/messages_post)
+ for more details.
+ Supported generation_kwargs parameters are:
+- `system`: The system message to be passed to the model.
+- `max_tokens`: The maximum number of tokens to generate.
+- `metadata`: A dictionary of metadata to be passed to the model.
+- `stop_sequences`: A list of strings that the model should stop generating at.
+- `temperature`: The temperature to use for sampling.
+- `top_p`: The top_p value to use for nucleus sampling.
+- `top_k`: The top_k value to use for top-k sampling.
+- `extra_headers`: A dictionary of extra headers to be passed to the model (i.e. for beta features).
+- **ignore_tools_thinking_messages** (bool) – Anthropic's approach to tools (function calling) resolution involves a
+ "chain of thought" messages before returning the actual function names and parameters in a message. If
+ `ignore_tools_thinking_messages` is `True`, the generator will drop so-called thinking messages when tool
+ use is detected. See the Anthropic [tools](https://docs.anthropic.com/en/docs/tool-use#chain-of-thought-tool-use)
+ for more details.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset, that the model can use.
+ Each tool should have a unique name.
+- **timeout** (float | None) – Timeout for Anthropic client calls. If not set, it defaults to the default set by the Anthropic client.
+- **max_retries** (int | None) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by
+ the Anthropic client.
+- **azure_ad_token_provider** (Callable\[[], str\] | None) – A function that returns an Azure AD token for authentication.
+ Can be used instead of `api_key` for enhanced security.
+ See [Azure Identity documentation](https://learn.microsoft.com/en-us/azure/developer/python/sdk/authentication/overview)
+ for more details.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the AnthropicFoundry clients.
+
+This method is idempotent — it only creates clients once.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Invokes the AnthropicFoundry API with the given messages and generation kwargs.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Anthropic generation endpoint.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset, that the model can use.
+ Each tool should have a unique name. If set, it will override the `tools` parameter set during component
+ initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: The responses from the model
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Async version of the run method. Invokes the AnthropicFoundry API with the given messages and generation kwargs.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Anthropic generation endpoint.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset, that the model can use.
+ Each tool should have a unique name. If set, it will override the `tools` parameter set during component
+ initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: The responses from the model
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnthropicFoundryChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- AnthropicFoundryChatGenerator – The deserialized component instance.
+
+## haystack_integrations.components.generators.anthropic.chat.vertex_chat_generator
+
+### AnthropicVertexChatGenerator
+
+Bases: AnthropicChatGenerator
+
+Enables text generation using Anthropic's Claude models via the Anthropic Vertex AI API.
+
+A variety of Claude models (Opus, Sonnet, Haiku, and others) are available through the Vertex AI API endpoint.
+
+To use AnthropicVertexChatGenerator, you must have a GCP project with Vertex AI enabled.
+Additionally, ensure that the desired Anthropic model is activated in the Vertex AI Model Garden.
+Before making requests, you may need to authenticate with GCP using `gcloud auth login`.
+For more details, refer to the [guide] (https://docs.anthropic.com/en/api/claude-on-vertex-ai).
+
+Any valid text generation parameters for the Anthropic messaging API can be passed to
+the AnthropicVertex API. Users can provide these parameters directly to the component via
+the `generation_kwargs` parameter in `__init__` or the `run` method.
+
+For more details on the parameters supported by the Anthropic API, refer to the
+Anthropic Message API [documentation](https://docs.anthropic.com/en/api/messages).
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicVertexChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+client = AnthropicVertexChatGenerator(
+ model="claude-sonnet-4@20250514",
+ project_id="your-project-id", region="your-region"
+ )
+response = client.run(messages)
+print(response)
+
+>> {'replies': [ChatMessage(_role=str) – The region where the Anthropic model is deployed. Defaults to "us-central1".
+- **project_id** (str) – The GCP project ID where the Anthropic model is deployed.
+- **model** (str) – The name of the model to use.
+- **streaming_callback** (Callable\\[[StreamingChunk\], None\] | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the AnthropicVertex endpoint. See Anthropic [documentation](https://docs.anthropic.com/claude/reference/messages_post)
+ for more details.
+
+Supported generation_kwargs parameters are:
+
+- `system`: The system message to be passed to the model.
+- `max_tokens`: The maximum number of tokens to generate.
+- `metadata`: A dictionary of metadata to be passed to the model.
+- `stop_sequences`: A list of strings that the model should stop generating at.
+- `temperature`: The temperature to use for sampling.
+- `top_p`: The top_p value to use for nucleus sampling.
+- `top_k`: The top_k value to use for top-k sampling.
+- `extra_headers`: A dictionary of extra headers to be passed to the model (i.e. for beta features).
+- **ignore_tools_thinking_messages** (bool) – Anthropic's approach to tools (function calling) resolution involves a
+ "chain of thought" messages before returning the actual function names and parameters in a message. If
+ `ignore_tools_thinking_messages` is `True`, the generator will drop so-called thinking messages when tool
+ use is detected. See the Anthropic [tools](https://docs.anthropic.com/en/docs/tool-use#chain-of-thought-tool-use)
+ for more details.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset, that the model can use.
+ Each tool should have a unique name.
+- **timeout** (float | None) – Timeout for Anthropic client calls. If not set, it defaults to the default set by the Anthropic client.
+- **max_retries** (int | None) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by
+ the Anthropic client.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnthropicVertexChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- AnthropicVertexChatGenerator – The deserialized component instance.
+
+## haystack_integrations.components.generators.anthropic.generator
+
+### AnthropicGenerator
+
+Enables text generation using Anthropic large language models (LLMs). It supports the Claude family of models.
+
+Although Anthropic natively supports a much richer messaging API, we have intentionally simplified it in this
+component so that the main input/output interface is string-based.
+For more complete support, consider using the AnthropicChatGenerator.
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicGenerator
+
+client = AnthropicGenerator(model="claude-sonnet-4-20250514")
+response = client.run("What's Natural Language Processing? Be brief.")
+print(response)
+>>{'replies': ['Natural language processing (NLP) is a branch of artificial intelligence focused on enabling
+>>computers to understand, interpret, and manipulate human language. The goal of NLP is to read, decipher,
+>> understand, and make sense of the human languages in a manner that is valuable.'], 'meta': {'model':
+>> 'claude-2.1', 'index': 0, 'finish_reason': 'end_turn', 'usage': {'input_tokens': 18, 'output_tokens': 58}}}
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("ANTHROPIC_API_KEY"),
+ model: str = "claude-sonnet-4-20250514",
+ streaming_callback: Callable[[StreamingChunk], None] | None = None,
+ system_prompt: str | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ *,
+ timeout: float | None = None,
+ max_retries: int | None = None
+) -> None
+```
+
+Initialize the AnthropicGenerator.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Anthropic API key.
+- **model** (str) – The name of the Anthropic model to use.
+- **streaming_callback** (Callable\\[[StreamingChunk\], None\] | None) – An optional callback function to handle streaming chunks.
+- **system_prompt** (str | None) – An optional system prompt to use for generation.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for generation.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnthropicGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- AnthropicGenerator – The deserialized component instance.
+
+#### run
+
+```python
+run(
+ prompt: str,
+ generation_kwargs: dict[str, Any] | None = None,
+ streaming_callback: Callable[[StreamingChunk], None] | None = None,
+) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Generate replies using the Anthropic API.
+
+**Parameters:**
+
+- **prompt** (str) – The input prompt for generation.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for generation.
+- **streaming_callback** (Callable\\[[StreamingChunk\], None\] | None) – An optional callback function to handle streaming chunks.
+
+**Returns:**
+
+- dict\[str, list\[str\] | list\[dict\[str, Any\]\]\] – A dictionary containing:
+- `replies`: A list of generated replies.
+- `meta`: A list of metadata dictionaries for each reply.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/arcadedb.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/arcadedb.md
new file mode 100644
index 0000000000..466f49e35c
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/arcadedb.md
@@ -0,0 +1,391 @@
+---
+title: "ArcadeDB"
+id: integrations-arcadedb
+description: "ArcadeDB integration for Haystack"
+slug: "/integrations-arcadedb"
+---
+
+
+## haystack_integrations.components.retrievers.arcadedb.embedding_retriever
+
+### ArcadeDBEmbeddingRetriever
+
+Retrieve documents from ArcadeDB using vector similarity (LSM_VECTOR / HNSW index).
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack_integrations.components.retrievers.arcadedb import ArcadeDBEmbeddingRetriever
+from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore
+
+store = ArcadeDBDocumentStore(database="mydb")
+retriever = ArcadeDBEmbeddingRetriever(document_store=store, top_k=5)
+
+# Add documents to DocumentStore
+documents = [
+ Document(text="My name is Carla and I live in Berlin"),
+ Document(text="My name is Paul and I live in New York"),
+ Document(text="My name is Silvano and I live in Matera"),
+ Document(text="My name is Usagi Tsukino and I live in Tokyo"),
+]
+document_store.write_documents(documents)
+
+embedder = SentenceTransformersTextEmbedder()
+query_embeddings = embedder.run("Who lives in Berlin?")["embedding"]
+
+result = retriever.run(query=query_embeddings)
+for doc in result["documents"]:
+ print(doc.content)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: ArcadeDBDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create an ArcadeDBEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (ArcadeDBDocumentStore) – An instance of `ArcadeDBDocumentStore`.
+- **filters** (dict\[str, Any\] | None) – Default filters applied to every retrieval call.
+- **top_k** (int) – Maximum number of documents to return.
+- **filter_policy** (FilterPolicy) – How runtime filters interact with default filters.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by vector similarity.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – The embedding vector to search with.
+- **filters** (dict\[str, Any\] | None) – Optional filters to narrow results.
+- **top_k** (int | None) – Maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s most similar to the given `query_embedding`
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ArcadeDBEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ArcadeDBEmbeddingRetriever – Deserialized component.
+
+## haystack_integrations.document_stores.arcadedb.document_store
+
+ArcadeDB DocumentStore for Haystack 2.x — document storage + vector search via HTTP/JSON API.
+
+### ArcadeDBDocumentStore
+
+An ArcadeDB-backed DocumentStore for Haystack 2.x.
+
+Uses ArcadeDB's HTTP/JSON API for all operations — no special drivers required.
+Supports HNSW vector search (LSM_VECTOR) and SQL metadata filtering.
+
+Usage example:
+
+```python
+from haystack.dataclasses.document import Document
+from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore
+
+document_store = ArcadeDBDocumentStore(
+ url="http://localhost:2480",
+ database="haystack",
+ embedding_dimension=768,
+)
+document_store.write_documents([
+ Document(content="This is first", embedding=[0.0]*5),
+ Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5])
+])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ url: str = "http://localhost:2480",
+ database: str = "haystack",
+ username: Secret = Secret.from_env_var("ARCADEDB_USERNAME", strict=False),
+ password: Secret = Secret.from_env_var("ARCADEDB_PASSWORD", strict=False),
+ type_name: str = "Document",
+ embedding_dimension: int = 768,
+ similarity_function: str = "cosine",
+ recreate_type: bool = False,
+ create_database: bool = True
+) -> None
+```
+
+Create an ArcadeDBDocumentStore instance.
+
+**Parameters:**
+
+- **url** (str) – ArcadeDB HTTP endpoint.
+- **database** (str) – Database name.
+- **username** (Secret) – HTTP Basic Auth username (default: `ARCADEDB_USERNAME` env var).
+- **password** (Secret) – HTTP Basic Auth password (default: `ARCADEDB_PASSWORD` env var).
+- **type_name** (str) – Vertex type name for documents.
+- **embedding_dimension** (int) – Vector dimension for the HNSW index.
+- **similarity_function** (str) – Distance metric — `"cosine"`, `"euclidean"`, or `"dot"`.
+- **recreate_type** (bool) – If `True`, drop and recreate the type on initialization.
+- **create_database** (bool) – If `True`, create the database if it doesn't exist.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the DocumentStore to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ArcadeDBDocumentStore
+```
+
+Deserializes the DocumentStore from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- ArcadeDBDocumentStore – The deserialized DocumentStore.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – Number of documents in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Return documents matching the given filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Haystack filter dictionary.
+
+**Returns:**
+
+- list\[Document\] – List of matching documents.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to the store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Haystack Documents to write.
+- **policy** (DuplicatePolicy) – How to handle duplicate document IDs.
+
+**Returns:**
+
+- int – Number of documents written.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents by their IDs.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – List of document IDs to delete.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents in the document store.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Counts the number of documents matching the provided filter
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the documents
+
+**Returns:**
+
+- int – The number of documents that match the filter
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Counts unique values for each metadata field in documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the document list.
+- **metadata_fields** (list\[str\]) – Metadata fields for which to count unique values.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary where keys are metadata field names and values are the
+ counts of unique values for that field.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the metadata fields and their corresponding types based on sampled documents.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary mapping field names to dictionaries with a `type` key.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+For a given metadata field, finds its min and max values.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to inspect.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with `min` and `max` keys and their corresponding values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a field matching a search term or all possible values
+if no search term is given.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to inspect.
+- **search_term** (str | None) – Optional case-insensitive substring search term.
+- **from\_** (int) – The starting index for pagination.
+- **size** (int) – The number of values to return.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple containing the paginated values and the total count.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/astra.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/astra.md
new file mode 100644
index 0000000000..8119b02c00
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/astra.md
@@ -0,0 +1,520 @@
+---
+title: "Astra"
+id: integrations-astra
+description: "Astra integration for Haystack"
+slug: "/integrations-astra"
+---
+
+
+## haystack_integrations.components.retrievers.astra.retriever
+
+### AstraEmbeddingRetriever
+
+A component for retrieving documents from an AstraDocumentStore.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.astra import AstraDocumentStore
+from haystack_integrations.components.retrievers.astra import AstraEmbeddingRetriever
+
+document_store = AstraDocumentStore(
+ api_endpoint=api_endpoint,
+ token=token,
+ collection_name=collection_name,
+ duplicates_policy=DuplicatePolicy.SKIP,
+ embedding_dim=384,
+)
+
+retriever = AstraEmbeddingRetriever(document_store=document_store)
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: AstraDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Initialize the AstraEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (AstraDocumentStore) – An instance of AstraDocumentStore.
+- **filters** (dict\[str, Any\] | None) – a dictionary with filters to narrow down the search space.
+- **top_k** (int) – the maximum number of documents to retrieve.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the AstraDocumentStore.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – floats representing the query embedding
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – the maximum number of documents to retrieve.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – a dictionary with the following keys:
+- `documents`: A list of documents retrieved from the AstraDocumentStore.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the AstraDocumentStore asynchronously.
+
+Runs the sync search in a thread pool to avoid blocking the event loop.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – floats representing the query embedding
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – the maximum number of documents to retrieve.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – a dictionary with the following keys:
+- `documents`: A list of documents retrieved from the AstraDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AstraEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AstraEmbeddingRetriever – Deserialized component.
+
+## haystack_integrations.document_stores.astra.document_store
+
+### AstraDocumentStore
+
+An AstraDocumentStore document store for Haystack.
+
+Example Usage:
+
+```python
+from haystack_integrations.document_stores.astra import AstraDocumentStore
+
+document_store = AstraDocumentStore(
+ api_endpoint=api_endpoint,
+ token=token,
+ collection_name=collection_name,
+ duplicates_policy=DuplicatePolicy.SKIP,
+ embedding_dim=384,
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ api_endpoint: Secret = Secret.from_env_var("ASTRA_DB_API_ENDPOINT"),
+ token: Secret = Secret.from_env_var("ASTRA_DB_APPLICATION_TOKEN"),
+ collection_name: str = "documents",
+ embedding_dimension: int = 768,
+ duplicates_policy: DuplicatePolicy = DuplicatePolicy.NONE,
+ similarity: str = "cosine",
+ namespace: str | None = None,
+) -> None
+```
+
+The connection to Astra DB is established and managed through the JSON API.
+
+The required credentials (api endpoint and application token) can be generated
+through the UI by clicking and the connect tab, and then selecting JSON API and
+Generate Configuration.
+
+**Parameters:**
+
+- **api_endpoint** (Secret) – the Astra DB API endpoint.
+- **token** (Secret) – the Astra DB application token.
+- **collection_name** (str) – the current collection in the keyspace in the current Astra DB.
+- **embedding_dimension** (int) – dimension of embedding vector.
+- **duplicates_policy** (DuplicatePolicy) – handle duplicate documents based on DuplicatePolicy parameter options.
+ Parameter options : (`SKIP`, `OVERWRITE`, `FAIL`, `NONE`)
+- `DuplicatePolicy.NONE`: Default policy, If a Document with the same ID already exists,
+ it is skipped and not written.
+- `DuplicatePolicy.SKIP`: if a Document with the same ID already exists, it is skipped and not written.
+- `DuplicatePolicy.OVERWRITE`: if a Document with the same ID already exists, it is overwritten.
+- `DuplicatePolicy.FAIL`: if a Document with the same ID already exists, an error is raised.
+- **similarity** (str) – the similarity function used to compare document vectors.
+
+**Raises:**
+
+- ValueError – if the API endpoint or token is not set.
+
+#### index
+
+```python
+index: AstraClient
+```
+
+Return the AstraClient index, initializing it if necessary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AstraDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AstraDocumentStore – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Indexes documents for later queries.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – a list of Haystack Document objects.
+- **policy** (DuplicatePolicy) – handle duplicate documents based on DuplicatePolicy parameter options.
+ Parameter options : (`SKIP`, `OVERWRITE`, `FAIL`, `NONE`)
+- `DuplicatePolicy.NONE`: Default policy, If a Document with the same ID already exists,
+ it is skipped and not written.
+- `DuplicatePolicy.SKIP`: If a Document with the same ID already exists,
+ it is skipped and not written.
+- `DuplicatePolicy.OVERWRITE`: If a Document with the same ID already exists, it is overwritten.
+- `DuplicatePolicy.FAIL`: If a Document with the same ID already exists, an error is raised.
+
+**Returns:**
+
+- int – number of documents written.
+
+**Raises:**
+
+- ValueError – if the documents are not of type Document or dict.
+- DuplicateDocumentError – if a document with the same ID already exists and policy is set to FAIL.
+- Exception – if the document ID is not a string or if `id` and `_id` are both present in the document.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Counts the number of documents in the document store.
+
+**Returns:**
+
+- int – the number of documents in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns at most 1000 documents that match the filter.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – filters to apply.
+
+**Returns:**
+
+- list\[Document\] – matching documents.
+
+**Raises:**
+
+- AstraDocumentStoreFilterError – if the filter is invalid or not supported by this class.
+
+#### get_documents_by_id
+
+```python
+get_documents_by_id(ids: list[str]) -> list[Document]
+```
+
+Gets documents by their IDs.
+
+**Parameters:**
+
+- **ids** (list\[str\]) – the IDs of the documents to retrieve.
+
+**Returns:**
+
+- list\[Document\] – the matching documents.
+
+#### get_document_by_id
+
+```python
+get_document_by_id(document_id: str) -> Document
+```
+
+Gets a document by its ID.
+
+**Parameters:**
+
+- **document_id** (str) – the ID to filter by
+
+**Returns:**
+
+- Document – the found document
+
+**Raises:**
+
+- MissingDocumentError – if the document is not found
+
+#### search
+
+```python
+search(
+ query_embedding: list[float],
+ top_k: int,
+ filters: dict[str, Any] | None = None,
+) -> list[Document]
+```
+
+Perform a search for a list of queries.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – a list of query embeddings.
+- **top_k** (int) – the number of results to return.
+- **filters** (dict\[str, Any\] | None) – filters to apply during search.
+
+**Returns:**
+
+- list\[Document\] – matching documents.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – IDs of the documents to delete.
+
+**Raises:**
+
+- MissingDocumentError – if no document was deleted but document IDs were provided.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents from the document store.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to find documents to delete.
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+**Raises:**
+
+- AstraDocumentStoreFilterError – if the filter is invalid or not supported.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates documents that match the provided filters with the given metadata.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to find documents to update.
+- **meta** (dict\[str, Any\]) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+**Raises:**
+
+- AstraDocumentStoreFilterError – if the filter is invalid or not supported.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Applies a filter and counts the documents that matched it.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the document list.
+
+**Returns:**
+
+- int – The number of documents that match the filter.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Applies a filter selecting documents and counts the unique values for each meta field of the matched documents.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the document list.
+- **metadata_fields** (list\[str\]) – The metadata fields to count unique values for.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary where the keys are the metadata field names and the values are the count of unique
+ values.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the metadata fields and the corresponding types.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary mapping field names to dictionaries with a `type` key.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+For a given metadata field, find its max and min value.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to inspect.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with `min` and `max`.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a field matching a search term or all possible values if no search term is given.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to inspect.
+- **search_term** (str | None) – Optional case-insensitive substring search term.
+- **from\_** (int) – The starting index for pagination.
+- **size** (int) – The number of values to return.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple containing the paginated values and the total count.
+
+## haystack_integrations.document_stores.astra.errors
+
+### AstraDocumentStoreError
+
+Bases: DocumentStoreError
+
+Parent class for all AstraDocumentStore errors.
+
+### AstraDocumentStoreFilterError
+
+Bases: FilterError
+
+Raised when an invalid filter is passed to AstraDocumentStore.
+
+### AstraDocumentStoreConfigError
+
+Bases: AstraDocumentStoreError
+
+Raised when an invalid configuration is passed to AstraDocumentStore.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/azure_ai_search.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/azure_ai_search.md
new file mode 100644
index 0000000000..f08267a45d
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/azure_ai_search.md
@@ -0,0 +1,463 @@
+---
+title: "Azure AI Search"
+id: integrations-azure_ai_search
+description: "Azure AI Search integration for Haystack"
+slug: "/integrations-azure_ai_search"
+---
+
+
+## haystack_integrations.components.retrievers.azure_ai_search.embedding_retriever
+
+### AzureAISearchEmbeddingRetriever
+
+Retrieves documents from the AzureAISearchDocumentStore using a vector similarity metric.
+
+Must be connected to the AzureAISearchDocumentStore to run.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: AzureAISearchDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+ **kwargs: Any
+) -> None
+```
+
+Create the AzureAISearchEmbeddingRetriever component.
+
+**Parameters:**
+
+- **document_store** (AzureAISearchDocumentStore) – An instance of AzureAISearchDocumentStore to use with the Retriever.
+- **filters** (dict\[str, Any\] | None) – Filters applied when fetching documents from the Document Store.
+- **top_k** (int) – Maximum number of documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+- **kwargs** (Any) – Additional keyword arguments to pass to the Azure AI's search endpoint.
+ Some of the supported parameters:
+ - `query_type`: A string indicating the type of query to perform. Possible values are
+ 'simple','full' and 'semantic'.
+ - `semantic_configuration_name`: The name of semantic configuration to be used when
+ processing semantic queries.
+ For more information on parameters, see the
+ [official Azure AI Search documentation](https://learn.microsoft.com/en-us/azure/search/).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureAISearchEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AzureAISearchEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the AzureAISearchDocumentStore.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – A list of floats representing the query embedding.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See `__init__` method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to retrieve.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Dictionary with the following keys:
+- `documents`: A list of documents retrieved from the AzureAISearchDocumentStore.
+
+## haystack_integrations.document_stores.azure_ai_search.document_store
+
+### AzureAISearchDocumentStore
+
+Document store using [Azure AI Search](https://azure.microsoft.com/products/ai-services/ai-search/) as the backend.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var(
+ "AZURE_AI_SEARCH_API_KEY", strict=False
+ ),
+ azure_endpoint: Secret = Secret.from_env_var(
+ "AZURE_AI_SEARCH_ENDPOINT", strict=True
+ ),
+ index_name: str = "default",
+ embedding_dimension: int = 768,
+ metadata_fields: dict[str, SearchField | type] | None = None,
+ vector_search_configuration: VectorSearch | None = None,
+ include_search_metadata: bool = False,
+ azure_token_credential: TokenCredential | None = None,
+ **index_creation_kwargs: Any
+) -> None
+```
+
+Creates a new instance of AzureAISearchDocumentStore.
+
+**Parameters:**
+
+- **azure_endpoint** (Secret) – The URL endpoint of an Azure AI Search service.
+- **api_key** (Secret) – The API key to use for authentication.
+- **index_name** (str) – Name of index in Azure AI Search, if it doesn't exist it will be created.
+- **embedding_dimension** (int) – Dimension of the embeddings.
+- **metadata_fields** (dict\[str, SearchField | type\] | None) – A dictionary mapping metadata field names to their corresponding field definitions.
+ Each field can be defined either as:
+- A SearchField object to specify detailed field configuration like type, searchability, and filterability
+- A Python type (`str`, `bool`, `int`, `float`, or `datetime`) to create a simple filterable field
+
+These fields are automatically added when creating the search index.
+Example:
+
+```python
+metadata_fields={
+ "Title": SearchField(
+ name="Title",
+ type="Edm.String",
+ searchable=True,
+ filterable=True
+ ),
+ "Pages": int
+}
+```
+
+- **vector_search_configuration** (VectorSearch | None) – Configuration option related to vector search.
+ Default configuration uses the HNSW algorithm with cosine similarity to handle vector searches.
+- **include_search_metadata** (bool) – Whether to include Azure AI Search metadata fields
+ in the returned documents. When set to True, the `meta` field of the returned
+ documents will contain the @search.score, @search.reranker_score, @search.highlights,
+ @search.captions, and other fields returned by Azure AI Search.
+- **azure_token_credential** (TokenCredential | None) – An Azure `TokenCredential` instance used to authenticate requests.
+ When provided, this takes priority over `api_key`.
+- **index_creation_kwargs** (Any) – Optional keyword parameters to be passed to `SearchIndex` class
+ during index creation. Some of the supported parameters:
+ \- `semantic_search`: Defines semantic configuration of the search index. This parameter is needed
+ to enable semantic search capabilities in index.
+ \- `similarity`: The type of similarity algorithm to be used when scoring and ranking the documents
+ matching a search query. The similarity algorithm can only be defined at index creation time and
+ cannot be modified on existing indexes.
+
+For more information on parameters, see the [official Azure AI Search documentation](https://learn.microsoft.com/en-us/azure/search/).
+
+#### client
+
+```python
+client: SearchClient
+```
+
+Return the Azure SearchClient, creating the index if it does not exist.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureAISearchDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- AzureAISearchDocumentStore – Deserialized component.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the search index.
+
+**Returns:**
+
+- int – list of retrieved documents.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the count of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the document list.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Counts unique values for each specified metadata field in documents matching the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents.
+- **metadata_fields** (list\[str\]) – List of field names to count unique values for.
+
+**Returns:**
+
+- dict\[str, int\] – Dictionary mapping field names to counts of unique values.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the information about metadata fields in the index.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – Dictionary mapping field names to type information.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get the minimum and maximum values for.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the keys "min" and "max".
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a metadata field with optional search and pagination.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get unique values for.
+- **search_term** (str | None) – Optional search term to filter unique values.
+- **from\_** (int) – Starting offset for pagination.
+- **size** (int) – Number of values to return.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – Tuple of (list of unique values, total count of matching values).
+
+#### query_sql
+
+```python
+query_sql(query: str) -> Any
+```
+
+Executes an SQL query if supported by the document store backend.
+
+Azure AI Search does not support SQL queries.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes the provided documents to search index.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – documents to write to the index.
+- **policy** (DuplicatePolicy) – Policy to determine how duplicates are handled.
+
+**Returns:**
+
+- int – the number of documents added to index.
+
+**Raises:**
+
+- ValueError – If the documents are not of type Document.
+- TypeError – If the document ids are not strings.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with a matching document_ids from the search index.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – ids of the documents to be deleted.
+
+#### delete_all_documents
+
+```python
+delete_all_documents(recreate_index: bool = False) -> None
+```
+
+Deletes all documents in the document store.
+
+**Parameters:**
+
+- **recreate_index** (bool) – If True, the index will be deleted and recreated with the original schema.
+ If False, all documents will be deleted while preserving the index.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+Azure AI Search does not support server-side delete by query, so this method
+first searches for matching documents, then deletes them in a batch operation.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the fields of all documents that match the provided filters.
+
+Azure AI Search does not support server-side update by query, so this method
+first searches for matching documents, then updates them using merge operations.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The fields to update. These fields must exist in the index schema.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### get_documents_by_id
+
+```python
+get_documents_by_id(document_ids: list[str]) -> list[Document]
+```
+
+Retrieves documents by their IDs.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – IDs of the documents to retrieve.
+
+**Returns:**
+
+- list\[Document\] – List of documents with the given IDs.
+
+#### search_documents
+
+```python
+search_documents(search_text: str = '*', top_k: int = 10) -> list[Document]
+```
+
+Returns all documents that match the provided search_text.
+
+If search_text is None, returns all documents.
+
+**Parameters:**
+
+- **search_text** (str) – the text to search for in the Document list.
+- **top_k** (int) – Maximum number of documents to return.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given search_text.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the provided filters.
+
+Filters should be given as a dictionary supporting filtering by metadata. For details on
+filters, see the [metadata filtering documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – the filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+## haystack_integrations.document_stores.azure_ai_search.filters
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/azure_doc_intelligence.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/azure_doc_intelligence.md
new file mode 100644
index 0000000000..ee246b66ac
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/azure_doc_intelligence.md
@@ -0,0 +1,155 @@
+---
+title: "Azure Document Intelligence"
+id: integrations-azure_doc_intelligence
+description: "Azure Document Intelligence integration for Haystack"
+slug: "/integrations-azure_doc_intelligence"
+---
+
+
+
+## Module haystack\_integrations.components.converters.azure\_doc\_intelligence.converter
+
+
+
+### AzureDocumentIntelligenceConverter
+
+Converts files to Documents using Azure's Document Intelligence service.
+
+This component uses the azure-ai-documentintelligence package (v1.0.0+) and outputs
+GitHub Flavored Markdown for better integration with LLM/RAG applications.
+
+Supported file formats: PDF, JPEG, PNG, BMP, TIFF, DOCX, XLSX, PPTX, HTML.
+
+Key features:
+- Markdown output with preserved structure (headings, tables, lists)
+- Inline table integration (tables rendered as markdown tables)
+- Improved layout analysis and reading order
+- Support for section headings
+
+To use this component, you need an active Azure account
+and a Document Intelligence or Cognitive Services resource. For setup instructions, see
+[Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/quickstarts/get-started-sdks-rest-api).
+
+### Usage example
+
+```python
+import os
+from haystack_integrations.components.converters.azure_doc_intelligence import (
+ AzureDocumentIntelligenceConverter,
+)
+from haystack.utils import Secret
+
+converter = AzureDocumentIntelligenceConverter(
+ endpoint=os.environ["AZURE_DI_ENDPOINT"],
+ api_key=Secret.from_env_var("AZURE_DI_API_KEY"),
+)
+
+results = converter.run(sources=["invoice.pdf", "contract.docx"])
+documents = results["documents"]
+
+# Documents contain markdown with inline tables
+print(documents[0].content)
+```
+
+
+
+#### AzureDocumentIntelligenceConverter.\_\_init\_\_
+
+```python
+def __init__(endpoint: str,
+ *,
+ api_key: Secret = Secret.from_env_var("AZURE_DI_API_KEY"),
+ model_id: str = "prebuilt-document",
+ store_full_path: bool = False)
+```
+
+Creates an AzureDocumentIntelligenceConverter component.
+
+**Arguments**:
+
+- `endpoint`: The endpoint URL of your Azure Document Intelligence resource.
+Example: "https://YOUR_RESOURCE.cognitiveservices.azure.com/"
+- `api_key`: API key for Azure authentication. Can use Secret.from_env_var()
+to load from AZURE_DI_API_KEY environment variable.
+- `model_id`: Azure model to use for analysis. Options:
+- "prebuilt-document": General document analysis (default)
+- "prebuilt-read": Fast OCR for text extraction
+- "prebuilt-layout": Enhanced layout analysis with better table/structure detection
+- Custom model IDs from your Azure resource
+- `store_full_path`: If True, stores complete file path in metadata.
+If False, stores only the filename (default).
+
+
+
+#### AzureDocumentIntelligenceConverter.warm\_up
+
+```python
+def warm_up()
+```
+
+Initializes the Azure Document Intelligence client.
+
+
+
+#### AzureDocumentIntelligenceConverter.run
+
+```python
+@component.output_types(documents=list[Document],
+ raw_azure_response=list[dict])
+def run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, list[Document] | list[dict]]
+```
+
+Convert a list of files to Documents using Azure's Document Intelligence service.
+
+**Arguments**:
+
+- `sources`: List of file paths or ByteStream objects.
+- `meta`: Optional metadata to attach to the Documents.
+This value can be either a list of dictionaries or a single dictionary.
+If it's a single dictionary, its content is added to the metadata of all produced Documents.
+If it's a list, the length of the list must match the number of sources, because the two lists will be
+zipped. If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `documents`: List of created Documents
+- `raw_azure_response`: List of raw Azure responses used to create the Documents
+
+
+
+#### AzureDocumentIntelligenceConverter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### AzureDocumentIntelligenceConverter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str,
+ Any]) -> "AzureDocumentIntelligenceConverter"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/brave.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/brave.md
new file mode 100644
index 0000000000..c81cf38f0a
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/brave.md
@@ -0,0 +1,96 @@
+---
+title: "Brave Search"
+id: integrations-brave
+description: "Brave Search integration for Haystack"
+slug: "/integrations-brave"
+---
+
+
+## haystack_integrations.components.websearch.brave.brave_websearch
+
+### BraveWebSearch
+
+A component that uses the Brave Search API to search the web and return results as Haystack Documents.
+
+You need a Brave Search API key from [brave.com/search/api](https://brave.com/search/api/).
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.brave import BraveWebSearch
+from haystack.utils import Secret
+
+websearch = BraveWebSearch(
+ api_key=Secret.from_env_var("BRAVE_API_KEY"),
+ top_k=5,
+)
+result = websearch.run(query="What is Haystack by deepset?")
+documents = result["documents"]
+links = result["links"]
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("BRAVE_API_KEY"),
+ top_k: int | None = 10,
+ country: str | None = None,
+ search_lang: str | None = None,
+ extra_params: dict[str, Any] | None = None,
+ timeout: int = 10,
+ max_retries: int = 3,
+) -> None
+```
+
+Initialize the BraveWebSearch component.
+
+**Parameters:**
+
+- **api_key** (Secret) – Brave Search API key. Defaults to the `BRAVE_API_KEY` environment variable.
+- **top_k** (int | None) – Maximum number of results to return. Maps to the `count` parameter in the Brave API.
+- **country** (str | None) – 2-letter country code to bias search results (e.g. `"US"`, `"DE"`).
+- **search_lang** (str | None) – Language code for search results (e.g. `"en"`, `"de"`).
+- **extra_params** (dict\[str, Any\] | None) – Additional query parameters passed directly to the Brave Search API.
+- **timeout** (int) – Timeout in seconds for the HTTP request. Defaults to 10.
+- **max_retries** (int) – Maximum number of retry attempts on transient failures. Defaults to 3.
+
+#### run
+
+```python
+run(query: str, top_k: int | None = None) -> dict[str, Any]
+```
+
+Search the web using Brave Search and return results as Documents.
+
+**Parameters:**
+
+- **query** (str) – Search query string.
+- **top_k** (int | None) – Optional per-run override of the maximum number of results.
+ If not provided, the init-time `top_k` is used.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with:
+- `documents`: List of Documents containing search result content.
+- `links`: List of URLs from the search results.
+
+#### run_async
+
+```python
+run_async(query: str, top_k: int | None = None) -> dict[str, Any]
+```
+
+Asynchronously search the web using Brave Search and return results as Documents.
+
+**Parameters:**
+
+- **query** (str) – Search query string.
+- **top_k** (int | None) – Optional per-run override of the maximum number of results.
+ If not provided, the init-time `top_k` is used.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with:
+- `documents`: List of Documents containing search result content.
+- `links`: List of URLs from the search results.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/chonkie.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/chonkie.md
new file mode 100644
index 0000000000..6067dc53c9
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/chonkie.md
@@ -0,0 +1,394 @@
+---
+title: "Chonkie"
+id: integrations-chonkie
+description: "Chonkie integration for Haystack"
+slug: "/integrations-chonkie"
+---
+
+
+## haystack_integrations.components.preprocessors.chonkie.recursive_splitter
+
+### ChonkieRecursiveDocumentSplitter
+
+A Document Splitter that uses Chonkie's RecursiveChunker to split documents.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.chonkie import ChonkieRecursiveDocumentSplitter
+
+chunker = ChonkieRecursiveDocumentSplitter(chunk_size=512)
+documents = [Document(content="Hello world. This is a test.")]
+result = chunker.run(documents=documents)
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ tokenizer: str = "character",
+ chunk_size: int = 2048,
+ min_characters_per_chunk: int = 24,
+ rules: RecursiveRules | dict[str, Any] | None = None,
+ skip_empty_documents: bool = True,
+ page_break_character: str = "\x0c"
+) -> None
+```
+
+Initializes the ChonkieRecursiveDocumentSplitter.
+
+**Parameters:**
+
+- **tokenizer** (str) – The tokenizer to use for chunking. Defaults to "character".
+ Common options include "character", "gpt2", and "cl100k_base".
+ See the [Chonkie documentation](https://docs.chonkie.ai/) for more information on available tokenizers.
+- **chunk_size** (int) – The maximum number of tokens per chunk. The actual length depends on the chosen tokenizer.
+- **min_characters_per_chunk** (int) – The minimum number of characters per chunk.
+- **rules** (RecursiveRules | dict\[str, Any\] | None) – Custom rules for recursive chunking. If None, default rules are used.
+ See the [Chonkie documentation](https://docs.chonkie.ai/) for more information.
+- **skip_empty_documents** (bool) – Whether to skip empty documents.
+- **page_break_character** (str) – The character to use for page breaks.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Splits a list of documents into smaller chunks.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The list of documents to split.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the "documents" key containing the list of chunks.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChonkieRecursiveDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ChonkieRecursiveDocumentSplitter – Deserialized component.
+
+## haystack_integrations.components.preprocessors.chonkie.semantic_splitter
+
+### ChonkieSemanticDocumentSplitter
+
+A Document Splitter that uses Chonkie's SemanticChunker to split documents.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.chonkie import ChonkieSemanticDocumentSplitter
+
+chunker = ChonkieSemanticDocumentSplitter(chunk_size=512)
+documents = [Document(content="Hello world. This is a test.")]
+result = chunker.run(documents=documents)
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ embedding_model: Any = "minishlab/potion-base-32M",
+ threshold: float = 0.8,
+ chunk_size: int = 2048,
+ similarity_window: int = 3,
+ min_sentences_per_chunk: int = 1,
+ min_characters_per_sentence: int = 24,
+ delim: Any = None,
+ include_delim: str = "prev",
+ skip_window: int = 0,
+ filter_window: int = 5,
+ filter_polyorder: int = 3,
+ filter_tolerance: float = 0.2,
+ skip_empty_documents: bool = True,
+ page_break_character: str = "\x0c"
+) -> None
+```
+
+Initializes the ChonkieSemanticDocumentSplitter.
+
+**Parameters:**
+
+- **embedding_model** (Any) – The embedding model to use for semantic similarity.
+ See the [Chonkie documentation](https://docs.chonkie.ai/) for more information on supported models.
+- **threshold** (float) – The semantic similarity threshold.
+- **chunk_size** (int) – The maximum number of tokens per chunk. The actual length depends on the
+ embedding model's tokenizer.
+- **similarity_window** (int) – The window size for similarity calculations.
+- **min_sentences_per_chunk** (int) – The minimum number of sentences per chunk.
+- **min_characters_per_sentence** (int) – The minimum number of characters per sentence.
+- **delim** (Any) – Delimiters to use for splitting. If None, default delimiters are used.
+- **include_delim** (str) – Whether to include the delimiter in the chunks.
+- **skip_window** (int) – The skip window for similarity calculations.
+- **filter_window** (int) – The filter window for similarity calculations.
+- **filter_polyorder** (int) – The polynomial order for similarity filtering.
+- **filter_tolerance** (float) – The tolerance for similarity filtering.
+- **skip_empty_documents** (bool) – Whether to skip empty documents.
+- **page_break_character** (str) – The character to use for page breaks.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component by loading the embedding model.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Splits a list of documents into smaller semantic chunks.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The list of documents to split.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the "documents" key containing the list of chunks.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChonkieSemanticDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ChonkieSemanticDocumentSplitter – Deserialized component.
+
+## haystack_integrations.components.preprocessors.chonkie.sentence_splitter
+
+### ChonkieSentenceDocumentSplitter
+
+A Document Splitter that uses Chonkie's SentenceChunker to split documents.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.chonkie import ChonkieSentenceDocumentSplitter
+
+chunker = ChonkieSentenceDocumentSplitter(chunk_size=512)
+documents = [Document(content="Hello world. This is a test.")]
+result = chunker.run(documents=documents)
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ tokenizer: str = "character",
+ chunk_size: int = 2048,
+ chunk_overlap: int = 0,
+ min_sentences_per_chunk: int = 1,
+ min_characters_per_sentence: int = 12,
+ approximate: bool = False,
+ delim: Any = None,
+ include_delim: str = "prev",
+ skip_empty_documents: bool = True,
+ page_break_character: str = "\x0c"
+) -> None
+```
+
+Initializes the ChonkieSentenceDocumentSplitter.
+
+**Parameters:**
+
+- **tokenizer** (str) – The tokenizer to use for chunking. Defaults to "character".
+ Common options include "character", "gpt2", and "cl100k_base".
+ See the [Chonkie documentation](https://docs.chonkie.ai/) for more information on available tokenizers.
+- **chunk_size** (int) – The maximum number of tokens per chunk. The actual length depends on the chosen tokenizer.
+- **chunk_overlap** (int) – The overlap between consecutive chunks.
+- **min_sentences_per_chunk** (int) – The minimum number of sentences per chunk.
+- **min_characters_per_sentence** (int) – The minimum number of characters per sentence.
+- **approximate** (bool) – Whether to use approximate chunking.
+- **delim** (Any) – Delimiters to use for splitting. If None, default delimiters are used.
+- **include_delim** (str) – Whether to include the delimiter in the chunks ("prev" or "next").
+- **skip_empty_documents** (bool) – Whether to skip empty documents.
+- **page_break_character** (str) – The character to use for page breaks.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Splits a list of documents into smaller sentence-based chunks.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The list of documents to split.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the "documents" key containing the list of chunks.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChonkieSentenceDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ChonkieSentenceDocumentSplitter – Deserialized component.
+
+## haystack_integrations.components.preprocessors.chonkie.token_splitter
+
+### ChonkieTokenDocumentSplitter
+
+A Document Splitter that uses Chonkie's TokenChunker to split documents.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.chonkie import ChonkieTokenDocumentSplitter
+
+chunker = ChonkieTokenDocumentSplitter(chunk_size=512, chunk_overlap=50)
+documents = [Document(content="Hello world. This is a test.")]
+result = chunker.run(documents=documents)
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ tokenizer: str = "character",
+ chunk_size: int = 2048,
+ chunk_overlap: int = 0,
+ skip_empty_documents: bool = True,
+ page_break_character: str = "\x0c"
+) -> None
+```
+
+Initializes the ChonkieTokenDocumentSplitter.
+
+**Parameters:**
+
+- **tokenizer** (str) – The tokenizer to use for chunking. Defaults to "character".
+ Common options include "character", "gpt2", and "cl100k_base".
+ See the [Chonkie documentation](https://docs.chonkie.ai/) for more information on available tokenizers.
+- **chunk_size** (int) – The maximum number of tokens per chunk. The actual length depends on the chosen tokenizer.
+- **chunk_overlap** (int) – The overlap between consecutive chunks.
+- **skip_empty_documents** (bool) – Whether to skip empty documents.
+- **page_break_character** (str) – The character to use for page breaks.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Splits a list of documents into smaller token-based chunks.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The list of documents to split.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the "documents" key containing the list of chunks.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChonkieTokenDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ChonkieTokenDocumentSplitter – Deserialized component.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/chroma.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/chroma.md
new file mode 100644
index 0000000000..81a8db88c7
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/chroma.md
@@ -0,0 +1,986 @@
+---
+title: "Chroma"
+id: integrations-chroma
+description: "Chroma integration for Haystack"
+slug: "/integrations-chroma"
+---
+
+
+## haystack_integrations.components.retrievers.chroma.retriever
+
+### ChromaQueryTextRetriever
+
+A component for retrieving documents from a [Chroma database](https://docs.trychroma.com/) using the `query` API.
+
+Example usage:
+
+```python
+from haystack import Pipeline
+from haystack.components.converters import TextFileToDocument
+from haystack.components.writers import DocumentWriter
+
+from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+from haystack_integrations.components.retrievers.chroma import ChromaQueryTextRetriever
+
+file_paths = ...
+
+# Chroma is used in-memory so we use the same instances in the two pipelines below
+document_store = ChromaDocumentStore()
+
+indexing = Pipeline()
+indexing.add_component("converter", TextFileToDocument())
+indexing.add_component("writer", DocumentWriter(document_store))
+indexing.connect("converter", "writer")
+indexing.run({"converter": {"sources": file_paths}})
+
+querying = Pipeline()
+querying.add_component("retriever", ChromaQueryTextRetriever(document_store))
+results = querying.run({"retriever": {"query": "Variable declarations", "top_k": 3}})
+
+for d in results["retriever"]["documents"]:
+ print(d.meta, d.score)
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: ChromaDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Initialize the ChromaQueryTextRetriever.
+
+**Parameters:**
+
+- **document_store** (ChromaDocumentStore) – an instance of `ChromaDocumentStore`.
+- **filters** (dict\[str, Any\] | None) – filters to narrow down the search space.
+- **top_k** (int) – the maximum number of documents to retrieve.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+#### run
+
+```python
+run(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, Any]
+```
+
+Run the retriever on the given input data.
+
+**Parameters:**
+
+- **query** (str) – The input data for the retriever. In this case, a plain-text query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to retrieve.
+ If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+**Raises:**
+
+- ValueError – If the specified document store is not found or is not a MemoryDocumentStore instance.
+
+#### run_async
+
+```python
+run_async(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously run the retriever on the given input data.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **query** (str) – The input data for the retriever. In this case, a plain-text query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to retrieve.
+ If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+**Raises:**
+
+- ValueError – If the specified document store is not found or is not a MemoryDocumentStore instance.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChromaQueryTextRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ChromaQueryTextRetriever – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+### ChromaEmbeddingRetriever
+
+A component for retrieving documents from a [Chroma database](https://docs.trychroma.com/) using embeddings.
+
+#### __init__
+
+```python
+__init__(
+ document_store: ChromaDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Initialize the ChromaEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (ChromaDocumentStore) – an instance of `ChromaDocumentStore`.
+- **filters** (dict\[str, Any\] | None) – filters to narrow down the search space.
+- **top_k** (int) – the maximum number of documents to retrieve.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, Any]
+```
+
+Run the retriever on the given input data.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – the query embeddings.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – the maximum number of documents to retrieve.
+ If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- dict\[str, Any\] – a dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, Any]
+```
+
+Asynchronously run the retriever on the given input data.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – the query embeddings.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – the maximum number of documents to retrieve.
+ If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- dict\[str, Any\] – a dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChromaEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ChromaEmbeddingRetriever – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+## haystack_integrations.document_stores.chroma.document_store
+
+### ChromaDocumentStore
+
+A document store using [Chroma](https://docs.trychroma.com/) as the backend.
+
+We use the `collection.get` API to implement the document store protocol,
+the `collection.search` API will be used in the retriever instead.
+
+#### __init__
+
+```python
+__init__(
+ collection_name: str = "documents",
+ embedding_function: str = "default",
+ persist_path: str | None = None,
+ host: str | None = None,
+ port: int | None = None,
+ distance_function: Literal["l2", "cosine", "ip"] = "l2",
+ metadata: dict | None = None,
+ client_settings: dict[str, Any] | None = None,
+ **embedding_function_params: Any
+) -> None
+```
+
+Creates a new ChromaDocumentStore instance.
+
+It is meant to be connected to a Chroma collection.
+
+Note: for the component to be part of a serializable pipeline, the __init__
+parameters must be serializable, reason why we use a registry to configure the
+embedding function passing a string.
+
+**Parameters:**
+
+- **collection_name** (str) – the name of the collection to use in the database.
+- **embedding_function** (str) – the name of the embedding function to use to embed the query
+- **persist_path** (str | None) – Path for local persistent storage. Cannot be used in combination with `host` and `port`.
+ If none of `persist_path`, `host`, and `port` is specified, the database will be `in-memory`.
+- **host** (str | None) – The host address for the remote Chroma HTTP client connection. Cannot be used with `persist_path`.
+- **port** (int | None) – The port number for the remote Chroma HTTP client connection. Cannot be used with `persist_path`.
+- **distance_function** (Literal['l2', 'cosine', 'ip']) – The distance metric for the embedding space.
+- `"l2"` computes the Euclidean (straight-line) distance between vectors,
+ where smaller scores indicate more similarity.
+- `"cosine"` computes the cosine similarity between vectors,
+ with higher scores indicating greater similarity.
+- `"ip"` stands for inner product, where higher scores indicate greater similarity between vectors.
+ **Note**: `distance_function` can only be set during the creation of a collection.
+ To change the distance metric of an existing collection, consider cloning the collection.
+- **metadata** (dict | None) – a dictionary of chromadb collection parameters passed directly to chromadb's client
+ method `create_collection`. If it contains the key `"hnsw:space"`, the value will take precedence over the
+ `distance_function` parameter above.
+- **client_settings** (dict\[str, Any\] | None) – a dictionary of Chroma Settings configuration options passed to
+ `chromadb.config.Settings`. These settings configure the underlying Chroma client behavior.
+ For available options, see [Chroma's config.py](https://github.com/chroma-core/chroma/blob/main/chromadb/config.py).
+ **Note**: specifying these settings may interfere with standard client initialization parameters.
+ This option is intended for advanced customization.
+- **embedding_function_params** (Any) – additional parameters to pass to the embedding function.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – how many documents are present in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns how many documents are present in the document store.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Returns:**
+
+- int – how many documents are present in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – the filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – a list of Documents that match the given filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+Asynchronous methods are only supported for HTTP connections.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – the filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – a list of Documents that match the given filters.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents into the store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to write into the document store.
+- **policy** (DuplicatePolicy) – How to handle documents whose `id` already exists in the store:
+- `NONE` (default): treated as `FAIL`.
+- `OVERWRITE`: replace the existing document.
+- `SKIP`: keep the existing document and skip the new one.
+- `FAIL`: raise `DuplicateDocumentError`.
+
+**Returns:**
+
+- int – The number of documents written.
+
+**Raises:**
+
+- ValueError – When input is not valid.
+- DuplicateDocumentError – When `policy` is `FAIL` (or `NONE`) and any document `id` already exists.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously writes documents into the store.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to write into the document store.
+- **policy** (DuplicatePolicy) – How to handle documents whose `id` already exists in the store:
+- `NONE` (default): treated as `FAIL`.
+- `OVERWRITE`: replace the existing document.
+- `SKIP`: keep the existing document and skip the new one.
+- `FAIL`: raise `DuplicateDocumentError`.
+
+**Returns:**
+
+- int – The number of documents written.
+
+**Raises:**
+
+- ValueError – When input is not valid.
+- DuplicateDocumentError – When `policy` is `FAIL` (or `NONE`) and any document `id` already exists.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with a matching document_ids from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes all documents with a matching document_ids from the document store.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Note**: This operation is not atomic. Documents matching the filter are fetched first,
+then updated. If documents are modified between the fetch and update operations,
+those changes may be lost.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Note**: This operation is not atomic. Documents matching the filter are fetched first,
+then updated. If documents are modified between the fetch and update operations,
+those changes may be lost.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### delete_all_documents
+
+```python
+delete_all_documents(*, recreate_index: bool = False) -> None
+```
+
+Deletes all documents in the document store.
+
+A fast way to clear all documents from the document store while preserving any collection settings and mappings.
+
+**Parameters:**
+
+- **recreate_index** (bool) – Whether to recreate the index after deleting all documents.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async(*, recreate_index: bool = False) -> None
+```
+
+Asynchronously deletes all documents in the document store.
+
+A fast way to clear all documents from the document store while preserving any collection settings and mappings.
+
+**Parameters:**
+
+- **recreate_index** (bool) – Whether to recreate the index after deleting all documents.
+
+#### search
+
+```python
+search(
+ queries: list[str], top_k: int, filters: dict[str, Any] | None = None
+) -> list[list[Document]]
+```
+
+Search the documents in the store using the provided text queries.
+
+**Parameters:**
+
+- **queries** (list\[str\]) – the list of queries to search for.
+- **top_k** (int) – top_k documents to return for each query.
+- **filters** (dict\[str, Any\] | None) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- list\[list\[Document\]\] – matching documents for each query.
+
+#### search_async
+
+```python
+search_async(
+ queries: list[str], top_k: int, filters: dict[str, Any] | None = None
+) -> list[list[Document]]
+```
+
+Asynchronously search the documents in the store using the provided text queries.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **queries** (list\[str\]) – the list of queries to search for.
+- **top_k** (int) – top_k documents to return for each query.
+- **filters** (dict\[str, Any\] | None) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- list\[list\[Document\]\] – matching documents for each query.
+
+#### search_embeddings
+
+```python
+search_embeddings(
+ query_embeddings: list[list[float]],
+ top_k: int,
+ filters: dict[str, Any] | None = None,
+) -> list[list[Document]]
+```
+
+Perform vector search on the stored document, pass the embeddings of the queries instead of their text.
+
+**Parameters:**
+
+- **query_embeddings** (list\[list\[float\]\]) – a list of embeddings to use as queries.
+- **top_k** (int) – the maximum number of documents to retrieve.
+- **filters** (dict\[str, Any\] | None) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- list\[list\[Document\]\] – a list of lists of documents that match the given filters.
+
+#### search_embeddings_async
+
+```python
+search_embeddings_async(
+ query_embeddings: list[list[float]],
+ top_k: int,
+ filters: dict[str, Any] | None = None,
+) -> list[list[Document]]
+```
+
+Asynchronously perform vector search using query embeddings instead of text.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **query_embeddings** (list\[list\[float\]\]) – a list of embeddings to use as queries.
+- **top_k** (int) – the maximum number of documents to retrieve.
+- **filters** (dict\[str, Any\] | None) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- list\[list\[Document\]\] – a list of lists of documents that match the given filters.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the number of documents that match the provided filters.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Return unique value counts for metadata fields of documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of field names to calculate unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each metadata field name to the count of
+ its unique values among the filtered documents.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously return unique value counts for metadata fields of documents matching the provided filters.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of field names to calculate unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each metadata field name to the count of
+ its unique values among the filtered documents.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns information about the metadata fields in the collection.
+
+Since ChromaDB doesn't maintain a schema, this method samples documents
+to infer field types.
+
+If we populated the collection with documents like:
+
+```python
+Document(content="Doc 1", meta={"category": "A", "status": "active", "priority": 1})
+Document(content="Doc 2", meta={"category": "B", "status": "inactive"})
+```
+
+This method would return:
+
+```python
+{
+ 'category': {'type': 'keyword'},
+ 'status': {'type': 'keyword'},
+ 'priority': {'type': 'long'},
+}
+```
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – Dictionary mapping field names to their type information.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns information about the metadata fields in the collection.
+
+Asynchronous methods are only supported for HTTP connections.
+
+Since ChromaDB doesn't maintain a schema, this method samples documents
+to infer field types.
+
+If we populated the collection with documents like:
+
+```python
+Document(content="Doc 1", meta={"category": "A", "status": "active", "priority": 1})
+Document(content="Doc 2", meta={"category": "B", "status": "inactive"})
+```
+
+This method would return:
+
+```python
+{
+ 'category': {'type': 'keyword'},
+ 'status': {'type': 'keyword'},
+ 'priority': {'type': 'long'},
+}
+```
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – Dictionary mapping field names to their type information.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get the minimum and maximum values for.
+ Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the keys "min" and "max", where each value is
+ the minimum or maximum value of the metadata field across all documents.
+ Returns:
+
+```python
+ {"min": None, "max": None}
+```
+
+if field doesn't exist or has no values.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously returns the minimum and maximum values for the given metadata field.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get the minimum and maximum values for.
+ Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the keys "min" and "max", where each value is
+ the minimum or maximum value of the metadata field across all documents.
+ Returns:
+
+```python
+ {"min": None, "max": None}
+```
+
+if field doesn't exist or has no values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Return unique metadata field values, optionally filtered by a content search term, with pagination.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get unique values for.
+ Can include or omit the "meta." prefix.
+- **search_term** (str | None) – Optional search term to filter documents by matching
+ in the content field.
+- **from\_** (int) – The offset to start returning values from (for pagination).
+- **size** (int) – The maximum number of unique values to return.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple containing list of unique values and total count of unique values.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously return unique metadata field values, optionally filtered by content, with pagination.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get unique values for.
+ Can include or omit the "meta." prefix.
+- **search_term** (str | None) – Optional search term to filter documents by matching
+ in the content field.
+- **from\_** (int) – The offset to start returning values from (for pagination).
+- **size** (int) – The maximum number of unique values to return.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple containing list of unique values and total count of unique values.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChromaDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ChromaDocumentStore – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+## haystack_integrations.document_stores.chroma.errors
+
+### ChromaDocumentStoreError
+
+Bases: DocumentStoreError
+
+Parent class for all ChromaDocumentStore exceptions.
+
+### ChromaDocumentStoreFilterError
+
+Bases: FilterError, ValueError
+
+Raised when a filter is not valid for a ChromaDocumentStore.
+
+### ChromaDocumentStoreConfigError
+
+Bases: ChromaDocumentStoreError
+
+Raised when a configuration is not valid for a ChromaDocumentStore.
+
+## haystack_integrations.document_stores.chroma.utils
+
+### get_embedding_function
+
+```python
+get_embedding_function(function_name: str, **kwargs: Any) -> EmbeddingFunction
+```
+
+Load an embedding function by name.
+
+**Parameters:**
+
+- **function_name** (str) – the name of the embedding function.
+- **kwargs** (Any) – additional arguments to pass to the embedding function.
+
+**Returns:**
+
+- EmbeddingFunction – the loaded embedding function.
+
+**Raises:**
+
+- ChromaDocumentStoreConfigError – if the function name is invalid.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/cohere.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/cohere.md
new file mode 100644
index 0000000000..a0e56d9faa
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/cohere.md
@@ -0,0 +1,1021 @@
+---
+title: "Cohere"
+id: integrations-cohere
+description: "Cohere integration for Haystack"
+slug: "/integrations-cohere"
+---
+
+
+## haystack_integrations.components.embedders.cohere.document_embedder
+
+### CohereDocumentEmbedder
+
+A component for computing Document embeddings using Cohere models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.cohere import CohereDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = CohereDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [-0.453125, 1.2236328, 2.0058594, ...]
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "embed-v4.0",
+ "embed-english-v3.0",
+ "embed-english-light-v3.0",
+ "embed-multilingual-v3.0",
+ "embed-multilingual-light-v3.0",
+]
+
+```
+
+A non-exhaustive list of embed models supported by this component.
+See https://docs.cohere.com/docs/models#embed for the full list.
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var(["COHERE_API_KEY", "CO_API_KEY"]),
+ model: str = "embed-v4.0",
+ input_type: str = "search_document",
+ api_base_url: str = "https://api.cohere.com",
+ truncate: str = "END",
+ timeout: float = 120.0,
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ embedding_type: EmbeddingTypes | None = None,
+) -> None
+```
+
+Initialize the CohereDocumentEmbedder.
+
+**Parameters:**
+
+- **api_key** (Secret) – the Cohere API key.
+- **model** (str) – the name of the model to use.
+ Read [Cohere documentation](https://docs.cohere.com/docs/models#embed) for a list of all supported models.
+- **input_type** (str) – specifies the type of input you're giving to the model. Supported values are
+ "search_document", "search_query", "classification" and "clustering".
+- **api_base_url** (str) – the Cohere API Base url.
+- **truncate** (str) – truncate embeddings that are too long from start or end, ("NONE"|"START"|"END").
+ Passing "START" will discard the start of the input. "END" will discard the end of the input. In both
+ cases, input is discarded until the remaining input is exactly the maximum input token length for the model.
+ If "NONE" is selected, when the input exceeds the maximum input token length an error will be returned.
+- **timeout** (float) – request timeout in seconds.
+- **batch_size** (int) – number of Documents to encode at once.
+- **progress_bar** (bool) – whether to show a progress bar or not. Can be helpful to disable in production deployments
+ to keep the logs clean.
+- **meta_fields_to_embed** (list\[str\] | None) – list of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (str) – separator used to concatenate the meta fields to the Document text.
+- **embedding_type** (EmbeddingTypes | None) – the type of embeddings to return. Defaults to float embeddings.
+ Note that int8, uint8, binary, and ubinary are only valid for v3 models.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CohereDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- CohereDocumentEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Embed a list of `Documents`.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with the following keys:
+- `documents`: documents with the `embedding` field set.
+- `meta`: metadata about the embedding process.
+
+**Raises:**
+
+- TypeError – if the input is not a list of `Documents`.
+
+#### run_async
+
+```python
+run_async(
+ documents: list[Document],
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Embed a list of `Documents` asynchronously.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with the following keys:
+- `documents`: documents with the `embedding` field set.
+- `meta`: metadata about the embedding process.
+
+**Raises:**
+
+- TypeError – if the input is not a list of `Documents`.
+
+## haystack_integrations.components.embedders.cohere.document_image_embedder
+
+### CohereDocumentImageEmbedder
+
+A component for computing Document embeddings based on images using Cohere models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.cohere import CohereDocumentImageEmbedder
+
+embedder = CohereDocumentImageEmbedder(model="embed-v4.0")
+
+documents = [
+ Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
+ Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}),
+]
+
+result = embedder.run(documents=documents)
+documents_with_embeddings = result["documents"]
+print(documents_with_embeddings)
+
+# [Document(id=...,
+# content='A photo of a cat',
+# meta={'file_path': 'cat.jpg',
+# 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}},
+# embedding=vector of size 1536),
+# ...]
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "embed-v4.0",
+ "embed-english-v3.0",
+ "embed-english-light-v3.0",
+ "embed-multilingual-v3.0",
+ "embed-multilingual-light-v3.0",
+]
+
+```
+
+A non-exhaustive list of embed models supported by this component.
+See https://docs.cohere.com/docs/models#embed for the full list.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ file_path_meta_field: str = "file_path",
+ root_path: str | None = None,
+ image_size: tuple[int, int] | None = None,
+ api_key: Secret = Secret.from_env_var(["COHERE_API_KEY", "CO_API_KEY"]),
+ model: str = "embed-v4.0",
+ api_base_url: str = "https://api.cohere.com",
+ timeout: float = 120.0,
+ embedding_dimension: int | None = None,
+ embedding_type: EmbeddingTypes = EmbeddingTypes.FLOAT,
+ progress_bar: bool = True
+) -> None
+```
+
+Creates a CohereDocumentImageEmbedder component.
+
+**Parameters:**
+
+- **file_path_meta_field** (str) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (str | None) – The root directory path where document files are located. If provided, file paths in
+ document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **image_size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+ when working with models that have resolution constraints or when transmitting images to remote services.
+- **api_key** (Secret) – The Cohere API key.
+- **model** (str) – The Cohere model to use for calculating embeddings.
+ Read [Cohere documentation](https://docs.cohere.com/docs/models#embed) for a list of all supported models.
+- **api_base_url** (str) – The Cohere API base URL.
+- **timeout** (float) – Request timeout in seconds.
+- **embedding_dimension** (int | None) – The dimension of the embeddings to return. Only valid for v4 and newer models.
+ Read [Cohere API reference](https://docs.cohere.com/reference/embed) for a list possible values and
+ supported models.
+- **embedding_type** (EmbeddingTypes) – The type of embeddings to return. Defaults to float embeddings.
+ Specifying a type different from float is only supported for Embed v3.0 and newer models.
+- **progress_bar** (bool) – Whether to show a progress bar or not. Can be helpful to disable in production deployments
+ to keep the logs clean.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CohereDocumentImageEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- CohereDocumentImageEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of image documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Documents with embeddings.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Asynchronously embed a list of image documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Documents with embeddings.
+
+## haystack_integrations.components.embedders.cohere.text_embedder
+
+### CohereTextEmbedder
+
+A component for embedding strings using Cohere models.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.cohere import CohereTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = CohereTextEmbedder()
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [-0.453125, 1.2236328, 2.0058594, ...]
+# 'meta': {'api_version': {'version': '1'}, 'billed_units': {'input_tokens': 4}}}
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "embed-v4.0",
+ "embed-english-v3.0",
+ "embed-english-light-v3.0",
+ "embed-multilingual-v3.0",
+ "embed-multilingual-light-v3.0",
+]
+
+```
+
+A non-exhaustive list of embed models supported by this component.
+See https://docs.cohere.com/docs/models#embed for the full list.
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var(["COHERE_API_KEY", "CO_API_KEY"]),
+ model: str = "embed-v4.0",
+ input_type: str = "search_query",
+ api_base_url: str = "https://api.cohere.com",
+ truncate: str = "END",
+ timeout: float = 120.0,
+ embedding_type: EmbeddingTypes | None = None,
+) -> None
+```
+
+Initialize the CohereTextEmbedder.
+
+**Parameters:**
+
+- **api_key** (Secret) – the Cohere API key.
+- **model** (str) – the name of the model to use.
+ Read [Cohere documentation](https://docs.cohere.com/docs/models#embed) for a list of all supported models.
+- **input_type** (str) – specifies the type of input you're giving to the model. Supported values are
+ "search_document", "search_query", "classification" and "clustering".
+- **api_base_url** (str) – the Cohere API Base url.
+- **truncate** (str) – truncate embeddings that are too long from start or end, ("NONE"|"START"|"END").
+ Passing "START" will discard the start of the input. "END" will discard the end of the input. In both
+ cases, input is discarded until the remaining input is exactly the maximum input token length for the model.
+ If "NONE" is selected, when the input exceeds the maximum input token length an error will be returned.
+- **timeout** (float) – request timeout in seconds.
+- **embedding_type** (EmbeddingTypes | None) – the type of embeddings to return. Defaults to float embeddings.
+ Note that int8, uint8, binary, and ubinary are only valid for v3 models.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CohereTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- CohereTextEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Embed text.
+
+**Parameters:**
+
+- **text** (str) – the text to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\] | dict\[str, Any\]\] – A dictionary with the following keys:
+ - `embedding`: the embedding of the text.
+ - `meta`: metadata about the request.
+
+**Raises:**
+
+- TypeError – If the input is not a string.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Asynchronously embed text.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+:param text:
+Text to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\] | dict\[str, Any\]\] – A dictionary with the following keys:
+- `embedding`: the embedding of the text.
+- `meta`: metadata about the request.
+
+**Raises:**
+
+- TypeError – If the input is not a string.
+
+## haystack_integrations.components.embedders.cohere.utils
+
+### get_async_response
+
+```python
+get_async_response(
+ cohere_async_client: AsyncClientV2,
+ texts: list[str],
+ model_name: str,
+ input_type: str,
+ truncate: str,
+ embedding_type: EmbeddingTypes | None = None,
+) -> tuple[list[list[float]], dict[str, Any]]
+```
+
+Embeds a list of texts asynchronously using the Cohere API.
+
+**Parameters:**
+
+- **cohere_async_client** (AsyncClientV2) – the Cohere `AsyncClient`
+- **texts** (list\[str\]) – the texts to embed
+- **model_name** (str) – the name of the model to use
+- **input_type** (str) – one of "classification", "clustering", "search_document", "search_query".
+ The type of input text provided to embed.
+- **truncate** (str) – one of "NONE", "START", "END". How the API handles text longer than the maximum token length.
+- **embedding_type** (EmbeddingTypes | None) – the type of embeddings to return. Defaults to float embeddings.
+
+**Returns:**
+
+- tuple\[list\[list\[float\]\], dict\[str, Any\]\] – A tuple of the embeddings and metadata.
+
+**Raises:**
+
+- ValueError – If an error occurs while querying the Cohere API.
+
+### get_response
+
+```python
+get_response(
+ cohere_client: ClientV2,
+ texts: list[str],
+ model_name: str,
+ input_type: str,
+ truncate: str,
+ batch_size: int = 32,
+ progress_bar: bool = False,
+ embedding_type: EmbeddingTypes | None = None,
+) -> tuple[list[list[float]], dict[str, Any]]
+```
+
+Embeds a list of texts using the Cohere API.
+
+**Parameters:**
+
+- **cohere_client** (ClientV2) – the Cohere `Client`
+- **texts** (list\[str\]) – the texts to embed
+- **model_name** (str) – the name of the model to use
+- **input_type** (str) – one of "classification", "clustering", "search_document", "search_query".
+ The type of input text provided to embed.
+- **truncate** (str) – one of "NONE", "START", "END". How the API handles text longer than the maximum token length.
+- **batch_size** (int) – the batch size to use
+- **progress_bar** (bool) – if `True`, show a progress bar
+- **embedding_type** (EmbeddingTypes | None) – the type of embeddings to return. Defaults to float embeddings.
+
+**Returns:**
+
+- tuple\[list\[list\[float\]\], dict\[str, Any\]\] – A tuple of the embeddings and metadata.
+
+**Raises:**
+
+- ValueError – If an error occurs while querying the Cohere API.
+
+## haystack_integrations.components.generators.cohere.chat.chat_generator
+
+### CohereChatGenerator
+
+Completes chats using Cohere's models using cohere.ClientV2 `chat` endpoint.
+
+This component supports both text-only and multimodal (text + image) conversations
+using Cohere's vision models like Command A Vision.
+
+Supported image formats: PNG, JPEG, WEBP, GIF (non-animated).
+Maximum 20 images per request with 20MB total limit.
+
+You can customize how the chat response is generated by passing parameters to the
+Cohere API through the `**generation_kwargs` parameter. You can do this when
+initializing or running the component. Any parameter that works with
+`cohere.ClientV2.chat` will work here too.
+For details, see [Cohere API](https://docs.cohere.com/reference/chat).
+
+Below is an example of how to use the component:
+
+### Simple example
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack_integrations.components.generators.cohere import CohereChatGenerator
+
+client = CohereChatGenerator(api_key=Secret.from_env_var("COHERE_API_KEY"))
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+client.run(messages)
+
+# Output: {'replies': [ChatMessage(_role=Secret) – The API key for the Cohere API.
+- **model** (str) – The name of the model to use. You can use models from the `command` family.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk)
+ as an argument.
+- **api_base_url** (str | None) – The base URL of the Cohere API.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model during generation. For a list of parameters,
+ see [Cohere Chat endpoint](https://docs.cohere.com/reference/chat).
+ Some of the parameters are:
+- 'messages': A list of messages between the user and the model, meant to give the model
+ conversational context for responding to the user's message.
+- 'system_message': When specified, adds a system message at the beginning of the conversation.
+- 'citation_quality': Defaults to `accurate`. Dictates the approach taken to generating citations
+ as part of the RAG flow by allowing the user to specify whether they want
+ `accurate` results or `fast` results.
+- 'temperature': A non-negative float that tunes the degree of randomness in generation. Lower temperatures
+ mean less random generations.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset that the model can use.
+ Each tool should have a unique name.
+- **timeout** (float | None) – Timeout for Cohere client calls. If not set, it defaults to the default set by the Cohere client.
+- **max_retries** (int | None) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by
+ the Cohere client.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CohereChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- CohereChatGenerator – Deserialized component.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Invoke the chat endpoint based on the provided messages and generation parameters.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – list of `ChatMessage` instances representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – additional keyword arguments for chat generation. These parameters will
+ potentially override the parameters passed in the __init__ method.
+ For more details on the parameters supported by the Cohere API, refer to the
+ Cohere [documentation](https://docs.cohere.com/reference/chat).
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter set during component initialization.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: a list of `ChatMessage` instances representing the generated responses.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Asynchronously invoke the chat endpoint based on the provided messages and generation parameters.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – list of `ChatMessage` instances representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – additional keyword arguments for chat generation. These parameters will
+ potentially override the parameters passed in the __init__ method.
+ For more details on the parameters supported by the Cohere API, refer to the
+ Cohere [documentation](https://docs.cohere.com/reference/chat).
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter set during component initialization.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: a list of `ChatMessage` instances representing the generated responses.
+
+## haystack_integrations.components.generators.cohere.generator
+
+### CohereGenerator
+
+Bases: CohereChatGenerator
+
+Generates text using Cohere's models through Cohere's `generate` endpoint.
+
+NOTE: Cohere discontinued the `generate` API, so this generator is a mere wrapper
+around `CohereChatGenerator` provided for backward compatibility.
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.cohere import CohereGenerator
+
+generator = CohereGenerator(api_key="test-api-key")
+generator.run(prompt="What's the capital of France?")
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "command-a-03-2025",
+ "command-r7b-12-2024",
+ "command-a-translate-08-2025",
+ "command-a-reasoning-08-2025",
+ "command-a-vision-07-2025",
+ "command-r-08-2024",
+ "command-r-plus-08-2024",
+ "command-r-03-2024",
+ "command-r-plus-04-2024",
+ "command-r-plus",
+ "command-r",
+ "command-light",
+ "command",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+See https://docs.cohere.com/docs/models#command for the full list.
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var(["COHERE_API_KEY", "CO_API_KEY"]),
+ model: str = "command-a-03-2025",
+ streaming_callback: Callable | None = None,
+ api_base_url: str | None = None,
+ **kwargs: Any
+) -> None
+```
+
+Instantiates a `CohereGenerator` component.
+
+**Parameters:**
+
+- **api_key** (Secret) – Cohere API key.
+- **model** (str) – Cohere model to use for generation.
+- **streaming_callback** (Callable | None) – Callback function that is called when a new token is received from the stream.
+ The callback function accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk)
+ as an argument.
+- **api_base_url** (str | None) – Cohere base URL.
+- \*\***kwargs** (Any) – Additional arguments passed to the model. These arguments are specific to the model.
+ You can check them in model's documentation.
+
+#### run
+
+```python
+run(prompt: str) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Queries the LLM with the prompts to produce replies.
+
+**Parameters:**
+
+- **prompt** (str) – the prompt to be sent to the generative model.
+
+**Returns:**
+
+- dict\[str, list\[str\] | list\[dict\[str, Any\]\]\] – A dictionary with the following keys:
+- `replies`: A list of replies generated by the model.
+- `meta`: Information about the request.
+
+#### run_async
+
+```python
+run_async(prompt: str) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Queries the LLM asynchronously with the prompts to produce replies.
+
+**Parameters:**
+
+- **prompt** (str) – the prompt to be sent to the generative model.
+
+**Returns:**
+
+- dict\[str, list\[str\] | list\[dict\[str, Any\]\]\] – A dictionary with the following keys:
+- `replies`: A list of replies generated by the model.
+- `meta`: Information about the request.
+
+## haystack_integrations.components.rankers.cohere.ranker
+
+### CohereRanker
+
+Ranks Documents based on their similarity to the query using [Cohere models](https://docs.cohere.com/reference/rerank-1).
+
+Documents are indexed from most to least semantically relevant to the query.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.cohere import CohereRanker
+
+ranker = CohereRanker(model="rerank-v3.5", top_k=2)
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "What is the capital of germany?"
+output = ranker.run(query=query, documents=docs)
+docs = output["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "rerank-v3.5",
+ top_k: int = 10,
+ api_key: Secret = Secret.from_env_var(["COHERE_API_KEY", "CO_API_KEY"]),
+ api_base_url: str = "https://api.cohere.com",
+ meta_fields_to_embed: list[str] | None = None,
+ meta_data_separator: str = "\n",
+ max_tokens_per_doc: int = 4096,
+) -> None
+```
+
+Creates an instance of the 'CohereRanker'.
+
+**Parameters:**
+
+- **model** (str) – Cohere model name. Check the list of supported models in the [Cohere documentation](https://docs.cohere.com/docs/models).
+- **top_k** (int) – The maximum number of documents to return.
+- **api_key** (Secret) – Cohere API key.
+- **api_base_url** (str) – the base URL of the Cohere API.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be concatenated
+ with the document content for reranking.
+- **meta_data_separator** (str) – Separator used to concatenate the meta fields
+ to the Document content.
+- **max_tokens_per_doc** (int) – The maximum number of tokens to embed for each document defaults to 4096.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CohereRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- CohereRanker – The deserialized component.
+
+#### run
+
+```python
+run(
+ query: str, documents: list[Document], top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Use the Cohere Reranker to re-rank the list of documents based on the query.
+
+**Parameters:**
+
+- **query** (str) – Query string.
+- **documents** (list\[Document\]) – List of Documents.
+- **top_k** (int | None) – The maximum number of Documents you want the Ranker to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+
+#### run_async
+
+```python
+run_async(
+ query: str, documents: list[Document], top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously re-rank the list of documents based on the query.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **query** (str) – Query string.
+- **documents** (list\[Document\]) – List of Documents.
+- **top_k** (int | None) – The maximum number of Documents you want the Ranker to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/cometapi.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/cometapi.md
new file mode 100644
index 0000000000..4b061911f8
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/cometapi.md
@@ -0,0 +1,37 @@
+---
+title: "Comet API"
+id: integrations-cometapi
+description: "Comet API integration for Haystack"
+slug: "/integrations-cometapi"
+---
+
+
+
+## Module haystack\_integrations.components.generators.cometapi.chat.chat\_generator
+
+
+
+### CometAPIChatGenerator
+
+A chat generator that uses the CometAPI for generating chat responses.
+
+This class extends Haystack's OpenAIChatGenerator to specifically interact with the CometAPI.
+It sets the `api_base_url` to the CometAPI endpoint and allows for all the
+standard configurations available in the OpenAIChatGenerator.
+
+**Arguments**:
+
+- `api_key`: The API key for authenticating with the CometAPI. Defaults to
+loading from the "COMET_API_KEY" environment variable.
+- `model`: The name of the model to use for chat generation (e.g., "gpt-5-mini", "grok-3-mini").
+Defaults to "gpt-5-mini".
+- `streaming_callback`: An optional callable that will be called with each chunk of
+a streaming response.
+- `generation_kwargs`: Optional keyword arguments to pass to the underlying generation
+API call.
+- `timeout`: The maximum time in seconds to wait for a response from the API.
+- `max_retries`: The maximum number of times to retry a failed API request.
+- `tools`: An optional list of tool definitions that the model can use.
+- `tools_strict`: If True, the model is forced to use one of the provided tools if a tool call is made.
+- `http_client_kwargs`: Optional keyword arguments to pass to the HTTP client.
+
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/deepeval.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/deepeval.md
new file mode 100644
index 0000000000..1211eff805
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/deepeval.md
@@ -0,0 +1,193 @@
+---
+title: "DeepEval"
+id: integrations-deepeval
+description: "DeepEval integration for Haystack"
+slug: "/integrations-deepeval"
+---
+
+
+
+## Module haystack\_integrations.components.evaluators.deepeval.evaluator
+
+
+
+### DeepEvalEvaluator
+
+A component that uses the [DeepEval framework](https://docs.confident-ai.com/docs/evaluation-introduction)
+to evaluate inputs against a specific metric. Supported metrics are defined by `DeepEvalMetric`.
+
+Usage example:
+```python
+from haystack_integrations.components.evaluators.deepeval import DeepEvalEvaluator, DeepEvalMetric
+
+evaluator = DeepEvalEvaluator(
+ metric=DeepEvalMetric.FAITHFULNESS,
+ metric_params={"model": "gpt-4"},
+)
+output = evaluator.run(
+ questions=["Which is the most popular global sport?"],
+ contexts=[
+ [
+ "Football is undoubtedly the world's most popular sport with"
+ "major events like the FIFA World Cup and sports personalities"
+ "like Ronaldo and Messi, drawing a followership of more than 4"
+ "billion people."
+ ]
+ ],
+ responses=["Football is the most popular sport with around 4 billion" "followers worldwide"],
+)
+print(output["results"])
+```
+
+
+
+#### DeepEvalEvaluator.\_\_init\_\_
+
+```python
+def __init__(metric: str | DeepEvalMetric,
+ metric_params: dict[str, Any] | None = None)
+```
+
+Construct a new DeepEval evaluator.
+
+**Arguments**:
+
+- `metric`: The metric to use for evaluation.
+- `metric_params`: Parameters to pass to the metric's constructor.
+Refer to the `RagasMetric` class for more details
+on required parameters.
+
+
+
+#### DeepEvalEvaluator.run
+
+```python
+@component.output_types(results=list[list[dict[str, Any]]])
+def run(**inputs: Any) -> dict[str, Any]
+```
+
+Run the DeepEval evaluator on the provided inputs.
+
+**Arguments**:
+
+- `inputs`: The inputs to evaluate. These are determined by the
+metric being calculated. See `DeepEvalMetric` for more
+information.
+
+**Returns**:
+
+A dictionary with a single `results` entry that contains
+a nested list of metric results. Each input can have one or more
+results, depending on the metric. Each result is a dictionary
+containing the following keys and values:
+- `name` - The name of the metric.
+- `score` - The score of the metric.
+- `explanation` - An optional explanation of the score.
+
+
+
+#### DeepEvalEvaluator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Raises**:
+
+- `DeserializationError`: If the component cannot be serialized.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### DeepEvalEvaluator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "DeepEvalEvaluator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+## Module haystack\_integrations.components.evaluators.deepeval.metrics
+
+
+
+### DeepEvalMetric
+
+Metrics supported by DeepEval.
+
+All metrics require a `model` parameter, which specifies
+the model to use for evaluation. Refer to the DeepEval
+documentation for information on the supported models.
+
+
+
+#### ANSWER\_RELEVANCY
+
+Answer relevancy.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]`
+
+
+
+#### FAITHFULNESS
+
+Faithfulness.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]`
+
+
+
+#### CONTEXTUAL\_PRECISION
+
+Contextual precision.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str], ground_truths: List[str]`\
+The ground truth is the expected response.
+
+
+
+#### CONTEXTUAL\_RECALL
+
+Contextual recall.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str], ground_truths: List[str]`\
+The ground truth is the expected response.\
+
+
+
+#### CONTEXTUAL\_RELEVANCE
+
+Contextual relevance.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]`
+
+
+
+#### DeepEvalMetric.from\_str
+
+```python
+@classmethod
+def from_str(cls, string: str) -> "DeepEvalMetric"
+```
+
+Create a metric type from a string.
+
+**Arguments**:
+
+- `string`: The string to convert.
+
+**Returns**:
+
+The metric.
+
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/docling.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/docling.md
new file mode 100644
index 0000000000..988d56f740
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/docling.md
@@ -0,0 +1,177 @@
+---
+title: "Docling"
+id: integrations-docling
+description: "Docling integration for Haystack"
+slug: "/integrations-docling"
+---
+
+
+## haystack_integrations.components.converters.docling.converter
+
+Docling Haystack converter module.
+
+### ExportType
+
+Bases: str, Enum
+
+Enumeration of available export types.
+
+### BaseMetaExtractor
+
+Bases: ABC
+
+BaseMetaExtractor.
+
+#### extract_chunk_meta
+
+```python
+extract_chunk_meta(chunk: BaseChunk) -> dict[str, Any]
+```
+
+Extract chunk meta.
+
+#### extract_dl_doc_meta
+
+```python
+extract_dl_doc_meta(dl_doc: DoclingDocument) -> dict[str, Any]
+```
+
+Extract Docling document meta.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> BaseMetaExtractor
+```
+
+Deserialize from a dictionary.
+
+### MetaExtractor
+
+Bases: BaseMetaExtractor
+
+MetaExtractor.
+
+#### extract_chunk_meta
+
+```python
+extract_chunk_meta(chunk: BaseChunk) -> dict[str, Any]
+```
+
+Extract chunk meta.
+
+#### extract_dl_doc_meta
+
+```python
+extract_dl_doc_meta(dl_doc: DoclingDocument) -> dict[str, Any]
+```
+
+Extract Docling document meta.
+
+### DoclingConverter
+
+Docling Haystack converter.
+
+#### __init__
+
+```python
+__init__(
+ converter: DocumentConverter | None = None,
+ convert_kwargs: dict[str, Any] | None = None,
+ export_type: ExportType = ExportType.MARKDOWN,
+ md_export_kwargs: dict[str, Any] | None = None,
+ chunker: BaseChunker | None = None,
+ meta_extractor: BaseMetaExtractor | None = None,
+) -> None
+```
+
+Create a Docling Haystack converter.
+
+**Parameters:**
+
+- **converter** (DocumentConverter | None) – The Docling `DocumentConverter` to use; if not set, a system
+ default is used.
+- **convert_kwargs** (dict\[str, Any\] | None) – Any parameters to pass to Docling conversion; if not set, a
+ system default is used.
+- **export_type** (ExportType) – The export mode to use:
+
+* `ExportType.MARKDOWN` (default) captures each input document as a single
+ markdown `Document`.
+* `ExportType.DOC_CHUNKS` first chunks each input document and then returns
+ one `Document` per chunk.
+* `ExportType.JSON` serializes the full Docling document to a JSON string.
+
+- **md_export_kwargs** (dict\[str, Any\] | None) – Any parameters to pass to Markdown export (applicable in
+ case of `ExportType.MARKDOWN`).
+- **chunker** (BaseChunker | None) – The Docling chunker instance to use; if not set, a system default
+ is used.
+- **meta_extractor** (BaseMetaExtractor | None) – The extractor instance to use for populating the output
+ document metadata; if not set, a system default is used.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DoclingConverter
+```
+
+Deserialize this component from a dictionary.
+
+The `converter` and `chunker` parameters are not serializable and are always ignored during
+deserialization; the restored instance will use the default `DocumentConverter` and `HybridChunker`
+respectively.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary with keys `type` and `init_parameters`, as produced by `to_dict`.
+
+**Returns:**
+
+- DoclingConverter – A new `DoclingConverter` instance.
+
+#### run
+
+```python
+run(
+ paths: list[str | Path] | None = None,
+ sources: list[str | Path | ByteStream] | None = None,
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Run the DoclingConverter.
+
+**Parameters:**
+
+- **paths** (list\[str | Path\] | None) – Deprecated. Use `sources` instead.
+- **sources** (list\[str | Path | ByteStream\] | None) – List of file paths, URLs, or ByteStream objects to convert.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced Documents.
+ If it's a list, the length of the list must match the number of sources, because the two lists will
+ be zipped.
+ If a source is a ByteStream, its own metadata is also merged into the output.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with key `"documents"` containing the output Haystack Documents.
+
+**Raises:**
+
+- ValueError – If `meta` is a list whose length does not match the number of sources.
+- RuntimeError – If an unexpected `export_type` is encountered.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/docling_serve.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/docling_serve.md
new file mode 100644
index 0000000000..14e9d04910
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/docling_serve.md
@@ -0,0 +1,151 @@
+---
+title: "Docling Serve"
+id: integrations-docling_serve
+description: "Docling Serve integration for Haystack"
+slug: "/integrations-docling_serve"
+---
+
+
+## haystack_integrations.components.converters.docling_serve.converter
+
+### ExportType
+
+Bases: str, Enum
+
+Enumeration of export formats supported by DoclingServe.
+
+- `MARKDOWN`: Converts documents to Markdown format.
+- `TEXT`: Extracts plain text.
+- `JSON`: Returns the full Docling document as a JSON string.
+
+### DoclingServeConverter
+
+Converts documents to Haystack Documents using a DoclingServe server.
+
+See [DoclingServe](https://github.com/docling-project/docling-serve).
+
+DoclingServe hosts Docling in a scalable HTTP server, supporting PDFs, Office documents, HTML, and many other
+formats. Unlike the local `DoclingConverter`, this component has no heavy ML dependencies — all processing
+happens on the remote server.
+
+Local files and ByteStreams are uploaded via the `/v1/convert/file` endpoint. URL strings are sent to
+`/v1/convert/source`.
+
+Supports both synchronous (`run`) and asynchronous (`run_async`) execution.
+
+### Usage example
+
+```python
+from haystack_integrations.components.converters.docling_serve import DoclingServeConverter
+
+converter = DoclingServeConverter(base_url="http://localhost:5001")
+result = converter.run(sources=["https://arxiv.org/pdf/2206.01062"])
+print(result["documents"][0].content[:200])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ base_url: str = "http://localhost:5001",
+ export_type: ExportType = ExportType.MARKDOWN,
+ convert_options: dict[str, Any] | None = None,
+ timeout: float = 120.0,
+ api_key: Secret | None = Secret.from_env_var(
+ "DOCLING_SERVE_API_KEY", strict=False
+ )
+) -> None
+```
+
+Initializes the DoclingServeConverter.
+
+**Parameters:**
+
+- **base_url** (str) – Base URL of the DoclingServe instance. Defaults to `"http://localhost:5001"`.
+- **export_type** (ExportType) – The output format for converted documents. One of `ExportType.MARKDOWN` (default),
+ `ExportType.TEXT`, or `ExportType.JSON`.
+- **convert_options** (dict\[str, Any\] | None) – Optional dictionary of conversion options passed directly to the DoclingServe API
+ (e.g. `{"do_ocr": True, "ocr_engine": "tesseract"}`).
+ See [DoclingServe options](https://github.com/docling-project/docling-serve/blob/main/docs/usage.md).
+ Note: `to_formats` is set automatically based on `export_type` and should not be included here.
+- **timeout** (float) – HTTP request timeout in seconds. Defaults to `120.0`.
+- **api_key** (Secret | None) – API key for authenticating with a secured DoclingServe instance. Reads from the
+ `DOCLING_SERVE_API_KEY` environment variable by default. Set to `None` to disable
+ authentication.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DoclingServeConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary representation of the component.
+
+**Returns:**
+
+- DoclingServeConverter – A new `DoclingServeConverter` instance.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Converts documents by sending them to DoclingServe and returns Haystack Documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of sources to convert. Each item can be a URL string, a local file path, or a
+ `ByteStream`. URL strings are sent to `/v1/convert/source`; all other sources are
+ uploaded to `/v1/convert/file`.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the output Documents. Can be a single dict applied to
+ all documents, or a list of dicts with one entry per source.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with key `"documents"` containing the converted Haystack Documents.
+
+#### run_async
+
+```python
+run_async(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously converts documents by sending them to DoclingServe.
+
+This is the async equivalent of `run()`, useful when DoclingServe requests should not
+block the event loop.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of sources to convert. Each item can be a URL string, a local file path, or a
+ `ByteStream`. URL strings are sent to `/v1/convert/source`; all other sources are
+ uploaded to `/v1/convert/file`.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the output Documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with key `"documents"` containing the converted Haystack Documents.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/e2b.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/e2b.md
new file mode 100644
index 0000000000..88af83f295
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/e2b.md
@@ -0,0 +1,418 @@
+---
+title: "E2B"
+id: integrations-e2b
+description: "E2B integration for Haystack"
+slug: "/integrations-e2b"
+---
+
+
+## haystack_integrations.tools.e2b.bash_tool
+
+### RunBashCommandTool
+
+Bases: Tool
+
+A :class:`~haystack.tools.Tool` that executes bash commands inside an E2B sandbox.
+
+Pass the same :class:`E2BSandbox` instance to multiple tool classes so they
+all operate in the same live sandbox environment.
+
+### Usage example
+
+```python
+from haystack_integrations.tools.e2b import E2BSandbox, RunBashCommandTool, ReadFileTool
+
+sandbox = E2BSandbox()
+agent = Agent(
+ chat_generator=...,
+ tools=[
+ RunBashCommandTool(sandbox=sandbox),
+ ReadFileTool(sandbox=sandbox),
+ ],
+)
+```
+
+#### __init__
+
+```python
+__init__(sandbox: E2BSandbox) -> None
+```
+
+Create a RunBashCommandTool.
+
+**Parameters:**
+
+- **sandbox** (E2BSandbox) – The :class:`E2BSandbox` instance that will execute commands.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> RunBashCommandTool
+```
+
+Deserialize a RunBashCommandTool from a dictionary.
+
+## haystack_integrations.tools.e2b.e2b_sandbox
+
+### E2BSandbox
+
+Manages the lifecycle of an E2B cloud sandbox.
+
+Instantiate this class and pass it to one or more E2B tool classes
+(`RunBashCommandTool`, `ReadFileTool`, `WriteFileTool`,
+`ListDirectoryTool`) to share a single sandbox environment across all
+tools. All tools that receive the same `E2BSandbox` instance operate
+inside the same live sandbox process.
+
+### Usage example
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.agents import Agent
+
+from haystack_integrations.tools.e2b import (
+ E2BSandbox,
+ RunBashCommandTool,
+ ReadFileTool,
+ WriteFileTool,
+ ListDirectoryTool,
+)
+
+sandbox = E2BSandbox()
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-4o"),
+ tools=[
+ RunBashCommandTool(sandbox=sandbox),
+ ReadFileTool(sandbox=sandbox),
+ WriteFileTool(sandbox=sandbox),
+ ListDirectoryTool(sandbox=sandbox),
+ ],
+)
+```
+
+Lifecycle is handled automatically by the Agent's pipeline. If you use the
+tools standalone, call :meth:`warm_up` before the first tool invocation:
+
+```python
+sandbox.warm_up()
+# ... use tools ...
+sandbox.close()
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("E2B_API_KEY", strict=True),
+ sandbox_template: str = "base",
+ timeout: int = 120,
+ environment_vars: dict[str, str] | None = None,
+ instance_id: str | None = None,
+) -> None
+```
+
+Create an E2BSandbox instance.
+
+**Parameters:**
+
+- **api_key** (Secret) – E2B API key.
+- **sandbox_template** (str) – E2B sandbox template name.
+- **timeout** (int) – Sandbox inactivity timeout in seconds.
+- **environment_vars** (dict\[str, str\] | None) – Optional environment variables to inject into the sandbox.
+- **instance_id** (str | None) – Stable identifier preserved across `to_dict`/`from_dict`. When
+ omitted, a fresh UUID is generated. Tools that share the same `E2BSandbox`
+ instance inherit this id, which is what lets them re-share the instance after
+ a serialization round-trip. Distinct from the cloud-side sandbox id assigned
+ by E2B at warm-up.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Establish the connection to the E2B sandbox.
+
+Idempotent -- calling it multiple times has no effect if the sandbox is
+already running.
+
+**Raises:**
+
+- RuntimeError – If the E2B sandbox cannot be created.
+
+#### close
+
+```python
+close() -> None
+```
+
+Shut down the E2B sandbox and release all associated resources.
+
+Call this when you are done to avoid leaving idle sandboxes running.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the sandbox configuration to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary containing the serialised configuration.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> E2BSandbox
+```
+
+Deserialize an :class:`E2BSandbox` from a dictionary.
+
+Multiple tools that shared a single :class:`E2BSandbox` before serialization
+will share the same restored instance: each tool's `from_dict` consults a
+process-wide cache keyed on `instance_id`. A cache hit is only honored when
+the full serialized config (api_key, template, timeout, environment_vars)
+matches the cached entry — a crafted YAML with a guessed id but a different
+config falls through to a fresh instance and never observes the cached one.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary created by :meth:`to_dict`.
+
+**Returns:**
+
+- E2BSandbox – An :class:`E2BSandbox` instance ready to be warmed up. May be a
+ previously-restored instance if the id and config match.
+
+## haystack_integrations.tools.e2b.list_directory_tool
+
+### ListDirectoryTool
+
+Bases: Tool
+
+A :class:`~haystack.tools.Tool` that lists directory contents in an E2B sandbox.
+
+Pass the same :class:`E2BSandbox` instance to multiple tool classes so they
+all operate in the same live sandbox environment.
+
+### Usage example
+
+```python
+from haystack_integrations.tools.e2b import E2BSandbox, ListDirectoryTool
+
+sandbox = E2BSandbox()
+agent = Agent(chat_generator=..., tools=[ListDirectoryTool(sandbox=sandbox)])
+```
+
+#### __init__
+
+```python
+__init__(sandbox: E2BSandbox) -> None
+```
+
+Create a ListDirectoryTool.
+
+**Parameters:**
+
+- **sandbox** (E2BSandbox) – The :class:`E2BSandbox` instance to list directories from.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ListDirectoryTool
+```
+
+Deserialize a ListDirectoryTool from a dictionary.
+
+## haystack_integrations.tools.e2b.read_file_tool
+
+### ReadFileTool
+
+Bases: Tool
+
+A :class:`~haystack.tools.Tool` that reads files from an E2B sandbox filesystem.
+
+Pass the same :class:`E2BSandbox` instance to multiple tool classes so they
+all operate in the same live sandbox environment.
+
+### Usage example
+
+```python
+from haystack_integrations.tools.e2b import E2BSandbox, ReadFileTool
+
+sandbox = E2BSandbox()
+agent = Agent(chat_generator=..., tools=[ReadFileTool(sandbox=sandbox)])
+```
+
+#### __init__
+
+```python
+__init__(sandbox: E2BSandbox) -> None
+```
+
+Create a ReadFileTool.
+
+**Parameters:**
+
+- **sandbox** (E2BSandbox) – The :class:`E2BSandbox` instance to read files from.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ReadFileTool
+```
+
+Deserialize a ReadFileTool from a dictionary.
+
+## haystack_integrations.tools.e2b.sandbox_toolset
+
+### E2BToolset
+
+Bases: Toolset
+
+A :class:`~haystack.tools.Toolset` that bundles all E2B sandbox tools.
+
+All tools in the set share a single :class:`E2BSandbox` instance so they
+operate inside the same live sandbox process. The toolset owns the sandbox
+lifecycle: calling :meth:`warm_up` starts the sandbox, and serialisation
+round-trips preserve the shared-sandbox relationship.
+
+### Usage example
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.agents import Agent
+
+from haystack_integrations.tools.e2b import E2BToolset
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-4o"),
+ tools=E2BToolset(),
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("E2B_API_KEY", strict=True),
+ sandbox_template: str = "base",
+ timeout: int = 120,
+ environment_vars: dict[str, str] | None = None,
+) -> None
+```
+
+Create an E2BToolset.
+
+**Parameters:**
+
+- **api_key** (Secret) – E2B API key. Defaults to `Secret.from_env_var("E2B_API_KEY")`.
+- **sandbox_template** (str) – E2B sandbox template name. Defaults to `"base"`.
+- **timeout** (int) – Sandbox inactivity timeout in seconds. Defaults to `120`.
+- **environment_vars** (dict\[str, str\] | None) – Optional environment variables to inject into the sandbox.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Start the shared E2B sandbox (idempotent).
+
+#### close
+
+```python
+close() -> None
+```
+
+Shut down the shared E2B sandbox and release cloud resources.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this toolset to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> E2BToolset
+```
+
+Deserialize an E2BToolset from a dictionary.
+
+## haystack_integrations.tools.e2b.write_file_tool
+
+### WriteFileTool
+
+Bases: Tool
+
+A :class:`~haystack.tools.Tool` that writes files to an E2B sandbox filesystem.
+
+Pass the same :class:`E2BSandbox` instance to multiple tool classes so they
+all operate in the same live sandbox environment.
+
+### Usage example
+
+```python
+from haystack_integrations.tools.e2b import E2BSandbox, WriteFileTool
+
+sandbox = E2BSandbox()
+agent = Agent(chat_generator=..., tools=[WriteFileTool(sandbox=sandbox)])
+```
+
+#### __init__
+
+```python
+__init__(sandbox: E2BSandbox) -> None
+```
+
+Create a WriteFileTool.
+
+**Parameters:**
+
+- **sandbox** (E2BSandbox) – The :class:`E2BSandbox` instance to write files to.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WriteFileTool
+```
+
+Deserialize a WriteFileTool from a dictionary.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/elasticsearch.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/elasticsearch.md
new file mode 100644
index 0000000000..c16c6839af
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/elasticsearch.md
@@ -0,0 +1,1117 @@
+---
+title: "Elasticsearch"
+id: integrations-elasticsearch
+description: "Elasticsearch integration for Haystack"
+slug: "/integrations-elasticsearch"
+---
+
+
+## haystack_integrations.components.retrievers.elasticsearch.bm25_retriever
+
+### ElasticsearchBM25Retriever
+
+Retrieves documents from ElasticsearchDocumentStore using the BM25 algorithm.
+
+Finds the most similar documents to a user's query.
+
+This retriever is only compatible with ElasticsearchDocumentStore.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore
+from haystack_integrations.components.retrievers.elasticsearch import ElasticsearchBM25Retriever
+
+document_store = ElasticsearchDocumentStore(hosts="http://localhost:9200")
+retriever = ElasticsearchBM25Retriever(document_store=document_store)
+
+# Add documents to DocumentStore
+documents = [
+ Document(text="My name is Carla and I live in Berlin"),
+ Document(text="My name is Paul and I live in New York"),
+ Document(text="My name is Silvano and I live in Matera"),
+ Document(text="My name is Usagi Tsukino and I live in Tokyo"),
+]
+document_store.write_documents(documents)
+
+result = retriever.run(query="Who lives in Berlin?")
+for doc in result["documents"]:
+ print(doc.content)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: ElasticsearchDocumentStore,
+ filters: dict[str, Any] | None = None,
+ fuzziness: str = "AUTO",
+ top_k: int = 10,
+ scale_score: bool = False,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize ElasticsearchBM25Retriever with an instance ElasticsearchDocumentStore.
+
+**Parameters:**
+
+- **document_store** (ElasticsearchDocumentStore) – An instance of ElasticsearchDocumentStore.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents, for more info
+ see `ElasticsearchDocumentStore.filter_documents`.
+- **fuzziness** (str) – Fuzziness parameter passed to Elasticsearch. See the official
+ [documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#fuzziness)
+ for more details.
+- **top_k** (int) – Maximum number of Documents to return.
+- **scale_score** (bool) – If `True` scales the Document\`s scores between 0 and 1.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `ElasticsearchDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ElasticsearchBM25Retriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ElasticsearchBM25Retriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents using the BM25 keyword-based algorithm.
+
+**Parameters:**
+
+- **query** (str) – String to search in the `Document`s text.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of `Document` to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s that match the query.
+
+#### run_async
+
+```python
+run_async(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents using the BM25 keyword-based algorithm.
+
+**Parameters:**
+
+- **query** (str) – String to search in the `Document` text.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of `Document` to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s that match the query.
+
+## haystack_integrations.components.retrievers.elasticsearch.embedding_retriever
+
+### ElasticsearchEmbeddingRetriever
+
+ElasticsearchEmbeddingRetriever retrieves documents from the ElasticsearchDocumentStore using vector similarity.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore
+from haystack_integrations.components.retrievers.elasticsearch import ElasticsearchEmbeddingRetriever
+
+document_store = ElasticsearchDocumentStore(hosts="http://localhost:9200")
+retriever = ElasticsearchEmbeddingRetriever(document_store=document_store)
+
+# Add documents to DocumentStore
+documents = [
+ Document(text="My name is Carla and I live in Berlin"),
+ Document(text="My name is Paul and I live in New York"),
+ Document(text="My name is Silvano and I live in Matera"),
+ Document(text="My name is Usagi Tsukino and I live in Tokyo"),
+]
+document_store.write_documents(documents)
+
+te = SentenceTransformersTextEmbedder()
+te.warm_up()
+query_embeddings = te.run("Who lives in Berlin?")["embedding"]
+
+result = retriever.run(query=query_embeddings)
+for doc in result["documents"]:
+ print(doc.content)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: ElasticsearchDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ num_candidates: int | None = None,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create the ElasticsearchEmbeddingRetriever component.
+
+**Parameters:**
+
+- **document_store** (ElasticsearchDocumentStore) – An instance of ElasticsearchDocumentStore.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents.
+ Filters are applied during the approximate KNN search to ensure that top_k matching documents are returned.
+- **top_k** (int) – Maximum number of Documents to return.
+- **num_candidates** (int | None) – Number of approximate nearest neighbor candidates on each shard. Defaults to top_k * 10.
+ Increasing this value will improve search accuracy at the cost of slower search speeds.
+ You can read more about it in the Elasticsearch
+ [documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/knn-search.html#tune-approximate-knn-for-speed-accuracy)
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of ElasticsearchDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ElasticsearchEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ElasticsearchEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents using a vector similarity metric.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied when fetching documents from the Document Store.
+ Filters are applied during the approximate kNN search to ensure the Retriever returns
+ `top_k` matching documents.
+ The way runtime filters are applied depends on the `filter_policy` selected when initializing the Retriever.
+- **top_k** (int | None) – Maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s most similar to the given `query_embedding`
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents using a vector similarity metric.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied when fetching documents from the Document Store.
+ Filters are applied during the approximate kNN search to ensure the Retriever returns
+ `top_k` matching documents.
+ The way runtime filters are applied depends on the `filter_policy` selected when initializing the Retriever.
+- **top_k** (int | None) – Maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s that match the query.
+
+## haystack_integrations.components.retrievers.elasticsearch.sql_retriever
+
+### ElasticsearchSQLRetriever
+
+Executes raw Elasticsearch SQL queries against an ElasticsearchDocumentStore.
+
+This component allows you to execute SQL queries directly against the Elasticsearch index,
+which is useful for fetching metadata, aggregations, and other structured data at runtime.
+
+Returns the raw JSON response from the Elasticsearch SQL API.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore
+from haystack_integrations.components.retrievers.elasticsearch import ElasticsearchSQLRetriever
+
+document_store = ElasticsearchDocumentStore(hosts="http://localhost:9200")
+retriever = ElasticsearchSQLRetriever(document_store=document_store)
+
+result = retriever.run(
+ query="SELECT content, category FROM \"my_index\" WHERE category = 'A'"
+)
+# result["result"] contains the raw Elasticsearch JSON response
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: ElasticsearchDocumentStore,
+ raise_on_failure: bool = True,
+ fetch_size: int | None = None
+) -> None
+```
+
+Creates the ElasticsearchSQLRetriever component.
+
+**Parameters:**
+
+- **document_store** (ElasticsearchDocumentStore) – An instance of ElasticsearchDocumentStore to use with the Retriever.
+- **raise_on_failure** (bool) – Whether to raise an exception if the API call fails. Otherwise, log a warning and return an empty dict.
+- **fetch_size** (int | None) – Optional number of results to fetch per page. If not provided, the default
+ fetch size set in Elasticsearch is used.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of ElasticsearchDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ElasticsearchSQLRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ElasticsearchSQLRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ document_store: ElasticsearchDocumentStore | None = None,
+ fetch_size: int | None = None,
+) -> dict[str, dict[str, Any]]
+```
+
+Execute a raw Elasticsearch SQL query against the index.
+
+**Parameters:**
+
+- **query** (str) – The Elasticsearch SQL query to execute.
+- **document_store** (ElasticsearchDocumentStore | None) – Optionally, an instance of ElasticsearchDocumentStore to use with the Retriever.
+- **fetch_size** (int | None) – Optional number of results to fetch per page. If not provided, uses the value
+ specified during initialization, or the default fetch size set in Elasticsearch.
+
+**Returns:**
+
+- dict\[str, dict\[str, Any\]\] – A dictionary containing the raw JSON response from Elasticsearch SQL API:
+ - result: The raw JSON response from Elasticsearch (dict) or empty dict on error.
+
+Example:
+`python retriever = ElasticsearchSQLRetriever(document_store=document_store) result = retriever.run( query="SELECT content, category FROM \"my_index\" WHERE category = 'A'" ) # result["result"] contains the raw Elasticsearch JSON response # result["result"]["columns"] contains column metadata # result["result"]["rows"] contains the data rows `
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ document_store: ElasticsearchDocumentStore | None = None,
+ fetch_size: int | None = None,
+) -> dict[str, dict[str, Any]]
+```
+
+Asynchronously execute a raw Elasticsearch SQL query against the index.
+
+**Parameters:**
+
+- **query** (str) – The Elasticsearch SQL query to execute.
+- **document_store** (ElasticsearchDocumentStore | None) – Optionally, an instance of ElasticsearchDocumentStore to use with the Retriever.
+- **fetch_size** (int | None) – Optional number of results to fetch per page. If not provided, uses the value
+ specified during initialization, or the default fetch size set in Elasticsearch.
+
+**Returns:**
+
+- dict\[str, dict\[str, Any\]\] – A dictionary containing the raw JSON response from Elasticsearch SQL API:
+ - result: The raw JSON response from Elasticsearch (dict) or empty dict on error.
+
+Example:
+`python retriever = ElasticsearchSQLRetriever(document_store=document_store) result = await retriever.run_async( query="SELECT content, category FROM \"my_index\" WHERE category = 'A'" ) # result["result"] contains the raw Elasticsearch JSON response # result["result"]["columns"] contains column metadata # result["result"]["rows"] contains the data rows `
+
+## haystack_integrations.document_stores.elasticsearch.document_store
+
+### ElasticsearchDocumentStore
+
+An ElasticsearchDocumentStore instance that works with Elastic Cloud or your own Elasticsearch cluster.
+
+Usage example (Elastic Cloud):
+
+```python
+from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore
+document_store = ElasticsearchDocumentStore(
+ api_key_id=Secret.from_env_var("ELASTIC_API_KEY_ID", strict=False),
+ api_key=Secret.from_env_var("ELASTIC_API_KEY", strict=False),
+)
+```
+
+Usage example (self-hosted Elasticsearch instance):
+
+```python
+from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore
+document_store = ElasticsearchDocumentStore(hosts="http://localhost:9200")
+```
+
+In the above example we connect with security disabled just to show the basic usage.
+We strongly recommend to enable security so that only authorized users can access your data.
+
+For more details on how to connect to Elasticsearch and configure security,
+see the official Elasticsearch
+[documentation](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/connecting.html)
+
+All extra keyword arguments will be passed to the Elasticsearch client.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ hosts: Hosts | None = None,
+ custom_mapping: dict[str, Any] | None = None,
+ index: str = "default",
+ api_key: Secret | str | None = Secret.from_env_var(
+ "ELASTIC_API_KEY", strict=False
+ ),
+ api_key_id: Secret | str | None = Secret.from_env_var(
+ "ELASTIC_API_KEY_ID", strict=False
+ ),
+ embedding_similarity_function: Literal[
+ "cosine", "dot_product", "l2_norm", "max_inner_product"
+ ] = "cosine",
+ sparse_vector_field: str | None = None,
+ ingest_pipeline: str | None = None,
+ **kwargs: Any
+) -> None
+```
+
+Creates a new ElasticsearchDocumentStore instance.
+
+It will also try to create that index if it doesn't exist yet. Otherwise, it will use the existing one.
+
+One can also set the similarity function used to compare Documents embeddings. This is mostly useful
+when using the `ElasticsearchDocumentStore` in a Pipeline with an `ElasticsearchEmbeddingRetriever`.
+
+For more information on connection parameters, see the official Elasticsearch
+[documentation](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/connecting.html)
+
+For the full list of supported kwargs, see the official Elasticsearch
+[reference](https://elasticsearch-py.readthedocs.io/en/stable/api.html#module-elasticsearch)
+
+Authentication is provided via Secret objects, which by default are loaded from environment variables.
+You can either provide both `api_key_id` and `api_key`, or just `api_key` containing a base64-encoded string
+of `id:secret`. Secret instances can also be loaded from a token using the `Secret.from_token()` method.
+
+**Parameters:**
+
+- **hosts** (Hosts | None) – List of hosts running the Elasticsearch client.
+- **custom_mapping** (dict\[str, Any\] | None) – Custom mapping for the index. If not provided, a default mapping will be used.
+- **index** (str) – Name of index in Elasticsearch.
+- **api_key** (Secret | str | None) – A Secret object containing the API key for authenticating or base64-encoded with the
+ concatenated secret and id for authenticating with Elasticsearch (separated by “:”).
+- **api_key_id** (Secret | str | None) – A Secret object containing the API key ID for authenticating with Elasticsearch.
+- **embedding_similarity_function** (Literal['cosine', 'dot_product', 'l2_norm', 'max_inner_product']) – The similarity function used to compare Documents embeddings.
+ This parameter only takes effect if the index does not yet exist and is created.
+ To choose the most appropriate function, look for information about your embedding model.
+ To understand how document scores are computed, see the Elasticsearch
+ [documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/dense-vector.html#dense-vector-params)
+- **sparse_vector_field** (str | None) – If set, the name of the Elasticsearch field where sparse embeddings
+ will be stored using the `sparse_vector` field type. When not set, any `sparse_embedding`
+ data on Documents is silently dropped during writes.
+- **ingest_pipeline** (str | None) – If set, the id of an Elasticsearch ingest pipeline to run on each bulk
+ index or create. This is the recommended way to generate embeddings at index time using
+ Elasticsearch's inference processors (e.g. ELSER or a dense model) without running a
+ Haystack embedder component. Leading and trailing whitespace is stripped.
+
+Requirements when using inference processors:
+
+- Configure the processor with `input_output` so the embedding is written directly
+ to the right field: `output_field` must match `"embedding"` (for dense retrieval)
+ or the value of `sparse_vector_field` (for ELSER / sparse retrieval). The ES default
+ target `ml.inference.Any) – Optional arguments that `Elasticsearch` takes.
+
+#### client
+
+```python
+client: Elasticsearch
+```
+
+Returns the synchronous Elasticsearch client, initializing it if necessary.
+
+#### async_client
+
+```python
+async_client: AsyncElasticsearch
+```
+
+Returns the asynchronous Elasticsearch client, initializing it if necessary.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ElasticsearchDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ElasticsearchDocumentStore – Deserialized component.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – Number of documents in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – Number of documents in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+The main query method for the document store. It retrieves all documents that match the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – A dictionary of filters to apply. For more information on the structure of the filters,
+ see the official Elasticsearch
+ [documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html)
+
+**Returns:**
+
+- list\[Document\] – List of `Document`s that match the filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously retrieves all documents that match the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – A dictionary of filters to apply. For more information on the structure of the filters,
+ see the official Elasticsearch
+ [documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html)
+
+**Returns:**
+
+- list\[Document\] – List of `Document`s that match the filters.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document],
+ policy: DuplicatePolicy = DuplicatePolicy.NONE,
+ refresh: Literal["wait_for", True, False] = "wait_for",
+) -> int
+```
+
+Writes `Document`s to Elasticsearch.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – DuplicatePolicy to apply when a document with the same ID already exists in the document store.
+- **refresh** (Literal['wait_for', True, False]) – Controls when changes are made visible to search operations.
+- `True`: Force refresh immediately after the operation.
+- `False`: Do not refresh (better performance for bulk operations).
+- `"wait_for"`: Wait for the next refresh cycle (default, ensures read-your-writes consistency).
+ For more details, see the [Elasticsearch refresh documentation](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/refresh-parameter).
+
+**Returns:**
+
+- int – Number of documents written to the document store.
+
+**Raises:**
+
+- ValueError – If `documents` is not a list of `Document`s.
+- DuplicateDocumentError – If a document with the same ID already exists in the document store and
+ `policy` is set to `DuplicatePolicy.FAIL` or `DuplicatePolicy.NONE`.
+- DocumentStoreError – If an error occurs while writing the documents to the document store.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document],
+ policy: DuplicatePolicy = DuplicatePolicy.NONE,
+ refresh: Literal["wait_for", True, False] = "wait_for",
+) -> int
+```
+
+Asynchronously writes `Document`s to Elasticsearch.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – DuplicatePolicy to apply when a document with the same ID already exists in the document store.
+- **refresh** (Literal['wait_for', True, False]) – Controls when changes are made visible to search operations.
+- `True`: Force refresh immediately after the operation.
+- `False`: Do not refresh (better performance for bulk operations).
+- `"wait_for"`: Wait for the next refresh cycle (default, ensures read-your-writes consistency).
+ For more details, see the [Elasticsearch refresh documentation](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/refresh-parameter).
+
+**Returns:**
+
+- int – Number of documents written to the document store.
+
+**Raises:**
+
+- ValueError – If `documents` is not a list of `Document`s.
+- DuplicateDocumentError – If a document with the same ID already exists in the document store and
+ `policy` is set to `DuplicatePolicy.FAIL` or `DuplicatePolicy.NONE`.
+- DocumentStoreError – If an error occurs while writing the documents to the document store.
+
+#### delete_documents
+
+```python
+delete_documents(
+ document_ids: list[str],
+ refresh: Literal["wait_for", True, False] = "wait_for",
+) -> None
+```
+
+Deletes all documents with a matching document_ids from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+- **refresh** (Literal['wait_for', True, False]) – Controls when changes are made visible to search operations.
+- `True`: Force refresh immediately after the operation.
+- `False`: Do not refresh (better performance for bulk operations).
+- `"wait_for"`: Wait for the next refresh cycle (default, ensures read-your-writes consistency).
+ For more details, see the [Elasticsearch refresh documentation](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/refresh-parameter).
+
+#### delete_documents_async
+
+```python
+delete_documents_async(
+ document_ids: list[str],
+ refresh: Literal["wait_for", True, False] = "wait_for",
+) -> None
+```
+
+Asynchronously deletes all documents with a matching document_ids from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+- **refresh** (Literal['wait_for', True, False]) – Controls when changes are made visible to search operations.
+- `True`: Force refresh immediately after the operation.
+- `False`: Do not refresh (better performance for bulk operations).
+- `"wait_for"`: Wait for the next refresh cycle (default, ensures read-your-writes consistency).
+ For more details, see the [Elasticsearch refresh documentation](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/refresh-parameter).
+
+#### delete_all_documents
+
+```python
+delete_all_documents(
+ recreate_index: bool = False, refresh: bool = True
+) -> None
+```
+
+Deletes all documents in the document store.
+
+A fast way to clear all documents from the document store while preserving any index settings and mappings.
+
+**Parameters:**
+
+- **recreate_index** (bool) – If True, the index will be deleted and recreated with the original mappings and
+ settings. If False, all documents will be deleted using the `delete_by_query` API.
+- **refresh** (bool) – If True, Elasticsearch refreshes all shards involved in the delete by query after the request
+ completes. If False, no refresh is performed. For more details, see the
+ [Elasticsearch delete_by_query refresh documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-delete-by-query#operation-delete-by-query-refresh).
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async(
+ recreate_index: bool = False, refresh: bool = True
+) -> None
+```
+
+Asynchronously deletes all documents in the document store.
+
+A fast way to clear all documents from the document store while preserving any index settings and mappings.
+
+**Parameters:**
+
+- **recreate_index** (bool) – If True, the index will be deleted and recreated with the original mappings and
+ settings. If False, all documents will be deleted using the `delete_by_query` API.
+- **refresh** (bool) – If True, Elasticsearch refreshes all shards involved in the delete by query after the request
+ completes. If False, no refresh is performed. For more details, see the
+ [Elasticsearch delete_by_query refresh documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-delete-by-query#operation-delete-by-query-refresh).
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any], refresh: bool = False) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **refresh** (bool) – If True, Elasticsearch refreshes all shards involved in the delete by query after the request
+ completes. If False, no refresh is performed. For more details, see the
+ [Elasticsearch delete_by_query refresh documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-delete-by-query#operation-delete-by-query-refresh).
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any], refresh: bool = False) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **refresh** (bool) – If True, Elasticsearch refreshes all shards involved in the delete by query after the request
+ completes. If False, no refresh is performed. For more details, see the
+ [Elasticsearch refresh documentation](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/refresh-parameter).
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(
+ filters: dict[str, Any], meta: dict[str, Any], refresh: bool = False
+) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update.
+- **refresh** (bool) – If True, Elasticsearch refreshes all shards involved in the update by query after the request
+ completes. If False, no refresh is performed. For more details, see the
+ [Elasticsearch update_by_query refresh documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update-by-query#operation-update-by-query-refresh).
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(
+ filters: dict[str, Any], meta: dict[str, Any], refresh: bool = False
+) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update.
+- **refresh** (bool) – If True, Elasticsearch refreshes all shards involved in the update by query after the request
+ completes. If False, no refresh is performed. For more details, see the
+ [Elasticsearch update_by_query refresh documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update-by-query#operation-update-by-query-refresh).
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the number of unique values for each specified metadata field that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of field names to calculate unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each metadata field name to the count of its unique values among the filtered
+ documents.
+
+**Raises:**
+
+- ValueError – If any of the requested fields don't exist in the index mapping.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously returns unique value counts for each specified metadata field matching the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of field names to calculate unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each metadata field name to the count of its unique values among the filtered
+ documents.
+
+**Raises:**
+
+- ValueError – If any of the requested fields don't exist in the index mapping.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the information about the fields in the index.
+
+If we populated the index with documents like:
+
+```python
+ Document(content="Doc 1", meta={"category": "A", "status": "active", "priority": 1})
+ Document(content="Doc 2", meta={"category": "B", "status": "inactive"})
+```
+
+This method would return:
+
+```python
+ {
+ 'content': {'type': 'text'},
+ 'category': {'type': 'keyword'},
+ 'status': {'type': 'keyword'},
+ 'priority': {'type': 'long'},
+ }
+```
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – The information about the fields in the index.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns the information about the fields in the index.
+
+If we populated the index with documents like:
+
+```python
+ Document(content="Doc 1", meta={"category": "A", "status": "active", "priority": 1})
+ Document(content="Doc 2", meta={"category": "B", "status": "inactive"})
+```
+
+This method would return:
+
+```python
+ {
+ 'content': {'type': 'text'},
+ 'category': {'type': 'keyword'},
+ 'status': {'type': 'keyword'},
+ 'priority': {'type': 'long'},
+ }
+```
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – The information about the fields in the index.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, int | None]
+```
+
+Returns the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get the minimum and maximum values for.
+
+**Returns:**
+
+- dict\[str, int | None\] – A dictionary with the keys "min" and "max", where each value is the minimum or maximum value of the
+ metadata field across all documents.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, int | None]
+```
+
+Asynchronously returns the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get the minimum and maximum values for.
+
+**Returns:**
+
+- dict\[str, int | None\] – A dictionary with the keys "min" and "max", where each value is the minimum or maximum value of the
+ metadata field across all documents.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ size: int | None = 10000,
+ after: dict[str, Any] | None = None,
+) -> tuple[list[str], dict[str, Any] | None]
+```
+
+Returns unique values for a metadata field, optionally filtered by a search term in the content.
+
+Uses composite aggregations for proper pagination beyond 10k results.
+
+See: https://www.elastic.co/docs/reference/aggregations/search-aggregations-bucket-composite-aggregation
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get unique values for.
+- **search_term** (str | None) – Optional search term to filter documents by matching in the content field.
+- **size** (int | None) – The number of unique values to return per page. Defaults to 10000.
+- **after** (dict\[str, Any\] | None) – Optional pagination key from the previous response. Use None for the first page.
+ For subsequent pages, pass the `after_key` from the previous response.
+
+**Returns:**
+
+- tuple\[list\[str\], dict\[str, Any\] | None\] – A tuple containing (list of unique values, after_key for pagination).
+ The after_key is None when there are no more results. Use it in the `after` parameter
+ for the next page.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str,
+ search_term: str | None = None,
+ size: int | None = 10000,
+ after: dict[str, Any] | None = None,
+) -> tuple[list[str], dict[str, Any] | None]
+```
+
+Asynchronously returns unique values for a metadata field, optionally filtered by a search term in the content.
+
+Uses composite aggregations for proper pagination beyond 10k results.
+
+See: https://www.elastic.co/docs/reference/aggregations/search-aggregations-bucket-composite-aggregation
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get unique values for.
+- **search_term** (str | None) – Optional search term to filter documents by matching in the content field.
+- **size** (int | None) – The number of unique values to return per page. Defaults to 10000.
+- **after** (dict\[str, Any\] | None) – Optional pagination key from the previous response. Use None for the first page.
+ For subsequent pages, pass the `after_key` from the previous response.
+
+**Returns:**
+
+- tuple\[list\[str\], dict\[str, Any\] | None\] – A tuple containing (list of unique values, after_key for pagination).
+ The after_key is None when there are no more results. Use it in the `after` parameter
+ for the next page.
+
+## haystack_integrations.document_stores.elasticsearch.filters
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/faiss.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/faiss.md
new file mode 100644
index 0000000000..26f85f0c89
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/faiss.md
@@ -0,0 +1,456 @@
+---
+title: "FAISS"
+id: integrations-faiss
+description: "FAISS integration for Haystack"
+slug: "/integrations-faiss"
+---
+
+
+## haystack_integrations.components.retrievers.faiss.embedding_retriever
+
+### FAISSEmbeddingRetriever
+
+Retrieves documents from the `FAISSDocumentStore`, based on their dense embeddings.
+
+Example usage:
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack.document_stores.types import DuplicatePolicy
+
+from haystack_integrations.document_stores.faiss import FAISSDocumentStore
+from haystack_integrations.components.retrievers.faiss import FAISSEmbeddingRetriever
+
+document_store = FAISSDocumentStore(embedding_dim=768)
+
+documents = [
+ Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of intelligence."),
+ Document(content="In certain places, you can witness the phenomenon of bioluminescent waves."),
+]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+
+document_store.write_documents(documents_with_embeddings, policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", FAISSEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+res = query_pipeline.run({"text_embedder": {"text": query}})
+
+assert res["retriever"]["documents"][0].content == "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: FAISSDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize FAISSEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (FAISSDocumentStore) – An instance of `FAISSDocumentStore`.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents at initialisation time. At runtime, these are merged
+ with any runtime filters according to the `filter_policy`.
+- **top_k** (int) – Maximum number of Documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how init-time and runtime filters are combined.
+ See `FilterPolicy` for details. Defaults to `FilterPolicy.REPLACE`.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `FAISSDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FAISSEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- FAISSEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `FAISSDocumentStore`, based on their embeddings.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of Documents to return. Overrides the value set at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s that are similar to `query_embedding`.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the `FAISSDocumentStore`, based on their embeddings.
+
+Since FAISS search is CPU-bound and fully in-memory, this delegates directly to the synchronous
+`run()` method. No I/O or network calls are involved.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of Documents to return. Overrides the value set at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s that are similar to `query_embedding`.
+
+## haystack_integrations.document_stores.faiss.document_store
+
+### FAISSDocumentStore
+
+A Document Store using FAISS for vector search and a simple JSON file for metadata storage.
+
+This Document Store is suitable for small to medium-sized datasets where simplicity is preferred over scalability.
+It supports basic persistence by saving the FAISS index to a `.faiss` file and documents to a `.json` file.
+
+#### __init__
+
+```python
+__init__(
+ index_path: str | None = None,
+ index_string: str = "Flat",
+ embedding_dim: int = 768,
+) -> None
+```
+
+Initializes the FAISSDocumentStore.
+
+**Parameters:**
+
+- **index_path** (str | None) – Path to save/load the index and documents. If None, the store is in-memory only.
+- **index_string** (str) – The FAISS index factory string. Default is "Flat".
+- **embedding_dim** (int) – The dimension of the embeddings. Default is 768.
+
+**Raises:**
+
+- DocumentStoreError – If the FAISS index cannot be initialized.
+- ValueError – If `index_path` points to a missing `.faiss` file when loading persisted data.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns the number of documents in the store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – A dictionary of filters to apply.
+
+**Returns:**
+
+- list\[Document\] – A list of matching Documents.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.FAIL
+) -> int
+```
+
+Writes documents to the store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The list of documents to write.
+- **policy** (DuplicatePolicy) – The policy to handle duplicate documents.
+
+**Returns:**
+
+- int – The number of documents written.
+
+**Raises:**
+
+- ValueError – If `documents` is not an iterable of `Document` objects.
+- DuplicateDocumentError – If a duplicate document is found and `policy` is `DuplicatePolicy.FAIL`.
+- DocumentStoreError – If the FAISS index is unexpectedly unavailable when adding embeddings.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents from the store.
+
+**Raises:**
+
+- DocumentStoreError – If the FAISS index is unexpectedly unavailable when removing embeddings.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents from the store.
+
+#### search
+
+```python
+search(
+ query_embedding: list[float],
+ top_k: int = 10,
+ filters: dict[str, Any] | None = None,
+) -> list[Document]
+```
+
+Performs a vector search.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – The query embedding.
+- **top_k** (int) – The number of results to return.
+- **filters** (dict\[str, Any\] | None) – Filters to apply.
+
+**Returns:**
+
+- list\[Document\] – A list of matching Documents.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes documents that match the provided filters from the store.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – A dictionary of filters to apply to find documents to delete.
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+- DocumentStoreError – If the FAISS index is unexpectedly unavailable when removing embeddings.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – A dictionary of filters to apply.
+
+**Returns:**
+
+- int – The number of matching documents.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates documents that match the provided filters with the new metadata.
+
+Note: Updates are performed in-memory only. To persist these changes,
+you must explicitly call `save()` after updating.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – A dictionary of filters to apply to find documents to update.
+- **meta** (dict\[str, Any\]) – A dictionary of metadata key-value pairs to update in the matching documents.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, Any]]
+```
+
+Infers and returns the types of all metadata fields from the stored documents.
+
+**Returns:**
+
+- dict\[str, dict\[str, Any\]\] – A dictionary mapping field names to dictionaries with a "type" key
+ (e.g. `{"field": {"type": "long"}}`).
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(field_name: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for a specific metadata field.
+
+**Parameters:**
+
+- **field_name** (str) – The name of the metadata field.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys "min" and "max" containing the respective min and max values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(field_name: str) -> list[Any]
+```
+
+Returns all unique values for a specific metadata field.
+
+**Parameters:**
+
+- **field_name** (str) – The name of the metadata field.
+
+**Returns:**
+
+- list\[Any\] – A list of unique values for the specified field.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns a count of unique values for multiple metadata fields, optionally scoped by a filter.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – A dictionary of filters to apply.
+- **metadata_fields** (list\[str\]) – A list of metadata field names to count unique values for.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each field name to the count of its unique values.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the store to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FAISSDocumentStore
+```
+
+Deserializes the store from a dictionary.
+
+#### save
+
+```python
+save(index_path: str | Path) -> None
+```
+
+Saves the index and documents to disk.
+
+**Raises:**
+
+- DocumentStoreError – If the FAISS index is unexpectedly unavailable.
+
+#### load
+
+```python
+load(index_path: str | Path) -> None
+```
+
+Loads the index and documents from disk.
+
+**Raises:**
+
+- ValueError – If the `.faiss` file does not exist.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/falkordb.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/falkordb.md
new file mode 100644
index 0000000000..77345d32b2
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/falkordb.md
@@ -0,0 +1,401 @@
+---
+title: "FalkorDB"
+id: integrations-falkordb
+description: "FalkorDB integration for Haystack"
+slug: "/integrations-falkordb"
+---
+
+
+## haystack_integrations.components.retrievers.falkordb.cypher_retriever
+
+### FalkorDBCypherRetriever
+
+A power-user retriever for executing arbitrary OpenCypher queries against FalkorDB.
+
+This retriever allows you to leverage graph traversal and multi-hop queries in
+GraphRAG pipelines. The query must return nodes or dictionaries that can be
+mapped exactly to a Haystack `Document`.
+
+**Security Warning:** Raw Cypher queries must only come from trusted sources. Do
+not use un-sanitised user input directly in query strings. Use `parameters` instead.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.falkordb import FalkorDBDocumentStore
+from haystack_integrations.components.retrievers.falkordb import FalkorDBCypherRetriever
+
+store = FalkorDBDocumentStore(host="localhost", port=6379)
+retriever = FalkorDBCypherRetriever(
+ document_store=store,
+ custom_cypher_query="MATCH (d:Document)-[:RELATES_TO]->(:Concept {name: $concept}) RETURN d"
+)
+
+res = retriever.run(parameters={"concept": "GraphRAG"})
+print(res["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: FalkorDBDocumentStore,
+ custom_cypher_query: str | None = None,
+) -> None
+```
+
+Create a new FalkorDBCypherRetriever.
+
+**Parameters:**
+
+- **document_store** (FalkorDBDocumentStore) – The FalkorDBDocumentStore instance.
+- **custom_cypher_query** (str | None) – A static OpenCypher query to execute. Can be
+ overridden at runtime by passing `query` to `run()`.
+
+**Raises:**
+
+- ValueError – If the provided `document_store` is not a `FalkorDBDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialise the retriever to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary representation of the retriever.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FalkorDBCypherRetriever
+```
+
+Deserialise a `FalkorDBCypherRetriever` produced by `to_dict`.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Serialised retriever dictionary.
+
+**Returns:**
+
+- FalkorDBCypherRetriever – Reconstructed `FalkorDBCypherRetriever` instance.
+
+#### run
+
+```python
+run(
+ query: str | None = None, parameters: dict[str, Any] | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by executing an OpenCypher query.
+
+If a `query` is provided here, it overrides the `custom_cypher_query`
+set during initialisation.
+
+**Parameters:**
+
+- **query** (str | None) – Optional OpenCypher query string.
+- **parameters** (dict\[str, Any\] | None) – Optional dictionary of query parameters (referenced as
+ `$param_name` in the Cypher string).
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Dictionary containing a `"documents"` key with the retrieved documents.
+
+**Raises:**
+
+- ValueError – If no query string is provided (both here and at init).
+
+## haystack_integrations.components.retrievers.falkordb.embedding_retriever
+
+### FalkorDBEmbeddingRetriever
+
+A component for retrieving documents from a FalkorDBDocumentStore using vector similarity.
+
+The retriever uses FalkorDB's native vector search index to find documents whose embeddings
+are most similar to the provided query embedding.
+
+Usage example:
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.document_stores.falkordb import FalkorDBDocumentStore
+from haystack_integrations.components.retrievers.falkordb import FalkorDBEmbeddingRetriever
+
+store = FalkorDBDocumentStore(host="localhost", port=6379)
+store.write_documents([
+ Document(content="GraphRAG is powerful.", embedding=[0.1, 0.2, 0.3]),
+ Document(content="FalkorDB is fast.", embedding=[0.8, 0.9, 0.1]),
+])
+
+retriever = FalkorDBEmbeddingRetriever(document_store=store)
+res = retriever.run(query_embedding=[0.1, 0.2, 0.3])
+print(res["documents"][0].content) # "GraphRAG is powerful."
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: FalkorDBDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Create a new FalkorDBEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (FalkorDBDocumentStore) – The FalkorDBDocumentStore instance.
+- **filters** (dict\[str, Any\] | None) – Optional Haystack filters to narrow down the search space.
+- **top_k** (int) – Maximum number of documents to retrieve.
+- **filter_policy** (FilterPolicy) – Policy to determine how runtime filters are combined with
+ initialization filters.
+
+**Raises:**
+
+- ValueError – If the provided `document_store` is not a `FalkorDBDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialise the retriever to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary representation of the retriever.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FalkorDBEmbeddingRetriever
+```
+
+Deserialise a `FalkorDBEmbeddingRetriever` produced by `to_dict`.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Serialised retriever dictionary.
+
+**Returns:**
+
+- FalkorDBEmbeddingRetriever – Reconstructed `FalkorDBEmbeddingRetriever` instance.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by vector similarity.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Query embedding vector.
+- **filters** (dict\[str, Any\] | None) – Optional Haystack filters to be combined with the init filters based
+ on the configured filter policy.
+- **top_k** (int | None) – Maximum number of documents to return. If not provided, the default
+ top_k from initialization is used.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Dictionary containing a `"documents"` key with the retrieved documents.
+
+## haystack_integrations.document_stores.falkordb.document_store
+
+### FalkorDBDocumentStore
+
+Bases: DocumentStore
+
+A Haystack DocumentStore backed by FalkorDB — a high-performance graph database.
+
+Optimised for GraphRAG workloads.
+
+Documents are stored as graph nodes (labelled `Document` by default) in a named
+FalkorDB graph. Document properties, including `meta` fields, are stored
+**flat** at the same level as `id` and `content` — exactly the same layout as
+the `neo4j-haystack` reference integration.
+
+Vector search is performed via FalkorDB's native vector index —
+**no APOC is required**. All bulk writes use `UNWIND` + `MERGE` for safe,
+idiomatic OpenCypher upserts.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.falkordb import FalkorDBDocumentStore
+from haystack.dataclasses import Document
+
+store = FalkorDBDocumentStore(host="localhost", port=6379)
+store.write_documents([
+ Document(content="Hello, GraphRAG!", meta={"year": 2024}),
+])
+print(store.count_documents()) # 1
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ host: str = "localhost",
+ port: int = 6379,
+ graph_name: str = "haystack",
+ username: str | None = None,
+ password: Secret | None = None,
+ node_label: str = "Document",
+ embedding_dim: int = 768,
+ embedding_field: str = "embedding",
+ similarity: SimilarityFunction = "cosine",
+ write_batch_size: int = 100,
+ recreate_graph: bool = False,
+ verify_connectivity: bool = False
+) -> None
+```
+
+Create a new FalkorDBDocumentStore.
+
+**Parameters:**
+
+- **host** (str) – Hostname of the FalkorDB server.
+- **port** (int) – Port the FalkorDB server listens on.
+- **graph_name** (str) – Name of the FalkorDB graph to use. Each graph is an isolated
+ namespace.
+- **username** (str | None) – Optional username for FalkorDB authentication.
+- **password** (Secret | None) – Optional :class:`haystack.utils.Secret` holding the FalkorDB
+ password. The secret value is resolved lazily on first connection.
+- **node_label** (str) – Label used for document nodes in the graph.
+- **embedding_dim** (int) – Dimensionality of the vector embeddings. Used when
+ creating the vector index.
+- **embedding_field** (str) – Name of the node property that stores the embedding
+ vector.
+- **similarity** (SimilarityFunction) – Similarity function for the vector index. Accepted values
+ are `"cosine"` and `"euclidean"`.
+- **write_batch_size** (int) – Number of documents written per `UNWIND` batch.
+- **recreate_graph** (bool) – When `True` the existing graph (and all its data) is
+ dropped and recreated on initialisation. Useful for tests.
+- **verify_connectivity** (bool) – When `True` a connectivity probe is run
+ immediately in `__init__` — raises if the server is unreachable.
+
+**Raises:**
+
+- ValueError – If `similarity` is not `"cosine"` or `"euclidean"`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialise the store to a dictionary suitable for `from_dict`.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary representation of the store.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FalkorDBDocumentStore
+```
+
+Deserialise a `FalkorDBDocumentStore` produced by `to_dict`.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Serialised store dictionary.
+
+**Returns:**
+
+- FalkorDBDocumentStore – Reconstructed `FalkorDBDocumentStore` instance.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Return the number of documents currently stored in the graph.
+
+**Returns:**
+
+- int – Integer count of document nodes.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Retrieve all documents that match the provided Haystack filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Optional Haystack filter dict. When `None` all documents are
+ returned. For filter syntax see
+ [Metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- list\[Document\] – List of matching :class:`haystack.dataclasses.Document` objects.
+
+**Raises:**
+
+- ValueError – If the filter dict is malformed.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to the FalkorDB graph using `UNWIND` + `MERGE` for batching.
+
+Document `meta` fields are stored **flat** at the same level as `id` and
+`content` — no prefix is added. This matches the layout used by the
+`neo4j-haystack` reference integration.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of :class:`haystack.dataclasses.Document` objects.
+- **policy** (DuplicatePolicy) – How to handle documents whose `id` already exists.
+ Defaults to :attr:`DuplicatePolicy.NONE` (treated as FAIL).
+
+**Returns:**
+
+- int – Number of documents written or updated.
+
+**Raises:**
+
+- ValueError – If `documents` contains non-Document elements.
+- DuplicateDocumentError – If `policy` is FAIL / NONE and a duplicate
+ ID is encountered.
+- DocumentStoreError – If any other DB error occurs.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents by their IDs using a single `UNWIND`-based query.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – List of document IDs to remove from the graph.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/fastembed.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/fastembed.md
new file mode 100644
index 0000000000..b49abfcb72
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/fastembed.md
@@ -0,0 +1,701 @@
+---
+title: "FastEmbed"
+id: fastembed-embedders
+description: "FastEmbed integration for Haystack"
+slug: "/fastembed-embedders"
+---
+
+
+## haystack_integrations.components.embedders.fastembed.fastembed_document_embedder
+
+### FastembedDocumentEmbedder
+
+FastembedDocumentEmbedder computes Document embeddings using Fastembed embedding models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+# To use this component, install the "fastembed-haystack" package.
+# pip install fastembed-haystack
+
+from haystack_integrations.components.embedders.fastembed import FastembedDocumentEmbedder
+from haystack.dataclasses import Document
+
+doc_embedder = FastembedDocumentEmbedder(
+ model="BAAI/bge-small-en-v1.5",
+ batch_size=256,
+)
+
+# Text taken from PubMed QA Dataset (https://huggingface.co/datasets/pubmed_qa)
+document_list = [
+ Document(
+ content=("Oxidative stress generated within inflammatory joints can produce autoimmune phenomena and joint "
+ "destruction. Radical species with oxidative activity, including reactive nitrogen species, "
+ "represent mediators of inflammation and cartilage damage."),
+ meta={
+ "pubid": "25,445,628",
+ "long_answer": "yes",
+ },
+ ),
+ Document(
+ content=("Plasma levels of pancreatic polypeptide (PP) rise upon food intake. Although other pancreatic "
+ "islet hormones, such as insulin and glucagon, have been extensively investigated, PP secretion "
+ "and actions are still poorly understood."),
+ meta={
+ "pubid": "25,445,712",
+ "long_answer": "yes",
+ },
+ ),
+]
+
+result = doc_embedder.run(document_list)
+print(f"Document Text: {result['documents'][0].content}")
+print(f"Document Embedding: {result['documents'][0].embedding}")
+print(f"Embedding Dimension: {len(result['documents'][0].embedding)}")
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "BAAI/bge-small-en-v1.5",
+ cache_dir: str | None = None,
+ threads: int | None = None,
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 256,
+ progress_bar: bool = True,
+ parallel: int | None = None,
+ local_files_only: bool = False,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+) -> None
+```
+
+Create an FastembedDocumentEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – Local path or name of the model in Hugging Face's model hub,
+ such as `BAAI/bge-small-en-v1.5`.
+- **cache_dir** (str | None) – The path to the cache directory.
+ Can be set using the `FASTEMBED_CACHE_PATH` env variable.
+ Defaults to `fastembed_cache` in the system's temp directory.
+- **threads** (int | None) – The number of threads single onnxruntime session can use. Defaults to None.
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **batch_size** (int) – Number of strings to encode at once.
+- **progress_bar** (bool) – If `True`, displays progress bar during embedding.
+- **parallel** (int | None) – If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets.
+ If 0, use all available cores.
+ If None, don't use data-parallel processing, use default onnxruntime threading instead.
+- **local_files_only** (bool) – If `True`, only use the model files in the `cache_dir`.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be embedded along with the Document content.
+- **embedding_separator** (str) – Separator used to concatenate the meta fields to the Document content.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embeds a list of Documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents with each Document's `embedding` field set to the computed embeddings.
+
+**Raises:**
+
+- TypeError – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.fastembed.fastembed_sparse_document_embedder
+
+### FastembedSparseDocumentEmbedder
+
+FastembedSparseDocumentEmbedder computes Document embeddings using Fastembed sparse models.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.fastembed import FastembedSparseDocumentEmbedder
+from haystack.dataclasses import Document
+
+sparse_doc_embedder = FastembedSparseDocumentEmbedder(
+ model="prithivida/Splade_PP_en_v1",
+ batch_size=32,
+)
+
+# Text taken from PubMed QA Dataset (https://huggingface.co/datasets/pubmed_qa)
+document_list = [
+ Document(
+ content=("Oxidative stress generated within inflammatory joints can produce autoimmune phenomena and joint "
+ "destruction. Radical species with oxidative activity, including reactive nitrogen species, "
+ "represent mediators of inflammation and cartilage damage."),
+ meta={
+ "pubid": "25,445,628",
+ "long_answer": "yes",
+ },
+ ),
+ Document(
+ content=("Plasma levels of pancreatic polypeptide (PP) rise upon food intake. Although other pancreatic "
+ "islet hormones, such as insulin and glucagon, have been extensively investigated, PP secretion "
+ "and actions are still poorly understood."),
+ meta={
+ "pubid": "25,445,712",
+ "long_answer": "yes",
+ },
+ ),
+]
+
+result = sparse_doc_embedder.run(document_list)
+print(f"Document Text: {result['documents'][0].content}")
+print(f"Document Sparse Embedding: {result['documents'][0].sparse_embedding}")
+print(f"Sparse Embedding Dimension: {len(result['documents'][0].sparse_embedding)}")
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "prithivida/Splade_PP_en_v1",
+ cache_dir: str | None = None,
+ threads: int | None = None,
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ parallel: int | None = None,
+ local_files_only: bool = False,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ model_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Create an FastembedDocumentEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – Local path or name of the model in Hugging Face's model hub,
+ such as `prithivida/Splade_PP_en_v1`.
+- **cache_dir** (str | None) – The path to the cache directory.
+ Can be set using the `FASTEMBED_CACHE_PATH` env variable.
+ Defaults to `fastembed_cache` in the system's temp directory.
+- **threads** (int | None) – The number of threads single onnxruntime session can use.
+- **batch_size** (int) – Number of strings to encode at once.
+- **progress_bar** (bool) – If `True`, displays progress bar during embedding.
+- **parallel** (int | None) – If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets.
+ If 0, use all available cores.
+ If None, don't use data-parallel processing, use default onnxruntime threading instead.
+- **local_files_only** (bool) – If `True`, only use the model files in the `cache_dir`.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be embedded along with the Document content.
+- **embedding_separator** (str) – Separator used to concatenate the meta fields to the Document content.
+- **model_kwargs** (dict\[str, Any\] | None) – Dictionary containing model parameters such as `k`, `b`, `avg_len`, `language`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embeds a list of Documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents with each Document's `sparse_embedding`
+ field set to the computed embeddings.
+
+**Raises:**
+
+- TypeError – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.fastembed.fastembed_sparse_text_embedder
+
+### FastembedSparseTextEmbedder
+
+FastembedSparseTextEmbedder computes string embedding using fastembed sparse models.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.fastembed import FastembedSparseTextEmbedder
+
+text = ("It clearly says online this will work on a Mac OS system. "
+ "The disk comes and it does not, only Windows. Do Not order this if you have a Mac!!")
+
+sparse_text_embedder = FastembedSparseTextEmbedder(
+ model="prithivida/Splade_PP_en_v1"
+)
+
+sparse_embedding = sparse_text_embedder.run(text)["sparse_embedding"]
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "prithivida/Splade_PP_en_v1",
+ cache_dir: str | None = None,
+ threads: int | None = None,
+ progress_bar: bool = True,
+ parallel: int | None = None,
+ local_files_only: bool = False,
+ model_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Create a FastembedSparseTextEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – Local path or name of the model in Fastembed's model hub, such as `prithivida/Splade_PP_en_v1`
+- **cache_dir** (str | None) – The path to the cache directory.
+ Can be set using the `FASTEMBED_CACHE_PATH` env variable.
+ Defaults to `fastembed_cache` in the system's temp directory.
+- **threads** (int | None) – The number of threads single onnxruntime session can use. Defaults to None.
+- **progress_bar** (bool) – If `True`, displays progress bar during embedding.
+- **parallel** (int | None) – If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets.
+ If 0, use all available cores.
+ If None, don't use data-parallel processing, use default onnxruntime threading instead.
+- **local_files_only** (bool) – If `True`, only use the model files in the `cache_dir`.
+- **model_kwargs** (dict\[str, Any\] | None) – Dictionary containing model parameters such as `k`, `b`, `avg_len`, `language`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, SparseEmbedding]
+```
+
+Embeds text using the Fastembed model.
+
+**Parameters:**
+
+- **text** (str) – A string to embed.
+
+**Returns:**
+
+- dict\[str, SparseEmbedding\] – A dictionary with the following keys:
+- `embedding`: A list of floats representing the embedding of the input text.
+
+**Raises:**
+
+- TypeError – If the input is not a string.
+
+## haystack_integrations.components.embedders.fastembed.fastembed_text_embedder
+
+### FastembedTextEmbedder
+
+FastembedTextEmbedder computes string embedding using fastembed embedding models.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.fastembed import FastembedTextEmbedder
+
+text = ("It clearly says online this will work on a Mac OS system. "
+ "The disk comes and it does not, only Windows. Do Not order this if you have a Mac!!")
+
+text_embedder = FastembedTextEmbedder(
+ model="BAAI/bge-small-en-v1.5"
+)
+
+embedding = text_embedder.run(text)["embedding"]
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "BAAI/bge-small-en-v1.5",
+ cache_dir: str | None = None,
+ threads: int | None = None,
+ prefix: str = "",
+ suffix: str = "",
+ progress_bar: bool = True,
+ parallel: int | None = None,
+ local_files_only: bool = False,
+) -> None
+```
+
+Create a FastembedTextEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – Local path or name of the model in Fastembed's model hub, such as `BAAI/bge-small-en-v1.5`
+- **cache_dir** (str | None) – The path to the cache directory.
+ Can be set using the `FASTEMBED_CACHE_PATH` env variable.
+ Defaults to `fastembed_cache` in the system's temp directory.
+- **threads** (int | None) – The number of threads single onnxruntime session can use. Defaults to None.
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **progress_bar** (bool) – If `True`, displays progress bar during embedding.
+- **parallel** (int | None) – If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets.
+ If 0, use all available cores.
+ If None, don't use data-parallel processing, use default onnxruntime threading instead.
+- **local_files_only** (bool) – If `True`, only use the model files in the `cache_dir`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float]]
+```
+
+Embeds text using the Fastembed model.
+
+**Parameters:**
+
+- **text** (str) – A string to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\]\] – A dictionary with the following keys:
+- `embedding`: A list of floats representing the embedding of the input text.
+
+**Raises:**
+
+- TypeError – If the input is not a string.
+
+## haystack_integrations.components.rankers.fastembed.late_interaction_ranker
+
+### FastembedLateInteractionRanker
+
+Ranks Documents based on their similarity to the query using ColBERT models via Fastembed.
+
+Uses late interaction (MaxSim) scoring to compute token-level similarity between
+query and document embeddings, then ranks documents accordingly.
+
+See https://qdrant.github.io/fastembed/examples/Supported_Models/ for supported models.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.fastembed import FastembedLateInteractionRanker
+
+ranker = FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0", top_k=2)
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "What is the capital of germany?"
+output = ranker.run(query=query, documents=docs)
+print(output["documents"][0].content)
+
+# Berlin
+```
+
+#### __init__
+
+```python
+__init__(
+ model_name: str = "colbert-ir/colbertv2.0",
+ top_k: int = 10,
+ cache_dir: str | None = None,
+ threads: int | None = None,
+ batch_size: int = 64,
+ parallel: int | None = None,
+ local_files_only: bool = False,
+ meta_fields_to_embed: list[str] | None = None,
+ meta_data_separator: str = "\n",
+ score_threshold: float | None = None,
+) -> None
+```
+
+Creates an instance of the 'FastembedLateInteractionRanker'.
+
+**Parameters:**
+
+- **model_name** (str) – Fastembed ColBERT model name. Check the list of supported models in the
+ [Fastembed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+- **top_k** (int) – The maximum number of documents to return.
+- **cache_dir** (str | None) – The path to the cache directory.
+ Can be set using the `FASTEMBED_CACHE_PATH` env variable.
+ Defaults to `fastembed_cache` in the system's temp directory.
+- **threads** (int | None) – The number of threads single onnxruntime session can use. Defaults to None.
+- **batch_size** (int) – Number of strings to encode at once.
+- **parallel** (int | None) – If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets.
+ If 0, use all available cores.
+ If None, don't use data-parallel processing, use default onnxruntime threading instead.
+- **local_files_only** (bool) – If `True`, only use the model files in the `cache_dir`.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be concatenated
+ with the document content for reranking.
+- **meta_data_separator** (str) – Separator used to concatenate the meta fields
+ to the Document content.
+- **score_threshold** (float | None) – If provided, only documents with a score above the threshold are returned.
+ Note that ColBERT scores are unnormalized sums and typically range from 3 to 25.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FastembedLateInteractionRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- FastembedLateInteractionRanker – The deserialized component.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(
+ query: str, documents: list[Document], top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Returns a list of documents ranked by their similarity to the given query using ColBERT MaxSim scoring.
+
+**Parameters:**
+
+- **query** (str) – The input query to compare the documents to.
+- **documents** (list\[Document\]) – A list of documents to be ranked.
+- **top_k** (int | None) – The maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: A list of documents closest to the query, sorted from most similar to least similar.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+
+## haystack_integrations.components.rankers.fastembed.ranker
+
+### FastembedRanker
+
+Ranks Documents based on their similarity to the query using Fastembed models.
+
+See https://qdrant.github.io/fastembed/examples/Supported_Models/ for supported models.
+
+Documents are indexed from most to least semantically relevant to the query.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.fastembed import FastembedRanker
+
+ranker = FastembedRanker(model_name="Xenova/ms-marco-MiniLM-L-6-v2", top_k=2)
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "What is the capital of germany?"
+output = ranker.run(query=query, documents=docs)
+print(output["documents"][0].content)
+
+# Berlin
+```
+
+#### __init__
+
+```python
+__init__(
+ model_name: str = "Xenova/ms-marco-MiniLM-L-6-v2",
+ top_k: int = 10,
+ cache_dir: str | None = None,
+ threads: int | None = None,
+ batch_size: int = 64,
+ parallel: int | None = None,
+ local_files_only: bool = False,
+ meta_fields_to_embed: list[str] | None = None,
+ meta_data_separator: str = "\n",
+ score_threshold: float | None = None,
+) -> None
+```
+
+Creates an instance of the 'FastembedRanker'.
+
+**Parameters:**
+
+- **model_name** (str) – Fastembed model name. Check the list of supported models in the [Fastembed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+- **top_k** (int) – The maximum number of documents to return.
+- **cache_dir** (str | None) – The path to the cache directory.
+ Can be set using the `FASTEMBED_CACHE_PATH` env variable.
+ Defaults to `fastembed_cache` in the system's temp directory.
+- **threads** (int | None) – The number of threads single onnxruntime session can use. Defaults to None.
+- **batch_size** (int) – Number of strings to encode at once.
+- **parallel** (int | None) – If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets.
+ If 0, use all available cores.
+ If None, don't use data-parallel processing, use default onnxruntime threading instead.
+- **local_files_only** (bool) – If `True`, only use the model files in the `cache_dir`.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be concatenated
+ with the document content for reranking.
+- **meta_data_separator** (str) – Separator used to concatenate the meta fields
+ to the Document content.
+- **score_threshold** (float | None) – If provided, only documents with a score above the threshold are returned.
+ Applied after `top_k`, so the output may contain fewer than `top_k` documents.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FastembedRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- FastembedRanker – The deserialized component.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### run
+
+```python
+run(
+ query: str, documents: list[Document], top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Returns a list of documents ranked by their similarity to the given query, using FastEmbed.
+
+**Parameters:**
+
+- **query** (str) – The input query to compare the documents to.
+- **documents** (list\[Document\]) – A list of documents to be ranked.
+- **top_k** (int | None) – The maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: A list of documents closest to the query, sorted from most similar to least similar.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/firecrawl.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/firecrawl.md
new file mode 100644
index 0000000000..4910b4016c
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/firecrawl.md
@@ -0,0 +1,206 @@
+---
+title: "Firecrawl"
+id: integrations-firecrawl
+description: "Firecrawl integration for Haystack"
+slug: "/integrations-firecrawl"
+---
+
+
+## haystack_integrations.components.fetchers.firecrawl.firecrawl_crawler
+
+### FirecrawlCrawler
+
+A component that uses Firecrawl to crawl one or more URLs and return the content as Haystack Documents.
+
+Crawling starts from each given URL and follows links to discover subpages, up to a configurable limit.
+This is useful for ingesting entire websites or documentation sites, not just single pages.
+
+Firecrawl is a service that crawls websites and returns content in a structured format (e.g. Markdown)
+suitable for LLMs. You need a Firecrawl API key from [firecrawl.dev](https://firecrawl.dev).
+
+### Usage example
+
+```python
+from haystack_integrations.components.fetchers.firecrawl import FirecrawlFetcher
+
+fetcher = FirecrawlFetcher(
+ api_key=Secret.from_env_var("FIRECRAWL_API_KEY"),
+ params={"limit": 5},
+)
+fetcher.warm_up()
+
+result = fetcher.run(urls=["https://docs.haystack.deepset.ai/docs/intro"])
+documents = result["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("FIRECRAWL_API_KEY"),
+ params: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the FirecrawlFetcher.
+
+**Parameters:**
+
+- **api_key** (Secret) – API key for Firecrawl.
+ Defaults to the `FIRECRAWL_API_KEY` environment variable.
+- **params** (dict\[str, Any\] | None) – Parameters for the crawl request. See the
+ [Firecrawl API reference](https://docs.firecrawl.dev/api-reference/endpoint/crawl-post)
+ for available parameters.
+ Defaults to `{"limit": 1, "scrape_options": {"formats": ["markdown"]}}`.
+ Without a limit, Firecrawl may crawl all subpages and consume credits quickly.
+
+#### run
+
+```python
+run(urls: list[str], params: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Crawls the given URLs and returns the extracted content as Documents.
+
+**Parameters:**
+
+- **urls** (list\[str\]) – List of URLs to crawl.
+- **params** (dict\[str, Any\] | None) – Optional override of crawl parameters for this run.
+ If provided, fully replaces the init-time params.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of documents, one for each URL crawled.
+
+#### run_async
+
+```python
+run_async(
+ urls: list[str], params: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously crawls the given URLs and returns the extracted content as Documents.
+
+**Parameters:**
+
+- **urls** (list\[str\]) – List of URLs to crawl.
+- **params** (dict\[str, Any\] | None) – Optional override of crawl parameters for this run.
+ If provided, fully replaces the init-time params.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of documents, one for each URL crawled.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Firecrawl client by initializing the clients.
+This is useful to avoid cold start delays when crawling many URLs.
+
+## haystack_integrations.components.websearch.firecrawl.firecrawl_websearch
+
+### FirecrawlWebSearch
+
+A component that uses Firecrawl to search the web and return results as Haystack Documents.
+
+This component wraps the Firecrawl Search API, enabling web search queries that return
+structured documents with content and links. It follows the standard Haystack WebSearch
+component interface.
+
+Firecrawl is a service that crawls and scrapes websites, returning content in formats suitable
+for LLMs. You need a Firecrawl API key from [firecrawl.dev](https://firecrawl.dev).
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.firecrawl import FirecrawlWebSearch
+from haystack.utils import Secret
+
+websearch = FirecrawlWebSearch(
+ api_key=Secret.from_env_var("FIRECRAWL_API_KEY"),
+ top_k=5,
+)
+result = websearch.run(query="What is Haystack by deepset?")
+documents = result["documents"]
+links = result["links"]
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("FIRECRAWL_API_KEY"),
+ top_k: int | None = 10,
+ search_params: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the FirecrawlWebSearch component.
+
+**Parameters:**
+
+- **api_key** (Secret) – API key for Firecrawl.
+ Defaults to the `FIRECRAWL_API_KEY` environment variable.
+- **top_k** (int | None) – Maximum number of documents to return.
+ Defaults to 10. This can be overridden by the `"limit"` parameter in `search_params`.
+- **search_params** (dict\[str, Any\] | None) – Additional parameters passed to the Firecrawl search API.
+ See the [Firecrawl API reference](https://docs.firecrawl.dev/api-reference/endpoint/search)
+ for available parameters. Supported keys include: `tbs`, `location`,
+ `scrape_options`, `sources`, `categories`, `timeout`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Firecrawl clients by initializing the sync and async clients.
+This is useful to avoid cold start delays when performing searches.
+
+#### run
+
+```python
+run(query: str, search_params: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Search the web using Firecrawl and return results as Documents.
+
+**Parameters:**
+
+- **query** (str) – Search query string.
+- **search_params** (dict\[str, Any\] | None) – Optional override of search parameters for this run.
+ If provided, fully replaces the init-time search_params.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of documents with search result content.
+- `links`: List of URLs from the search results.
+
+#### run_async
+
+```python
+run_async(
+ query: str, search_params: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously search the web using Firecrawl and return results as Documents.
+
+**Parameters:**
+
+- **query** (str) – Search query string.
+- **search_params** (dict\[str, Any\] | None) – Optional override of search parameters for this run.
+ If provided, fully replaces the init-time search_params.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of documents with search result content.
+- `links`: List of URLs from the search results.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/github.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/github.md
new file mode 100644
index 0000000000..45e2f50d42
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/github.md
@@ -0,0 +1,687 @@
+---
+title: "GitHub"
+id: integrations-github
+description: "GitHub integration for Haystack"
+slug: "/integrations-github"
+---
+
+
+
+## Module haystack\_integrations.components.connectors.github.file\_editor
+
+
+
+### Command
+
+Available commands for file operations in GitHub.
+
+**Attributes**:
+
+- `EDIT` - Edit an existing file by replacing content
+- `UNDO` - Revert the last commit if made by the same user
+- `CREATE` - Create a new file
+- `DELETE` - Delete an existing file
+
+
+
+### GitHubFileEditor
+
+A Haystack component for editing files in GitHub repositories.
+
+Supports editing, undoing changes, deleting files, and creating new files
+through the GitHub API.
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import Command, GitHubFileEditor
+from haystack.utils import Secret
+
+# Initialize with default repo and branch
+editor = GitHubFileEditor(
+ github_token=Secret.from_env_var("GITHUB_TOKEN"),
+ repo="owner/repo",
+ branch="main"
+)
+
+# Edit a file using default repo and branch
+result = editor.run(
+ command=Command.EDIT,
+ payload={
+ "path": "path/to/file.py",
+ "original": "def old_function():",
+ "replacement": "def new_function():",
+ "message": "Renamed function for clarity"
+ }
+)
+
+# Edit a file in a different repo/branch
+result = editor.run(
+ command=Command.EDIT,
+ repo="other-owner/other-repo", # Override default repo
+ branch="feature", # Override default branch
+ payload={
+ "path": "path/to/file.py",
+ "original": "def old_function():",
+ "replacement": "def new_function():",
+ "message": "Renamed function for clarity"
+ }
+)
+```
+
+
+
+#### GitHubFileEditor.\_\_init\_\_
+
+```python
+def __init__(*,
+ github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+ repo: str | None = None,
+ branch: str = "main",
+ raise_on_failure: bool = True)
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for API authentication
+- `repo`: Default repository in owner/repo format
+- `branch`: Default branch to work with
+- `raise_on_failure`: If True, raises exceptions on API errors
+
+**Raises**:
+
+- `TypeError`: If github_token is not a Secret
+
+
+
+#### GitHubFileEditor.run
+
+```python
+@component.output_types(result=str)
+def run(command: Command | str,
+ payload: dict[str, Any],
+ repo: str | None = None,
+ branch: str | None = None) -> dict[str, str]
+```
+
+Process GitHub file operations.
+
+**Arguments**:
+
+- `command`: Operation to perform ("edit", "undo", "create", "delete")
+- `payload`: Dictionary containing command-specific parameters
+- `repo`: Repository in owner/repo format (overrides default if provided)
+- `branch`: Branch to perform operations on (overrides default if provided)
+
+**Raises**:
+
+- `ValueError`: If command is not a valid Command enum value
+
+**Returns**:
+
+Dictionary containing operation result
+
+
+
+#### GitHubFileEditor.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+
+
+#### GitHubFileEditor.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubFileEditor"
+```
+
+Deserialize the component from a dictionary.
+
+
+
+## Module haystack\_integrations.components.connectors.github.issue\_commenter
+
+
+
+### GitHubIssueCommenter
+
+Posts comments to GitHub issues.
+
+The component takes a GitHub issue URL and comment text, then posts the comment
+to the specified issue using the GitHub API.
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import GitHubIssueCommenter
+from haystack.utils import Secret
+
+commenter = GitHubIssueCommenter(github_token=Secret.from_env_var("GITHUB_TOKEN"))
+result = commenter.run(
+ url="https://github.com/owner/repo/issues/123",
+ comment="Thanks for reporting this issue! We'll look into it."
+)
+
+print(result["success"])
+```
+
+
+
+#### GitHubIssueCommenter.\_\_init\_\_
+
+```python
+def __init__(*,
+ github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+ raise_on_failure: bool = True,
+ retry_attempts: int = 2)
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for API authentication as a Secret
+- `raise_on_failure`: If True, raises exceptions on API errors
+- `retry_attempts`: Number of retry attempts for failed requests
+
+
+
+#### GitHubIssueCommenter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### GitHubIssueCommenter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubIssueCommenter"
+```
+
+Deserialize the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### GitHubIssueCommenter.run
+
+```python
+@component.output_types(success=bool)
+def run(url: str, comment: str) -> dict
+```
+
+Post a comment to a GitHub issue.
+
+**Arguments**:
+
+- `url`: GitHub issue URL
+- `comment`: Comment text to post
+
+**Returns**:
+
+Dictionary containing success status
+
+
+
+## Module haystack\_integrations.components.connectors.github.issue\_viewer
+
+
+
+### GitHubIssueViewer
+
+Fetches and parses GitHub issues into Haystack documents.
+
+The component takes a GitHub issue URL and returns a list of documents where:
+- First document contains the main issue content
+- Subsequent documents contain the issue comments
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import GitHubIssueViewer
+
+viewer = GitHubIssueViewer()
+docs = viewer.run(
+ url="https://github.com/owner/repo/issues/123"
+)["documents"]
+
+print(docs)
+```
+
+
+
+#### GitHubIssueViewer.\_\_init\_\_
+
+```python
+def __init__(*,
+ github_token: Secret | None = None,
+ raise_on_failure: bool = True,
+ retry_attempts: int = 2)
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for API authentication as a Secret
+- `raise_on_failure`: If True, raises exceptions on API errors
+- `retry_attempts`: Number of retry attempts for failed requests
+
+
+
+#### GitHubIssueViewer.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### GitHubIssueViewer.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubIssueViewer"
+```
+
+Deserialize the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### GitHubIssueViewer.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(url: str) -> dict
+```
+
+Process a GitHub issue URL and return documents.
+
+**Arguments**:
+
+- `url`: GitHub issue URL
+
+**Returns**:
+
+Dictionary containing list of documents
+
+
+
+## Module haystack\_integrations.components.connectors.github.pr\_creator
+
+
+
+### GitHubPRCreator
+
+A Haystack component for creating pull requests from a fork back to the original repository.
+
+Uses the authenticated user's fork to create the PR and links it to an existing issue.
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import GitHubPRCreator
+from haystack.utils import Secret
+
+pr_creator = GitHubPRCreator(
+ github_token=Secret.from_env_var("GITHUB_TOKEN") # Token from the fork owner
+)
+
+# Create a PR from your fork
+result = pr_creator.run(
+ issue_url="https://github.com/owner/repo/issues/123",
+ title="Fix issue `123`",
+ body="This PR addresses issue `123`",
+ branch="feature-branch", # The branch in your fork with the changes
+ base="main" # The branch in the original repo to merge into
+)
+```
+
+
+
+#### GitHubPRCreator.\_\_init\_\_
+
+```python
+def __init__(*,
+ github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+ raise_on_failure: bool = True)
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for authentication (from the fork owner)
+- `raise_on_failure`: If True, raises exceptions on API errors
+
+
+
+#### GitHubPRCreator.run
+
+```python
+@component.output_types(result=str)
+def run(issue_url: str,
+ title: str,
+ branch: str,
+ base: str,
+ body: str = "",
+ draft: bool = False) -> dict[str, str]
+```
+
+Create a new pull request from your fork to the original repository, linked to the specified issue.
+
+**Arguments**:
+
+- `issue_url`: URL of the GitHub issue to link the PR to
+- `title`: Title of the pull request
+- `branch`: Name of the branch in your fork where changes are implemented
+- `base`: Name of the branch in the original repo you want to merge into
+- `body`: Additional content for the pull request description
+- `draft`: Whether to create a draft pull request
+
+**Returns**:
+
+Dictionary containing operation result
+
+
+
+#### GitHubPRCreator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+
+
+#### GitHubPRCreator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubPRCreator"
+```
+
+Deserialize the component from a dictionary.
+
+
+
+## Module haystack\_integrations.components.connectors.github.repo\_forker
+
+
+
+### GitHubRepoForker
+
+Forks a GitHub repository from an issue URL.
+
+The component takes a GitHub issue URL, extracts the repository information,
+creates or syncs a fork of that repository, and optionally creates an issue-specific branch.
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import GitHubRepoForker
+from haystack.utils import Secret
+
+# Using direct token with auto-sync and branch creation
+forker = GitHubRepoForker(
+ github_token=Secret.from_env_var("GITHUB_TOKEN"),
+ auto_sync=True,
+ create_branch=True
+)
+
+result = forker.run(url="https://github.com/owner/repo/issues/123")
+print(result)
+# Will create or sync fork and create branch "fix-123"
+```
+
+
+
+#### GitHubRepoForker.\_\_init\_\_
+
+```python
+def __init__(*,
+ github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+ raise_on_failure: bool = True,
+ wait_for_completion: bool = False,
+ max_wait_seconds: int = 300,
+ poll_interval: int = 2,
+ auto_sync: bool = True,
+ create_branch: bool = True)
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for API authentication
+- `raise_on_failure`: If True, raises exceptions on API errors
+- `wait_for_completion`: If True, waits until fork is fully created
+- `max_wait_seconds`: Maximum time to wait for fork completion in seconds
+- `poll_interval`: Time between status checks in seconds
+- `auto_sync`: If True, syncs fork with original repository if it already exists
+- `create_branch`: If True, creates a fix branch based on the issue number
+
+
+
+#### GitHubRepoForker.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### GitHubRepoForker.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubRepoForker"
+```
+
+Deserialize the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### GitHubRepoForker.run
+
+```python
+@component.output_types(repo=str, issue_branch=str)
+def run(url: str) -> dict
+```
+
+Process a GitHub issue URL and create or sync a fork of the repository.
+
+**Arguments**:
+
+- `url`: GitHub issue URL
+
+**Returns**:
+
+Dictionary containing repository path in owner/repo format
+
+
+
+## Module haystack\_integrations.components.connectors.github.repo\_viewer
+
+
+
+### GitHubItem
+
+Represents an item (file or directory) in a GitHub repository
+
+
+
+#### type
+
+"file" or "dir"
+
+
+
+### GitHubRepoViewer
+
+Navigates and fetches content from GitHub repositories.
+
+For directories:
+- Returns a list of Documents, one for each item
+- Each Document's content is the item name
+- Full path and metadata in Document.meta
+
+For files:
+- Returns a single Document
+- Document's content is the file content
+- Full path and metadata in Document.meta
+
+For errors:
+- Returns a single Document
+- Document's content is the error message
+- Document's meta contains type="error"
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import GitHubRepoViewer
+
+viewer = GitHubRepoViewer()
+
+# List directory contents - returns multiple documents
+result = viewer.run(
+ repo="owner/repository",
+ path="docs/",
+ branch="main"
+)
+print(result)
+
+# Get specific file - returns single document
+result = viewer.run(
+ repo="owner/repository",
+ path="README.md",
+ branch="main"
+)
+print(result)
+```
+
+
+
+#### GitHubRepoViewer.\_\_init\_\_
+
+```python
+def __init__(*,
+ github_token: Secret | None = None,
+ raise_on_failure: bool = True,
+ max_file_size: int = 1_000_000,
+ repo: str | None = None,
+ branch: str = "main")
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for API authentication
+- `raise_on_failure`: If True, raises exceptions on API errors
+- `max_file_size`: Maximum file size in bytes to fetch (default: 1MB)
+- `repo`: Repository in format "owner/repo"
+- `branch`: Git reference (branch, tag, commit) to use
+
+
+
+#### GitHubRepoViewer.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### GitHubRepoViewer.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubRepoViewer"
+```
+
+Deserialize the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### GitHubRepoViewer.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(path: str,
+ repo: str | None = None,
+ branch: str | None = None) -> dict[str, list[Document]]
+```
+
+Process a GitHub repository path and return documents.
+
+**Arguments**:
+
+- `repo`: Repository in format "owner/repo"
+- `path`: Path within repository (default: root)
+- `branch`: Git reference (branch, tag, commit) to use
+
+**Returns**:
+
+Dictionary containing list of documents
+
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/google_ai.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/google_ai.md
new file mode 100644
index 0000000000..871ae8eccd
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/google_ai.md
@@ -0,0 +1,346 @@
+---
+title: "Google AI"
+id: integrations-google-ai
+description: "Google AI integration for Haystack"
+slug: "/integrations-google-ai"
+---
+
+
+
+## Module haystack\_integrations.components.generators.google\_ai.gemini
+
+
+
+### GoogleAIGeminiGenerator
+
+Generates text using multimodal Gemini models through Google AI Studio.
+
+### Usage example
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.generators.google_ai import GoogleAIGeminiGenerator
+
+gemini = GoogleAIGeminiGenerator(model="gemini-2.0-flash", api_key=Secret.from_token("Secret) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
+ Not needed if using Vertex AI with Application Default Credentials.
+ Go to https://aistudio.google.com/app/apikey for a Gemini API key.
+ Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
+- **api** (Literal['gemini', 'vertex']) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (str | None) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+ Application Default Credentials.
+- **vertex_ai_location** (str | None) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+ Required when using Vertex AI with Application Default Credentials.
+- **model** (str) – The name of the model to use for calculating embeddings.
+ The default model is `gemini-embedding-001`.
+- **prefix** (str) – A string to add at the beginning of each text. It can be used to specify a task type for
+ `gemini-embedding-2`. For available task types, see
+ [Gemini documentation](https://ai.google.dev/gemini-api/docs/embeddings#task-types).
+- **suffix** (str) – A string to add at the end of each text.
+- **batch_size** (int) – Number of documents to embed at once.
+- **progress_bar** (bool) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (str) – Separator used to concatenate the metadata fields to the document text.
+- **config** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure embedding content configuration.
+ See [Google API documentation](https://googleapis.github.io/python-genai/genai.html#genai.types.EmbedContentConfig)
+ for the available options.
+ Specifying task types in `config` does not take effect for `gemini-embedding-2`.
+ See [Gemini documentation](https://ai.google.dev/gemini-api/docs/embeddings#task-types) for more
+ information.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAIDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- GoogleGenAIDocumentEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]] | dict[str, Any]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] | dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(
+ documents: list[Document],
+) -> dict[str, list[Document]] | dict[str, Any]
+```
+
+Embeds a list of documents asynchronously.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] | dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.embedders.google_genai.multimodal_document_embedder
+
+### GoogleGenAIMultimodalDocumentEmbedder
+
+Computes non-textual document embeddings using Google AI models.
+
+It supports images, PDFs, video and audio files. They are mapped to vectors in a single vector space.
+
+To embed textual documents, use the GoogleGenAIDocumentEmbedder.
+To embed a string, like a user query, use the GoogleGenAITextEmbedder.
+
+### Authentication examples
+
+**1. Gemini Developer API (API Key Authentication)**
+
+````python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+document_embedder = GoogleGenAIMultimodalDocumentEmbedder(model="gemini-embedding-2-preview")
+
+**2. Vertex AI (Application Default Credentials)**
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
+
+# Using Application Default Credentials (requires gcloud auth setup)
+document_embedder = GoogleGenAIMultimodalDocumentEmbedder(
+ api="vertex",
+ vertex_ai_project="my-project",
+ vertex_ai_location="us-central1",
+ model="gemini-embedding-2-preview"
+)
+````
+
+**3. Vertex AI (API Key Authentication)**
+
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+document_embedder = GoogleGenAIMultimodalDocumentEmbedder(
+ api="vertex",
+ model="gemini-embedding-2-preview"
+)
+```
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
+
+doc = Document(content=None, meta={"file_path": "path/to/image.jpg"})
+
+document_embedder = GoogleGenAIMultimodalDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var(
+ ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
+ ),
+ api: Literal["gemini", "vertex"] = "gemini",
+ vertex_ai_project: str | None = None,
+ vertex_ai_location: str | None = None,
+ file_path_meta_field: str = "file_path",
+ root_path: str | None = None,
+ image_size: tuple[int, int] | None = None,
+ model: str = "gemini-embedding-2",
+ batch_size: int = 6,
+ progress_bar: bool = True,
+ config: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an GoogleGenAIMultimodalDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
+ Not needed if using Vertex AI with Application Default Credentials.
+ Go to https://aistudio.google.com/app/apikey for a Gemini API key.
+ Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
+- **api** (Literal['gemini', 'vertex']) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (str | None) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+ Application Default Credentials.
+- **vertex_ai_location** (str | None) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+ Required when using Vertex AI with Application Default Credentials.
+- **file_path_meta_field** (str) – The metadata field in the Document that contains the file path to the file to embed.
+- **root_path** (str | None) – The root directory path where document files are located. If provided, file paths in
+ document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **image_size** (tuple\[int, int\] | None) – Only used for images and PDF pages. If provided, resizes the image to fit within the specified dimensions
+ (width, height) while maintaining aspect ratio. This reduces file size, memory usage, and processing time,
+ which is beneficial when working with models that have resolution constraints or when transmitting images
+ to remote services.
+- **model** (str) – The name of the model to use for calculating embeddings.
+- **batch_size** (int) – Number of documents to embed at once. Maximum batch size varies depending on the input type.
+ See [Google AI documentation](https://ai.google.dev/gemini-api/docs/embeddings#supported-modalities) for
+ more information.
+- **progress_bar** (bool) – If `True`, shows a progress bar when running.
+- **config** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure embedding content configuration.
+ You can for example set the output dimensionality of the embedding: `{"output_dimensionality": 768}`.
+ See [Google API documentation](https://googleapis.github.io/python-genai/genai.html#genai.types.EmbedContentConfig)
+ for the available options.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]] | dict[str, Any]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] | dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(
+ documents: list[Document],
+) -> dict[str, list[Document]] | dict[str, Any]
+```
+
+Embeds a list of documents asynchronously.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] | dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.embedders.google_genai.text_embedder
+
+### GoogleGenAITextEmbedder
+
+Embeds strings using Google AI models.
+
+You can use it to embed user query and send it to an embedding Retriever.
+
+### Authentication examples
+
+**1. Gemini Developer API (API Key Authentication)**
+
+````python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+text_embedder = GoogleGenAITextEmbedder(model="gemini-embedding-001")
+
+**2. Vertex AI (Application Default Credentials)**
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+# Using Application Default Credentials (requires gcloud auth setup)
+text_embedder = GoogleGenAITextEmbedder(
+ api="vertex",
+ vertex_ai_project="my-project",
+ vertex_ai_location="us-central1",
+ model="gemini-embedding-001"
+)
+````
+
+**3. Vertex AI (API Key Authentication)**
+
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+text_embedder = GoogleGenAITextEmbedder(
+ api="vertex",
+ model="gemini-embedding-001"
+)
+```
+
+### Usage example
+
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = GoogleGenAITextEmbedder()
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+# 'meta': {'model': 'gemini-embedding-001-v2',
+# 'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var(
+ ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
+ ),
+ api: Literal["gemini", "vertex"] = "gemini",
+ vertex_ai_project: str | None = None,
+ vertex_ai_location: str | None = None,
+ model: str = "gemini-embedding-001",
+ prefix: str = "",
+ suffix: str = "",
+ config: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an GoogleGenAITextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
+ Not needed if using Vertex AI with Application Default Credentials.
+ Go to https://aistudio.google.com/app/apikey for a Gemini API key.
+ Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
+- **api** (Literal['gemini', 'vertex']) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (str | None) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+ Application Default Credentials.
+- **vertex_ai_location** (str | None) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+ Required when using Vertex AI with Application Default Credentials.
+- **model** (str) – The name of the model to use for calculating embeddings.
+ The default model is `gemini-embedding-001`.
+- **prefix** (str) – A string to add at the beginning of each text. It can be used to specify a task type for
+ `gemini-embedding-2`. For available task types, see
+ [Gemini documentation](https://ai.google.dev/gemini-api/docs/embeddings#task-types).
+- **suffix** (str) – A string to add at the end of each text to embed.
+- **config** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure embedding content configuration.
+ See [Google API documentation](https://googleapis.github.io/python-genai/genai.html#genai.types.EmbedContentConfig)
+ for the available options.
+ Specifying task types in `config` does not take effect for `gemini-embedding-2`.
+ See [Gemini documentation](https://ai.google.dev/gemini-api/docs/embeddings#task-types) for more
+ information.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAITextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- GoogleGenAITextEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float]] | dict[str, Any]
+```
+
+Embeds a single string.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\]\] | dict\[str, Any\] – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, list[float]] | dict[str, Any]
+```
+
+Asynchronously embed a single string.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\]\] | dict\[str, Any\] – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.generators.google_genai.chat.chat_generator
+
+### GoogleGenAIChatGenerator
+
+A component for generating chat completions using Google's Gemini models via the Google Gen AI SDK.
+
+Supports models like gemini-2.5-flash and other Gemini variants. For Gemini 2.5 series models,
+enables thinking features via `generation_kwargs={"thinking_budget": value}`.
+
+### Thinking Support (Gemini 2.5 Series)
+
+- **Reasoning transparency**: Models can show their reasoning process
+- **Thought signatures**: Maintains thought context across multi-turn conversations with tools
+- **Configurable thinking budgets**: Control token allocation for reasoning
+
+Configure thinking behavior:
+
+- `thinking_budget: -1`: Dynamic allocation (default)
+- `thinking_budget: 0`: Disable thinking (Flash/Flash-Lite only)
+- `thinking_budget: N`: Set explicit token budget
+
+### Multi-Turn Thinking with Thought Signatures
+
+Gemini uses **thought signatures** when tools are present - encrypted "save states" that maintain
+context across turns. Include previous assistant responses in chat history for context preservation.
+
+### Authentication
+
+**Gemini Developer API**: Set `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable
+**Vertex AI**: Use `api="vertex"` with Application Default Credentials or API key
+
+### Authentication Examples
+
+**1. Gemini Developer API (API Key Authentication)**
+
+```python
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+chat_generator = GoogleGenAIChatGenerator(model="gemini-2.5-flash")
+```
+
+**2. Vertex AI (Application Default Credentials)**
+
+```python
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# Using Application Default Credentials (requires gcloud auth setup)
+chat_generator = GoogleGenAIChatGenerator(
+ api="vertex",
+ vertex_ai_project="my-project",
+ vertex_ai_location="us-central1",
+ model="gemini-2.5-flash",
+)
+```
+
+**3. Vertex AI (API Key Authentication)**
+
+```python
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+chat_generator = GoogleGenAIChatGenerator(
+ api="vertex",
+ model="gemini-2.5-flash",
+)
+```
+
+### Usage example
+
+```python
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# Initialize the chat generator with thinking support
+chat_generator = GoogleGenAIChatGenerator(
+ model="gemini-2.5-flash",
+ generation_kwargs={"thinking_budget": 1024} # Enable thinking with 1024 token budget
+)
+
+# Generate a response
+messages = [ChatMessage.from_user("Tell me about the future of AI")]
+response = chat_generator.run(messages=messages)
+print(response["replies"][0].text)
+
+# Access reasoning content if available
+message = response["replies"][0]
+if message.reasonings:
+ for reasoning in message.reasonings:
+ print("Reasoning:", reasoning.reasoning_text)
+
+# Tool usage example with thinking
+def weather_function(city: str):
+ return f"The weather in {city} is sunny and 25°C"
+
+weather_tool = Tool(
+ name="weather",
+ description="Get weather information for a city",
+ parameters={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
+ function=weather_function
+)
+
+# Can use either List[Tool] or Toolset
+chat_generator_with_tools = GoogleGenAIChatGenerator(
+ model="gemini-2.5-flash",
+ tools=[weather_tool], # or tools=Toolset([weather_tool])
+ generation_kwargs={"thinking_budget": -1} # Dynamic thinking allocation
+)
+
+messages = [ChatMessage.from_user("What's the weather in Paris?")]
+response = chat_generator_with_tools.run(messages=messages)
+```
+
+### Usage example with structured output
+
+```python
+from pydantic import BaseModel
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+class City(BaseModel):
+ name: str
+ country: str
+ population: int
+
+chat_generator = GoogleGenAIChatGenerator(
+ model="gemini-2.5-flash",
+ generation_kwargs={"response_format": City}
+)
+
+messages = [ChatMessage.from_user("Tell me about Paris")]
+response = chat_generator.run(messages=messages)
+print(response["replies"][0].text) # JSON output matching the City schema
+```
+
+### Usage example with FileContent embedded in a ChatMessage
+
+```python
+from haystack.dataclasses import ChatMessage, FileContent
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+file_content = FileContent.from_url("https://arxiv.org/pdf/2309.08632")
+chat_message = ChatMessage.from_user(content_parts=[file_content, "Summarize this paper in 100 words."])
+chat_generator = GoogleGenAIChatGenerator()
+response = chat_generator.run(messages=[chat_message])
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "gemini-3.1-pro-preview",
+ "gemini-3-flash-preview",
+ "gemini-3.1-flash-lite-preview",
+ "gemini-2.5-pro",
+ "gemini-2.5-flash",
+ "gemini-2.5-flash-lite",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+
+See https://ai.google.dev/gemini-api/docs/models for the full list of models and up-to-date model IDs.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var(
+ ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
+ ),
+ api: Literal["gemini", "vertex"] = "gemini",
+ vertex_ai_project: str | None = None,
+ vertex_ai_location: str | None = None,
+ model: str = "gemini-2.5-flash",
+ generation_kwargs: dict[str, Any] | None = None,
+ safety_settings: list[dict[str, Any]] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ tools: ToolsType | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None
+) -> None
+```
+
+Initialize a GoogleGenAIChatGenerator instance.
+
+**Parameters:**
+
+- **api_key** (Secret) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
+ Not needed if using Vertex AI with Application Default Credentials.
+ Go to https://aistudio.google.com/app/apikey for a Gemini API key.
+ Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
+- **api** (Literal['gemini', 'vertex']) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (str | None) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+ Application Default Credentials.
+- **vertex_ai_location** (str | None) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+ Required when using Vertex AI with Application Default Credentials.
+- **model** (str) – Name of the model to use (e.g., "gemini-2.5-flash")
+- **generation_kwargs** (dict\[str, Any\] | None) – Configuration for generation (temperature, max_tokens, etc.).
+ For Gemini 2.5 series, supports `thinking_budget` to configure thinking behavior:
+- `thinking_budget`: int, controls thinking token allocation
+ - `-1`: Dynamic (default for most models)
+ - `0`: Disable thinking (Flash/Flash-Lite only)
+ - Positive integer: Set explicit budget
+ For Gemini 3 series and newer, supports `thinking_level` to configure thinking depth:
+- `thinking_level`: str, controls thinking (https://ai.google.dev/gemini-api/docs/thinking#levels-budgets)
+ - `minimal`: Matches the "no thinking" setting for most queries. The model may think very minimally for
+ complex coding tasks. Minimizes latency for chat or high throughput applications.
+ - `low`: Minimizes latency and cost. Best for simple instruction following, chat, or high-throughput
+ applications.
+ - `medium`: Balanced thinking for most tasks.
+ - `high`: (Default, dynamic): Maximizes reasoning depth. The model may take significantly longer to reach
+ a first token, but the output will be more carefully reasoned.
+- **safety_settings** (list\[dict\[str, Any\]\] | None) – Safety settings for content filtering
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ Each tool should have a unique name.
+- **timeout** (float | None) – Timeout for Google GenAI client calls. If not set, it defaults to the default set by the Google GenAI
+ client.
+- **max_retries** (int | None) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by
+ the Google GenAI client.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAIChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- GoogleGenAIChatGenerator – Deserialized component.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ safety_settings: list[dict[str, Any]] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ tools: ToolsType | None = None,
+) -> dict[str, Any]
+```
+
+Run the Google Gen AI chat generator on the given input data.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Configuration for generation. If provided, it will override
+ the default config. Supports `thinking_budget` for Gemini 2.5 series thinking configuration.
+- **safety_settings** (list\[dict\[str, Any\]\] | None) – Safety settings for content filtering. If provided, it will override the
+ default settings.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is
+ received from the stream.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If provided, it will override the tools set during initialization.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `replies`: A list containing the generated ChatMessage responses.
+
+**Raises:**
+
+- RuntimeError – If there is an error in the Google Gen AI chat generation.
+- ValueError – If a ChatMessage does not contain at least one of TextContent, ToolCall, or
+ ToolCallResult or if the role in ChatMessage is different from User, System, Assistant.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ safety_settings: list[dict[str, Any]] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ tools: ToolsType | None = None,
+) -> dict[str, Any]
+```
+
+Async version of the run method. Run the Google Gen AI chat generator on the given input data.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Configuration for generation. If provided, it will override
+ the default config. Supports `thinking_budget` for Gemini 2.5 series thinking configuration.
+ See https://ai.google.dev/gemini-api/docs/thinking for possible values.
+- **safety_settings** (list\[dict\[str, Any\]\] | None) – Safety settings for content filtering. If provided, it will override the
+ default settings.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is
+ received from the stream.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If provided, it will override the tools set during initialization.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `replies`: A list containing the generated ChatMessage responses.
+
+**Raises:**
+
+- RuntimeError – If there is an error in the async Google Gen AI chat generation.
+- ValueError – If a ChatMessage does not contain at least one of TextContent, ToolCall, or
+ ToolCallResult or if the role in ChatMessage is different from User, System, Assistant.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/google_vertex.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/google_vertex.md
new file mode 100644
index 0000000000..897f7e5fa6
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/google_vertex.md
@@ -0,0 +1,1222 @@
+---
+title: "Google Vertex"
+id: integrations-google-vertex
+description: "Google Vertex integration for Haystack"
+slug: "/integrations-google-vertex"
+---
+
+
+
+## Module haystack\_integrations.components.generators.google\_vertex.gemini
+
+
+
+### VertexAIGeminiGenerator
+
+`VertexAIGeminiGenerator` enables text generation using Google Gemini models.
+
+Usage example:
+```python
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiGenerator
+
+
+gemini = VertexAIGeminiGenerator()
+result = gemini.run(parts = ["What is the most interesting thing you know?"])
+for answer in result["replies"]:
+ print(answer)
+
+>>> 1. **The Origin of Life:** How and where did life begin? The answers to this ...
+>>> 2. **The Unseen Universe:** The vast majority of the universe is ...
+>>> 3. **Quantum Entanglement:** This eerie phenomenon in quantum mechanics allows ...
+>>> 4. **Time Dilation:** Einstein's theory of relativity revealed that time can ...
+>>> 5. **The Fermi Paradox:** Despite the vastness of the universe and the ...
+>>> 6. **Biological Evolution:** The idea that life evolves over time through natural ...
+>>> 7. **Neuroplasticity:** The brain's ability to adapt and change throughout life, ...
+>>> 8. **The Goldilocks Zone:** The concept of the habitable zone, or the Goldilocks zone, ...
+>>> 9. **String Theory:** This theoretical framework in physics aims to unify all ...
+>>> 10. **Consciousness:** The nature of human consciousness and how it arises ...
+```
+
+
+
+#### VertexAIGeminiGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+ model: str = "gemini-2.0-flash",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ generation_config: Optional[Union[GenerationConfig,
+ dict[str, Any]]] = None,
+ safety_settings: Optional[dict[HarmCategory,
+ HarmBlockThreshold]] = None,
+ system_instruction: Optional[Union[str, ByteStream, Part]] = None,
+ streaming_callback: Optional[Callable[[StreamingChunk],
+ None]] = None)
+```
+
+Multi-modal generator using Gemini model via Google Vertex AI.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+**Arguments**:
+
+- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- `model`: Name of the model to use. For available models, see https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models.
+- `location`: The default location to use when making API calls, if not set uses us-central-1.
+- `generation_config`: The generation config to use.
+Can either be a [`GenerationConfig`](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.GenerationConfig)
+object or a dictionary of parameters.
+Accepted fields are:
+ - temperature
+ - top_p
+ - top_k
+ - candidate_count
+ - max_output_tokens
+ - stop_sequences
+- `safety_settings`: The safety settings to use. See the documentation
+for [HarmBlockThreshold](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.HarmBlockThreshold)
+and [HarmCategory](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.HarmCategory)
+for more details.
+- `system_instruction`: Default system instruction to use for generating content.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+The callback function accepts StreamingChunk as an argument.
+
+
+
+#### VertexAIGeminiGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### VertexAIGeminiGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "VertexAIGeminiGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### VertexAIGeminiGenerator.run
+
+```python
+@component.output_types(replies=list[str])
+def run(parts: Variadic[Union[str, ByteStream, Part]],
+ streaming_callback: Optional[Callable[[StreamingChunk], None]] = None)
+```
+
+Generates content using the Gemini model.
+
+**Arguments**:
+
+- `parts`: Prompt for the model.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list of generated content.
+
+
+
+## Module haystack\_integrations.components.generators.google\_vertex.captioner
+
+
+
+### VertexAIImageCaptioner
+
+`VertexAIImageCaptioner` enables text generation using Google Vertex AI imagetext generative model.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Usage example:
+```python
+import requests
+
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIImageCaptioner
+
+captioner = VertexAIImageCaptioner()
+
+image = ByteStream(
+ data=requests.get(
+ "https://raw.githubusercontent.com/deepset-ai/haystack-core-integrations/main/integrations/google_vertex/example_assets/robot1.jpg"
+ ).content
+)
+result = captioner.run(image=image)
+
+for caption in result["captions"]:
+ print(caption)
+
+>>> two gold robots are standing next to each other in the desert
+```
+
+
+
+#### VertexAIImageCaptioner.\_\_init\_\_
+
+```python
+def __init__(*,
+ model: str = "imagetext",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ **kwargs)
+```
+
+Generate image captions using a Google Vertex AI model.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+**Arguments**:
+
+- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- `model`: Name of the model to use.
+- `location`: The default location to use when making API calls, if not set uses us-central-1.
+Defaults to None.
+- `kwargs`: Additional keyword arguments to pass to the model.
+For a list of supported arguments see the `ImageTextModel.get_captions()` documentation.
+
+
+
+#### VertexAIImageCaptioner.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### VertexAIImageCaptioner.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "VertexAIImageCaptioner"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### VertexAIImageCaptioner.run
+
+```python
+@component.output_types(captions=list[str])
+def run(image: ByteStream)
+```
+
+Prompts the model to generate captions for the given image.
+
+**Arguments**:
+
+- `image`: The image to generate captions for.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `captions`: A list of captions generated by the model.
+
+
+
+## Module haystack\_integrations.components.generators.google\_vertex.code\_generator
+
+
+
+### VertexAICodeGenerator
+
+This component enables code generation using Google Vertex AI generative model.
+
+`VertexAICodeGenerator` supports `code-bison`, `code-bison-32k`, and `code-gecko`.
+
+Usage example:
+```python
+ from haystack_integrations.components.generators.google_vertex import VertexAICodeGenerator
+
+ generator = VertexAICodeGenerator()
+
+ result = generator.run(prefix="def to_json(data):")
+
+ for answer in result["replies"]:
+ print(answer)
+
+ >>> ```python
+ >>> import json
+ >>>
+ >>> def to_json(data):
+ >>> """Converts a Python object to a JSON string.
+ >>>
+ >>> Args:
+ >>> data: The Python object to convert.
+ >>>
+ >>> Returns:
+ >>> A JSON string representing the Python object.
+ >>> """
+ >>>
+ >>> return json.dumps(data)
+ >>> ```
+```
+
+
+
+#### VertexAICodeGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+ model: str = "code-bison",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ **kwargs)
+```
+
+Generate code using a Google Vertex AI model.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+**Arguments**:
+
+- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- `model`: Name of the model to use.
+- `location`: The default location to use when making API calls, if not set uses us-central-1.
+- `kwargs`: Additional keyword arguments to pass to the model.
+For a list of supported arguments see the `TextGenerationModel.predict()` documentation.
+
+
+
+#### VertexAICodeGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### VertexAICodeGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "VertexAICodeGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### VertexAICodeGenerator.run
+
+```python
+@component.output_types(replies=list[str])
+def run(prefix: str, suffix: Optional[str] = None)
+```
+
+Generate code using a Google Vertex AI model.
+
+**Arguments**:
+
+- `prefix`: Code before the current point.
+- `suffix`: Code after the current point.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list of generated code snippets.
+
+
+
+## Module haystack\_integrations.components.generators.google\_vertex.image\_generator
+
+
+
+### VertexAIImageGenerator
+
+This component enables image generation using Google Vertex AI generative model.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Usage example:
+```python
+from pathlib import Path
+
+from haystack_integrations.components.generators.google_vertex import VertexAIImageGenerator
+
+generator = VertexAIImageGenerator()
+result = generator.run(prompt="Generate an image of a cute cat")
+result["images"][0].to_file(Path("my_image.png"))
+```
+
+
+
+#### VertexAIImageGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+ model: str = "imagegeneration",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ **kwargs)
+```
+
+Generates images using a Google Vertex AI model.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+**Arguments**:
+
+- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- `model`: Name of the model to use.
+- `location`: The default location to use when making API calls, if not set uses us-central-1.
+- `kwargs`: Additional keyword arguments to pass to the model.
+For a list of supported arguments see the `ImageGenerationModel.generate_images()` documentation.
+
+
+
+#### VertexAIImageGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### VertexAIImageGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "VertexAIImageGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### VertexAIImageGenerator.run
+
+```python
+@component.output_types(images=list[ByteStream])
+def run(prompt: str, negative_prompt: Optional[str] = None)
+```
+
+Produces images based on the given prompt.
+
+**Arguments**:
+
+- `prompt`: The prompt to generate images from.
+- `negative_prompt`: A description of what you want to omit in
+the generated images.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `images`: A list of ByteStream objects, each containing an image.
+
+
+
+## Module haystack\_integrations.components.generators.google\_vertex.question\_answering
+
+
+
+### VertexAIImageQA
+
+This component enables text generation (image captioning) using Google Vertex AI generative models.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Usage example:
+```python
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIImageQA
+
+qa = VertexAIImageQA()
+
+image = ByteStream.from_file_path("dog.jpg")
+
+res = qa.run(image=image, question="What color is this dog")
+
+print(res["replies"][0])
+
+>>> white
+```
+
+
+
+#### VertexAIImageQA.\_\_init\_\_
+
+```python
+def __init__(*,
+ model: str = "imagetext",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ **kwargs)
+```
+
+Answers questions about an image using a Google Vertex AI model.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+**Arguments**:
+
+- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- `model`: Name of the model to use.
+- `location`: The default location to use when making API calls, if not set uses us-central-1.
+- `kwargs`: Additional keyword arguments to pass to the model.
+For a list of supported arguments see the `ImageTextModel.ask_question()` documentation.
+
+
+
+#### VertexAIImageQA.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### VertexAIImageQA.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "VertexAIImageQA"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### VertexAIImageQA.run
+
+```python
+@component.output_types(replies=list[str])
+def run(image: ByteStream, question: str)
+```
+
+Prompts model to answer a question about an image.
+
+**Arguments**:
+
+- `image`: The image to ask the question about.
+- `question`: The question to ask.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list of answers to the question.
+
+
+
+## Module haystack\_integrations.components.generators.google\_vertex.text\_generator
+
+
+
+### VertexAITextGenerator
+
+This component enables text generation using Google Vertex AI generative models.
+
+`VertexAITextGenerator` supports `text-bison`, `text-unicorn` and `text-bison-32k` models.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Usage example:
+```python
+ from haystack_integrations.components.generators.google_vertex import VertexAITextGenerator
+
+ generator = VertexAITextGenerator()
+ res = generator.run("Tell me a good interview question for a software engineer.")
+
+ print(res["replies"][0])
+
+ >>> **Question:**
+ >>> You are given a list of integers and a target sum.
+ >>> Find all unique combinations of numbers in the list that add up to the target sum.
+ >>>
+ >>> **Example:**
+ >>>
+ >>> ```
+ >>> Input: [1, 2, 3, 4, 5], target = 7
+ >>> Output: [[1, 2, 4], [3, 4]]
+ >>> ```
+ >>>
+ >>> **Follow-up:** What if the list contains duplicate numbers?
+```
+
+
+
+#### VertexAITextGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+ model: str = "text-bison",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ **kwargs)
+```
+
+Generate text using a Google Vertex AI model.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+**Arguments**:
+
+- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- `model`: Name of the model to use.
+- `location`: The default location to use when making API calls, if not set uses us-central-1.
+- `kwargs`: Additional keyword arguments to pass to the model.
+For a list of supported arguments see the `TextGenerationModel.predict()` documentation.
+
+
+
+#### VertexAITextGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### VertexAITextGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "VertexAITextGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### VertexAITextGenerator.run
+
+```python
+@component.output_types(replies=list[str],
+ safety_attributes=dict[str, float],
+ citations=list[dict[str, Any]])
+def run(prompt: str)
+```
+
+Prompts the model to generate text.
+
+**Arguments**:
+
+- `prompt`: The prompt to use for text generation.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list of generated replies.
+- `safety_attributes`: A dictionary with the [safety scores](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/responsible-ai#safety_attribute_descriptions)
+ of each answer.
+- `citations`: A list of citations for each answer.
+
+
+
+## Module haystack\_integrations.components.generators.google\_vertex.chat.gemini
+
+
+
+### VertexAIGeminiChatGenerator
+
+`VertexAIGeminiChatGenerator` enables chat completion using Google Gemini models.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+### Usage example
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiChatGenerator
+
+gemini_chat = VertexAIGeminiChatGenerator()
+
+messages = [ChatMessage.from_user("Tell me the name of a movie")]
+res = gemini_chat.run(messages)
+
+print(res["replies"][0].text)
+>>> The Shawshank Redemption
+
+#### With Tool calling:
+
+```python
+from typing import Annotated
+from haystack.utils import Secret
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack.components.tools import ToolInvoker
+from haystack.tools import create_tool_from_function
+
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiChatGenerator
+
+__example function to get the current weather__
+
+def get_current_weather(
+ location: Annotated[str, "The city for which to get the weather, e.g. 'San Francisco'"] = "Munich",
+ unit: Annotated[str, "The unit for the temperature, e.g. 'celsius'"] = "celsius",
+) -> str:
+ return f"The weather in {location} is sunny. The temperature is 20 {unit}."
+
+tool = create_tool_from_function(get_current_weather)
+tool_invoker = ToolInvoker(tools=[tool])
+
+gemini_chat = VertexAIGeminiChatGenerator(
+ model="gemini-2.0-flash-exp",
+ tools=[tool],
+)
+user_message = [ChatMessage.from_user("What is the temperature in celsius in Berlin?")]
+replies = gemini_chat.run(messages=user_message)["replies"]
+print(replies[0].tool_calls)
+
+__actually invoke the tool__
+
+tool_messages = tool_invoker.run(messages=replies)["tool_messages"]
+messages = user_message + replies + tool_messages
+
+__transform the tool call result into a human readable message__
+
+final_replies = gemini_chat.run(messages=messages)["replies"]
+print(final_replies[0].text)
+```
+
+
+
+#### VertexAIGeminiChatGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+ model: str = "gemini-1.5-flash",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ generation_config: Optional[Union[GenerationConfig,
+ dict[str, Any]]] = None,
+ safety_settings: Optional[dict[HarmCategory,
+ HarmBlockThreshold]] = None,
+ tools: Optional[list[Tool]] = None,
+ tool_config: Optional[ToolConfig] = None,
+ streaming_callback: Optional[StreamingCallbackT] = None)
+```
+
+`VertexAIGeminiChatGenerator` enables chat completion using Google Gemini models.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+**Arguments**:
+
+- `model`: Name of the model to use. For available models, see https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models.
+- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- `location`: The default location to use when making API calls, if not set uses us-central-1.
+Defaults to None.
+- `generation_config`: Configuration for the generation process.
+See the [GenerationConfig documentation](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.GenerationConfig
+for a list of supported arguments.
+- `safety_settings`: Safety settings to use when generating content. See the documentation
+for [HarmBlockThreshold](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.HarmBlockThreshold)
+and [HarmCategory](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.HarmCategory)
+for more details.
+- `tools`: A list of tools for which the model can prepare calls.
+- `tool_config`: The tool config to use. See the documentation for [ToolConfig]
+(https://cloud.google.com/vertex-ai/generative-ai/docs/reference/python/latest/vertexai.generative_models.ToolConfig)
+- `streaming_callback`: A callback function that is called when a new token is received from
+the stream. The callback function accepts StreamingChunk as an argument.
+
+
+
+#### VertexAIGeminiChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### VertexAIGeminiChatGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "VertexAIGeminiChatGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### VertexAIGeminiChatGenerator.run
+
+```python
+@component.output_types(replies=list[ChatMessage])
+def run(messages: list[ChatMessage],
+ streaming_callback: Optional[StreamingCallbackT] = None,
+ *,
+ tools: Optional[list[Tool]] = None)
+```
+
+**Arguments**:
+
+- `messages`: A list of `ChatMessage` instances, representing the input messages.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+- `tools`: A list of tools for which the model can prepare calls. If set, it will override the `tools` parameter set
+during component initialization.
+
+**Returns**:
+
+A dictionary containing the following key:
+- `replies`: A list containing the generated responses as `ChatMessage` instances.
+
+
+
+#### VertexAIGeminiChatGenerator.run\_async
+
+```python
+@component.output_types(replies=list[ChatMessage])
+async def run_async(messages: list[ChatMessage],
+ streaming_callback: Optional[StreamingCallbackT] = None,
+ *,
+ tools: Optional[list[Tool]] = None)
+```
+
+Async version of the run method. Generates text based on the provided messages.
+
+**Arguments**:
+
+- `messages`: A list of `ChatMessage` instances, representing the input messages.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+- `tools`: A list of tools for which the model can prepare calls. If set, it will override the `tools` parameter set
+during component initialization.
+
+**Returns**:
+
+A dictionary containing the following key:
+- `replies`: A list containing the generated responses as `ChatMessage` instances.
+
+
+
+## Module haystack\_integrations.components.embedders.google\_vertex.document\_embedder
+
+
+
+### VertexAIDocumentEmbedder
+
+Embed text using Vertex AI Embeddings API.
+
+See available models in the official
+[Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#syntax).
+
+Usage example:
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.google_vertex import VertexAIDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = VertexAIDocumentEmbedder(model="text-embedding-005")
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+# [-0.044606007635593414, 0.02857724390923977, -0.03549133986234665,
+```
+
+
+
+#### VertexAIDocumentEmbedder.\_\_init\_\_
+
+```python
+def __init__(model: Literal[
+ "text-embedding-004",
+ "text-embedding-005",
+ "textembedding-gecko-multilingual@001",
+ "text-multilingual-embedding-002",
+ "text-embedding-large-exp-03-07",
+],
+ task_type: Literal[
+ "RETRIEVAL_DOCUMENT",
+ "RETRIEVAL_QUERY",
+ "SEMANTIC_SIMILARITY",
+ "CLASSIFICATION",
+ "CLUSTERING",
+ "QUESTION_ANSWERING",
+ "FACT_VERIFICATION",
+ "CODE_RETRIEVAL_QUERY",
+ ] = "RETRIEVAL_DOCUMENT",
+ gcp_region_name: Optional[Secret] = Secret.from_env_var(
+ "GCP_DEFAULT_REGION", strict=False),
+ gcp_project_id: Optional[Secret] = Secret.from_env_var(
+ "GCP_PROJECT_ID", strict=False),
+ batch_size: int = 32,
+ max_tokens_total: int = 20000,
+ time_sleep: int = 30,
+ retries: int = 3,
+ progress_bar: bool = True,
+ truncate_dim: Optional[int] = None,
+ meta_fields_to_embed: Optional[list[str]] = None,
+ embedding_separator: str = "\n") -> None
+```
+
+Generate Document Embedder using a Google Vertex AI model.
+
+Authenticates using Google Cloud Application Default Credentials (ADCs).
+For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+**Arguments**:
+
+- `model`: Name of the model to use.
+- `task_type`: The type of task for which the embeddings are being generated.
+For more information see the official [Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#tasktype).
+- `gcp_region_name`: The default location to use when making API calls, if not set uses us-central-1.
+- `gcp_project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- `batch_size`: The number of documents to process in a single batch.
+- `max_tokens_total`: The maximum number of tokens to process in total.
+- `time_sleep`: The time to sleep between retries in seconds.
+- `retries`: The number of retries in case of failure.
+- `progress_bar`: Whether to display a progress bar during processing.
+- `truncate_dim`: The dimension to truncate the embeddings to, if specified.
+- `meta_fields_to_embed`: A list of metadata fields to include in the embeddings.
+- `embedding_separator`: The separator to use between different embeddings.
+
+**Raises**:
+
+- `ValueError`: If the provided model is not in the list of supported models.
+
+
+
+#### VertexAIDocumentEmbedder.get\_text\_embedding\_input
+
+```python
+def get_text_embedding_input(
+ batch: list[Document]) -> list[TextEmbeddingInput]
+```
+
+Converts a batch of Document objects into a list of TextEmbeddingInput objects.
+
+**Arguments**:
+
+- `batch` _List[Document]_ - A list of Document objects to be converted.
+
+
+**Returns**:
+
+- `List[TextEmbeddingInput]` - A list of TextEmbeddingInput objects created from the input documents.
+
+
+
+#### VertexAIDocumentEmbedder.embed\_batch\_by\_smaller\_batches
+
+```python
+def embed_batch_by_smaller_batches(batch: list[str],
+ subbatch=1) -> list[list[float]]
+```
+
+Embeds a batch of text strings by dividing them into smaller sub-batches.
+
+**Arguments**:
+
+- `batch` _List[str]_ - A list of text strings to be embedded.
+- `subbatch` _int, optional_ - The size of the smaller sub-batches. Defaults to 1.
+
+**Returns**:
+
+- `List[List[float]]` - A list of embeddings, where each embedding is a list of floats.
+
+**Raises**:
+
+- `Exception` - If embedding fails at the item level, an exception is raised with the error details.
+
+
+
+#### VertexAIDocumentEmbedder.embed\_batch
+
+```python
+def embed_batch(batch: list[str]) -> list[list[float]]
+```
+
+Generate embeddings for a batch of text strings.
+
+**Arguments**:
+
+- `batch` _List[str]_ - A list of text strings to be embedded.
+
+
+**Returns**:
+
+- `List[List[float]]` - A list of embeddings, where each embedding is a list of floats.
+
+
+
+#### VertexAIDocumentEmbedder.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document])
+```
+
+Processes all documents in batches while adhering to the API's token limit per request.
+
+**Arguments**:
+
+- `documents`: A list of documents to embed.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+
+
+
+#### VertexAIDocumentEmbedder.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### VertexAIDocumentEmbedder.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "VertexAIDocumentEmbedder"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+## Module haystack\_integrations.components.embedders.google\_vertex.text\_embedder
+
+
+
+### VertexAITextEmbedder
+
+Embed text using VertexAI Text Embeddings API.
+
+See available models in the official
+[Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#syntax).
+
+Usage example:
+```python
+from haystack_integrations.components.embedders.google_vertex import VertexAITextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = VertexAITextEmbedder(model="text-embedding-005")
+
+print(text_embedder.run(text_to_embed))
+# {'embedding': [-0.08127457648515701, 0.03399784862995148, -0.05116401985287666, ...]
+```
+
+
+
+#### VertexAITextEmbedder.\_\_init\_\_
+
+```python
+def __init__(model: Literal[
+ "text-embedding-004",
+ "text-embedding-005",
+ "textembedding-gecko-multilingual@001",
+ "text-multilingual-embedding-002",
+ "text-embedding-large-exp-03-07",
+],
+ task_type: Literal[
+ "RETRIEVAL_DOCUMENT",
+ "RETRIEVAL_QUERY",
+ "SEMANTIC_SIMILARITY",
+ "CLASSIFICATION",
+ "CLUSTERING",
+ "QUESTION_ANSWERING",
+ "FACT_VERIFICATION",
+ "CODE_RETRIEVAL_QUERY",
+ ] = "RETRIEVAL_QUERY",
+ gcp_region_name: Optional[Secret] = Secret.from_env_var(
+ "GCP_DEFAULT_REGION", strict=False),
+ gcp_project_id: Optional[Secret] = Secret.from_env_var(
+ "GCP_PROJECT_ID", strict=False),
+ progress_bar: bool = True,
+ truncate_dim: Optional[int] = None) -> None
+```
+
+Initializes the TextEmbedder with the specified model, task type, and GCP configuration.
+
+**Arguments**:
+
+- `model`: Name of the model to use.
+- `task_type`: The type of task for which the embeddings are being generated.
+For more information see the official [Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#tasktype).
+- `gcp_region_name`: The default location to use when making API calls, if not set uses us-central-1.
+- `gcp_project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- `progress_bar`: Whether to display a progress bar during processing.
+- `truncate_dim`: The dimension to truncate the embeddings to, if specified.
+
+
+
+#### VertexAITextEmbedder.run
+
+```python
+@component.output_types(embedding=list[float])
+def run(text: Union[list[Document], list[str], str])
+```
+
+Processes text in batches while adhering to the API's token limit per request.
+
+**Arguments**:
+
+- `text`: The text to embed.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+
+
+
+#### VertexAITextEmbedder.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### VertexAITextEmbedder.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "VertexAITextEmbedder"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/hanlp.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/hanlp.md
new file mode 100644
index 0000000000..4d0eac98bd
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/hanlp.md
@@ -0,0 +1,143 @@
+---
+title: "HanLP"
+id: integrations-hanlp
+description: "HanLP integration for Haystack"
+slug: "/integrations-hanlp"
+---
+
+
+## haystack_integrations.components.preprocessors.hanlp.chinese_document_splitter
+
+### ChineseDocumentSplitter
+
+A DocumentSplitter for Chinese text.
+
+'coarse' represents coarse granularity Chinese word segmentation, 'fine' represents fine granularity word
+segmentation, default is coarse granularity word segmentation.
+
+Unlike English where words are usually separated by spaces,
+Chinese text is written continuously without spaces between words.
+Chinese words can consist of multiple characters.
+For example, the English word "America" is translated to "美国" in Chinese,
+which consists of two characters but is treated as a single word.
+Similarly, "Portugal" is "葡萄牙" in Chinese, three characters but one word.
+Therefore, splitting by word means splitting by these multi-character tokens,
+not simply by single characters or spaces.
+
+### Usage example
+
+```python
+doc = Document(content=
+ "这是第一句话，这是第二句话，这是第三句话。"
+ "这是第四句话，这是第五句话，这是第六句话！"
+ "这是第七句话，这是第八句话，这是第九句话？"
+)
+
+splitter = ChineseDocumentSplitter(
+ split_by="word", split_length=10, split_overlap=3, respect_sentence_boundary=True
+)
+result = splitter.run(documents=[doc])
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+ split_by: Literal[
+ "word", "sentence", "passage", "page", "line", "period", "function"
+ ] = "word",
+ split_length: int = 1000,
+ split_overlap: int = 200,
+ split_threshold: int = 0,
+ respect_sentence_boundary: bool = False,
+ splitting_function: Callable | None = None,
+ granularity: Literal["coarse", "fine"] = "coarse",
+) -> None
+```
+
+Initialize the ChineseDocumentSplitter component.
+
+**Parameters:**
+
+- **split_by** (Literal['word', 'sentence', 'passage', 'page', 'line', 'period', 'function']) – The unit for splitting your documents. Choose from:
+- `word` for splitting by spaces (" ")
+- `period` for splitting by periods (".")
+- `page` for splitting by form feed ("\\f")
+- `passage` for splitting by double line breaks ("\\n\\n")
+- `line` for splitting each line ("\\n")
+- `sentence` for splitting by HanLP sentence tokenizer
+- **split_length** (int) – The maximum number of units in each split.
+- **split_overlap** (int) – The number of overlapping units for each split.
+- **split_threshold** (int) – The minimum number of units per split. If a split has fewer units
+ than the threshold, it's attached to the previous split.
+- **respect_sentence_boundary** (bool) – Choose whether to respect sentence boundaries when splitting by "word".
+ If True, uses HanLP to detect sentence boundaries, ensuring splits occur only between sentences.
+- **splitting_function** (Callable | None) – Necessary when `split_by` is set to "function".
+ This is a function which must accept a single `str` as input and return a `list` of `str` as output,
+ representing the chunks after splitting.
+- **granularity** (Literal['coarse', 'fine']) – The granularity of Chinese word segmentation, either 'coarse' or 'fine'.
+
+**Raises:**
+
+- ValueError – If the granularity is not 'coarse' or 'fine'.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Split documents into smaller chunks.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The documents to split.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing the split documents.
+
+**Raises:**
+
+- RuntimeError – If the Chinese word segmentation model is not loaded.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the component by loading the necessary models.
+
+#### chinese_sentence_split
+
+```python
+chinese_sentence_split(text: str) -> list[dict[str, Any]]
+```
+
+Split Chinese text into sentences.
+
+**Parameters:**
+
+- **text** (str) – The text to split.
+
+**Returns:**
+
+- list\[dict\[str, Any\]\] – A list of split sentences.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChineseDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/jina.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/jina.md
new file mode 100644
index 0000000000..51f63eae27
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/jina.md
@@ -0,0 +1,685 @@
+---
+title: "Jina"
+id: integrations-jina
+description: "Jina integration for Haystack"
+slug: "/integrations-jina"
+---
+
+
+## haystack_integrations.components.connectors.jina.reader
+
+### JinaReaderConnector
+
+A component that interacts with Jina AI's reader service to process queries and return documents.
+
+This component supports different modes of operation: `read`, `search`, and `ground`.
+
+Usage example:
+
+```python
+from haystack_integrations.components.connectors.jina import JinaReaderConnector
+
+reader = JinaReaderConnector(mode="read")
+query = "https://example.com"
+result = reader.run(query=query)
+document = result["documents"][0]
+print(document.content)
+
+>>> "This domain is for use in illustrative examples..."
+```
+
+#### __init__
+
+```python
+__init__(
+ mode: JinaReaderMode | str,
+ api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+ json_response: bool = True,
+) -> None
+```
+
+Initialize a JinaReader instance.
+
+**Parameters:**
+
+- **mode** (JinaReaderMode | str) – The operation mode for the reader (`read`, `search` or `ground`).
+- `read`: process a URL and return the textual content of the page.
+- `search`: search the web and return textual content of the most relevant pages.
+- `ground`: call the grounding engine to perform fact checking.
+ For more information on the modes, see the [Jina Reader documentation](https://jina.ai/reader/).
+- **api_key** (Secret) – The Jina API key. It can be explicitly provided or automatically read from the
+ environment variable JINA_API_KEY (recommended).
+- **json_response** (bool) – Controls the response format from the Jina Reader API.
+ If `True`, requests a JSON response, resulting in Documents with rich structured metadata.
+ If `False`, requests a raw response, resulting in one Document with minimal metadata.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaReaderConnector
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- JinaReaderConnector – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str, headers: dict[str, str] | None = None
+) -> dict[str, list[Document]]
+```
+
+Process the query/URL using the Jina AI reader service.
+
+**Parameters:**
+
+- **query** (str) – The query string or URL to process.
+- **headers** (dict\[str, str\] | None) – Optional headers to include in the request for customization. Refer to the
+ [Jina Reader documentation](https://jina.ai/reader/) for more information.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+ - `documents`: A list of `Document` objects.
+
+#### run_async
+
+```python
+run_async(
+ query: str, headers: dict[str, str] | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously process the query/URL using the Jina AI reader service.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **query** (str) – The query string or URL to process.
+- **headers** (dict\[str, str\] | None) – Optional headers to include in the request for customization. Refer to the
+ [Jina Reader documentation](https://jina.ai/reader/) for more information.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+ - `documents`: A list of `Document` objects.
+
+## haystack_integrations.components.embedders.jina.document_embedder
+
+### JinaDocumentEmbedder
+
+A component for computing Document embeddings using Jina AI models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.jina import JinaDocumentEmbedder
+
+# Make sure that the environment variable JINA_API_KEY is set
+
+document_embedder = JinaDocumentEmbedder(task="retrieval.query")
+
+doc = Document(content="I love pizza!")
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+ model: str = "jina-embeddings-v3",
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ task: str | None = None,
+ dimensions: int | None = None,
+ late_chunking: bool | None = None,
+ *,
+ base_url: str = JINA_API_URL
+) -> None
+```
+
+Create a JinaDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Jina API key.
+- **model** (str) – The name of the Jina model to use.
+ Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **batch_size** (int) – Number of Documents to encode at once.
+- **progress_bar** (bool) – Whether to show a progress bar or not. Can be helpful to disable in production deployments
+ to keep the logs clean.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (str) – Separator used to concatenate the meta fields to the Document text.
+- **task** (str | None) – The downstream task for which the embeddings will be used.
+ The model will return the optimized embeddings for that task.
+ Check the list of available tasks on [Jina documentation](https://jina.ai/embeddings/).
+- **dimensions** (int | None) – Number of desired dimension.
+ Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
+- **late_chunking** (bool | None) – A boolean to enable or disable late chunking.
+ Apply the late chunking technique to leverage the model's long-context capabilities for
+ generating contextual chunk embeddings.
+- **base_url** (str) – The base URL of the Jina API.
+
+The support of `task` and `late_chunking` parameters is only available for jina-embeddings-v3.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- JinaDocumentEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, Any]
+```
+
+Compute the embeddings for a list of Documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with following keys:
+- `documents`: List of Documents, each with an `embedding` field containing the computed embedding.
+- `meta`: A dictionary with metadata including the model name and usage statistics.
+
+**Raises:**
+
+- TypeError – If the input is not a list of Documents.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, Any]
+```
+
+Asynchronously compute the embeddings for a list of Documents.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with following keys:
+- `documents`: List of Documents, each with an `embedding` field containing the computed embedding.
+- `meta`: A dictionary with metadata including the model name and usage statistics.
+
+**Raises:**
+
+- TypeError – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.jina.document_image_embedder
+
+### JinaDocumentImageEmbedder
+
+A component for computing Document embeddings based on images using Jina AI multimodal models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+The JinaDocumentImageEmbedder supports models from the jina-clip series and jina-embeddings-v4
+which can encode images into vector representations in the same embedding space as text.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.jina import JinaDocumentImageEmbedder
+
+# Make sure that the environment variable JINA_API_KEY is set
+
+embedder = JinaDocumentImageEmbedder(model="jina-clip-v2")
+
+documents = [
+ Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
+ Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}),
+]
+
+result = embedder.run(documents=documents)
+documents_with_embeddings = result["documents"]
+print(documents_with_embeddings[0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+ model: str = "jina-clip-v2",
+ base_url: str = JINA_API_URL,
+ file_path_meta_field: str = "file_path",
+ root_path: str | None = None,
+ embedding_dimension: int | None = None,
+ image_size: tuple[int, int] | None = None,
+ batch_size: int = 5
+) -> None
+```
+
+Create a JinaDocumentImageEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Jina API key. It can be explicitly provided or automatically read from the
+ environment variable `JINA_API_KEY` (recommended).
+- **model** (str) – The name of the Jina multimodal model to use.
+ Supported models include:
+- "jina-clip-v1"
+- "jina-clip-v2" (default)
+- "jina-embeddings-v4"
+ Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
+- **base_url** (str) – The base URL of the Jina API.
+- **file_path_meta_field** (str) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (str | None) – The root directory path where document files are located. If provided, file paths in
+ document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **embedding_dimension** (int | None) – Number of desired dimensions for the embedding.
+ Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
+ Only supported by jina-embeddings-v4.
+- **image_size** (tuple\[int, int\] | None) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+ maintaining aspect ratio. This reduces file size, memory usage, and processing time.
+- **batch_size** (int) – Number of images to send in each API request. Defaults to 5.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaDocumentImageEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- JinaDocumentImageEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of image documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Documents with embeddings.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Asynchronously embed a list of image documents.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: Documents with embeddings.
+
+## haystack_integrations.components.embedders.jina.text_embedder
+
+### JinaTextEmbedder
+
+A component for embedding strings using Jina AI models.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.jina import JinaTextEmbedder
+
+# Make sure that the environment variable JINA_API_KEY is set
+
+text_embedder = JinaTextEmbedder(task="retrieval.query")
+
+text_to_embed = "I love pizza!"
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+# 'meta': {'model': 'jina-embeddings-v3',
+# 'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+ model: str = "jina-embeddings-v3",
+ prefix: str = "",
+ suffix: str = "",
+ task: str | None = None,
+ dimensions: int | None = None,
+ late_chunking: bool | None = None,
+ *,
+ base_url: str = JINA_API_URL
+) -> None
+```
+
+Create a JinaTextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Jina API key. It can be explicitly provided or automatically read from the
+ environment variable `JINA_API_KEY` (recommended).
+- **model** (str) – The name of the Jina model to use.
+ Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **task** (str | None) – The downstream task for which the embeddings will be used.
+ The model will return the optimized embeddings for that task.
+ Check the list of available tasks on [Jina documentation](https://jina.ai/embeddings/).
+- **dimensions** (int | None) – Number of desired dimension.
+ Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
+- **late_chunking** (bool | None) – A boolean to enable or disable late chunking.
+ Apply the late chunking technique to leverage the model's long-context capabilities for
+ generating contextual chunk embeddings.
+- **base_url** (str) – The base URL of the Jina API.
+
+The support of `task` and `late_chunking` parameters is only available for jina-embeddings-v3.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- JinaTextEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embed a string.
+
+**Parameters:**
+
+- **text** (str) – The string to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with following keys:
+- `embedding`: The embedding of the input string.
+- `meta`: A dictionary with metadata including the model name and usage statistics.
+
+**Raises:**
+
+- TypeError – If the input is not a string.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, Any]
+```
+
+Asynchronously embed a string.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **text** (str) – The string to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with following keys:
+- `embedding`: The embedding of the input string.
+- `meta`: A dictionary with metadata including the model name and usage statistics.
+
+**Raises:**
+
+- TypeError – If the input is not a string.
+
+## haystack_integrations.components.rankers.jina.ranker
+
+### JinaRanker
+
+Ranks Documents based on their similarity to the query using Jina AI models.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.jina import JinaRanker
+
+ranker = JinaRanker()
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "City in Germany"
+result = ranker.run(query=query, documents=docs)
+docs = result["documents"]
+print(docs[0].content)
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "jina-reranker-v1-base-en",
+ api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+ top_k: int | None = None,
+ score_threshold: float | None = None,
+ *,
+ base_url: str = JINA_API_URL
+) -> None
+```
+
+Creates an instance of JinaRanker.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Jina API key. It can be explicitly provided or automatically read from the
+ environment variable JINA_API_KEY (recommended).
+- **model** (str) – The name of the Jina model to use. Check the list of available models on `https://jina.ai/reranker/`
+- **top_k** (int | None) – The maximum number of Documents to return per query. If `None`, all documents are returned
+- **score_threshold** (float | None) – If provided only returns documents with a score above this threshold.
+- **base_url** (str) – The base URL of the Jina API.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- JinaRanker – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ documents: list[Document],
+ top_k: int | None = None,
+ score_threshold: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Returns a list of Documents ranked by their similarity to the given query.
+
+**Parameters:**
+
+- **query** (str) – Query string.
+- **documents** (list\[Document\]) – List of Documents.
+- **top_k** (int | None) – The maximum number of Documents you want the Ranker to return.
+- **score_threshold** (float | None) – If provided only returns documents with a score above this threshold.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ documents: list[Document],
+ top_k: int | None = None,
+ score_threshold: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously returns a list of Documents ranked by their similarity to the given query.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **query** (str) – Query string.
+- **documents** (list\[Document\]) – List of Documents.
+- **top_k** (int | None) – The maximum number of Documents you want the Ranker to return.
+- **score_threshold** (float | None) – If provided only returns documents with a score above this threshold.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/kreuzberg.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/kreuzberg.md
new file mode 100644
index 0000000000..220043d0ec
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/kreuzberg.md
@@ -0,0 +1,152 @@
+---
+title: "Kreuzberg"
+id: integrations-kreuzberg
+description: "Kreuzberg integration for Haystack"
+slug: "/integrations-kreuzberg"
+---
+
+
+## haystack_integrations.components.converters.kreuzberg.converter
+
+### KreuzbergConverter
+
+Converts files to Documents using [Kreuzberg](https://docs.kreuzberg.dev/).
+
+Kreuzberg is a document intelligence framework that extracts text from
+PDFs, Office documents, images, and 75+ other formats. All processing
+is performed locally with no external API calls.
+
+**Usage Example:**
+
+```python
+from haystack_integrations.components.converters.kreuzberg import (
+ KreuzbergConverter,
+)
+
+converter = KreuzbergConverter()
+result = converter.run(sources=["document.pdf", "report.docx"])
+documents = result["documents"]
+```
+
+You can also pass kreuzberg's `ExtractionConfig` to customize extraction:
+
+```python
+from kreuzberg import ExtractionConfig, OcrConfig
+
+converter = KreuzbergConverter(
+ config=ExtractionConfig(
+ output_format="markdown",
+ ocr=OcrConfig(backend="tesseract", language="eng"),
+ ),
+)
+```
+
+**Token reduction** can be configured via
+`ExtractionConfig(token_reduction=TokenReductionConfig(mode="moderate"))`
+to reduce output size for LLM consumption. Five levels are available:
+`"off"`, `"light"`, `"moderate"`, `"aggressive"`, `"maximum"`.
+The reduced text appears directly in `Document.content`.
+
+**Image preprocessing for OCR** can be tuned via
+`OcrConfig(tesseract_config=TesseractConfig(preprocessing=ImagePreprocessingConfig(...)))`
+with options for target DPI, auto-rotate, deskew, denoise,
+contrast enhancement, and binarization method.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ config: ExtractionConfig | None = None,
+ config_path: str | Path | None = None,
+ store_full_path: bool = False,
+ batch: bool = True,
+ easyocr_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Create a `KreuzbergConverter` component.
+
+**Parameters:**
+
+- **config** (ExtractionConfig | None) – An optional `kreuzberg.ExtractionConfig` object to customize
+ extraction behavior. Use this to set output format, OCR backend
+ and language, force-OCR mode, per-page extraction, chunking,
+ keyword extraction, and other kreuzberg options. If not provided,
+ kreuzberg's defaults are used.
+ See the [kreuzberg API reference](https://docs.kreuzberg.dev/reference/api-python/)
+ for the full list of configuration options.
+- **config_path** (str | Path | None) – Path to a kreuzberg configuration file (`.toml`, `.yaml`, or
+ `.json`). Cannot be used together with `config`.
+- **store_full_path** (bool) – If `True`, the full file path is stored in the Document metadata.
+ If `False`, only the file name is stored.
+- **batch** (bool) – If `True`, use kreuzberg's batch extraction APIs, which leverage
+ Rust's rayon thread pool for parallel processing. If `False`,
+ sources are extracted one at a time.
+- **easyocr_kwargs** (dict\[str, Any\] | None) – Optional keyword arguments to pass to EasyOCR when using the
+ `"easyocr"` backend. Supports GPU, beam width, model storage,
+ and other EasyOCR-specific options.
+ See the [EasyOCR documentation](https://www.jaided.ai/easyocr/documentation/)
+ for the full list of supported arguments.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> KreuzbergConverter
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- KreuzbergConverter – Deserialized component.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Convert files to Documents using Kreuzberg.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths, directory paths, or ByteStream objects to
+ convert. Directory paths are expanded to their direct file children
+ (non-recursive, sorted alphabetically).
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single
+ dictionary. If it's a single dictionary, its content is added to
+ the metadata of all produced Documents. If it's a list, the length
+ of the list must match the number of sources, because the two
+ lists will be zipped. If `sources` contains ByteStream objects,
+ their `meta` will be added to the output Documents.
+
+**Note:** When directories are present in `sources`, `meta` must
+be a single dictionary (not a list), since the number of files in
+a directory is not known in advance.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following key:
+
+- `documents`: A list of created Documents.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/langfuse.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/langfuse.md
new file mode 100644
index 0000000000..122d7139e5
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/langfuse.md
@@ -0,0 +1,495 @@
+---
+title: "langfuse"
+id: integrations-langfuse
+description: "Langfuse integration for Haystack"
+slug: "/integrations-langfuse"
+---
+
+
+## haystack_integrations.components.connectors.langfuse.langfuse_connector
+
+### LangfuseConnector
+
+LangfuseConnector connects Haystack LLM framework with [Langfuse](https://langfuse.com) in order to enable the
+
+tracing of operations and data flow within various components of a pipeline.
+
+To use LangfuseConnector, add it to your pipeline without connecting it to any other components.
+It will automatically trace all pipeline operations when tracing is enabled.
+
+**Environment Configuration:**
+
+- `LANGFUSE_SECRET_KEY` and `LANGFUSE_PUBLIC_KEY`: Required Langfuse API credentials.
+- `HAYSTACK_CONTENT_TRACING_ENABLED`: Must be set to `"true"` to enable tracing.
+- `HAYSTACK_LANGFUSE_ENFORCE_FLUSH`: (Optional) If set to `"false"`, disables flushing after each component.
+ Be cautious: this may cause data loss on crashes unless you manually flush before shutdown.
+ By default, the data is flushed after each component and blocks the thread until the data is sent to Langfuse.
+
+If you disable flushing after each component make sure you will call langfuse.flush() explicitly before the
+program exits. For example:
+
+```python
+from haystack.tracing import tracer
+
+try:
+ # your code here
+finally:
+ tracer.actual_tracer.flush()
+```
+
+or in FastAPI by defining a shutdown event handler:
+
+```python
+from haystack.tracing import tracer
+
+# ...
+
+@app.on_event("shutdown")
+async def shutdown_event():
+ tracer.actual_tracer.flush()
+```
+
+Here is an example of how to use LangfuseConnector in a pipeline:
+
+```python
+import os
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.connectors.langfuse import (
+ LangfuseConnector,
+)
+
+pipe = Pipeline()
+pipe.add_component("tracer", LangfuseConnector("Chat example"))
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+messages = [
+ ChatMessage.from_system(
+ "Always respond in German even if some input data is in other languages."
+ ),
+ ChatMessage.from_user("Tell me about {{location}}"),
+]
+
+response = pipe.run(
+ data={
+ "prompt_builder": {
+ "template_variables": {"location": "Berlin"},
+ "template": messages,
+ }
+ }
+)
+print(response["llm"]["replies"][0])
+print(response["tracer"]["trace_url"])
+print(response["tracer"]["trace_id"])
+```
+
+For advanced use cases, you can also customize how spans are created and processed by providing a custom
+SpanHandler. This allows you to add custom metrics, set warning levels, or attach additional metadata to your
+Langfuse traces:
+
+```python
+from haystack_integrations.tracing.langfuse import DefaultSpanHandler, LangfuseSpan
+from typing import Optional
+
+class CustomSpanHandler(DefaultSpanHandler):
+
+ def handle(self, span: LangfuseSpan, component_type: Optional[str]) -> None:
+ # Custom span handling logic, customize Langfuse spans however it fits you
+ # see DefaultSpanHandler for how we create and process spans by default
+ pass
+
+connector = LangfuseConnector(span_handler=CustomSpanHandler())
+```
+
+#### __init__
+
+```python
+__init__(
+ name: str,
+ public: bool = False,
+ public_key: Secret | None = Secret.from_env_var("LANGFUSE_PUBLIC_KEY"),
+ secret_key: Secret | None = Secret.from_env_var("LANGFUSE_SECRET_KEY"),
+ httpx_client: httpx.Client | None = None,
+ span_handler: SpanHandler | None = None,
+ *,
+ host: str | None = None,
+ langfuse_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Initialize the LangfuseConnector component.
+
+**Parameters:**
+
+- **name** (str) – The name for the trace. This name will be used to identify the tracing run in the Langfuse
+ dashboard.
+- **public** (bool) – Whether the tracing data should be public or private. If set to `True`, the tracing data will be
+ publicly accessible to anyone with the tracing URL. If set to `False`, the tracing data will be private and
+ only accessible to the Langfuse account owner. The default is `False`.
+- **public_key** (Secret | None) – The Langfuse public key. Defaults to reading from LANGFUSE_PUBLIC_KEY environment variable.
+- **secret_key** (Secret | None) – The Langfuse secret key. Defaults to reading from LANGFUSE_SECRET_KEY environment variable.
+- **httpx_client** (Client | None) – Optional custom httpx.Client instance to use for Langfuse API calls. Note that when
+ deserializing a pipeline from YAML, any custom client is discarded and Langfuse will create its own default
+ client, since HTTPX clients cannot be serialized.
+- **span_handler** (SpanHandler | None) – Optional custom handler for processing spans. If None, uses DefaultSpanHandler.
+ The span handler controls how spans are created and processed, allowing customization of span types
+ based on component types and additional processing after spans are yielded. See SpanHandler class for
+ details on implementing custom handlers.
+ host: Host of Langfuse API. Can also be set via `LANGFUSE_HOST` environment variable.
+ By default it is set to `https://cloud.langfuse.com`.
+- **langfuse_client_kwargs** (dict\[str, Any\] | None) – Optional custom configuration for the Langfuse client. This is a dictionary
+ containing any additional configuration options for the Langfuse client. See the Langfuse documentation
+ for more details on available configuration options.
+
+#### run
+
+```python
+run(invocation_context: dict[str, Any] | None = None) -> dict[str, str]
+```
+
+Runs the LangfuseConnector component.
+
+**Parameters:**
+
+- **invocation_context** (dict\[str, Any\] | None) – A dictionary with additional context for the invocation. This parameter
+ is useful when users want to mark this particular invocation with additional information, e.g.
+ a run id from their own execution framework, user id, etc. These key-value pairs are then visible
+ in the Langfuse traces.
+
+**Returns:**
+
+- dict\[str, str\] – A dictionary with the following keys:
+- `name`: The name of the tracing component.
+- `trace_url`: The URL to the tracing data.
+- `trace_id`: The ID of the trace.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LangfuseConnector
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- LangfuseConnector – The deserialized component instance.
+
+## haystack_integrations.tracing.langfuse.tracer
+
+### LangfuseSpan
+
+Bases: Span
+
+Internal class representing a bridge between the Haystack span tracing API and Langfuse.
+
+#### __init__
+
+```python
+__init__(context_manager: AbstractContextManager) -> None
+```
+
+Initialize a LangfuseSpan instance.
+
+**Parameters:**
+
+- **context_manager** (AbstractContextManager) – The context manager from Langfuse created with
+ `langfuse.get_client().start_as_current_observation`.
+
+#### set_tag
+
+```python
+set_tag(key: str, value: Any) -> None
+```
+
+Set a generic tag for this span.
+
+**Parameters:**
+
+- **key** (str) – The tag key.
+- **value** (Any) – The tag value.
+
+#### set_content_tag
+
+```python
+set_content_tag(key: str, value: Any) -> None
+```
+
+Set a content-specific tag for this span.
+
+**Parameters:**
+
+- **key** (str) – The content tag key.
+- **value** (Any) – The content tag value.
+
+#### raw_span
+
+```python
+raw_span() -> LangfuseClientSpan
+```
+
+Return the underlying span instance.
+
+**Returns:**
+
+- LangfuseSpan – The Langfuse span instance.
+
+#### get_data
+
+```python
+get_data() -> dict[str, Any]
+```
+
+Return the data associated with the span.
+
+**Returns:**
+
+- dict\[str, Any\] – The data associated with the span.
+
+#### get_correlation_data_for_logs
+
+```python
+get_correlation_data_for_logs() -> dict[str, Any]
+```
+
+Return correlation data for log enrichment.
+
+### SpanContext
+
+Context for creating spans in Langfuse.
+
+Encapsulates the information needed to create and configure a span in Langfuse tracing.
+Used by SpanHandler to determine the span type (trace, generation, or default) and its configuration.
+
+**Parameters:**
+
+- **name** (str) – The name of the span to create. For components, this is typically the component name.
+- **operation_name** (str) – The operation being traced (e.g. "haystack.pipeline.run"). Used to determine
+ if a new trace should be created without warning.
+- **component_type** (str | None) – The type of component creating the span (e.g. "OpenAIChatGenerator").
+ Can be used to determine the type of span to create.
+- **tags** (dict\[str, Any\]) – Additional metadata to attach to the span. Contains component input/output data
+ and other trace information.
+- **parent_span** (Span | None) – The parent span if this is a child span. If None, a new trace will be created.
+- **trace_name** (str) – The name to use for the trace when creating a parent span. Defaults to "Haystack".
+- **public** (bool) – Whether traces should be publicly accessible. Defaults to False.
+
+### SpanHandler
+
+Bases: ABC
+
+Abstract base class for customizing how Langfuse spans are created and processed.
+
+This class defines two key extension points:
+
+1. create_span: Controls what type of span to create (default or generation)
+1. handle: Processes the span after component execution (adding metadata, metrics, etc.)
+
+To implement a custom handler:
+
+- Extend this class or DefaultSpanHandler
+- Override create_span and handle methods. It is more common to override handle.
+- Pass your handler to LangfuseConnector init method
+
+#### init_tracer
+
+```python
+init_tracer(tracer: langfuse.Langfuse) -> None
+```
+
+Initialize with Langfuse tracer. Called internally by LangfuseTracer.
+
+**Parameters:**
+
+- **tracer** (Langfuse) – The Langfuse client instance to use for creating spans
+
+#### create_span
+
+```python
+create_span(context: SpanContext) -> LangfuseSpan
+```
+
+Create a span of appropriate type based on the context.
+
+This method determines what kind of span to create:
+
+- A new trace if there's no parent span
+- A generation span for LLM components
+- A default span for other components
+
+**Parameters:**
+
+- **context** (SpanContext) – The context containing all information needed to create the span
+
+**Returns:**
+
+- LangfuseSpan – A new LangfuseSpan instance configured according to the context
+
+#### handle
+
+```python
+handle(span: LangfuseSpan, component_type: str | None) -> None
+```
+
+Process a span after component execution by attaching metadata and metrics.
+
+This method is called after the component or pipeline yields its span, allowing you to:
+
+- Extract and attach token usage statistics
+- Add model information
+- Record timing data (e.g., time-to-first-token)
+- Set log levels for quality monitoring
+- Add custom metrics and observations
+
+**Parameters:**
+
+- **span** (LangfuseSpan) – The span that was yielded by the component
+- **component_type** (str | None) – The type of component that created the span, used to determine
+ what metadata to extract and how to process it
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SpanHandler
+```
+
+Deserialize a SpanHandler from a dictionary.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this SpanHandler to a dictionary.
+
+### DefaultSpanHandler
+
+Bases: SpanHandler
+
+DefaultSpanHandler provides the default Langfuse tracing behavior for Haystack.
+
+#### create_span
+
+```python
+create_span(context: SpanContext) -> LangfuseSpan
+```
+
+Create a Langfuse span based on the given context.
+
+#### handle
+
+```python
+handle(span: LangfuseSpan, component_type: str | None) -> None
+```
+
+Process and enrich a span after component execution.
+
+### LangfuseTracer
+
+Bases: Tracer
+
+Internal class representing a bridge between the Haystack tracer and Langfuse.
+
+#### __init__
+
+```python
+__init__(
+ tracer: langfuse.Langfuse,
+ name: str = "Haystack",
+ public: bool = False,
+ span_handler: SpanHandler | None = None,
+) -> None
+```
+
+Initialize a LangfuseTracer instance.
+
+**Parameters:**
+
+- **tracer** (Langfuse) – The Langfuse tracer instance.
+- **name** (str) – The name of the pipeline or component. This name will be used to identify the tracing run on the
+ Langfuse dashboard.
+- **public** (bool) – Whether the tracing data should be public or private. If set to `True`, the tracing data will
+ be publicly accessible to anyone with the tracing URL. If set to `False`, the tracing data will be private
+ and only accessible to the Langfuse account owner.
+- **span_handler** (SpanHandler | None) – Custom handler for processing spans. If None, uses DefaultSpanHandler.
+
+#### trace
+
+```python
+trace(
+ operation_name: str,
+ tags: dict[str, Any] | None = None,
+ parent_span: Span | None = None,
+) -> Iterator[Span]
+```
+
+Create and manage a tracing span as a context manager.
+
+#### flush
+
+```python
+flush() -> None
+```
+
+Flush all pending spans to Langfuse.
+
+#### current_span
+
+```python
+current_span() -> Span | None
+```
+
+Return the current active span.
+
+**Returns:**
+
+- Span | None – The current span if available, else None.
+
+#### get_trace_url
+
+```python
+get_trace_url() -> str
+```
+
+Return the URL to the tracing data.
+
+**Returns:**
+
+- str – The URL to the tracing data.
+
+#### get_trace_id
+
+```python
+get_trace_id() -> str
+```
+
+Return the trace ID.
+
+**Returns:**
+
+- str – The trace ID.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/lara.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/lara.md
new file mode 100644
index 0000000000..ab42181ed0
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/lara.md
@@ -0,0 +1,177 @@
+---
+title: "Lara"
+id: integrations-lara
+description: "Lara integration for Haystack"
+slug: "/integrations-lara"
+---
+
+
+## haystack_integrations.components.translators.lara.document_translator
+
+### LaraDocumentTranslator
+
+Translates the text content of Haystack Documents using translated's Lara translation API.
+
+Lara is an adaptive translation AI that combines the fluency and context handling
+of LLMs with low hallucination and latency. It adapts to domains at inference time
+using optional context, instructions, translation memories, and glossaries. You can find
+more detailed information in the [Lara documentation](https://developers.laratranslate.com/docs/introduction).
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.utils import Secret
+from haystack_integrations.components.lara import LaraDocumentTranslator
+
+translator = LaraDocumentTranslator(
+ access_key_id=Secret.from_env_var("LARA_ACCESS_KEY_ID"),
+ access_key_secret=Secret.from_env_var("LARA_ACCESS_KEY_SECRET"),
+ source_lang="en-US",
+ target_lang="de-DE",
+)
+
+doc = Document(content="Hello, world!")
+result = translator.run(documents=[doc])
+print(result["documents"][0].content)
+```
+
+#### __init__
+
+```python
+__init__(
+ access_key_id: Secret = Secret.from_env_var("LARA_ACCESS_KEY_ID"),
+ access_key_secret: Secret = Secret.from_env_var("LARA_ACCESS_KEY_SECRET"),
+ source_lang: str | None = None,
+ target_lang: str | None = None,
+ context: str | None = None,
+ instructions: str | None = None,
+ style: Literal["faithful", "fluid", "creative"] = "faithful",
+ adapt_to: list[str] | None = None,
+ glossaries: list[str] | None = None,
+ reasoning: bool = False,
+)
+```
+
+Creats an instance of the LaraDocumentTranslator component.
+
+**Parameters:**
+
+- **access_key_id** (Secret) – Lara API access key ID. Defaults to the `LARA_ACCESS_KEY_ID` environment variable.
+- **access_key_secret** (Secret) – Lara API access key secret. Defaults to the `LARA_ACCESS_KEY_SECRET` environment variable.
+- **source_lang** (str | None) – Language code of the source text. If `None`, Lara auto-detects the source language.
+ Use locale codes from the
+ [supported languages list](https://developers.laratranslate.com/docs/supported-languages).
+- **target_lang** (str | None) – Language code of the target text.
+ Use locale codes from the
+ [supported languages list](https://developers.laratranslate.com/docs/supported-languages).
+- **context** (str | None) – Optional external context: text that is not translated but is sent to Lara to
+ improve translation quality (e.g. surrounding sentences, prior messages).
+ You can find more detailed information in the
+ [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-context).
+- **instructions** (str | None) – Optional natural-language instructions to guide translation and
+ specify domain-specific terminology (e.g. "Be formal", "Use a professional tone").
+ You can find more detailed information in the
+ [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-instructions).
+- **style** (Literal['faithful', 'fluid', 'creative']) – One of `"faithful"`, `"fluid"`, or `"creative"`.
+ Default is `"faithful"`.
+ Style description:
+- `"faithful"`: For accuracy and precision. Keeps original structure and meaning.
+ Ideal for manuals, legal documents.
+- `"fluid"`: For readability and natural flow. Smooth, conversational. Good for general content.
+- `"creative"`: For artistic and creative expression. Best for literature, marketing, or content
+ where impact and tone matter more than literal wording.
+ You can find more detailed information in the
+ [Lara documentation](https://support.laratranslate.com/en/translation-styles).
+- **adapt_to** (list\[str\] | None) – Optional list of translation memory IDs. Lara adapts to the style and terminology of these memories
+ at inference time. Domain adaptation is available depending on your plan. You can find more
+ detailed information in the
+ [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-translation-memories).
+- **glossaries** (list\[str\] | None) – Optional list of glossary IDs. Lara applies these glossaries at inference time to enforce
+ consistent terminology (e.g. brand names, product terms, legal or technical phrases) across translations.
+ Glossary management and availability depends on your plan.
+ You can find more detailed information in the
+ [Lara documentation](https://developers.laratranslate.com/docs/manage-glossaries).
+- **reasoning** (bool) – If `True`, uses the Lara Think model for higher-quality translation (multi-step linguistic analysis).
+ Increases latency and cost. Availability depends on your plan. You can find more detailed information in the
+ [Lara documentation](https://developers.laratranslate.com/docs/translate-text#reasoning-lara-think).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Lara translator by initializing the client.
+
+#### run
+
+```python
+run(
+ documents: list[Document],
+ source_lang: str | list[str | None] | None = None,
+ target_lang: str | list[str] | None = None,
+ context: str | list[str] | None = None,
+ instructions: str | list[str] | None = None,
+ style: str | list[str] | None = None,
+ adapt_to: list[str] | list[list[str]] | None = None,
+ glossaries: list[str] | list[list[str]] | None = None,
+ reasoning: bool | list[bool] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Translate the text content of each input Document using the Lara API.
+
+Any of the translation parameters (source_lang, target_lang, context,
+instructions, style, adapt_to, glossaries, reasoning) can be passed here
+to override the defaults set when creating the component. They can be a single value
+(applied to all documents) or a list of values with the same length as
+`documents` for per-document settings.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Haystack Documents whose `content` is to be translated.
+- **source_lang** (str | list\[str | None\] | None) – Source language code(s). Use locale codes from the
+ [supported languages list](https://developers.laratranslate.com/docs/supported-languages).
+ If `None`, Lara auto-detects the source language. Single value or list (one per document).
+- **target_lang** (str | list\[str\] | None) – Target language code(s). Use locale codes from the
+ [supported languages list](https://developers.laratranslate.com/docs/supported-languages).
+ Single value or list (one per document).
+- **context** (str | list\[str\] | None) – Optional external context: text that is not translated but is sent to Lara to
+ improve translation quality (e.g. surrounding sentences, prior messages).
+ You can find more detailed information in the
+ [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-context).
+- **instructions** (str | list\[str\] | None) – Optional natural-language instructions to guide translation and specify
+ domain-specific terminology (e.g. "Be formal", "Use a professional tone").
+ You can find more detailed information in the
+ [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-instructions).
+- **style** (str | list\[str\] | None) – One of `"faithful"`, `"fluid"`, or `"creative"`.
+ Style description:
+- `"faithful"`: For accuracy and precision. Keeps original structure and meaning.
+ Ideal for manuals, legal documents.
+- `"fluid"`: For readability and natural flow. Smooth, conversational. Good for general content.
+- `"creative"`: For artistic and creative expression. Best for literature, marketing, or content
+ where impact and tone matter more than literal wording.
+ You can find more detailed information in the
+ [Lara documentation](https://support.laratranslate.com/en/translation-styles).
+- **adapt_to** (list\[str\] | list\[list\[str\]\] | None) – Optional list of translation memory IDs. Lara adapts to the style and terminology
+ of these memories at inference time. Domain adaptation is available depending on your plan.
+ You can find more detailed information in the
+ [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-translation-memories).
+- **glossaries** (list\[str\] | list\[list\[str\]\] | None) – Optional list of glossary IDs. Lara applies these glossaries at inference time to enforce
+ consistent terminology (e.g. brand names, product terms, legal or technical phrases) across translations.
+ Glossary management and availability depends on your plan.
+ You can find more detailed information in the
+ [Lara documentation](https://developers.laratranslate.com/docs/manage-glossaries).
+- **reasoning** (bool | list\[bool\] | None) – If `True`, uses the Lara Think model for higher-quality translation (multi-step linguistic analysis).
+ Increases latency and cost. Availability depends on your plan. You can find more detailed information in the
+ [Lara documentation](https://developers.laratranslate.com/docs/translate-text#reasoning-lara-think).
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: A list of translated documents.
+
+**Raises:**
+
+- ValueError – If any list-valued parameter has length != `len(documents)`.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/libreoffice.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/libreoffice.md
new file mode 100644
index 0000000000..7b3b4dcacc
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/libreoffice.md
@@ -0,0 +1,194 @@
+---
+title: "LibreOffice"
+id: integrations-libreoffice
+description: "LibreOffice integration for Haystack"
+slug: "/integrations-libreoffice"
+---
+
+
+## haystack_integrations.components.converters.libreoffice.converter
+
+### LibreOfficeFileConverter
+
+Component that uses libreoffice's command line utility (soffice) to convert files into various formats.
+
+### Usage examples
+
+**Simple conversion:**
+
+```python
+from pathlib import Path
+
+from haystack_integrations.components.converters.libreoffice import LibreOfficeFileConverter
+
+# Convert documents
+converter = LibreOfficeFileConverter()
+results = converter.run(sources=[Path("sample.doc")], output_file_type="docx")
+print(results["output"]) # [ByteStream(data=b'...', meta={}, mime_type=None)]
+```
+
+**Conversion pipeline:**
+
+```python
+from pathlib import Path
+
+from haystack import Pipeline
+from haystack.components.converters import DOCXToDocument
+
+from haystack_integrations.components.converters.libreoffice import LibreOfficeFileConverter
+
+# Create pipeline with components
+pipeline = Pipeline()
+pipeline.add_component("libreoffice_converter", LibreOfficeFileConverter())
+pipeline.add_component("docx_converter", DOCXToDocument())
+
+pipeline.connect("libreoffice_converter.output", "docx_converter.sources")
+
+# Run pipeline and convert legacy documents into Haystack documents
+results = pipeline.run(
+ {
+ "libreoffice_converter": {
+ "sources": [Path("sample_doc.doc")],
+ "output_file_type": "docx",
+ }
+ }
+)
+print(results["docx_converter"]["documents"])
+```
+
+#### SUPPORTED_TYPES
+
+```python
+SUPPORTED_TYPES: dict[str, frozenset[str]] = {
+ "doc": frozenset(["pdf", "docx", "odt", "rtf", "txt", "html", "epub"]),
+ "docx": frozenset(["pdf", "doc", "odt", "rtf", "txt", "html", "epub"]),
+ "odt": frozenset(["pdf", "docx", "doc", "rtf", "txt", "html", "epub"]),
+ "rtf": frozenset(["pdf", "docx", "doc", "odt", "txt", "html"]),
+ "txt": frozenset(["pdf", "docx", "doc", "odt", "rtf", "html"]),
+ "html": frozenset(["pdf", "docx", "doc", "odt", "rtf", "txt"]),
+ "xlsx": frozenset(["pdf", "xls", "ods", "csv", "html"]),
+ "xls": frozenset(["pdf", "xlsx", "ods", "csv", "html"]),
+ "ods": frozenset(["pdf", "xlsx", "xls", "csv", "html"]),
+ "csv": frozenset(["pdf", "xlsx", "xls", "ods"]),
+ "pptx": frozenset(["pdf", "ppt", "odp", "html", "png", "jpg"]),
+ "ppt": frozenset(["pdf", "pptx", "odp", "html", "png", "jpg"]),
+ "odp": frozenset(["pdf", "pptx", "ppt", "html", "png", "jpg"]),
+}
+
+```
+
+A non-exhaustive mapping of supported conversion types by this component.
+See https://help.libreoffice.org/latest/en-GB/text/shared/guide/convertfilters.html for more information.
+
+#### __init__
+
+```python
+__init__(output_file_type: OUTPUT_FILE_TYPE | None = None) -> None
+```
+
+Check whether soffice is installed.
+
+**Parameters:**
+
+- **output_file_type** (OUTPUT_FILE_TYPE | None) – Target file format to convert to. Must be a valid conversion target for
+ each source's input type — see :attr:`SUPPORTED_TYPES` for the full mapping.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Self
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- Self – The deserialized component.
+
+#### run
+
+```python
+run(
+ sources: Iterable[str | Path | ByteStream],
+ output_file_type: OUTPUT_FILE_TYPE | None = None,
+) -> LibreOfficeFileConverterOutput
+```
+
+Convert office files to the specified output format using LibreOffice.
+
+**Parameters:**
+
+- **sources** (Iterable\[str | Path | ByteStream\]) – List of sources to convert. Each source can be a file path (`str` or
+ `Path`) or a `ByteStream`. For `ByteStream` sources, the input file
+ type cannot be inferred from the filename, so only `output_file_type` is
+ validated (not the source type).
+- **output_file_type** (OUTPUT_FILE_TYPE | None) – Target file format to convert to. Must be a valid conversion target for
+ each source's input type — see :attr:`SUPPORTED_TYPES` for the full mapping.
+ If set, it will override the `output_file_type` parameter provided during initialization.
+
+**Returns:**
+
+- LibreOfficeFileConverterOutput – A dictionary with the following key:
+- `output`: List of `ByteStream` objects containing the converted file
+ data, in the same order as `sources`.
+
+**Raises:**
+
+- FileNotFoundError – If a source file path does not exist.
+- OSError – If the internal temporary output directory is not writable.
+- ValueError – If a source's file type is not in :attr:`SUPPORTED_TYPES`,
+ or if `output_file_type` is not a valid conversion target for it,
+ or if `output_file_type` has not been provided anywhere.
+
+#### run_async
+
+```python
+run_async(
+ sources: Iterable[str | Path | ByteStream],
+ output_file_type: OUTPUT_FILE_TYPE | None = None,
+) -> LibreOfficeFileConverterOutput
+```
+
+Asynchronously convert office files to the specified output format using LibreOffice.
+
+This is the asynchronous version of the `run` method with the same parameters and return values.
+
+**Parameters:**
+
+- **sources** (Iterable\[str | Path | ByteStream\]) – List of sources to convert. Each source can be a file path (`str` or
+ `Path`) or a `ByteStream`. For `ByteStream` sources, the input file
+ type cannot be inferred from the filename, so only `output_file_type` is
+ validated (not the source type).
+- **output_file_type** (OUTPUT_FILE_TYPE | None) – Target file format to convert to. Must be a valid conversion target for
+ each source's input type — see :attr:`SUPPORTED_TYPES` for the full mapping.
+ If set, it will override the `output_file_type` parameter provided during initialization.
+
+**Returns:**
+
+- LibreOfficeFileConverterOutput – A dictionary with the following key:
+- `output`: List of `ByteStream` objects containing the converted file
+ data, in the same order as `sources`.
+
+**Raises:**
+
+- FileNotFoundError – If a source file path does not exist.
+- OSError – If the internal temporary output directory is not writable.
+- ValueError – If a source's file type is not in :attr:`SUPPORTED_TYPES`,
+ or if `output_file_type` is not a valid conversion target for it,
+ or if `output_file_type` has not been provided anywhere.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/llama_cpp.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/llama_cpp.md
new file mode 100644
index 0000000000..11e02ce273
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/llama_cpp.md
@@ -0,0 +1,275 @@
+---
+title: "Llama.cpp"
+id: integrations-llama-cpp
+description: "Llama.cpp integration for Haystack"
+slug: "/integrations-llama-cpp"
+---
+
+
+
+## Module haystack\_integrations.components.generators.llama\_cpp.chat.chat\_generator
+
+
+
+### LlamaCppChatGenerator
+
+Provides an interface to generate text using LLM via llama.cpp.
+
+[llama.cpp](https://github.com/ggml-org/llama.cpp) is a project written in C/C++ for efficient inference of LLMs.
+It employs the quantized GGUF format, suitable for running these models on standard machines (even without GPUs).
+Supports both text-only and multimodal (text + image) models like LLaVA.
+
+Usage example:
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+user_message = [ChatMessage.from_user("Who is the best American actor?")]
+generator = LlamaCppGenerator(model="zephyr-7b-beta.Q4_0.gguf", n_ctx=2048, n_batch=512)
+
+print(generator.run(user_message, generation_kwargs={"max_tokens": 128}))
+# {"replies": [ChatMessage(content="John Cusack", role=bool) – If `True`, the full file path is stored in the Document metadata.
+ If `False`, only the file name is stored. Defaults to `False`.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Converts files to Documents using MarkItDown.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of file paths or ByteStream objects to convert.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents. Can be a single dict
+ applied to all Documents, or a list of dicts aligned with `sources`.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with key `documents` containing the converted Documents.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/mcp.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/mcp.md
new file mode 100644
index 0000000000..48ca192811
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/mcp.md
@@ -0,0 +1,982 @@
+---
+title: "MCP"
+id: integrations-mcp
+description: "MCP integration for Haystack"
+slug: "/integrations-mcp"
+---
+
+
+## haystack_integrations.tools.mcp.mcp_tool
+
+### AsyncExecutor
+
+Thread-safe event loop executor for running async code from sync contexts.
+
+#### get_instance
+
+```python
+get_instance() -> AsyncExecutor
+```
+
+Get or create the global singleton executor instance.
+
+#### __init__
+
+```python
+__init__() -> None
+```
+
+Initialize a dedicated event loop
+
+#### run
+
+```python
+run(coro: Coroutine[Any, Any, Any], timeout: float | None = None) -> Any
+```
+
+Run a coroutine in the event loop.
+
+**Parameters:**
+
+- **coro** (Coroutine\[Any, Any, Any\]) – Coroutine to execute
+- **timeout** (float | None) – Optional timeout in seconds
+
+**Returns:**
+
+- Any – Result of the coroutine
+
+**Raises:**
+
+- TimeoutError – If execution exceeds timeout
+
+#### get_loop
+
+```python
+get_loop() -> asyncio.AbstractEventLoop
+```
+
+Get the event loop.
+
+**Returns:**
+
+- AbstractEventLoop – The event loop
+
+#### run_background
+
+```python
+run_background(
+ coro_factory: Callable[[asyncio.Event], Coroutine[Any, Any, Any]],
+ timeout: float | None = None,
+) -> tuple[concurrent.futures.Future[Any], asyncio.Event]
+```
+
+Schedule `coro_factory` to run in the executor's event loop **without** blocking the caller thread.
+
+The factory receives an :class:`asyncio.Event` that can be used to cooperatively shut
+the coroutine down. The method returns **both** the concurrent future (to observe
+completion or failure) and the created *stop_event* so that callers can signal termination.
+
+**Parameters:**
+
+- **coro_factory** (Callable\\[[Event\], Coroutine\[Any, Any, Any\]\]) – A callable receiving the stop_event and returning the coroutine to execute.
+- **timeout** (float | None) – Optional timeout while waiting for the stop_event to be created.
+
+**Returns:**
+
+- tuple\[Future\[Any\], Event\] – Tuple `(future, stop_event)`.
+
+#### shutdown
+
+```python
+shutdown(timeout: float = 2) -> None
+```
+
+Shut down the background event loop and thread.
+
+**Parameters:**
+
+- **timeout** (float) – Timeout in seconds for shutting down the event loop
+
+### MCPError
+
+Bases: Exception
+
+Base class for MCP-related errors.
+
+#### __init__
+
+```python
+__init__(message: str) -> None
+```
+
+Initialize the MCPError.
+
+**Parameters:**
+
+- **message** (str) – Descriptive error message
+
+### MCPConnectionError
+
+Bases: MCPError
+
+Error connecting to MCP server.
+
+#### __init__
+
+```python
+__init__(
+ message: str,
+ server_info: MCPServerInfo | None = None,
+ operation: str | None = None,
+) -> None
+```
+
+Initialize the MCPConnectionError.
+
+**Parameters:**
+
+- **message** (str) – Descriptive error message
+- **server_info** (MCPServerInfo | None) – Server connection information that was used
+- **operation** (str | None) – Name of the operation that was being attempted
+
+### MCPToolNotFoundError
+
+Bases: MCPError
+
+Error when a tool is not found on the server.
+
+#### __init__
+
+```python
+__init__(
+ message: str, tool_name: str, available_tools: list[str] | None = None
+) -> None
+```
+
+Initialize the MCPToolNotFoundError.
+
+**Parameters:**
+
+- **message** (str) – Descriptive error message
+- **tool_name** (str) – Name of the tool that was requested but not found
+- **available_tools** (list\[str\] | None) – List of available tool names, if known
+
+### MCPInvocationError
+
+Bases: ToolInvocationError
+
+Error during tool invocation.
+
+#### __init__
+
+```python
+__init__(
+ message: str, tool_name: str, tool_args: dict[str, Any] | None = None
+) -> None
+```
+
+Initialize the MCPInvocationError.
+
+**Parameters:**
+
+- **message** (str) – Descriptive error message
+- **tool_name** (str) – Name of the tool that was being invoked
+- **tool_args** (dict\[str, Any\] | None) – Arguments that were passed to the tool
+
+### MCPClient
+
+Bases: ABC
+
+Abstract base class for MCP clients.
+
+This class defines the common interface and shared functionality for all MCP clients,
+regardless of the transport mechanism used.
+
+#### connect
+
+```python
+connect() -> list[types.Tool]
+```
+
+Connect to an MCP server.
+
+**Returns:**
+
+- list\[Tool\] – List of available tools on the server
+
+**Raises:**
+
+- MCPConnectionError – If connection to the server fails
+
+#### call_tool
+
+```python
+call_tool(tool_name: str, tool_args: dict[str, Any]) -> str
+```
+
+Call a tool on the connected MCP server.
+
+**Parameters:**
+
+- **tool_name** (str) – Name of the tool to call
+- **tool_args** (dict\[str, Any\]) – Arguments to pass to the tool
+
+**Returns:**
+
+- str – JSON string representation of the tool invocation result
+
+**Raises:**
+
+- MCPConnectionError – If not connected to an MCP server
+- MCPInvocationError – If the tool invocation fails
+
+#### aclose
+
+```python
+aclose() -> None
+```
+
+Close the connection and clean up resources.
+
+This method ensures all resources are properly released, even if errors occur.
+
+### StdioClient
+
+Bases: MCPClient
+
+MCP client that connects to servers using stdio transport.
+
+#### __init__
+
+```python
+__init__(
+ command: str,
+ args: list[str] | None = None,
+ env: dict[str, str | Secret] | None = None,
+ max_retries: int = 3,
+ base_delay: float = 1.0,
+ max_delay: float = 30.0,
+) -> None
+```
+
+Initialize a stdio MCP client.
+
+**Parameters:**
+
+- **command** (str) – Command to run (e.g., "python", "node")
+- **args** (list\[str\] | None) – Arguments to pass to the command
+- **env** (dict\[str, str | Secret\] | None) – Environment variables for the command
+- **max_retries** (int) – Maximum number of reconnection attempts
+- **base_delay** (float) – Base delay for exponential backoff in seconds
+
+#### connect
+
+```python
+connect() -> list[types.Tool]
+```
+
+Connect to an MCP server using stdio transport.
+
+**Returns:**
+
+- list\[Tool\] – List of available tools on the server
+
+**Raises:**
+
+- MCPConnectionError – If connection to the server fails
+
+### SSEClient
+
+Bases: MCPClient
+
+MCP client that connects to servers using SSE transport.
+
+#### __init__
+
+```python
+__init__(
+ server_info: SSEServerInfo,
+ max_retries: int = 3,
+ base_delay: float = 1.0,
+ max_delay: float = 30.0,
+) -> None
+```
+
+Initialize an SSE MCP client using server configuration.
+
+**Parameters:**
+
+- **server_info** (SSEServerInfo) – Configuration object containing URL, token, timeout, etc.
+- **max_retries** (int) – Maximum number of reconnection attempts
+- **base_delay** (float) – Base delay for exponential backoff in seconds
+
+#### connect
+
+```python
+connect() -> list[types.Tool]
+```
+
+Connect to an MCP server using SSE transport.
+
+Note: If both custom headers and token are provided, custom headers take precedence.
+
+**Returns:**
+
+- list\[Tool\] – List of available tools on the server
+
+**Raises:**
+
+- MCPConnectionError – If connection to the server fails
+
+### StreamableHttpClient
+
+Bases: MCPClient
+
+MCP client that connects to servers using streamable HTTP transport.
+
+#### __init__
+
+```python
+__init__(
+ server_info: StreamableHttpServerInfo,
+ max_retries: int = 3,
+ base_delay: float = 1.0,
+ max_delay: float = 30.0,
+) -> None
+```
+
+Initialize a streamable HTTP MCP client using server configuration.
+
+**Parameters:**
+
+- **server_info** (StreamableHttpServerInfo) – Configuration object containing URL, token, timeout, etc.
+- **max_retries** (int) – Maximum number of reconnection attempts
+- **base_delay** (float) – Base delay for exponential backoff in seconds
+
+#### connect
+
+```python
+connect() -> list[types.Tool]
+```
+
+Connect to an MCP server using streamable HTTP transport.
+
+Note: If both custom headers and token are provided, custom headers take precedence.
+
+**Returns:**
+
+- list\[Tool\] – List of available tools on the server
+
+**Raises:**
+
+- MCPConnectionError – If connection to the server fails
+
+### MCPServerInfo
+
+Bases: ABC
+
+Abstract base class for MCP server connection parameters.
+
+This class defines the common interface for all MCP server connection types.
+
+#### create_client
+
+```python
+create_client() -> MCPClient
+```
+
+Create an appropriate MCP client for this server info.
+
+**Returns:**
+
+- MCPClient – An instance of MCPClient configured with this server info
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this server info to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary representation of this server info
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MCPServerInfo
+```
+
+Deserialize server info from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary containing serialized server info
+
+**Returns:**
+
+- MCPServerInfo – Instance of the appropriate server info class
+
+### SSEServerInfo
+
+Bases: MCPServerInfo
+
+Data class that encapsulates SSE MCP server connection parameters.
+
+For authentication tokens containing sensitive data, you can use Secret objects
+for secure handling and serialization:
+
+```python
+server_info = SSEServerInfo(
+ url="https://my-mcp-server.com",
+ token=Secret.from_env_var("API_KEY"),
+)
+```
+
+For custom headers (e.g., non-standard authentication):
+
+```python
+# Single custom header with Secret
+server_info = SSEServerInfo(
+ url="https://my-mcp-server.com",
+ headers={"X-API-Key": Secret.from_env_var("API_KEY")},
+)
+
+# Multiple headers (mix of Secret and plain strings)
+server_info = SSEServerInfo(
+ url="https://my-mcp-server.com",
+ headers={
+ "X-API-Key": Secret.from_env_var("API_KEY"),
+ "X-Client-ID": "my-client-id",
+ },
+)
+```
+
+**Parameters:**
+
+- **url** (str | None) – Full URL of the MCP server (including /sse endpoint)
+- **base_url** (str | None) – Base URL of the MCP server (deprecated, use url instead)
+- **token** (str | Secret | None) – Authentication token for the server (optional, generates "Authorization: Bearer `dict\[str, str | Secret\] | None) – Custom HTTP headers (optional, takes precedence over token parameter if provided)
+- **timeout** (int) – Connection timeout in seconds
+
+#### create_client
+
+```python
+create_client() -> MCPClient
+```
+
+Create an SSE MCP client.
+
+**Returns:**
+
+- MCPClient – Configured MCPClient instance
+
+### StreamableHttpServerInfo
+
+Bases: MCPServerInfo
+
+Data class that encapsulates streamable HTTP MCP server connection parameters.
+
+For authentication tokens containing sensitive data, you can use Secret objects
+for secure handling and serialization:
+
+```python
+server_info = StreamableHttpServerInfo(
+ url="https://my-mcp-server.com",
+ token=Secret.from_env_var("API_KEY"),
+)
+```
+
+For custom headers (e.g., non-standard authentication):
+
+```python
+# Single custom header with Secret
+server_info = StreamableHttpServerInfo(
+ url="https://my-mcp-server.com",
+ headers={"X-API-Key": Secret.from_env_var("API_KEY")},
+)
+
+# Multiple headers (mix of Secret and plain strings)
+server_info = StreamableHttpServerInfo(
+ url="https://my-mcp-server.com",
+ headers={
+ "X-API-Key": Secret.from_env_var("API_KEY"),
+ "X-Client-ID": "my-client-id",
+ },
+)
+```
+
+**Parameters:**
+
+- **url** (str) – Full URL of the MCP server (streamable HTTP endpoint)
+- **token** (str | Secret | None) – Authentication token for the server (optional, generates "Authorization: Bearer `dict\[str, str | Secret\] | None) – Custom HTTP headers (optional, takes precedence over token parameter if provided)
+- **timeout** (int) – Connection timeout in seconds
+
+#### create_client
+
+```python
+create_client() -> MCPClient
+```
+
+Create a streamable HTTP MCP client.
+
+**Returns:**
+
+- MCPClient – Configured StreamableHttpClient instance
+
+### StdioServerInfo
+
+Bases: MCPServerInfo
+
+Data class that encapsulates stdio MCP server connection parameters.
+
+**Parameters:**
+
+- **command** (str) – Command to run (e.g., "python", "node")
+- **args** (list\[str\] | None) – Arguments to pass to the command
+- **env** (dict\[str, str | Secret\] | None) – Environment variables for the command
+
+For environment variables containing sensitive data, you can use Secret objects
+for secure handling and serialization:
+
+```python
+server_info = StdioServerInfo(
+ command="uv",
+ args=["run", "my-mcp-server"],
+ env={
+ "WORKSPACE_PATH": "/path/to/workspace", # Plain string
+ "API_KEY": Secret.from_env_var("API_KEY"), # Secret object
+ }
+)
+```
+
+Secret objects will be properly serialized and deserialized without exposing
+the secret value, while plain strings will be preserved as-is. Use Secret objects
+for sensitive data that needs to be handled securely.
+
+#### create_client
+
+```python
+create_client() -> MCPClient
+```
+
+Create a stdio MCP client.
+
+**Returns:**
+
+- MCPClient – Configured StdioMCPClient instance
+
+### MCPTool
+
+Bases: Tool
+
+A Tool that represents a single tool from an MCP server.
+
+This implementation uses the official MCP SDK for protocol handling while maintaining
+compatibility with the Haystack tool ecosystem.
+
+Response handling:
+
+- Text and image content are supported and returned as JSON strings
+- The JSON contains the structured response from the MCP server
+- Use json.loads() to parse the response into a dictionary
+
+State-mapping support:
+
+- MCPTool supports state-mapping parameters (`outputs_to_string`, `inputs_from_state`, `outputs_to_state`)
+- These enable integration with Agent state for automatic parameter injection and output handling
+- See the `__init__` method documentation for details on each parameter
+
+Example using Streamable HTTP:
+
+```python
+import json
+from haystack_integrations.tools.mcp import MCPTool, StreamableHttpServerInfo
+
+# Create tool instance
+tool = MCPTool(
+ name="multiply",
+ server_info=StreamableHttpServerInfo(url="http://localhost:8000/mcp")
+)
+
+# Use the tool and parse result
+result_json = tool.invoke(a=5, b=3)
+result = json.loads(result_json)
+```
+
+Example using SSE (deprecated):
+
+```python
+import json
+from haystack.tools import MCPTool, SSEServerInfo
+
+# Create tool instance
+tool = MCPTool(
+ name="add",
+ server_info=SSEServerInfo(url="http://localhost:8000/sse")
+)
+
+# Use the tool and parse result
+result_json = tool.invoke(a=5, b=3)
+result = json.loads(result_json)
+```
+
+Example using stdio:
+
+```python
+import json
+from haystack.tools import MCPTool, StdioServerInfo
+
+# Create tool instance
+tool = MCPTool(
+ name="get_current_time",
+ server_info=StdioServerInfo(command="python", args=["path/to/server.py"])
+)
+
+# Use the tool and parse result
+result_json = tool.invoke(timezone="America/New_York")
+result = json.loads(result_json)
+```
+
+#### __init__
+
+```python
+__init__(
+ name: str,
+ server_info: MCPServerInfo,
+ description: str | None = None,
+ connection_timeout: int = 30,
+ invocation_timeout: int = 30,
+ eager_connect: bool = False,
+ outputs_to_string: dict[str, Any] | None = None,
+ inputs_from_state: dict[str, str] | None = None,
+ outputs_to_state: dict[str, dict[str, Any]] | None = None,
+) -> None
+```
+
+Initialize the MCP tool.
+
+**Parameters:**
+
+- **name** (str) – Name of the tool to use
+- **server_info** (MCPServerInfo) – Server connection information
+- **description** (str | None) – Custom description (if None, server description will be used)
+- **connection_timeout** (int) – Timeout in seconds for server connection
+- **invocation_timeout** (int) – Default timeout in seconds for tool invocations
+- **eager_connect** (bool) – If True, connect to server during initialization.
+ If False (default), defer connection until warm_up or first tool use,
+ whichever comes first.
+- **outputs_to_string** (dict\[str, Any\] | None) – Optional dictionary defining how tool outputs should be converted into a string.
+ If the source is provided only the specified output key is sent to the handler.
+ If the source is omitted the whole tool result is sent to the handler.
+ Example: `{"source": "docs", "handler": my_custom_function}`
+- **inputs_from_state** (dict\[str, str\] | None) – Optional dictionary mapping state keys to tool parameter names.
+ Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- **outputs_to_state** (dict\[str, dict\[str, Any\]\] | None) – Optional dictionary defining how tool outputs map to keys within state as well as
+ optional handlers. If the source is provided only the specified output key is sent
+ to the handler.
+ Example with source: `{"documents": {"source": "docs", "handler": custom_handler}}`
+ Example without source: `{"documents": {"handler": custom_handler}}`
+
+**Raises:**
+
+- MCPConnectionError – If connection to the server fails
+- MCPToolNotFoundError – If no tools are available or the requested tool is not found
+- TimeoutError – If connection times out
+
+#### ainvoke
+
+```python
+ainvoke(**kwargs: Any) -> str | dict[str, Any]
+```
+
+Asynchronous tool invocation.
+
+**Parameters:**
+
+- **kwargs** (Any) – Arguments to pass to the tool
+
+**Returns:**
+
+- str | dict\[str, Any\] – JSON string or dictionary representation of the tool invocation result.
+ Returns a dictionary when outputs_to_state is configured to enable state updates.
+
+**Raises:**
+
+- MCPInvocationError – If the tool invocation fails
+- TimeoutError – If the operation times out
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Connect and fetch the tool schema if eager_connect is turned off.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the MCPTool to a dictionary.
+
+The serialization preserves all information needed to recreate the tool,
+including server connection parameters, timeout settings, and state-mapping parameters.
+Note that the active connection is not maintained.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data in the format:
+ `{"type": fully_qualified_class_name, "data": {parameters}}`
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Tool
+```
+
+Deserializes the MCPTool from a dictionary.
+
+This method reconstructs an MCPTool instance from a serialized dictionary,
+including recreating the server_info object and state-mapping parameters.
+A new connection will be established to the MCP server during initialization.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary containing serialized tool data
+
+**Returns:**
+
+- Tool – A fully initialized MCPTool instance
+
+**Raises:**
+
+- Exception – if connection fails
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the tool synchronously.
+
+## haystack_integrations.tools.mcp.mcp_toolset
+
+### MCPToolset
+
+Bases: Toolset
+
+A Toolset that connects to an MCP (Model Context Protocol) server and provides access to its tools.
+
+MCPToolset dynamically discovers and loads all tools from any MCP-compliant server,
+supporting both network-based streaming connections (Streamable HTTP, SSE) and local
+process-based stdio connections.
+This dual connectivity allows for integrating with both remote and local MCP servers.
+
+Example using MCPToolset in a Haystack Pipeline:
+
+```python
+# Prerequisites:
+# 1. pip install uvx mcp-server-time # Install required MCP server and tools
+# 2. export OPENAI_API_KEY="your-api-key" # Set up your OpenAI API key
+
+import os
+from haystack import Pipeline
+from haystack.components.converters import OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.tools import ToolInvoker
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.tools.mcp import MCPToolset, StdioServerInfo
+
+# Create server info for the time service (can also use SSEServerInfo for remote servers)
+server_info = StdioServerInfo(command="uvx", args=["mcp-server-time", "--local-timezone=Europe/Berlin"])
+
+# Create the toolset - this will automatically discover all available tools
+# You can optionally specify which tools to include
+mcp_toolset = MCPToolset(
+ server_info=server_info,
+ tool_names=["get_current_time"] # Only include the get_current_time tool
+)
+
+# Create a pipeline with the toolset
+pipeline = Pipeline()
+pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini", tools=mcp_toolset))
+pipeline.add_component("tool_invoker", ToolInvoker(tools=mcp_toolset))
+pipeline.add_component(
+ "adapter",
+ OutputAdapter(
+ template="{{ initial_msg + initial_tool_messages + tool_messages }}",
+ output_type=list[ChatMessage],
+ unsafe=True,
+ ),
+)
+pipeline.add_component("response_llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+pipeline.connect("llm.replies", "tool_invoker.messages")
+pipeline.connect("llm.replies", "adapter.initial_tool_messages")
+pipeline.connect("tool_invoker.tool_messages", "adapter.tool_messages")
+pipeline.connect("adapter.output", "response_llm.messages")
+
+# Run the pipeline with a user question
+user_input = "What is the time in New York? Be brief."
+user_input_msg = ChatMessage.from_user(text=user_input)
+
+result = pipeline.run({"llm": {"messages": [user_input_msg]}, "adapter": {"initial_msg": [user_input_msg]}})
+print(result["response_llm"]["replies"][0].text)
+```
+
+You can also use the toolset via Streamable HTTP to talk to remote servers:
+
+```python
+from haystack_integrations.tools.mcp import MCPToolset, StreamableHttpServerInfo
+
+# Create the toolset with streamable HTTP connection
+toolset = MCPToolset(
+ server_info=StreamableHttpServerInfo(url="http://localhost:8000/mcp"),
+ tool_names=["multiply"] # Optional: only include specific tools
+)
+# Use the toolset as shown in the pipeline example above
+```
+
+Example with state configuration for Agent integration:
+
+```python
+from haystack_integrations.tools.mcp import MCPToolset, StdioServerInfo
+
+# Create the toolset with per-tool state configuration
+# This enables tools to read from and write to the Agent's State
+toolset = MCPToolset(
+ server_info=StdioServerInfo(command="uvx", args=["mcp-server-git"]),
+ tool_names=["git_status", "git_diff", "git_log"],
+
+ # Maps the state key "repository" to the tool parameter "repo_path" for each tool
+ inputs_from_state={
+ "git_status": {"repository": "repo_path"},
+ "git_diff": {"repository": "repo_path"},
+ "git_log": {"repository": "repo_path"},
+ },
+ # Map tool outputs to state keys for each tool
+ outputs_to_state={
+ "git_status": {"status_result": {"source": "status"}}, # Extract "status" from output
+ "git_diff": {"diff_result": {}}, # use full output with default handling
+ },
+)
+```
+
+Example using SSE (deprecated):
+
+```python
+from haystack_integrations.tools.mcp import MCPToolset, SSEServerInfo
+from haystack.components.tools import ToolInvoker
+
+# Create the toolset with an SSE connection
+sse_toolset = MCPToolset(
+ server_info=SSEServerInfo(url="http://some-remote-server.com:8000/sse"),
+ tool_names=["add", "subtract"] # Only include specific tools
+)
+
+# Use the toolset as shown in the pipeline example above
+```
+
+#### __init__
+
+```python
+__init__(
+ server_info: MCPServerInfo,
+ tool_names: list[str] | None = None,
+ connection_timeout: float = 30.0,
+ invocation_timeout: float = 30.0,
+ eager_connect: bool = False,
+ inputs_from_state: dict[str, dict[str, str]] | None = None,
+ outputs_to_state: dict[str, dict[str, dict[str, Any]]] | None = None,
+ outputs_to_string: dict[str, dict[str, Any]] | None = None,
+) -> None
+```
+
+Initialize the MCP toolset.
+
+**Parameters:**
+
+- **server_info** (MCPServerInfo) – Connection information for the MCP server
+- **tool_names** (list\[str\] | None) – Optional list of tool names to include. If provided, only tools with
+ matching names will be added to the toolset.
+- **connection_timeout** (float) – Timeout in seconds for server connection
+- **invocation_timeout** (float) – Default timeout in seconds for tool invocations
+- **eager_connect** (bool) – If True, connect to server and load tools during initialization.
+ If False (default), defer connection to warm_up.
+- **inputs_from_state** (dict\[str, dict\[str, str\]\] | None) – Optional dictionary mapping tool names to their inputs_from_state config.
+ Each config maps state keys to tool parameter names.
+ Tool names should match available tools from the server; a warning is logged for
+ unknown tools. Note: With Haystack >= 2.22.0, parameter names are validated;
+ ValueError is raised for invalid parameters. With earlier versions, invalid
+ parameters fail at runtime.
+ Example: `{"git_status": {"repository": "repo_path"}}`
+- **outputs_to_state** (dict\[str, dict\[str, dict\[str, Any\]\]\] | None) – Optional dictionary mapping tool names to their outputs_to_state config.
+ Each config defines how tool outputs map to state keys with optional handlers.
+ Tool names should match available tools from the server; a warning is logged for
+ unknown tools.
+ Example: `{"git_status": {"status_result": {"source": "status"}}}`
+- **outputs_to_string** (dict\[str, dict\[str, Any\]\] | None) – Optional dictionary mapping tool names to their outputs_to_string config.
+ Each config defines how tool outputs are converted to strings.
+ Tool names should match available tools from the server; a warning is logged for
+ unknown tools.
+ Example: `{"git_diff": {"source": "diff", "handler": format_diff}}`
+
+**Raises:**
+
+- MCPToolNotFoundError – If any of the specified tool names are not found on the server
+- ValueError – If parameter names in inputs_from_state are invalid (Haystack >= 2.22.0 only)
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Connect and load tools when eager_connect is turned off.
+
+This method is automatically called by `ToolInvoker.warm_up()` and `Pipeline.warm_up()`.
+You can also call it directly before using the toolset to ensure all tool schemas
+are available without performing a real invocation.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the MCPToolset to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the MCPToolset
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MCPToolset
+```
+
+Deserialize an MCPToolset from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary representation of the MCPToolset
+
+**Returns:**
+
+- MCPToolset – A new MCPToolset instance
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the underlying MCP client safely.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/meta_llama.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/meta_llama.md
new file mode 100644
index 0000000000..7f691610f7
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/meta_llama.md
@@ -0,0 +1,127 @@
+---
+title: "Meta Llama API"
+id: integrations-meta-llama
+description: "Meta Llama API integration for Haystack"
+slug: "/integrations-meta-llama"
+---
+
+
+## haystack_integrations.components.generators.meta_llama.chat.chat_generator
+
+### MetaLlamaChatGenerator
+
+Bases: OpenAIChatGenerator
+
+Enables text generation using Llama generative models.
+For supported models, see [Llama API Docs](https://llama.developer.meta.com/docs/).
+
+Users can pass any text generation parameters valid for the Llama Chat Completion API
+directly to this component via the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+Key Features and Compatibility:
+
+- **Primary Compatibility**: Designed to work seamlessly with the Llama API Chat Completion endpoint.
+- **Streaming Support**: Supports streaming responses from the Llama API Chat Completion endpoint.
+- **Customizability**: Supports parameters supported by the Llama API Chat Completion endpoint.
+- **Response Format**: Currently only supports json_schema response format.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage)
+
+For more details on the parameters supported by the Llama API, refer to the
+[Llama API Docs](https://llama.developer.meta.com/docs/).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.llama import LlamaChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = LlamaChatGenerator()
+response = client.run(messages)
+print(response)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "Llama-4-Maverick-17B-128E-Instruct-FP8",
+ "Llama-4-Scout-17B-16E-Instruct-FP8",
+ "Llama-3.3-70B-Instruct",
+ "Llama-3.3-8B-Instruct",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+See https://llama.developer.meta.com/docs/models for the full list.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("LLAMA_API_KEY"),
+ model: str = "Llama-4-Scout-17B-16E-Instruct-FP8",
+ streaming_callback: StreamingCallbackT | None = None,
+ api_base_url: str | None = "https://api.llama.com/compat/v1/",
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ tools: ToolsType | None = None
+)
+```
+
+Creates an instance of LlamaChatGenerator. Unless specified otherwise in the `model`, this is for Llama's
+`Llama-4-Scout-17B-16E-Instruct-FP8` model.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Llama API key.
+- **model** (str) – The name of the Llama chat completion model to use.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **api_base_url** (str | None) – The Llama API Base url.
+ For more details, see LlamaAPI [docs](https://llama.developer.meta.com/docs/features/compatibility/).
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the Llama API endpoint. See [Llama API docs](https://llama.developer.meta.com/docs/features/compatibility/)
+ for more details.
+ Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+ Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+ considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+ comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+ events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+ If provided, the output will always be validated against this
+ format (unless the model returns a tool call).
+ For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+ For structured outputs with streaming, the `response_format` must be a JSON
+ schema and not a Pydantic model.
+- **timeout** (float | None) – Timeout for Llama API client calls.
+- **max_retries** (int | None) – Maximum number of retries to attempt for failed requests.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ Each tool should have a unique name.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/mistral.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/mistral.md
new file mode 100644
index 0000000000..5acc3e8b82
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/mistral.md
@@ -0,0 +1,558 @@
+---
+title: "Mistral"
+id: integrations-mistral
+description: "Mistral integration for Haystack"
+slug: "/integrations-mistral"
+---
+
+
+## haystack_integrations.components.converters.mistral.ocr_document_converter
+
+### MistralOCRDocumentConverter
+
+This component extracts text from documents using Mistral's OCR API, with optional structured
+annotations for both individual image regions (bounding boxes) and full documents.
+
+Accepts document sources in various formats (str/Path for local files, ByteStream for in-memory data,
+DocumentURLChunk for document URLs, ImageURLChunk for image URLs, or FileChunk for Mistral file IDs)
+and retrieves the recognized text via Mistral's OCR service. Local files are automatically uploaded
+to Mistral's storage.
+Returns Haystack Documents (one per source) containing all pages concatenated with form feed characters (\\f),
+ensuring compatibility with Haystack's DocumentSplitter for accurate page-wise splitting and overlap handling.
+
+**How Annotations Work:**
+When annotation schemas (`bbox_annotation_schema` or `document_annotation_schema`) are provided,
+the OCR model first extracts text and structure from the document. Then, a Vision LLM is called
+to analyze the content and generate structured annotations according to your defined schemas.
+For more details, see: https://docs.mistral.ai/capabilities/document_ai/annotations/#how-it-works
+
+**Usage Example:**
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.mistral import MistralOCRDocumentConverter
+from mistralai.models import DocumentURLChunk, ImageURLChunk, FileChunk
+
+converter = MistralOCRDocumentConverter(
+ api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+ model="mistral-ocr-2505"
+)
+
+# Process multiple sources
+sources = [
+ DocumentURLChunk(document_url="https://example.com/document.pdf"),
+ ImageURLChunk(image_url="https://example.com/receipt.jpg"),
+ FileChunk(file_id="file-abc123"),
+]
+result = converter.run(sources=sources)
+
+documents = result["documents"] # List of 3 Documents
+raw_responses = result["raw_mistral_response"] # List of 3 raw responses
+```
+
+**Structured Output Example:**
+
+```python
+from pydantic import BaseModel, Field
+from haystack_integrations.mistral import MistralOCRDocumentConverter
+
+# Define schema for structured image annotations
+class ImageAnnotation(BaseModel):
+ image_type: str = Field(..., description="The type of image content")
+ short_description: str = Field(..., description="Short natural-language description")
+ summary: str = Field(..., description="Detailed summary of the image content")
+
+# Define schema for structured document annotations
+class DocumentAnnotation(BaseModel):
+ language: str = Field(..., description="Primary language of the document")
+ chapter_titles: List[str] = Field(..., description="Detected chapter or section titles")
+ urls: List[str] = Field(..., description="URLs found in the text")
+
+converter = MistralOCRDocumentConverter(
+ model="mistral-ocr-2505",
+)
+
+sources = [DocumentURLChunk(document_url="https://example.com/report.pdf")]
+result = converter.run(
+ sources=sources,
+ bbox_annotation_schema=ImageAnnotation,
+ document_annotation_schema=DocumentAnnotation,
+)
+
+documents = result["documents"]
+raw_responses = result["raw_mistral_response"]
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "mistral-ocr-2512",
+ "mistral-ocr-latest",
+ "mistral-ocr-2503",
+ "mistral-ocr-2505",
+]
+
+```
+
+A list of models supported by Mistral AI
+see [Mistral AI docs](https://docs.mistral.ai/getting-started/models) for more information
+and send a GET HTTP request to "https://api.mistral.ai/v1/models" for a full list of model IDs.
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"),
+ model: str = "mistral-ocr-2505",
+ include_image_base64: bool = False,
+ pages: list[int] | None = None,
+ image_limit: int | None = None,
+ image_min_size: int | None = None,
+ cleanup_uploaded_files: bool = True,
+)
+```
+
+Creates a MistralOCRDocumentConverter component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Mistral API key. Defaults to the MISTRAL_API_KEY environment variable.
+- **model** (str) – The OCR model to use. Default is "mistral-ocr-2505".
+ See more: https://docs.mistral.ai/getting-started/models/models_overview/
+- **include_image_base64** (bool) – If True, includes base64 encoded images in the response.
+ This may significantly increase response size and processing time.
+- **pages** (list\[int\] | None) – Specific page numbers to process (0-indexed). If None, processes all pages.
+- **image_limit** (int | None) – Maximum number of images to extract from the document.
+- **image_min_size** (int | None) – Minimum height and width (in pixels) for images to be extracted.
+- **cleanup_uploaded_files** (bool) – If True, automatically deletes files uploaded to Mistral after processing.
+ Only affects files uploaded from local sources (str, Path, ByteStream).
+ Files provided as FileChunk are not deleted. Default is True.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MistralOCRDocumentConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- MistralOCRDocumentConverter – Deserialized component.
+
+#### run
+
+```python
+run(
+ sources: list[
+ str | Path | ByteStream | DocumentURLChunk | FileChunk | ImageURLChunk
+ ],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+ bbox_annotation_schema: type[BaseModel] | None = None,
+ document_annotation_schema: type[BaseModel] | None = None,
+) -> dict[str, Any]
+```
+
+Extract text from documents using Mistral OCR.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream | DocumentURLChunk | FileChunk | ImageURLChunk\]) – List of document sources to process. Each source can be one of:
+- str: File path to a local document
+- Path: Path object to a local document
+- ByteStream: Haystack ByteStream object containing document data
+- DocumentURLChunk: Mistral chunk for document URLs (signed or public URLs to PDFs, etc.)
+- ImageURLChunk: Mistral chunk for image URLs (signed or public URLs to images)
+- FileChunk: Mistral chunk for file IDs (files previously uploaded to Mistral)
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents.
+ This value can be either a list of dictionaries or a single dictionary.
+ If it's a single dictionary, its content is added to the metadata of all produced Documents.
+ If it's a list, the length of the list must match the number of sources, because they will be zipped.
+- **bbox_annotation_schema** (type\[BaseModel\] | None) – Optional Pydantic model for structured annotations per bounding box.
+ When provided, a Vision LLM analyzes each image region and returns structured data.
+- **document_annotation_schema** (type\[BaseModel\] | None) – Optional Pydantic model for structured annotations for the full document.
+ When provided, a Vision LLM analyzes the entire document and returns structured data.
+ Note: Document annotation is limited to a maximum of 8 pages. Documents exceeding
+ this limit will not be processed for document annotation.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of Haystack Documents (one per source). Each Document has the following structure:
+ - `content`: All pages joined with form feed (\\f) separators in markdown format.
+ When using bbox_annotation_schema, image tags will be enriched with your defined descriptions.
+ - `meta`: Aggregated metadata dictionary with structure:
+ `{"source_page_count": int, "source_total_images": int, "source_*": any}`.
+ If document_annotation_schema was provided, all annotation fields are unpacked
+ with 'source\_' prefix (e.g., source_language, source_chapter_titles, source_urls).
+- `raw_mistral_response`:
+ List of dictionaries containing raw OCR responses from Mistral API (one per source).
+ Each response includes per-page details, images, annotations, and usage info.
+
+## haystack_integrations.components.embedders.mistral.document_embedder
+
+### MistralDocumentEmbedder
+
+Bases: OpenAIDocumentEmbedder
+
+A component for computing Document embeddings using Mistral models.
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.mistral import MistralDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = MistralDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "mistral-embed-2312",
+ "mistral-embed",
+ "codestral-embed",
+ "codestral-embed-2505",
+]
+
+```
+
+A list of models supported by Mistral AI
+see [Mistral AI docs](https://docs.mistral.ai/getting-started/models) for more information
+and send a GET HTTP request to "https://api.mistral.ai/v1/models" for a full list of model IDs.
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"),
+ model: str = "mistral-embed",
+ api_base_url: str | None = "https://api.mistral.ai/v1",
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ *,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates a MistralDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Mistral API key.
+- **model** (str) – The name of the model to use.
+- **api_base_url** (str | None) – The Mistral API Base url. For more details, see Mistral [docs](https://docs.mistral.ai/api/).
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **batch_size** (int) – Number of Documents to encode at once.
+- **progress_bar** (bool) – Whether to show a progress bar or not. Can be helpful to disable in production deployments to keep
+ the logs clean.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (str) – Separator used to concatenate the meta fields to the Document text.
+- **timeout** (float | None) – Timeout for Mistral client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+ variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact Mistral after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+## haystack_integrations.components.embedders.mistral.text_embedder
+
+### MistralTextEmbedder
+
+Bases: OpenAITextEmbedder
+
+A component for embedding strings using Mistral models.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.mistral.text_embedder import MistralTextEmbedder
+
+text_to_embed = "I love pizza!"
+text_embedder = MistralTextEmbedder()
+print(text_embedder.run(text_to_embed))
+
+# output:
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+# 'meta': {'model': 'mistral-embed',
+# 'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "mistral-embed-2312",
+ "mistral-embed",
+ "codestral-embed",
+ "codestral-embed-2505",
+]
+
+```
+
+A list of models supported by Mistral AI
+see [Mistral AI docs](https://docs.mistral.ai/getting-started/models) for more information
+and send a GET HTTP request to "https://api.mistral.ai/v1/models" for a full list of model IDs.
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"),
+ model: str = "mistral-embed",
+ api_base_url: str | None = "https://api.mistral.ai/v1",
+ prefix: str = "",
+ suffix: str = "",
+ *,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates an MistralTextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Mistral API key.
+- **model** (str) – The name of the Mistral embedding model to be used.
+- **api_base_url** (str | None) – The Mistral API Base url.
+ For more details, see Mistral [docs](https://docs.mistral.ai/api/).
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **timeout** (float | None) – Timeout for Mistral client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+ variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact Mistral after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+## haystack_integrations.components.generators.mistral.chat.chat_generator
+
+### MistralChatGenerator
+
+Bases: OpenAIChatGenerator
+
+Enables text generation using Mistral AI generative models.
+For supported models, see [Mistral AI docs](https://docs.mistral.ai/getting-started/models).
+
+Users can pass any text generation parameters valid for the Mistral Chat Completion API
+directly to this component via the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+Key Features and Compatibility:
+
+- **Primary Compatibility**: Designed to work seamlessly with the Mistral API Chat Completion endpoint.
+- **Streaming Support**: Supports streaming responses from the Mistral API Chat Completion endpoint.
+- **Customizability**: Supports all parameters supported by the Mistral API Chat Completion endpoint.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage)
+
+For more details on the parameters supported by the Mistral API, refer to the
+[Mistral API Docs](https://docs.mistral.ai/api/).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = MistralChatGenerator()
+response = client.run(messages)
+print(response)
+
+>>{'replies': [ChatMessage(_role=Secret) – The Mistral API key.
+- **model** (str) – The name of the Mistral chat completion model to use.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **api_base_url** (str | None) – The Mistral API Base url.
+ For more details, see Mistral [docs](https://docs.mistral.ai/api/).
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the Mistral endpoint. See [Mistral API docs](https://docs.mistral.ai/api/) for more details.
+ Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+ Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+ considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+ comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+ events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+ If provided, the output will always be validated against this
+ format (unless the model returns a tool call).
+ For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+ Notes:
+ - For structured outputs with streaming,
+ the `response_format` must be a JSON schema and not a Pydantic model.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ Each tool should have a unique name.
+- **timeout** (float | None) – The timeout for the Mistral API call. If not set, it defaults to either the `OPENAI_TIMEOUT`
+ environment variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact OpenAI after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/mongodb_atlas.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/mongodb_atlas.md
new file mode 100644
index 0000000000..3aa6e43140
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/mongodb_atlas.md
@@ -0,0 +1,841 @@
+---
+title: "MongoDB Atlas"
+id: integrations-mongodb-atlas
+description: "MongoDB Atlas integration for Haystack"
+slug: "/integrations-mongodb-atlas"
+---
+
+
+## haystack_integrations.components.retrievers.mongodb_atlas.embedding_retriever
+
+### MongoDBAtlasEmbeddingRetriever
+
+Retrieves documents from the MongoDBAtlasDocumentStore by embedding similarity.
+
+The similarity is dependent on the vector_search_index used in the MongoDBAtlasDocumentStore and the chosen metric
+during the creation of the index (i.e. cosine, dot product, or euclidean). See MongoDBAtlasDocumentStore for more
+information.
+
+Usage example:
+
+```python
+import numpy as np
+from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore
+from haystack_integrations.components.retrievers.mongodb_atlas import MongoDBAtlasEmbeddingRetriever
+
+store = MongoDBAtlasDocumentStore(database_name="haystack_integration_test",
+ collection_name="test_embeddings_collection",
+ vector_search_index="cosine_index",
+ full_text_search_index="full_text_index")
+retriever = MongoDBAtlasEmbeddingRetriever(document_store=store)
+
+results = retriever.run(query_embedding=np.random.random(768).tolist())
+print(results["documents"])
+```
+
+The example above retrieves the 10 most similar documents to a random query embedding from the
+MongoDBAtlasDocumentStore. Note that dimensions of the query_embedding must match the dimensions of the embeddings
+stored in the MongoDBAtlasDocumentStore.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: MongoDBAtlasDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+)
+```
+
+Create the MongoDBAtlasDocumentStore component.
+
+**Parameters:**
+
+- **document_store** (MongoDBAtlasDocumentStore) – An instance of MongoDBAtlasDocumentStore.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. Make sure that the fields used in the filters are
+ included in the configuration of the `vector_search_index`. The configuration must be done manually
+ in the Web UI of MongoDB Atlas.
+- **top_k** (int) – Maximum number of Documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `MongoDBAtlasDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MongoDBAtlasEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- MongoDBAtlasEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the MongoDBAtlasDocumentStore, based on the provided embedding similarity.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given `query_embedding`
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the MongoDBAtlasDocumentStore, based on the provided embedding
+similarity.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given `query_embedding`
+
+## haystack_integrations.components.retrievers.mongodb_atlas.full_text_retriever
+
+### MongoDBAtlasFullTextRetriever
+
+Retrieves documents from the MongoDBAtlasDocumentStore by full-text search.
+
+The full-text search is dependent on the full_text_search_index used in the MongoDBAtlasDocumentStore.
+See MongoDBAtlasDocumentStore for more information.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore
+from haystack_integrations.components.retrievers.mongodb_atlas import MongoDBAtlasFullTextRetriever
+
+store = MongoDBAtlasDocumentStore(database_name="your_existing_db",
+ collection_name="your_existing_collection",
+ vector_search_index="your_existing_index",
+ full_text_search_index="your_existing_index")
+retriever = MongoDBAtlasFullTextRetriever(document_store=store)
+
+results = retriever.run(query="Lorem ipsum")
+print(results["documents"])
+```
+
+The example above retrieves the 10 most similar documents to the query "Lorem ipsum" from the
+MongoDBAtlasDocumentStore.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: MongoDBAtlasDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+)
+```
+
+**Parameters:**
+
+- **document_store** (MongoDBAtlasDocumentStore) – An instance of MongoDBAtlasDocumentStore.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. Make sure that the fields used in the filters are
+ included in the configuration of the `full_text_search_index`. The configuration must be done manually
+ in the Web UI of MongoDB Atlas.
+- **top_k** (int) – Maximum number of Documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of MongoDBAtlasDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MongoDBAtlasFullTextRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- MongoDBAtlasFullTextRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str | list[str],
+ fuzzy: dict[str, int] | None = None,
+ match_criteria: Literal["any", "all"] | None = None,
+ score: dict[str, dict] | None = None,
+ synonyms: str | None = None,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the MongoDBAtlasDocumentStore by full-text search.
+
+**Parameters:**
+
+- **query** (str | list\[str\]) – The query string or a list of query strings to search for.
+ If the query contains multiple terms, Atlas Search evaluates each term separately for matches.
+- **fuzzy** (dict\[str, int\] | None) – Enables finding strings similar to the search term(s).
+ Note, `fuzzy` cannot be used with `synonyms`. Configurable options include `maxEdits`, `prefixLength`,
+ and `maxExpansions`. For more details refer to MongoDB Atlas
+ [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **match_criteria** (Literal['any', 'all'] | None) – Defines how terms in the query are matched. Supported options are `"any"` and `"all"`.
+ For more details refer to MongoDB Atlas
+ [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **score** (dict\[str, dict\] | None) – Specifies the scoring method for matching results. Supported options include `boost`, `constant`,
+ and `function`. For more details refer to MongoDB Atlas
+ [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **synonyms** (str | None) – The name of the synonym mapping definition in the index. This value cannot be an empty string.
+ Note, `synonyms` can not be used with `fuzzy`.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given `query`
+
+#### run_async
+
+```python
+run_async(
+ query: str | list[str],
+ fuzzy: dict[str, int] | None = None,
+ match_criteria: Literal["any", "all"] | None = None,
+ score: dict[str, dict] | None = None,
+ synonyms: str | None = None,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the MongoDBAtlasDocumentStore by full-text search.
+
+**Parameters:**
+
+- **query** (str | list\[str\]) – The query string or a list of query strings to search for.
+ If the query contains multiple terms, Atlas Search evaluates each term separately for matches.
+- **fuzzy** (dict\[str, int\] | None) – Enables finding strings similar to the search term(s).
+ Note, `fuzzy` cannot be used with `synonyms`. Configurable options include `maxEdits`, `prefixLength`,
+ and `maxExpansions`. For more details refer to MongoDB Atlas
+ [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **match_criteria** (Literal['any', 'all'] | None) – Defines how terms in the query are matched. Supported options are `"any"` and `"all"`.
+ For more details refer to MongoDB Atlas
+ [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **score** (dict\[str, dict\] | None) – Specifies the scoring method for matching results. Supported options include `boost`, `constant`,
+ and `function`. For more details refer to MongoDB Atlas
+ [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **synonyms** (str | None) – The name of the synonym mapping definition in the index. This value cannot be an empty string.
+ Note, `synonyms` can not be used with `fuzzy`.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given `query`
+
+## haystack_integrations.document_stores.mongodb_atlas.document_store
+
+### MongoDBAtlasDocumentStore
+
+A MongoDBAtlasDocumentStore implementation that uses the
+[MongoDB Atlas](https://www.mongodb.com/atlas/database) service that is easy to deploy, operate, and scale.
+
+To connect to MongoDB Atlas, you need to provide a connection string in the format:
+`"mongodb+srv://{mongo_atlas_username}:{mongo_atlas_password}@{mongo_atlas_host}/?{mongo_atlas_params_string}"`.
+
+This connection string can be obtained on the MongoDB Atlas Dashboard by clicking on the `CONNECT` button, selecting
+Python as the driver, and copying the connection string. The connection string can be provided as an environment
+variable `MONGO_CONNECTION_STRING` or directly as a parameter to the `MongoDBAtlasDocumentStore` constructor.
+
+After providing the connection string, you'll need to specify the `database_name` and `collection_name` to use.
+Most likely that you'll create these via the MongoDB Atlas web UI but one can also create them via the MongoDB
+Python driver. Creating databases and collections is beyond the scope of MongoDBAtlasDocumentStore. The primary
+purpose of this document store is to read and write documents to an existing collection.
+
+Users must provide both a `vector_search_index` for vector search operations and a `full_text_search_index`
+for full-text search operations. The `vector_search_index` supports a chosen metric
+(e.g., cosine, dot product, or Euclidean), while the `full_text_search_index` enables efficient text-based searches.
+Both indexes can be created through the Atlas web UI.
+
+For more details on MongoDB Atlas, see the official
+MongoDB Atlas [documentation](https://www.mongodb.com/docs/atlas/getting-started/).
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore
+
+store = MongoDBAtlasDocumentStore(database_name="your_existing_db",
+ collection_name="your_existing_collection",
+ vector_search_index="your_existing_index",
+ full_text_search_index="your_existing_index")
+print(store.count_documents())
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ mongo_connection_string: Secret = Secret.from_env_var(
+ "MONGO_CONNECTION_STRING"
+ ),
+ database_name: str,
+ collection_name: str,
+ vector_search_index: str,
+ full_text_search_index: str,
+ embedding_field: str = "embedding",
+ content_field: str = "content"
+)
+```
+
+Creates a new MongoDBAtlasDocumentStore instance.
+
+**Parameters:**
+
+- **mongo_connection_string** (Secret) – MongoDB Atlas connection string in the format:
+ `"mongodb+srv://{mongo_atlas_username}:{mongo_atlas_password}@{mongo_atlas_host}/?{mongo_atlas_params_string}"`.
+ This can be obtained on the MongoDB Atlas Dashboard by clicking on the `CONNECT` button.
+ This value will be read automatically from the env var "MONGO_CONNECTION_STRING".
+- **database_name** (str) – Name of the database to use.
+- **collection_name** (str) – Name of the collection to use. To use this document store for embedding retrieval,
+ this collection needs to have a vector search index set up on the `embedding` field.
+- **vector_search_index** (str) – The name of the vector search index to use for vector search operations.
+ Create a vector_search_index in the Atlas web UI and specify the init params of MongoDBAtlasDocumentStore. For more details refer to MongoDB
+ Atlas [documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/create-index/#std-label-avs-create-index).
+- **full_text_search_index** (str) – The name of the search index to use for full-text search operations.
+ Create a full_text_search_index in the Atlas web UI and specify the init params of
+ MongoDBAtlasDocumentStore. For more details refer to MongoDB Atlas
+ [documentation](https://www.mongodb.com/docs/atlas/atlas-search/create-index/).
+- **embedding_field** (str) – The name of the field containing document embeddings. Default is "embedding".
+- **content_field** (str) – The name of the field containing the document content. Default is "content".
+ This field allows defining which field to load into the Haystack Document object as content.
+ It can be particularly useful when integrating with an existing collection for retrieval. We discourage
+ using this parameter when working with collections created by Haystack.
+
+**Raises:**
+
+- ValueError – If the collection name contains invalid characters.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MongoDBAtlasDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- MongoDBAtlasDocumentStore – Deserialized component.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – The number of documents in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – The number of documents in the document store.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Applies a filter and counts the documents that matched it.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the document list.
+
+**Returns:**
+
+- int – The number of documents that match the filter.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously applies a filter and counts the documents that matched it.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the document list.
+
+**Returns:**
+
+- int – The number of documents that match the filter.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Applies a filter selecting documents and counts the unique values for each meta field of the matched documents.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the document list.
+- **metadata_fields** (list\[str\]) – The metadata fields to count unique values for.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary where the keys are the metadata field names and the values are the count of unique
+ values.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously applies a filter selecting documents and counts the unique values for each meta field of the
+matched documents.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the document list.
+- **metadata_fields** (list\[str\]) – The metadata fields to count unique values for.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary where the keys are the metadata field names and the values are the count of unique
+ values.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict]
+```
+
+Returns the metadata fields and their corresponding types.
+
+Since MongoDB is schemaless, this method samples the latest 50 documents to infer the fields and their types.
+
+**Returns:**
+
+- dict\[str, dict\] – A dictionary where the keys are the metadata field names and the values are dictionary with 'type'.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict]
+```
+
+Asynchronously returns the metadata fields and their corresponding types.
+
+Since MongoDB is schemaless, this method samples the latest 50 documents to infer the fields and their types.
+
+**Returns:**
+
+- dict\[str, dict\] – A dictionary where the keys are the metadata field names and the values are dictionary with 'type'.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+For a given metadata field, find its max and min value.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get the min and max values for.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with 'min' and 'max' keys.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously for a given metadata field, find its max and min value.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get the min and max values for.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with 'min' and 'max' keys.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a field matching a search_term or all possible values if no search term is given.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to retrieve unique values for.
+- **search_term** (str | None) – The search term to filter values. Matches as a case-insensitive substring.
+- **from\_** (int) – The starting index for pagination.
+- **size** (int) – The number of values to return.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple containing a list of unique values and the total count of unique values matching the
+ search term.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously retrieves unique values for a field matching a search_term or all possible values if no search
+term is given.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to retrieve unique values for.
+- **search_term** (str | None) – The search term to filter values. Matches as a case-insensitive substring.
+- **from\_** (int) – The starting index for pagination.
+- **size** (int) – The number of values to return.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple containing a list of unique values and the total count of unique values matching the
+ search term.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the Haystack [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply. It returns only the documents that match the filters.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the Haystack [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply. It returns only the documents that match the filters.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents into the MongoDB Atlas collection.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+**Raises:**
+
+- DuplicateDocumentError – If a document with the same ID already exists in the document store
+ and the policy is set to DuplicatePolicy.FAIL (or not specified).
+- ValueError – If the documents are not of type Document.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents into the MongoDB Atlas collection.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+**Raises:**
+
+- DuplicateDocumentError – If a document with the same ID already exists in the document store
+ and the policy is set to DuplicatePolicy.FAIL (or not specified).
+- ValueError – If the documents are not of type Document.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with a matching document_ids from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes all documents with a matching document_ids from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### delete_all_documents
+
+```python
+delete_all_documents(*, recreate_collection: bool = False) -> None
+```
+
+Deletes all documents in the document store.
+
+**Parameters:**
+
+- **recreate_collection** (bool) – If True, the collection will be dropped and recreated with the original
+ configuration and indexes. If False, all documents will be deleted while preserving the collection.
+ Recreating the collection is faster for very large collections.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async(*, recreate_collection: bool = False) -> None
+```
+
+Asynchronously deletes all documents in the document store.
+
+**Parameters:**
+
+- **recreate_collection** (bool) – If True, the collection will be dropped and recreated with the original
+ configuration and indexes. If False, all documents will be deleted while preserving the collection.
+ Recreating the collection is faster for very large collections.
+
+## haystack_integrations.document_stores.mongodb_atlas.filters
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/nvidia.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/nvidia.md
new file mode 100644
index 0000000000..91b5f301d4
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/nvidia.md
@@ -0,0 +1,730 @@
+---
+title: "Nvidia"
+id: integrations-nvidia
+description: "Nvidia integration for Haystack"
+slug: "/integrations-nvidia"
+---
+
+
+## haystack_integrations.components.embedders.nvidia.document_embedder
+
+### NvidiaDocumentEmbedder
+
+A component for embedding documents using embedding models provided by [NVIDIA NIMs](https://ai.nvidia.com).
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.nvidia import NvidiaDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+text_embedder = NvidiaDocumentEmbedder(model="nvidia/nv-embedqa-e5-v5", api_url="https://integrate.api.nvidia.com/v1")
+# Components warm up automatically on first run.
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str | None = None,
+ api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+ api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ truncate: EmbeddingTruncateMode | str | None = None,
+ timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaTextEmbedder component.
+
+**Parameters:**
+
+- **model** (str | None) – Embedding model to use.
+ If no specific model along with locally hosted API URL is provided,
+ the system defaults to the available model found using /models API.
+- **api_key** (Secret | None) – API key for the NVIDIA NIM.
+- **api_url** (str) – Custom API URL for the NVIDIA NIM.
+ Format for API URL is `http://host:port`
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **batch_size** (int) – Number of Documents to encode at once.
+ Cannot be greater than 50.
+- **progress_bar** (bool) – Whether to show a progress bar or not.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (str) – Separator used to concatenate the meta fields to the Document text.
+- **truncate** (EmbeddingTruncateMode | str | None) – Specifies how inputs longer than the maximum token length should be truncated.
+ If None the behavior is model-dependent, see the official documentation for more information.
+- **timeout** (float | None) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+ or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### default_model
+
+```python
+default_model() -> None
+```
+
+Set default model in local NIM mode.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### available_models
+
+```python
+available_models: list[Model]
+```
+
+Get a list of available models that work with NvidiaDocumentEmbedder.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NvidiaDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- NvidiaDocumentEmbedder – The deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Embed a list of Documents.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with the following keys and values:
+- `documents` - List of processed Documents with embeddings.
+- `meta` - Metadata on usage statistics, etc.
+
+**Raises:**
+
+- TypeError – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.nvidia.text_embedder
+
+### NvidiaTextEmbedder
+
+A component for embedding strings using embedding models provided by [NVIDIA NIMs](https://ai.nvidia.com).
+
+For models that differentiate between query and document inputs,
+this component embeds the input string as a query.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.nvidia import NvidiaTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = NvidiaTextEmbedder(model="nvidia/nv-embedqa-e5-v5", api_url="https://integrate.api.nvidia.com/v1")
+# Components warm up automatically on first run.
+
+print(text_embedder.run(text_to_embed))
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str | None = None,
+ api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+ api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+ prefix: str = "",
+ suffix: str = "",
+ truncate: EmbeddingTruncateMode | str | None = None,
+ timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaTextEmbedder component.
+
+**Parameters:**
+
+- **model** (str | None) – Embedding model to use.
+ If no specific model along with locally hosted API URL is provided,
+ the system defaults to the available model found using /models API.
+- **api_key** (Secret | None) – API key for the NVIDIA NIM.
+- **api_url** (str) – Custom API URL for the NVIDIA NIM.
+ Format for API URL is `http://host:port`
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **truncate** (EmbeddingTruncateMode | str | None) – Specifies how inputs longer that the maximum token length should be truncated.
+ If None the behavior is model-dependent, see the official documentation for more information.
+- **timeout** (float | None) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+ or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### default_model
+
+```python
+default_model() -> None
+```
+
+Set default model in local NIM mode.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### available_models
+
+```python
+available_models: list[Model]
+```
+
+Get a list of available models that work with NvidiaTextEmbedder.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NvidiaTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- NvidiaTextEmbedder – The deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Embed a string.
+
+**Parameters:**
+
+- **text** (str) – The text to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\] | dict\[str, Any\]\] – A dictionary with the following keys and values:
+- `embedding` - Embedding of the text.
+- `meta` - Metadata on usage statistics, etc.
+
+**Raises:**
+
+- TypeError – If the input is not a string.
+- ValueError – If the input string is empty.
+
+## haystack_integrations.components.embedders.nvidia.truncate
+
+### EmbeddingTruncateMode
+
+Bases: Enum
+
+Specifies how inputs to the NVIDIA embedding components are truncated.
+
+If START, the input will be truncated from the start.
+If END, the input will be truncated from the end.
+If NONE, an error will be returned (if the input is too long).
+
+#### from_str
+
+```python
+from_str(string: str) -> EmbeddingTruncateMode
+```
+
+Create an truncate mode from a string.
+
+**Parameters:**
+
+- **string** (str) – String to convert.
+
+**Returns:**
+
+- EmbeddingTruncateMode – Truncate mode.
+
+## haystack_integrations.components.generators.nvidia.chat.chat_generator
+
+### NvidiaChatGenerator
+
+Bases: OpenAIChatGenerator
+
+Enables text generation using NVIDIA generative models.
+
+For supported models, see [NVIDIA Docs](https://build.nvidia.com/models).
+
+Users can pass any text generation parameters valid for the NVIDIA Chat Completion API
+directly to this component via the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage)
+
+For more details on the parameters supported by the NVIDIA API, refer to the
+[NVIDIA Docs](https://build.nvidia.com/models).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = NvidiaChatGenerator()
+response = client.run(messages)
+print(response)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("NVIDIA_API_KEY"),
+ model: str = "meta/llama-3.1-8b-instruct",
+ streaming_callback: StreamingCallbackT | None = None,
+ api_base_url: str | None = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of NvidiaChatGenerator.
+
+**Parameters:**
+
+- **api_key** (Secret) – The NVIDIA API key.
+- **model** (str) – The name of the NVIDIA chat completion model to use.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **api_base_url** (str | None) – The NVIDIA API Base url.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the NVIDIA API endpoint. See [NVIDIA API docs](https://docs.nvcf.nvidia.com/ai/generative-models/)
+ for more details.
+ Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+ Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+ considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+ comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+ events as they become available, with the stream terminated by a data: [DONE] message.
+- `response_format`: For NVIDIA NIM servers, this parameter has limited support.
+ The basic JSON mode with `{"type": "json_object"}` is supported by compatible models, to produce
+ valid JSON output.
+ To generate structured JSON output, use the `response_format` parameter.
+ Example:
+ ```python
+ generation_kwargs={
+ "response_format": {
+ "type": "json_schema",
+ "json_schema": {
+ "name": "my_schema",
+ "schema": json_schema,
+ },
+ }
+ }
+ ```
+ For more details, see the [NVIDIA NIM documentation](https://docs.nvidia.com/nim/vision-language-models/latest/structured-generation.html).
+- **tools** (ToolsType | None) – A list of tools or a Toolset for which the model can prepare calls. This parameter can accept either a
+ list of `Tool` objects or a `Toolset` instance.
+- **timeout** (float | None) – The timeout for the NVIDIA API call.
+- **max_retries** (int | None) – Maximum number of retries to contact NVIDIA after an internal error.
+ If not set, it defaults to either the `NVIDIA_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+## haystack_integrations.components.generators.nvidia.generator
+
+### NvidiaGenerator
+
+Generates text using generative models hosted with [NVIDIA NIM](https://ai.nvidia.com).
+
+Available via the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover).
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.nvidia import NvidiaGenerator
+
+generator = NvidiaGenerator(
+ model="meta/llama3-8b-instruct",
+ model_arguments={
+ "temperature": 0.2,
+ "top_p": 0.7,
+ "max_tokens": 1024,
+ },
+)
+# Components warm up automatically on first run.
+
+result = generator.run(prompt="What is the answer?")
+print(result["replies"])
+print(result["meta"])
+print(result["usage"])
+```
+
+You need an NVIDIA API key for this component to work.
+
+#### __init__
+
+```python
+__init__(
+ model: str | None = None,
+ api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+ api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+ model_arguments: dict[str, Any] | None = None,
+ timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaGenerator component.
+
+**Parameters:**
+
+- **model** (str | None) – Name of the model to use for text generation.
+ See the [NVIDIA NIMs](https://ai.nvidia.com)
+ for more information on the supported models.
+ `Note`: If no specific model along with locally hosted API URL is provided,
+ the system defaults to the available model found using /models API.
+ Check supported models at [NVIDIA NIM](https://ai.nvidia.com).
+- **api_key** (Secret | None) – API key for the NVIDIA NIM. Set it as the `NVIDIA_API_KEY` environment
+ variable or pass it here.
+- **api_url** (str) – Custom API URL for the NVIDIA NIM.
+- **model_arguments** (dict\[str, Any\] | None) – Additional arguments to pass to the model provider. These arguments are
+ specific to a model.
+ Search your model in the [NVIDIA NIM](https://ai.nvidia.com)
+ to find the arguments it accepts.
+- **timeout** (float | None) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+ or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### default_model
+
+```python
+default_model() -> None
+```
+
+Set default model in local NIM mode.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### available_models
+
+```python
+available_models: list[Model]
+```
+
+Get a list of available models that work with ChatNVIDIA.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NvidiaGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- NvidiaGenerator – Deserialized component.
+
+#### run
+
+```python
+run(prompt: str) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Queries the model with the provided prompt.
+
+**Parameters:**
+
+- **prompt** (str) – Text to be sent to the generative model.
+
+**Returns:**
+
+- dict\[str, list\[str\] | list\[dict\[str, Any\]\]\] – A dictionary with the following keys:
+- `replies` - Replies generated by the model.
+- `meta` - Metadata for each reply.
+
+## haystack_integrations.components.rankers.nvidia.ranker
+
+### NvidiaRanker
+
+A component for ranking documents using ranking models provided by [NVIDIA NIMs](https://ai.nvidia.com).
+
+Usage example:
+
+```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"),
+)
+# Components warm up automatically on first run.
+
+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"])
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str | None = None,
+ truncate: RankerTruncateMode | str | None = None,
+ api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+ api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+ top_k: int = 5,
+ query_prefix: str = "",
+ document_prefix: str = "",
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaRanker component.
+
+**Parameters:**
+
+- **model** (str | None) – Ranking model to use.
+- **truncate** (RankerTruncateMode | str | None) – Truncation strategy to use. Can be "NONE", "END", or RankerTruncateMode. Defaults to NIM's default.
+- **api_key** (Secret | None) – API key for the NVIDIA NIM.
+- **api_url** (str) – Custom API URL for the NVIDIA NIM.
+- **top_k** (int) – Number of documents to return.
+- **query_prefix** (str) – A string to add at the beginning of the query text before ranking.
+ Use it to prepend the text with an instruction, as required by reranking models like `bge`.
+- **document_prefix** (str) – A string to add at the beginning of each document before ranking. You can use it to prepend the document
+ with an instruction, as required by embedding models like `bge`.
+- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed with the document.
+- **embedding_separator** (str) – Separator to concatenate metadata fields to the document.
+- **timeout** (float | None) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+ or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the ranker to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the ranker's attributes.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NvidiaRanker
+```
+
+Deserialize the ranker from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – A dictionary containing the ranker's attributes.
+
+**Returns:**
+
+- NvidiaRanker – The deserialized ranker.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the ranker.
+
+**Raises:**
+
+- ValueError – If the API key is required for hosted NVIDIA NIMs.
+
+#### run
+
+```python
+run(
+ query: str, documents: list[Document], top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Rank a list of documents based on a given query.
+
+**Parameters:**
+
+- **query** (str) – The query to rank the documents against.
+- **documents** (list\[Document\]) – The list of documents to rank.
+- **top_k** (int | None) – The number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing the ranked documents.
+
+**Raises:**
+
+- TypeError – If the arguments are of the wrong type.
+
+## haystack_integrations.components.rankers.nvidia.truncate
+
+### RankerTruncateMode
+
+Bases: str, Enum
+
+Specifies how inputs to the NVIDIA ranker components are truncated.
+
+If NONE, the input will not be truncated and an error returned instead.
+If END, the input will be truncated from the end.
+
+#### from_str
+
+```python
+from_str(string: str) -> RankerTruncateMode
+```
+
+Create an truncate mode from a string.
+
+**Parameters:**
+
+- **string** (str) – String to convert.
+
+**Returns:**
+
+- RankerTruncateMode – Truncate mode.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/ollama.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/ollama.md
new file mode 100644
index 0000000000..e6f29073bd
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/ollama.md
@@ -0,0 +1,486 @@
+---
+title: "Ollama"
+id: integrations-ollama
+description: "Ollama integration for Haystack"
+slug: "/integrations-ollama"
+---
+
+
+## haystack_integrations.components.embedders.ollama.document_embedder
+
+### OllamaDocumentEmbedder
+
+Computes the embeddings of a list of Documents and stores the obtained vectors in each Document's embedding field.
+
+It uses embedding models compatible with the Ollama Library.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.ollama import OllamaDocumentEmbedder
+
+doc = Document(content="What do llamas say once you have thanked them? No probllama!")
+document_embedder = OllamaDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "nomic-embed-text",
+ url: str = "http://localhost:11434",
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: int = 120,
+ keep_alive: float | str | None = None,
+ prefix: str = "",
+ suffix: str = "",
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ batch_size: int = 32,
+) -> None
+```
+
+Create a new OllamaDocumentEmbedder instance.
+
+**Parameters:**
+
+- **model** (str) – The name of the model to use. The model should be available in the running Ollama instance.
+- **url** (str) – The URL of a running Ollama instance.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature, top_p, and others.
+ See the available arguments in
+ [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **timeout** (int) – The number of seconds before throwing a timeout error from the Ollama API.
+- **keep_alive** (float | str | None) – The option that controls how long the model will stay loaded into memory following the request.
+ If not set, it will use the default value from the Ollama (5 minutes).
+ The value can be set to:
+- a duration string (such as "10m" or "24h")
+- a number in seconds (such as 3600)
+- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m")
+- '0' which will unload the model immediately after generating a response.
+- **prefix** (str) – A string to add at the beginning of each text.
+- **suffix** (str) – A string to add at the end of each text.
+- **progress_bar** (bool) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (str) – Separator used to concatenate the metadata fields to the document text.
+- **batch_size** (int) – Number of documents to process at once.
+
+#### run
+
+```python
+run(
+ documents: list[Document], generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Runs an Ollama Model to compute embeddings of the provided documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to be converted to an embedding.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+ top_p, etc. See the
+ [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+
+**Returns:**
+
+- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with the following keys:
+- `documents`: Documents with embedding information attached
+- `meta`: The metadata collected during the embedding process
+
+#### run_async
+
+```python
+run_async(
+ documents: list[Document], generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Asynchronously run an Ollama Model to compute embeddings of the provided documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to be converted to an embedding.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+ top_p, etc. See the
+ [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+
+**Returns:**
+
+- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with the following keys:
+- `documents`: Documents with embedding information attached
+- `meta`: The metadata collected during the embedding process
+
+## haystack_integrations.components.embedders.ollama.text_embedder
+
+### OllamaTextEmbedder
+
+Computes the embeddings of a list of Documents and stores the obtained vectors in each Document's embedding field.
+
+It uses embedding models compatible with the Ollama Library.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.ollama import OllamaTextEmbedder
+
+embedder = OllamaTextEmbedder()
+result = embedder.run(text="What do llamas say once you have thanked them? No probllama!")
+print(result['embedding'])
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "nomic-embed-text",
+ url: str = "http://localhost:11434",
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: int = 120,
+ keep_alive: float | str | None = None,
+) -> None
+```
+
+Create a new OllamaTextEmbedder instance.
+
+**Parameters:**
+
+- **model** (str) – The name of the model to use. The model should be available in the running Ollama instance.
+- **url** (str) – The URL of a running Ollama instance.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+ top_p, and others. See the available arguments in
+ [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **timeout** (int) – The number of seconds before throwing a timeout error from the Ollama API.
+- **keep_alive** (float | str | None) – The option that controls how long the model will stay loaded into memory following the request.
+ If not set, it will use the default value from the Ollama (5 minutes).
+ The value can be set to:
+- a duration string (such as "10m" or "24h")
+- a number in seconds (such as 3600)
+- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m")
+- '0' which will unload the model immediately after generating a response.
+
+#### run
+
+```python
+run(
+ text: str, generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Runs an Ollama Model to compute embeddings of the provided text.
+
+**Parameters:**
+
+- **text** (str) – Text to be converted to an embedding.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+ top_p, etc. See the
+ [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+
+**Returns:**
+
+- dict\[str, list\[float\] | dict\[str, Any\]\] – A dictionary with the following keys:
+- `embedding`: The computed embeddings
+- `meta`: The metadata collected during the embedding process
+
+#### run_async
+
+```python
+run_async(
+ text: str, generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Asynchronously run an Ollama Model to compute embeddings of the provided text.
+
+**Parameters:**
+
+- **text** (str) – Text to be converted to an embedding.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+ top_p, etc. See the
+ [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+
+**Returns:**
+
+- dict\[str, list\[float\] | dict\[str, Any\]\] – A dictionary with the following keys:
+- `embedding`: The computed embeddings
+- `meta`: The metadata collected during the embedding process
+
+## haystack_integrations.components.generators.ollama.chat.chat_generator
+
+### OllamaChatGenerator
+
+Haystack Chat Generator for models served with Ollama (https://ollama.ai).
+
+Supports streaming, tool calls, reasoning, and structured outputs.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.ollama.chat import OllamaChatGenerator
+from haystack.dataclasses import ChatMessage
+
+llm = OllamaChatGenerator(model="qwen3:0.6b")
+result = llm.run(messages=[ChatMessage.from_user("What is the capital of France?")])
+print(result)
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "qwen3:0.6b",
+ url: str = "http://localhost:11434",
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: int = 120,
+ max_retries: int = 0,
+ keep_alive: float | str | None = None,
+ streaming_callback: Callable[[StreamingChunk], None] | None = None,
+ tools: ToolsType | None = None,
+ response_format: None | Literal["json"] | JsonSchemaValue | None = None,
+ think: bool | Literal["low", "medium", "high"] = False,
+) -> None
+```
+
+Create a new OllamaChatGenerator instance.
+
+**Parameters:**
+
+- **model** (str) – The name of the model to use. The model must already be present (pulled) in the running Ollama instance.
+- **url** (str) – The base URL of the Ollama server (default "http://localhost:11434").
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+ top_p, and others. See the available arguments in
+ [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **timeout** (int) – The number of seconds before throwing a timeout error from the Ollama API.
+- **max_retries** (int) – Maximum number of retries to attempt for failed requests (HTTP 429, 5xx, connection/timeout errors).
+ Uses exponential backoff between attempts. Set to 0 (default) to disable retries.
+- **think** (bool | Literal['low', 'medium', 'high']) – If True, the model will "think" before producing a response.
+ Only [thinking models](https://ollama.com/search?c=thinking) support this feature.
+ Some models like gpt-oss support different levels of thinking: "low", "medium", "high".
+ The intermediate "thinking" output can be found by inspecting the `reasoning` property of the returned
+ `ChatMessage`.
+- **keep_alive** (float | str | None) – The option that controls how long the model will stay loaded into memory following the request.
+ If not set, it will use the default value from the Ollama (5 minutes).
+ The value can be set to:
+- a duration string (such as "10m" or "24h")
+- a number in seconds (such as 3600)
+- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m")
+- '0' which will unload the model immediately after generating a response.
+- **streaming_callback** (Callable\\[[StreamingChunk\], None\] | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ Each tool should have a unique name. Not all models support tools. For a list of models compatible
+ with tools, see the [models page](https://ollama.com/search?c=tools).
+- **response_format** (None | Literal['json'] | JsonSchemaValue | None) – The format for structured model outputs. The value can be:
+- None: No specific structure or format is applied to the response. The response is returned as-is.
+- "json": The response is formatted as a JSON object.
+- JSON Schema: The response is formatted as a JSON object
+ that adheres to the specified JSON Schema. (needs Ollama ≥ 0.1.34)
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OllamaChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OllamaChatGenerator – Deserialized component.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ *,
+ streaming_callback: StreamingCallbackT | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Runs an Ollama Model on a given chat history.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Per-call overrides for Ollama inference options.
+ These are merged on top of the instance-level `generation_kwargs`.
+ Optional arguments to pass to the Ollama generation endpoint, such as temperature, top_p, etc. See the
+ [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter set during component initialization.
+- **streaming_callback** (StreamingCallbackT | None) – A callable to receive `StreamingChunk` objects as they
+ arrive. Supplying a callback (here or in the constructor) switches
+ the component into streaming mode.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: A list of ChatMessages containing the model's response
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ *,
+ streaming_callback: StreamingCallbackT | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Async version of run. Runs an Ollama Model on a given chat history.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Per-call overrides for Ollama inference options.
+ These are merged on top of the instance-level `generation_kwargs`.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter set during component initialization.
+- **streaming_callback** (StreamingCallbackT | None) – A callable to receive `StreamingChunk` objects as they arrive.
+ Supplying a callback switches the component into streaming mode.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys:
+- `replies`: A list of ChatMessages containing the model's response
+
+## haystack_integrations.components.generators.ollama.generator
+
+### OllamaGenerator
+
+Provides an interface to generate text using an LLM running on Ollama.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.ollama import OllamaGenerator
+
+generator = OllamaGenerator(model="zephyr",
+ url = "http://localhost:11434",
+ generation_kwargs={
+ "num_predict": 100,
+ "temperature": 0.9,
+ })
+
+print(generator.run("Who is the best American actor?"))
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "orca-mini",
+ url: str = "http://localhost:11434",
+ generation_kwargs: dict[str, Any] | None = None,
+ system_prompt: str | None = None,
+ template: str | None = None,
+ raw: bool = False,
+ timeout: int = 120,
+ keep_alive: float | str | None = None,
+ streaming_callback: Callable[[StreamingChunk], None] | None = None,
+) -> None
+```
+
+Create a new OllamaGenerator instance.
+
+**Parameters:**
+
+- **model** (str) – The name of the model to use. The model should be available in the running Ollama instance.
+- **url** (str) – The URL of a running Ollama instance.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+ top_p, and others. See the available arguments in
+ [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **system_prompt** (str | None) – Optional system message (overrides what is defined in the Ollama Modelfile).
+- **template** (str | None) – The full prompt template (overrides what is defined in the Ollama Modelfile).
+- **raw** (bool) – If True, no formatting will be applied to the prompt. You may choose to use the raw parameter
+ if you are specifying a full templated prompt in your API request.
+- **timeout** (int) – The number of seconds before throwing a timeout error from the Ollama API.
+- **streaming_callback** (Callable\\[[StreamingChunk\], None\] | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **keep_alive** (float | str | None) – The option that controls how long the model will stay loaded into memory following the request.
+ If not set, it will use the default value from the Ollama (5 minutes).
+ The value can be set to:
+- a duration string (such as "10m" or "24h")
+- a number in seconds (such as 3600)
+- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m")
+- '0' which will unload the model immediately after generating a response.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OllamaGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OllamaGenerator – Deserialized component.
+
+#### run
+
+```python
+run(
+ prompt: str,
+ generation_kwargs: dict[str, Any] | None = None,
+ *,
+ streaming_callback: Callable[[StreamingChunk], None] | None = None
+) -> dict[str, list[Any]]
+```
+
+Runs an Ollama Model on the given prompt.
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to generate a response for.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+ top_p, and others. See the available arguments in
+ [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **streaming_callback** (Callable\\[[StreamingChunk\], None\] | None) – A callback function that is called when a new token is received from the stream.
+
+**Returns:**
+
+- dict\[str, list\[Any\]\] – A dictionary with the following keys:
+- `replies`: The responses from the model
+- `meta`: The metadata collected during the run
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/openrouter.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/openrouter.md
new file mode 100644
index 0000000000..8ba2ddbf81
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/openrouter.md
@@ -0,0 +1,129 @@
+---
+title: "OpenRouter"
+id: integrations-openrouter
+description: "OpenRouter integration for Haystack"
+slug: "/integrations-openrouter"
+---
+
+
+
+## Module haystack\_integrations.components.generators.openrouter.chat.chat\_generator
+
+
+
+### OpenRouterChatGenerator
+
+Enables text generation using OpenRouter generative models.
+For supported models, see [OpenRouter docs](https://openrouter.ai/models).
+
+Users can pass any text generation parameters valid for the OpenRouter chat completion API
+directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+Key Features and Compatibility:
+- **Primary Compatibility**: Designed to work seamlessly with the OpenRouter chat completion endpoint.
+- **Streaming Support**: Supports streaming responses from the OpenRouter chat completion endpoint.
+- **Customizability**: Supports all parameters supported by the OpenRouter chat completion endpoint.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage)
+
+For more details on the parameters supported by the OpenRouter API, refer to the
+[OpenRouter API Docs](https://openrouter.ai/docs/quickstart).
+
+Usage example:
+```python
+from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = OpenRouterChatGenerator()
+response = client.run(messages)
+print(response)
+
+>>{'replies': [ChatMessage(_content='Natural Language Processing (NLP) is a branch of artificial intelligence
+>>that focuses on enabling computers to understand, interpret, and generate human language in a way that is
+>>meaningful and useful.', _role=OpenSearchDocumentStore) – An instance of OpenSearchDocumentStore to use with the Retriever.
+- **filters** (dict\[str, Any\] | None) – Filters to narrow down the search for documents in the Document Store.
+- **fuzziness** (int | str) – Determines how approximate string matching is applied in full-text queries.
+ This parameter sets the number of character edits (insertions, deletions, or substitutions)
+ required to transform one word into another. For example, the "fuzziness" between the words
+ "wined" and "wind" is 1 because only one edit is needed to match them.
+
+Defaults to `0` (exact matching). Use `"AUTO"` for automatic adjustment based on term length.
+For detailed guidance, refer to the
+[OpenSearch fuzzy query documentation](https://opensearch.org/docs/latest/query-dsl/term/fuzzy/).
+
+- **top_k** (int) – Maximum number of documents to return.
+
+- **scale_score** (bool) – If `True`, scales the score of retrieved documents to a range between 0 and 1.
+ This is useful when comparing documents across different indexes.
+
+- **all_terms_must_match** (bool) – If `True`, all terms in the query string must be present in the
+ retrieved documents. This is useful when searching for short text where even one term
+ can make a difference.
+
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied. Possible options:
+
+- `replace`: Runtime filters replace initialization filters. Use this policy to change the filtering scope
+ for specific queries.
+
+- `merge`: Runtime filters are merged with initialization filters.
+
+- **custom_query** (dict\[str, Any\] | None) – The query containing a mandatory `$query` and an optional `$filters` placeholder.
+
+ **An example custom_query:**
+
+ ```python
+ {
+ "query": {
+ "bool": {
+ "should": [{"multi_match": {
+ "query": "$query", // mandatory query placeholder
+ "type": "most_fields",
+ "fields": ["content", "title"]}}],
+ "filter": "$filters" // optional filter placeholder
+ }
+ }
+ }
+ ```
+
+An example `run()` method for this `custom_query`:
+
+```python
+retriever.run(
+ query="Why did the revenue increase?",
+ filters={
+ "operator": "AND",
+ "conditions": [
+ {"field": "meta.years", "operator": "==", "value": "2019"},
+ {"field": "meta.quarters", "operator": "in", "value": ["Q1", "Q2"]},
+ ],
+ },
+)
+```
+
+- **raise_on_failure** (bool) – Whether to raise an exception if the API call fails. Otherwise log a warning and return an empty list.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of OpenSearchDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenSearchBM25Retriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OpenSearchBM25Retriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ all_terms_must_match: bool | None = None,
+ top_k: int | None = None,
+ fuzziness: int | str | None = None,
+ scale_score: bool | None = None,
+ custom_query: dict[str, Any] | None = None,
+ document_store: OpenSearchDocumentStore | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents using BM25 retrieval.
+
+**Parameters:**
+
+- **query** (str) – The query string.
+
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved documents. The way runtime filters are applied depends on
+ the `filter_policy` specified at Retriever's initialization.
+
+- **all_terms_must_match** (bool | None) – If `True`, all terms in the query string must be present in the
+ retrieved documents.
+
+- **top_k** (int | None) – Maximum number of documents to return.
+
+- **fuzziness** (int | str | None) – Fuzziness parameter for full-text queries to apply approximate string matching.
+ For more information, see [OpenSearch fuzzy query](https://opensearch.org/docs/latest/query-dsl/term/fuzzy/).
+
+- **scale_score** (bool | None) – If `True`, scales the score of retrieved documents to a range between 0 and 1.
+ This is useful when comparing documents across different indexes.
+
+- **custom_query** (dict\[str, Any\] | None) – A custom OpenSearch query. It must include a `$query` and may optionally
+ include a `$filters` placeholder.
+
+ **An example custom_query:**
+
+ ```python
+ {
+ "query": {
+ "bool": {
+ "should": [{"multi_match": {
+ "query": "$query", // mandatory query placeholder
+ "type": "most_fields",
+ "fields": ["content", "title"]}}],
+ "filter": "$filters" // optional filter placeholder
+ }
+ }
+ }
+ ```
+
+**For this custom_query, a sample `run()` could be:**
+
+```python
+retriever.run(
+ query="Why did the revenue increase?",
+ filters={
+ "operator": "AND",
+ "conditions": [
+ {"field": "meta.years", "operator": "==", "value": "2019"},
+ {"field": "meta.quarters", "operator": "in", "value": ["Q1", "Q2"]},
+ ],
+ },
+)
+```
+
+- **document_store** (OpenSearchDocumentStore | None) – Optionally, an instance of OpenSearchDocumentStore to use with the Retriever
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing the retrieved documents with the following structure:
+- documents: List of retrieved Documents.
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ all_terms_must_match: bool | None = None,
+ top_k: int | None = None,
+ fuzziness: int | str | None = None,
+ scale_score: bool | None = None,
+ custom_query: dict[str, Any] | None = None,
+ document_store: OpenSearchDocumentStore | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents using BM25 retrieval.
+
+**Parameters:**
+
+- **query** (str) – The query string.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved documents. The way runtime filters are applied depends on
+ the `filter_policy` specified at Retriever's initialization.
+- **all_terms_must_match** (bool | None) – If `True`, all terms in the query string must be present in the
+ retrieved documents.
+- **top_k** (int | None) – Maximum number of documents to return.
+- **fuzziness** (int | str | None) – Fuzziness parameter for full-text queries to apply approximate string matching.
+ For more information, see [OpenSearch fuzzy query](https://opensearch.org/docs/latest/query-dsl/term/fuzzy/).
+- **scale_score** (bool | None) – If `True`, scales the score of retrieved documents to a range between 0 and 1.
+ This is useful when comparing documents across different indexes.
+- **custom_query** (dict\[str, Any\] | None) – A custom OpenSearch query. It must include a `$query` and may optionally
+ include a `$filters` placeholder.
+- **document_store** (OpenSearchDocumentStore | None) – Optionally, an instance of OpenSearchDocumentStore to use with the Retriever
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing the retrieved documents with the following structure:
+- documents: List of retrieved Documents.
+
+## haystack_integrations.components.retrievers.opensearch.embedding_retriever
+
+### OpenSearchEmbeddingRetriever
+
+Retrieves documents from the OpenSearchDocumentStore using a vector similarity metric.
+
+Must be connected to the OpenSearchDocumentStore to run.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: OpenSearchDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+ custom_query: dict[str, Any] | None = None,
+ raise_on_failure: bool = True,
+ efficient_filtering: bool = False,
+ search_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Create the OpenSearchEmbeddingRetriever component.
+
+**Parameters:**
+
+- **document_store** (OpenSearchDocumentStore) – An instance of OpenSearchDocumentStore to use with the Retriever.
+
+- **filters** (dict\[str, Any\] | None) – Filters applied when fetching documents from the Document Store.
+ Filters are applied during the approximate kNN search to ensure the Retriever returns
+ `top_k` matching documents.
+
+- **top_k** (int) – Maximum number of documents to return.
+
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied. Possible options:
+
+- `merge`: Runtime filters are merged with initialization filters.
+
+- `replace`: Runtime filters replace initialization filters. Use this policy to change the filtering scope.
+
+- **custom_query** (dict\[str, Any\] | None) – The custom OpenSearch query containing a mandatory `$query_embedding` and
+ an optional `$filters` placeholder.
+
+ **An example custom_query:**
+
+ ```python
+ {
+ "query": {
+ "bool": {
+ "must": [
+ {
+ "knn": {
+ "embedding": {
+ "vector": "$query_embedding", // mandatory query placeholder
+ "k": 10000,
+ }
+ }
+ }
+ ],
+ "filter": "$filters" // optional filter placeholder
+ }
+ }
+ }
+ ```
+
+For this `custom_query`, an example `run()` could be:
+
+```python
+retriever.run(
+ query_embedding=embedding,
+ filters={
+ "operator": "AND",
+ "conditions": [
+ {"field": "meta.years", "operator": "==", "value": "2019"},
+ {"field": "meta.quarters", "operator": "in", "value": ["Q1", "Q2"]},
+ ],
+ },
+)
+```
+
+- **raise_on_failure** (bool) – If `True`, raises an exception if the API call fails.
+ If `False`, logs a warning and returns an empty list.
+- **efficient_filtering** (bool) – If `True`, the filter will be applied during the approximate kNN search.
+ This is only supported for knn engines "faiss" and "lucene" and does not work with the default "nmslib".
+- **search_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for finetuning the embedding search.
+ E.g., to specify `k` and `ef_search`
+
+```python
+{
+ "k": 20, # See https://docs.opensearch.org/latest/vector-search/vector-search-techniques/approximate-knn/#the-number-of-returned-results
+ "method_parameters": {
+ "ef_search": 512, # See https://docs.opensearch.org/latest/query-dsl/specialized/k-nn/index/#ef_search
+ }
+}
+```
+
+For a full list of available parameters, see the OpenSearch documentation:
+https://docs.opensearch.org/latest/query-dsl/specialized/k-nn/index/#request-body-fields
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of OpenSearchDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenSearchEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OpenSearchEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ custom_query: dict[str, Any] | None = None,
+ efficient_filtering: bool | None = None,
+ document_store: OpenSearchDocumentStore | None = None,
+ search_kwargs: dict[str, Any] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents using a vector similarity metric.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+
+- **filters** (dict\[str, Any\] | None) – Filters applied when fetching documents from the Document Store.
+ Filters are applied during the approximate kNN search to ensure the Retriever returns `top_k` matching
+ documents.
+ The way runtime filters are applied depends on the `filter_policy` selected when initializing the Retriever.
+
+- **top_k** (int | None) – Maximum number of documents to return.
+
+- **custom_query** (dict\[str, Any\] | None) – A custom OpenSearch query containing a mandatory `$query_embedding` and an
+ optional `$filters` placeholder.
+
+ **An example custom_query:**
+
+ ```python
+ {
+ "query": {
+ "bool": {
+ "must": [
+ {
+ "knn": {
+ "embedding": {
+ "vector": "$query_embedding", // mandatory query placeholder
+ "k": 10000,
+ }
+ }
+ }
+ ],
+ "filter": "$filters" // optional filter placeholder
+ }
+ }
+ }
+ ```
+
+For this `custom_query`, an example `run()` could be:
+
+```python
+retriever.run(
+ query_embedding=embedding,
+ filters={
+ "operator": "AND",
+ "conditions": [
+ {"field": "meta.years", "operator": "==", "value": "2019"},
+ {"field": "meta.quarters", "operator": "in", "value": ["Q1", "Q2"]},
+ ],
+ },
+)
+```
+
+- **efficient_filtering** (bool | None) – If `True`, the filter will be applied during the approximate kNN search.
+ This is only supported for knn engines "faiss" and "lucene" and does not work with the default "nmslib".
+- **document_store** (OpenSearchDocumentStore | None) – Optional instance of OpenSearchDocumentStore to use with the Retriever.
+- **search_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for finetuning the embedding search. If not provided,
+ defaults to the parameter set at initialization (if any).
+ E.g., to specify `k` and `ef_search`
+
+```python
+{
+ "k": 20, # See https://docs.opensearch.org/latest/vector-search/vector-search-techniques/approximate-knn/#the-number-of-returned-results
+ "method_parameters": {
+ "ef_search": 512, # See https://docs.opensearch.org/latest/query-dsl/specialized/k-nn/index/#ef_search
+ }
+}
+```
+
+For a full list of available parameters, see the OpenSearch documentation:
+https://docs.opensearch.org/latest/query-dsl/specialized/k-nn/index/#request-body-fields
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Dictionary with key "documents" containing the retrieved Documents.
+- documents: List of Document similar to `query_embedding`.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ custom_query: dict[str, Any] | None = None,
+ efficient_filtering: bool | None = None,
+ document_store: OpenSearchDocumentStore | None = None,
+ search_kwargs: dict[str, Any] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents using a vector similarity metric.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+
+- **filters** (dict\[str, Any\] | None) – Filters applied when fetching documents from the Document Store.
+ Filters are applied during the approximate kNN search to ensure the Retriever
+ returns `top_k` matching documents.
+ The way runtime filters are applied depends on the `filter_policy` selected when initializing the Retriever.
+
+- **top_k** (int | None) – Maximum number of documents to return.
+
+- **custom_query** (dict\[str, Any\] | None) – A custom OpenSearch query containing a mandatory `$query_embedding` and an
+ optional `$filters` placeholder.
+
+ **An example custom_query:**
+
+ ```python
+ {
+ "query": {
+ "bool": {
+ "must": [
+ {
+ "knn": {
+ "embedding": {
+ "vector": "$query_embedding", // mandatory query placeholder
+ "k": 10000,
+ }
+ }
+ }
+ ],
+ "filter": "$filters" // optional filter placeholder
+ }
+ }
+ }
+ ```
+
+For this `custom_query`, an example `run()` could be:
+
+```python
+retriever.run(
+ query_embedding=embedding,
+ filters={
+ "operator": "AND",
+ "conditions": [
+ {"field": "meta.years", "operator": "==", "value": "2019"},
+ {"field": "meta.quarters", "operator": "in", "value": ["Q1", "Q2"]},
+ ],
+ },
+)
+```
+
+- **efficient_filtering** (bool | None) – If `True`, the filter will be applied during the approximate kNN search.
+ This is only supported for knn engines "faiss" and "lucene" and does not work with the default "nmslib".
+- **document_store** (OpenSearchDocumentStore | None) – Optional instance of OpenSearchDocumentStore to use with the Retriever.
+- **search_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for finetuning the embedding search. If not provided,
+ defaults to the parameter set at initialization (if any).
+ E.g., to specify `k` and `ef_search`
+
+```python
+{
+ "k": 20, # See https://docs.opensearch.org/latest/vector-search/vector-search-techniques/approximate-knn/#the-number-of-returned-results
+ "method_parameters": {
+ "ef_search": 512, # See https://docs.opensearch.org/latest/query-dsl/specialized/k-nn/index/#ef_search
+ }
+}
+```
+
+For a full list of available parameters, see the OpenSearch documentation:
+https://docs.opensearch.org/latest/query-dsl/specialized/k-nn/index/#request-body-fields
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Dictionary with key "documents" containing the retrieved Documents.
+- documents: List of Document similar to `query_embedding`.
+
+## haystack_integrations.components.retrievers.opensearch.metadata_retriever
+
+### OpenSearchMetadataRetriever
+
+Retrieves and ranks metadata from documents stored in an OpenSearchDocumentStore.
+
+It searches specified metadata fields for matches to a given query, ranks the results based on relevance using
+Jaccard similarity, and returns the top-k results containing only the specified metadata fields. Additionally, it
+adds a boost to the score of exact matches.
+
+The search is designed for metadata fields whose values are **text** (strings). It uses prefix, wildcard and fuzzy
+matching to find candidate documents; these query types operate only on text/keyword fields in OpenSearch.
+
+Metadata fields with **non-string types** (integers, floats, booleans, lists of non-strings) are indexed by
+OpenSearch as numeric, boolean, or array types. Those field types do not support prefix, wildcard, or full-text
+match queries, so documents are typically not found when you search only by such fields.
+
+**Mixed types** in the same metadata field (e.g. a list containing both strings and numbers) are not supported.
+
+Must be connected to the OpenSearchDocumentStore to run.
+
+Example:
+\`\`\`python
+from haystack import Document
+from haystack_integrations.document_stores.opensearch import OpenSearchDocumentStore
+from haystack_integrations.components.retrievers.opensearch import OpenSearchMetadataRetriever
+
+````
+# Create documents with metadata
+docs = [
+ Document(
+ content="Python programming guide",
+ meta={"category": "Python", "status": "active", "priority": 1, "author": "John Doe"}
+ ),
+ Document(
+ content="Java tutorial",
+ meta={"category": "Java", "status": "active", "priority": 2, "author": "Jane Smith"}
+ ),
+ Document(
+ content="Python advanced topics",
+ meta={"category": "Python", "status": "inactive", "priority": 3, "author": "John Doe"}
+ ),
+]
+document_store.write_documents(docs, refresh=True)
+
+# Create retriever specifying which metadata fields to search and return
+retriever = OpenSearchMetadataRetriever(
+ document_store=document_store,
+ metadata_fields=["category", "status", "priority"],
+ top_k=10,
+)
+
+# Search for metadata
+result = retriever.run(query="Python")
+
+# Result structure:
+# {
+# "metadata": [
+# {"category": "Python", "status": "active", "priority": 1},
+# {"category": "Python", "status": "inactive", "priority": 3},
+# ]
+# }
+#
+# Note: Only the specified metadata_fields are returned in the results.
+# Other metadata fields (like "author") and document content are excluded.
+```
+````
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: OpenSearchDocumentStore,
+ metadata_fields: list[str],
+ top_k: int = 20,
+ exact_match_weight: float = 0.6,
+ mode: Literal["strict", "fuzzy"] = "fuzzy",
+ fuzziness: int | Literal["AUTO"] = 2,
+ prefix_length: int = 0,
+ max_expansions: int = 200,
+ tie_breaker: float = 0.7,
+ jaccard_n: int = 3,
+ raise_on_failure: bool = True
+) -> None
+```
+
+Create the OpenSearchMetadataRetriever component.
+
+**Parameters:**
+
+- **document_store** (OpenSearchDocumentStore) – An instance of OpenSearchDocumentStore to use with the Retriever.
+- **metadata_fields** (list\[str\]) – List of metadata field names to search within each document's metadata.
+- **top_k** (int) – Maximum number of top results to return based on relevance. Default is 20.
+- **exact_match_weight** (float) – Weight to boost the score of exact matches in metadata fields.
+ Default is 0.6. It's used on both "strict" and "fuzzy" modes and applied after the search executes.
+- **mode** (Literal['strict', 'fuzzy']) – Search mode. "strict" uses prefix and wildcard matching,
+ "fuzzy" uses fuzzy matching with dis_max queries. Default is "fuzzy".
+ In both modes, results are scored using Jaccard similarity (n-gram based)
+ computed server-side via a Painless script; n is controlled by jaccard_n.
+- **fuzziness** (int | Literal['AUTO']) – Maximum allowed Damerau-Levenshtein distance (edit distance) for fuzzy matching.
+ Accepts an integer (e.g., 0, 1, 2) or "AUTO" which chooses based on term length.
+ Default is 2. Only applies when mode is "fuzzy".
+- **prefix_length** (int) – Number of leading characters that must match exactly before fuzzy matching applies.
+ Default is 0 (no prefix requirement). Only applies when mode is "fuzzy".
+- **max_expansions** (int) – Maximum number of term variations the fuzzy query can generate.
+ Default is 200. Only applies when mode is "fuzzy".
+- **tie_breaker** (float) – Weight (0..1) for other matching clauses in the dis_max query.
+ Boosts documents that match multiple clauses. Default is 0.7. Only applies when mode is "fuzzy".
+- **jaccard_n** (int) – N-gram size for Jaccard similarity scoring. Default 3; larger n favors longer token matches.
+- **raise_on_failure** (bool) – If `True`, raises an exception if the API call fails.
+ If `False`, logs a warning and returns an empty list.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of OpenSearchDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenSearchMetadataRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OpenSearchMetadataRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ *,
+ document_store: OpenSearchDocumentStore | None = None,
+ metadata_fields: list[str] | None = None,
+ top_k: int | None = None,
+ exact_match_weight: float | None = None,
+ mode: Literal["strict", "fuzzy"] | None = None,
+ fuzziness: int | Literal["AUTO"] | None = None,
+ prefix_length: int | None = None,
+ max_expansions: int | None = None,
+ tie_breaker: float | None = None,
+ jaccard_n: int | None = None,
+ filters: dict[str, Any] | None = None
+) -> dict[str, list[dict[str, Any]]]
+```
+
+Execute a search query against the metadata fields of documents stored in the Document Store.
+
+**Parameters:**
+
+- **query** (str) – The search query string, which can contain multiple comma-separated parts.
+ Each part will be searched across all specified fields.
+- **document_store** (OpenSearchDocumentStore | None) – The Document Store to run the query against.
+ If not provided, the one provided in `__init__` is used.
+- **metadata_fields** (list\[str\] | None) – List of metadata field names to search within.
+ If not provided, the fields provided in `__init__` are used.
+- **top_k** (int | None) – Maximum number of top results to return based on relevance.
+ The search retrieves up to 1000 hits from OpenSearch, then applies boosting and filters
+ the results to the top_k most relevant matches.
+ If not provided, the top_k provided in `__init__` is used.
+- **exact_match_weight** (float | None) – Weight to boost the score of exact matches in metadata fields.
+ If not provided, the exact_match_weight provided in `__init__` is used.
+- **mode** (Literal['strict', 'fuzzy'] | None) – Search mode. "strict" uses prefix and wildcard matching,
+ "fuzzy" uses fuzzy matching with dis_max queries.
+ In both modes, results are scored using Jaccard similarity (n-gram based) via a Painless script.
+ If not provided, the mode provided in `__init__` is used.
+- **fuzziness** (int | Literal['AUTO'] | None) – Maximum allowed Damerau-Levenshtein distance (edit distance) for fuzzy matching.
+ Accepts an integer (e.g., 0, 1, 2) or "AUTO" which chooses based on term length.
+ Only applies when mode is "fuzzy". If not provided, the fuzziness provided in `__init__` is used.
+- **prefix_length** (int | None) – Number of leading characters that must match exactly before fuzzy matching applies.
+ Only applies when mode is "fuzzy". If not provided, the prefix_length provided in `__init__` is used.
+- **max_expansions** (int | None) – Maximum number of term variations the fuzzy query can generate.
+ Only applies when mode is "fuzzy". If not provided, the max_expansions provided in `__init__` is used.
+- **tie_breaker** (float | None) – Weight (0..1) for other matching clauses; boosts docs matching multiple
+ clauses. Only applies when mode is "fuzzy". If not provided, the tie_breaker provided in `__init__` is used.
+- **jaccard_n** (int | None) – N-gram size for Jaccard similarity scoring. If not provided, the jaccard_n from `__init__`
+ is used.
+- **filters** (dict\[str, Any\] | None) – Additional filters to apply to the search query.
+
+**Returns:**
+
+- dict\[str, list\[dict\[str, Any\]\]\] – A dictionary containing the top-k retrieved metadata results.
+
+Example:
+\`\`\`python
+from haystack import Document
+
+````
+# First, add a document with matching metadata to the store
+store.write_documents([
+ Document(
+ content="Python programming guide",
+ meta={"category": "Python", "status": "active", "priority": 1}
+ )
+])
+
+retriever = OpenSearchMetadataRetriever(
+ document_store=store,
+ metadata_fields=["category", "status", "priority"]
+)
+result = retriever.run(query="Python, active")
+# Returns: {"metadata": [{"category": "Python", "status": "active", "priority": 1}]}
+```
+````
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ *,
+ document_store: OpenSearchDocumentStore | None = None,
+ metadata_fields: list[str] | None = None,
+ top_k: int | None = None,
+ exact_match_weight: float | None = None,
+ mode: Literal["strict", "fuzzy"] | None = None,
+ fuzziness: int | Literal["AUTO"] | None = None,
+ prefix_length: int | None = None,
+ max_expansions: int | None = None,
+ tie_breaker: float | None = None,
+ jaccard_n: int | None = None,
+ filters: dict[str, Any] | None = None
+) -> dict[str, list[dict[str, Any]]]
+```
+
+Asynchronously execute a search query against the metadata fields of documents stored in the Document Store.
+
+**Parameters:**
+
+- **query** (str) – The search query string, which can contain multiple comma-separated parts.
+ Each part will be searched across all specified fields.
+- **document_store** (OpenSearchDocumentStore | None) – The Document Store to run the query against.
+ If not provided, the one provided in `__init__` is used.
+- **metadata_fields** (list\[str\] | None) – List of metadata field names to search within.
+ If not provided, the fields provided in `__init__` are used.
+- **top_k** (int | None) – Maximum number of top results to return based on relevance.
+ The search retrieves up to 1000 hits from OpenSearch, then applies boosting and filters
+ the results to the top_k most relevant matches.
+ If not provided, the top_k provided in `__init__` is used.
+- **exact_match_weight** (float | None) – Weight to boost the score of exact matches in metadata fields.
+ If not provided, the exact_match_weight provided in `__init__` is used.
+- **mode** (Literal['strict', 'fuzzy'] | None) – Search mode. "strict" uses prefix and wildcard matching,
+ "fuzzy" uses fuzzy matching with dis_max queries.
+ In both modes, results are scored using Jaccard similarity (n-gram based) via a Painless script.
+ If not provided, the mode provided in `__init__` is used.
+- **fuzziness** (int | Literal['AUTO'] | None) – Maximum allowed Damerau-Levenshtein distance (edit distance) for fuzzy matching.
+ Accepts an integer (e.g., 0, 1, 2) or "AUTO" which chooses based on term length.
+ Only applies when mode is "fuzzy". If not provided, the fuzziness provided in `__init__` is used.
+- **prefix_length** (int | None) – Number of leading characters that must match exactly before fuzzy matching applies.
+ Only applies when mode is "fuzzy". If not provided, the prefix_length provided in `__init__` is used.
+- **max_expansions** (int | None) – Maximum number of term variations the fuzzy query can generate.
+ Only applies when mode is "fuzzy". If not provided, the max_expansions provided in `__init__` is used.
+- **tie_breaker** (float | None) – Weight (0..1) for other matching clauses; boosts docs matching multiple clauses.
+ Only applies when mode is "fuzzy". If not provided, the tie_breaker provided in `__init__` is used.
+- **jaccard_n** (int | None) – N-gram size for Jaccard similarity scoring. If not provided, the jaccard_n from `__init__`
+ is used.
+- **filters** (dict\[str, Any\] | None) – Additional filters to apply to the search query.
+
+**Returns:**
+
+- dict\[str, list\[dict\[str, Any\]\]\] – A dictionary containing the top-k retrieved metadata results.
+
+Example:
+\`\`\`python
+from haystack import Document
+
+````
+# First, add a document with matching metadata to the store
+await store.write_documents_async([
+ Document(
+ content="Python programming guide",
+ meta={"category": "Python", "status": "active", "priority": 1}
+ )
+])
+
+retriever = OpenSearchMetadataRetriever(
+ document_store=store,
+ metadata_fields=["category", "status", "priority"]
+)
+result = await retriever.run_async(query="Python, active")
+# Returns: {"metadata": [{"category": "Python", "status": "active", "priority": 1}]}
+```
+````
+
+## haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever
+
+### OpenSearchHybridRetriever
+
+A hybrid retriever that combines embedding-based and keyword-based retrieval from OpenSearch.
+
+Example usage:
+
+Make sure you have "sentence-transformers>=3.0.0":
+
+```
+pip install haystack-ai datasets "sentence-transformers>=3.0.0"
+```
+
+And OpenSearch running. You can run OpenSearch with Docker:
+
+```
+docker run -d --name opensearch-nosec -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node"
+-e "DISABLE_SECURITY_PLUGIN=true" opensearchproject/opensearch:2.12.0
+```
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack_integrations.components.retrievers.opensearch import OpenSearchHybridRetriever
+from haystack_integrations.document_stores.opensearch import OpenSearchDocumentStore
+
+# Initialize the document store
+doc_store = OpenSearchDocumentStore(
+ hosts=["OpenSearchDocumentStore) – The OpenSearchDocumentStore to use for retrieval.
+- **embedder** (TextEmbedder) – A TextEmbedder to use for embedding the query.
+ See `haystack.components.embedders.types.protocol.TextEmbedder` for more information.
+- **filters_bm25** (dict\[str, Any\] | None) – Filters for the BM25 retriever.
+- **fuzziness** (int | str) – The fuzziness for the BM25 retriever.
+- **top_k_bm25** (int) – The number of results to return from the BM25 retriever.
+- **scale_score** (bool) – Whether to scale the score for the BM25 retriever.
+- **all_terms_must_match** (bool) – Whether all terms must match for the BM25 retriever.
+- **filter_policy_bm25** (str | FilterPolicy) – The filter policy for the BM25 retriever.
+- **custom_query_bm25** (dict\[str, Any\] | None) – A custom query for the BM25 retriever.
+- **filters_embedding** (dict\[str, Any\] | None) – Filters for the embedding retriever.
+- **top_k_embedding** (int) – The number of results to return from the embedding retriever.
+- **filter_policy_embedding** (str | FilterPolicy) – The filter policy for the embedding retriever.
+- **custom_query_embedding** (dict\[str, Any\] | None) – A custom query for the embedding retriever.
+- **search_kwargs_embedding** (dict\[str, Any\] | None) – Additional search kwargs for the embedding retriever.
+- **join_mode** (str | JoinMode) – The mode to use for joining the results from the BM25 and embedding retrievers.
+- **weights** (list\[float\] | None) – The weights for the joiner.
+- **top_k** (int | None) – The number of results to return from the joiner.
+- **sort_by_score** (bool) – Whether to sort the results by score.
+- \*\***kwargs** (Any) – Additional keyword arguments. Use the following keys to pass extra parameters to the retrievers:
+- "bm25_retriever" -> OpenSearchBM25Retriever
+- "embedding_retriever" -> OpenSearchEmbeddingRetriever
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the underlying pipeline components.
+
+#### run
+
+```python
+run(
+ query: str,
+ filters_bm25: dict[str, Any] | None = None,
+ filters_embedding: dict[str, Any] | None = None,
+ top_k_bm25: int | None = None,
+ top_k_embedding: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Run the hybrid retrieval pipeline and return retrieved documents.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize OpenSearchHybridRetriever to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenSearchHybridRetriever
+```
+
+Deserialize an OpenSearchHybridRetriever from a dictionary.
+
+## haystack_integrations.components.retrievers.opensearch.sql_retriever
+
+### OpenSearchSQLRetriever
+
+Executes raw OpenSearch SQL queries against an OpenSearchDocumentStore.
+
+This component allows you to execute SQL queries directly against the OpenSearch index,
+which is useful for fetching metadata, aggregations, and other structured data at runtime.
+
+Returns the raw JSON response from the OpenSearch SQL API.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: OpenSearchDocumentStore,
+ raise_on_failure: bool = True,
+ fetch_size: int | None = None
+) -> None
+```
+
+Creates the OpenSearchSQLRetriever component.
+
+**Parameters:**
+
+- **document_store** (OpenSearchDocumentStore) – An instance of OpenSearchDocumentStore to use with the Retriever.
+- **raise_on_failure** (bool) – Whether to raise an exception if the API call fails. Otherwise, log a warning and return None.
+- **fetch_size** (int | None) – Optional number of results to fetch per page. If not provided, the default
+ fetch size set in OpenSearch is used.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of OpenSearchDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenSearchSQLRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OpenSearchSQLRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ document_store: OpenSearchDocumentStore | None = None,
+ fetch_size: int | None = None,
+) -> dict[str, dict[str, Any]]
+```
+
+Execute a raw OpenSearch SQL query against the index.
+
+**Parameters:**
+
+- **query** (str) – The OpenSearch SQL query to execute.
+- **document_store** (OpenSearchDocumentStore | None) – Optionally, an instance of OpenSearchDocumentStore to use with the Retriever.
+- **fetch_size** (int | None) – Optional number of results to fetch per page. If not provided, uses the value
+ specified during initialization, or the default fetch size set in OpenSearch.
+
+**Returns:**
+
+- dict\[str, dict\[str, Any\]\] – A dictionary containing the raw JSON response from OpenSearch SQL API:
+ - result: The raw JSON response from OpenSearch (dict) or None on error.
+
+Example:
+`python retriever = OpenSearchSQLRetriever(document_store=document_store) result = retriever.run( query="SELECT content, category FROM my_index WHERE category = 'A'" ) # result["result"] contains the raw OpenSearch JSON response # For regular queries: result["result"]["hits"]["hits"] contains documents # For aggregate queries: result["result"]["aggregations"] contains aggregations `
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ document_store: OpenSearchDocumentStore | None = None,
+ fetch_size: int | None = None,
+) -> dict[str, dict[str, Any]]
+```
+
+Asynchronously execute a raw OpenSearch SQL query against the index.
+
+**Parameters:**
+
+- **query** (str) – The OpenSearch SQL query to execute.
+- **document_store** (OpenSearchDocumentStore | None) – Optionally, an instance of OpenSearchDocumentStore to use with the Retriever.
+- **fetch_size** (int | None) – Optional number of results to fetch per page. If not provided, uses the value
+ specified during initialization, or the default fetch size set in OpenSearch.
+
+**Returns:**
+
+- dict\[str, dict\[str, Any\]\] – A dictionary containing the raw JSON response from OpenSearch SQL API:
+ - result: The raw JSON response from OpenSearch (dict) or None on error.
+
+Example:
+`python retriever = OpenSearchSQLRetriever(document_store=document_store) result = await retriever.run_async( query="SELECT content, category FROM my_index WHERE category = 'A'" ) # result["result"] contains the raw OpenSearch JSON response # For regular queries: result["result"]["hits"]["hits"] contains documents # For aggregate queries: result["result"]["aggregations"] contains aggregations `
+
+## haystack_integrations.document_stores.opensearch.document_store
+
+### OpenSearchDocumentStore
+
+An instance of an OpenSearch database you can use to store all types of data.
+
+This document store is a thin wrapper around the OpenSearch client.
+It allows you to store and retrieve documents from an OpenSearch index.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.opensearch import (
+ OpenSearchDocumentStore,
+)
+from haystack import Document
+
+document_store = OpenSearchDocumentStore(hosts="localhost:9200")
+
+document_store.write_documents(
+ [
+ Document(content="My first document", id="1"),
+ Document(content="My second document", id="2"),
+ ]
+)
+
+print(document_store.count_documents())
+# 2
+
+print(document_store.filter_documents())
+# [Document(id='1', content='My first document', ...), Document(id='2', content='My second document', ...)]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ hosts: Hosts | None = None,
+ index: str = "default",
+ max_chunk_bytes: int = DEFAULT_MAX_CHUNK_BYTES,
+ embedding_dim: int = 768,
+ return_embedding: bool = False,
+ method: dict[str, Any] | None = None,
+ mappings: dict[str, Any] | None = None,
+ settings: dict[str, Any] | None = DEFAULT_SETTINGS,
+ create_index: bool = True,
+ http_auth: (
+ tuple[Secret, Secret]
+ | tuple[str, str]
+ | list[str]
+ | str
+ | AWSAuth
+ | None
+ ) = (
+ Secret.from_env_var("OPENSEARCH_USERNAME", strict=False),
+ Secret.from_env_var("OPENSEARCH_PASSWORD", strict=False),
+ ),
+ use_ssl: bool | None = None,
+ verify_certs: bool | None = None,
+ timeout: int | None = None,
+ nested_fields: list[str] | Literal["*"] | None = None,
+ **kwargs: Any
+) -> None
+```
+
+Creates a new OpenSearchDocumentStore instance.
+
+The `embeddings_dim`, `method`, `mappings`, and `settings` arguments are only used if the index does not
+exist and needs to be created. If the index already exists, its current configurations will be used.
+
+For more information on connection parameters, see the [official OpenSearch documentation](https://opensearch.org/docs/latest/clients/python-low-level/#connecting-to-opensearch)
+
+**Parameters:**
+
+- **hosts** (Hosts | None) – List of hosts running the OpenSearch client. Defaults to None
+- **index** (str) – Name of index in OpenSearch, if it doesn't exist it will be created. Defaults to "default"
+- **max_chunk_bytes** (int) – Maximum size of the requests in bytes. Defaults to 100MB
+- **embedding_dim** (int) – Dimension of the embeddings. Defaults to 768
+- **return_embedding** (bool) – Whether to return the embedding of the retrieved Documents. This parameter also applies to the
+ `filter_documents` and `filter_documents_async` methods.
+- **method** (dict\[str, Any\] | None) – The method definition of the underlying configuration of the approximate k-NN algorithm. Please
+ see the [official OpenSearch docs](https://opensearch.org/docs/latest/search-plugins/knn/knn-index/#method-definitions)
+ for more information. Defaults to None
+- **mappings** (dict\[str, Any\] | None) – The mapping of how the documents are stored and indexed. Please see the [official OpenSearch docs](https://opensearch.org/docs/latest/field-types/)
+ for more information. If None, it uses the embedding_dim and method arguments to create default mappings.
+ Defaults to None
+- **settings** (dict\[str, Any\] | None) – The settings of the index to be created. Please see the [official OpenSearch docs](https://opensearch.org/docs/latest/search-plugins/knn/knn-index/#index-settings)
+ for more information. Defaults to `{"index.knn": True}`.
+- **create_index** (bool) – Whether to create the index if it doesn't exist. Defaults to True
+- **http_auth** (tuple\[Secret, Secret\] | tuple\[str, str\] | list\[str\] | str | AWSAuth | None) – http_auth param passed to the underlying connection class.
+ For basic authentication with default connection class `Urllib3HttpConnection` this can be
+- a tuple of (username, password)
+- a list of [username, password]
+- a string of "username:password"
+ If not provided, will read values from OPENSEARCH_USERNAME and OPENSEARCH_PASSWORD environment variables.
+ For AWS authentication with `Urllib3HttpConnection` pass an instance of `AWSAuth`.
+ Defaults to None
+- **use_ssl** (bool | None) – Whether to use SSL. Defaults to None
+- **verify_certs** (bool | None) – Whether to verify certificates. Defaults to None
+- **timeout** (int | None) – Timeout in seconds. Defaults to None
+- **nested_fields** (list\[str\] | Literal['\*'] | None) – List of metadata field paths (without the `meta.` prefix) that should be mapped
+ as OpenSearch `nested` type, enabling multi-condition filtering on array-of-objects fields.
+ Pass `"*"` to auto-detect `list[dict]` fields and map them as nested from
+ the first `write_documents` batch.
+ When the index already exists, nested fields are discovered from the live mapping.
+ Defaults to None (no nested support).
+- \*\***kwargs** (Any) – Optional arguments that `OpenSearch` takes. For the full list of supported kwargs,
+ see the [official OpenSearch reference](https://opensearch-project.github.io/opensearch-py/api-ref/clients/opensearch_client.html)
+
+#### create_index
+
+```python
+create_index(
+ index: str | None = None,
+ mappings: dict[str, Any] | None = None,
+ settings: dict[str, Any] | None = None,
+) -> None
+```
+
+Creates an index in OpenSearch.
+
+Note that this method ignores the `create_index` argument from the constructor.
+
+**Parameters:**
+
+- **index** (str | None) – Name of the index to create. If None, the index name from the constructor is used.
+- **mappings** (dict\[str, Any\] | None) – The mapping of how the documents are stored and indexed. Please see the [official OpenSearch docs](https://opensearch.org/docs/latest/field-types/)
+ for more information. If None, the mappings from the constructor are used.
+- **settings** (dict\[str, Any\] | None) – The settings of the index to be created. Please see the [official OpenSearch docs](https://opensearch.org/docs/latest/search-plugins/knn/knn-index/#index-settings)
+ for more information. If None, the settings from the constructor are used.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenSearchDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OpenSearchDocumentStore – Deserialized component.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns the total number of documents in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document],
+ policy: DuplicatePolicy = DuplicatePolicy.NONE,
+ refresh: Literal["wait_for", True, False] = "wait_for",
+) -> int
+```
+
+Writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+- **refresh** (Literal['wait_for', True, False]) – Controls when changes are made visible to search operations.
+- `True`: Force refresh immediately after the operation.
+- `False`: Do not refresh (better performance for bulk operations).
+- `"wait_for"`: Wait for the next refresh cycle (default, ensures read-your-writes consistency).
+ For more details, see the [OpenSearch refresh documentation](https://opensearch.org/docs/latest/api-reference/document-apis/index-document/).
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+**Raises:**
+
+- DuplicateDocumentError – If a document with the same id already exists in the document store
+ and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document],
+ policy: DuplicatePolicy = DuplicatePolicy.NONE,
+ refresh: Literal["wait_for", True, False] = "wait_for",
+) -> int
+```
+
+Asynchronously writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+- **refresh** (Literal['wait_for', True, False]) – Controls when changes are made visible to search operations.
+- `True`: Force refresh immediately after the operation.
+- `False`: Do not refresh (better performance for bulk operations).
+- `"wait_for"`: Wait for the next refresh cycle (default, ensures read-your-writes consistency).
+ For more details, see the [OpenSearch refresh documentation](https://opensearch.org/docs/latest/api-reference/document-apis/index-document/).
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+#### delete_documents
+
+```python
+delete_documents(
+ document_ids: list[str],
+ refresh: Literal["wait_for", True, False] = "wait_for",
+ routing: dict[str, str] | None = None,
+) -> None
+```
+
+Deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+- **refresh** (Literal['wait_for', True, False]) – Controls when changes are made visible to search operations.
+- `True`: Force refresh immediately after the operation.
+- `False`: Do not refresh (better performance for bulk operations).
+- `"wait_for"`: Wait for the next refresh cycle (default, ensures read-your-writes consistency).
+ For more details, see the [OpenSearch refresh documentation](https://opensearch.org/docs/latest/api-reference/document-apis/index-document/).
+- **routing** (dict\[str, str\] | None) – A dictionary mapping document IDs to their routing values.
+ Routing values are used to determine the shard where documents are stored.
+ If provided, the routing value for each document will be used during deletion.
+
+#### delete_documents_async
+
+```python
+delete_documents_async(
+ document_ids: list[str],
+ refresh: Literal["wait_for", True, False] = "wait_for",
+ routing: dict[str, str] | None = None,
+) -> None
+```
+
+Asynchronously deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+- **refresh** (Literal['wait_for', True, False]) – Controls when changes are made visible to search operations.
+- `True`: Force refresh immediately after the operation.
+- `False`: Do not refresh (better performance for bulk operations).
+- `"wait_for"`: Wait for the next refresh cycle (default, ensures read-your-writes consistency).
+ For more details, see the [OpenSearch refresh documentation](https://opensearch.org/docs/latest/api-reference/document-apis/index-document/).
+- **routing** (dict\[str, str\] | None) – A dictionary mapping document IDs to their routing values.
+ Routing values are used to determine the shard where documents are stored.
+ If provided, the routing value for each document will be used during deletion.
+
+#### delete_all_documents
+
+```python
+delete_all_documents(
+ recreate_index: bool = False, refresh: bool = True
+) -> None
+```
+
+Deletes all documents in the document store.
+
+**Parameters:**
+
+- **recreate_index** (bool) – If True, the index will be deleted and recreated with the original mappings and
+ settings. If False, all documents will be deleted using the `delete_by_query` API.
+- **refresh** (bool) – If True, OpenSearch refreshes all shards involved in the delete by query after the request
+ completes. If False, no refresh is performed. For more details, see the
+ [OpenSearch delete_by_query refresh documentation](https://opensearch.org/docs/latest/api-reference/document-apis/delete-by-query/).
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async(
+ recreate_index: bool = False, refresh: bool = True
+) -> None
+```
+
+Asynchronously deletes all documents in the document store.
+
+**Parameters:**
+
+- **recreate_index** (bool) – If True, the index will be deleted and recreated with the original mappings and
+ settings. If False, all documents will be deleted using the `delete_by_query` API.
+- **refresh** (bool) – If True, OpenSearch refreshes all shards involved in the delete by query after the request
+ completes. If False, no refresh is performed. For more details, see the
+ [OpenSearch delete_by_query refresh documentation](https://opensearch.org/docs/latest/api-reference/document-apis/delete-by-query/).
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any], refresh: bool = False) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **refresh** (bool) – If True, OpenSearch refreshes all shards involved in the delete by query after the request
+ completes so that subsequent reads (e.g. count_documents) see the update. If False, no refresh is
+ performed (better for bulk deletes). For more details, see the
+ [OpenSearch delete_by_query refresh documentation](https://opensearch.org/docs/latest/api-reference/document-apis/delete-by-query/).
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any], refresh: bool = False) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **refresh** (bool) – If True, OpenSearch refreshes all shards involved in the delete by query after the request
+ completes so that subsequent reads see the update. If False, no refresh is performed. For more details,
+ see the [OpenSearch delete_by_query refresh documentation](https://opensearch.org/docs/latest/api-reference/document-apis/delete-by-query/).
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(
+ filters: dict[str, Any], meta: dict[str, Any], refresh: bool = False
+) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update.
+- **refresh** (bool) – If True, OpenSearch refreshes all shards involved in the update by query after the request
+ completes. If False, no refresh is performed. For more details, see the
+ [OpenSearch update_by_query refresh documentation](https://opensearch.org/docs/latest/api-reference/document-apis/update-by-query/).
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(
+ filters: dict[str, Any], meta: dict[str, Any], refresh: bool = False
+) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update.
+- **refresh** (bool) – If True, OpenSearch refreshes all shards involved in the update by query after the request
+ completes. If False, no refresh is performed. For more details, see the
+ [OpenSearch update_by_query refresh documentation](https://opensearch.org/docs/latest/api-reference/document-apis/update-by-query/).
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the number of unique values for each specified metadata field of the documents that match the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of field names to calculate unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each metadata field name to the count of its unique values among the filtered
+ documents.
+
+**Raises:**
+
+- ValueError – If any of the requested fields don't exist in the index mapping.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously returns the number of unique values for each specified metadata field matching the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of field names to calculate unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each metadata field name to the count of its unique values among the filtered
+ documents.
+
+**Raises:**
+
+- ValueError – If any of the requested fields don't exist in the index mapping.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the information about the fields in the index.
+
+If we populated the index with documents like:
+
+```python
+ Document(content="Doc 1", meta={"category": "A", "status": "active", "priority": 1})
+ Document(content="Doc 2", meta={"category": "B", "status": "inactive"})
+```
+
+This method would return:
+
+```python
+ {
+ 'content': {'type': 'text'},
+ 'category': {'type': 'keyword'},
+ 'status': {'type': 'keyword'},
+ 'priority': {'type': 'long'},
+ }
+```
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – The information about the fields in the index.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns the information about the fields in the index.
+
+If we populated the index with documents like:
+
+```python
+ Document(content="Doc 1", meta={"category": "A", "status": "active", "priority": 1})
+ Document(content="Doc 2", meta={"category": "B", "status": "inactive"})
+```
+
+This method would return:
+
+```python
+ {
+ 'content': {'type': 'text'},
+ 'category': {'type': 'keyword'},
+ 'status': {'type': 'keyword'},
+ 'priority': {'type': 'long'},
+ }
+```
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – The information about the fields in the index.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, int | None]
+```
+
+Returns the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get the minimum and maximum values for.
+
+**Returns:**
+
+- dict\[str, int | None\] – A dictionary with the keys "min" and "max", where each value is the minimum or maximum value of the
+ metadata field across all documents.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, int | None]
+```
+
+Asynchronously returns the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get the minimum and maximum values for.
+
+**Returns:**
+
+- dict\[str, int | None\] – A dictionary with the keys "min" and "max", where each value is the minimum or maximum value of the
+ metadata field across all documents.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ size: int | None = 10000,
+ after: dict[str, Any] | None = None,
+) -> tuple[list[str], dict[str, Any] | None]
+```
+
+Returns unique values for a metadata field, optionally filtered by a search term in the content.
+
+Uses composite aggregations for proper pagination beyond 10k results.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get unique values for.
+- **search_term** (str | None) – Optional search term to filter documents by matching in the content field.
+- **size** (int | None) – The number of unique values to return per page. Defaults to 10000.
+- **after** (dict\[str, Any\] | None) – Optional pagination key from the previous response. Use None for the first page.
+ For subsequent pages, pass the `after_key` from the previous response.
+
+**Returns:**
+
+- tuple\[list\[str\], dict\[str, Any\] | None\] – A tuple containing (list of unique values, after_key for pagination).
+ The after_key is None when there are no more results. Use it in the `after` parameter
+ for the next page.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str,
+ search_term: str | None = None,
+ size: int | None = 10000,
+ after: dict[str, Any] | None = None,
+) -> tuple[list[str], dict[str, Any] | None]
+```
+
+Asynchronously returns unique values for a metadata field, optionally filtered by a search term in the content.
+
+Uses composite aggregations for proper pagination beyond 10k results.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get unique values for.
+- **search_term** (str | None) – Optional search term to filter documents by matching in the content field.
+- **size** (int | None) – The number of unique values to return per page. Defaults to 10000.
+- **after** (dict\[str, Any\] | None) – Optional pagination key from the previous response. Use None for the first page.
+ For subsequent pages, pass the `after_key` from the previous response.
+
+**Returns:**
+
+- tuple\[list\[str\], dict\[str, Any\] | None\] – A tuple containing (list of unique values, after_key for pagination).
+ The after_key is None when there are no more results. Use it in the `after` parameter
+ for the next page.
+
+## haystack_integrations.document_stores.opensearch.filters
+
+### normalize_filters
+
+```python
+normalize_filters(
+ filters: dict[str, Any], nested_fields: set[str] | None = None
+) -> dict[str, Any]
+```
+
+Converts Haystack filters in OpenSearch compatible filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dictionary.
+- **nested_fields** (set\[str\] | None) – Set of metadata field paths that are mapped as `nested` type in OpenSearch.
+ When provided, conditions targeting sub-fields of these paths are wrapped in `nested` queries.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/optimum.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/optimum.md
new file mode 100644
index 0000000000..da0d85c035
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/optimum.md
@@ -0,0 +1,629 @@
+---
+title: "Optimum"
+id: integrations-optimum
+description: "Optimum integration for Haystack"
+slug: "/integrations-optimum"
+---
+
+
+
+## Module haystack\_integrations.components.embedders.optimum.optimization
+
+
+
+### OptimumEmbedderOptimizationMode
+
+[ONXX Optimization modes](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/optimization)
+support by the Optimum Embedders.
+
+
+
+#### O1
+
+Basic general optimizations.
+
+
+
+#### O2
+
+Basic and extended general optimizations, transformers-specific fusions.
+
+
+
+#### O3
+
+Same as O2 with Gelu approximation.
+
+
+
+#### O4
+
+Same as O3 with mixed precision.
+
+
+
+#### OptimumEmbedderOptimizationMode.from\_str
+
+```python
+@classmethod
+def from_str(cls, string: str) -> "OptimumEmbedderOptimizationMode"
+```
+
+Create an optimization mode from a string.
+
+**Arguments**:
+
+- `string`: String to convert.
+
+**Returns**:
+
+Optimization mode.
+
+
+
+### OptimumEmbedderOptimizationConfig
+
+Configuration for Optimum Embedder Optimization.
+
+**Arguments**:
+
+- `mode`: Optimization mode.
+- `for_gpu`: Whether to optimize for GPUs.
+
+
+
+#### OptimumEmbedderOptimizationConfig.to\_optimum\_config
+
+```python
+def to_optimum_config() -> OptimizationConfig
+```
+
+Convert the configuration to a Optimum configuration.
+
+**Returns**:
+
+Optimum configuration.
+
+
+
+#### OptimumEmbedderOptimizationConfig.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Convert the configuration to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### OptimumEmbedderOptimizationConfig.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str,
+ Any]) -> "OptimumEmbedderOptimizationConfig"
+```
+
+Create an optimization configuration from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Optimization configuration.
+
+
+
+## Module haystack\_integrations.components.embedders.optimum.optimum\_document\_embedder
+
+
+
+### OptimumDocumentEmbedder
+
+A component for computing `Document` embeddings using models loaded with the
+[HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library,
+leveraging the ONNX runtime for high-speed inference.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.embedders.optimum import OptimumDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = OptimumDocumentEmbedder(model="sentence-transformers/all-mpnet-base-v2")
+document_embedder.warm_up()
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+
+
+#### OptimumDocumentEmbedder.\_\_init\_\_
+
+```python
+def __init__(model: str = "sentence-transformers/all-mpnet-base-v2",
+ token: Secret | None = Secret.from_env_var("HF_API_TOKEN",
+ strict=False),
+ prefix: str = "",
+ suffix: str = "",
+ normalize_embeddings: bool = True,
+ onnx_execution_provider: str = "CPUExecutionProvider",
+ pooling_mode: str | OptimumEmbedderPooling | None = None,
+ model_kwargs: dict[str, Any] | None = None,
+ working_dir: str | None = None,
+ optimizer_settings: OptimumEmbedderOptimizationConfig
+ | None = None,
+ quantizer_settings: OptimumEmbedderQuantizationConfig
+ | None = None,
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n") -> None
+```
+
+Create a OptimumDocumentEmbedder component.
+
+**Arguments**:
+
+- `model`: A string representing the model id on HF Hub.
+- `token`: The HuggingFace token to use as HTTP bearer authorization.
+- `prefix`: A string to add to the beginning of each text.
+- `suffix`: A string to add to the end of each text.
+- `normalize_embeddings`: Whether to normalize the embeddings to unit length.
+- `onnx_execution_provider`: The [execution provider](https://onnxruntime.ai/docs/execution-providers/)
+to use for ONNX models.
+
+Note: Using the TensorRT execution provider
+TensorRT requires to build its inference engine ahead of inference,
+which takes some time due to the model optimization and nodes fusion.
+To avoid rebuilding the engine every time the model is loaded, ONNX
+Runtime provides a pair of options to save the engine: `trt_engine_cache_enable`
+and `trt_engine_cache_path`. We recommend setting these two provider
+options using the `model_kwargs` parameter, when using the TensorRT execution provider.
+The usage is as follows:
+```python
+embedder = OptimumDocumentEmbedder(
+ model="sentence-transformers/all-mpnet-base-v2",
+ onnx_execution_provider="TensorrtExecutionProvider",
+ model_kwargs={
+ "provider_options": {
+ "trt_engine_cache_enable": True,
+ "trt_engine_cache_path": "tmp/trt_cache",
+ }
+ },
+)
+```
+- `pooling_mode`: The pooling mode to use. When `None`, pooling mode will be inferred from the model config.
+- `model_kwargs`: Dictionary containing additional keyword arguments to pass to the model.
+In case of duplication, these kwargs override `model`, `onnx_execution_provider`
+and `token` initialization parameters.
+- `working_dir`: The directory to use for storing intermediate files
+generated during model optimization/quantization. Required
+for optimization and quantization.
+- `optimizer_settings`: Configuration for Optimum Embedder Optimization.
+If `None`, no additional optimization is be applied.
+- `quantizer_settings`: Configuration for Optimum Embedder Quantization.
+If `None`, no quantization is be applied.
+- `batch_size`: Number of Documents to encode at once.
+- `progress_bar`: Whether to show a progress bar or not.
+- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document text.
+- `embedding_separator`: Separator used to concatenate the meta fields to the Document text.
+
+
+
+#### OptimumDocumentEmbedder.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Initializes the component.
+
+
+
+#### OptimumDocumentEmbedder.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### OptimumDocumentEmbedder.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "OptimumDocumentEmbedder"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+
+
+#### OptimumDocumentEmbedder.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of Documents.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+**Arguments**:
+
+- `documents`: A list of Documents to embed.
+
+**Raises**:
+
+- `TypeError`: If the input is not a list of Documents.
+
+**Returns**:
+
+The updated Documents with their embeddings.
+
+
+
+## Module haystack\_integrations.components.embedders.optimum.optimum\_text\_embedder
+
+
+
+### OptimumTextEmbedder
+
+A component to embed text using models loaded with the
+[HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library,
+leveraging the ONNX runtime for high-speed inference.
+
+Usage example:
+```python
+from haystack_integrations.components.embedders.optimum import OptimumTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = OptimumTextEmbedder(model="sentence-transformers/all-mpnet-base-v2")
+text_embedder.warm_up()
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]}
+```
+
+
+
+#### OptimumTextEmbedder.\_\_init\_\_
+
+```python
+def __init__(
+ model: str = "sentence-transformers/all-mpnet-base-v2",
+ token: Secret | None = Secret.from_env_var("HF_API_TOKEN",
+ strict=False),
+ prefix: str = "",
+ suffix: str = "",
+ normalize_embeddings: bool = True,
+ onnx_execution_provider: str = "CPUExecutionProvider",
+ pooling_mode: str | OptimumEmbedderPooling | None = None,
+ model_kwargs: dict[str, Any] | None = None,
+ working_dir: str | None = None,
+ optimizer_settings: OptimumEmbedderOptimizationConfig | None = None,
+ quantizer_settings: OptimumEmbedderQuantizationConfig | None = None)
+```
+
+Create a OptimumTextEmbedder component.
+
+**Arguments**:
+
+- `model`: A string representing the model id on HF Hub.
+- `token`: The HuggingFace token to use as HTTP bearer authorization.
+- `prefix`: A string to add to the beginning of each text.
+- `suffix`: A string to add to the end of each text.
+- `normalize_embeddings`: Whether to normalize the embeddings to unit length.
+- `onnx_execution_provider`: The [execution provider](https://onnxruntime.ai/docs/execution-providers/)
+to use for ONNX models.
+
+Note: Using the TensorRT execution provider
+TensorRT requires to build its inference engine ahead of inference,
+which takes some time due to the model optimization and nodes fusion.
+To avoid rebuilding the engine every time the model is loaded, ONNX
+Runtime provides a pair of options to save the engine: `trt_engine_cache_enable`
+and `trt_engine_cache_path`. We recommend setting these two provider
+options using the `model_kwargs` parameter, when using the TensorRT execution provider.
+The usage is as follows:
+```python
+embedder = OptimumDocumentEmbedder(
+ model="sentence-transformers/all-mpnet-base-v2",
+ onnx_execution_provider="TensorrtExecutionProvider",
+ model_kwargs={
+ "provider_options": {
+ "trt_engine_cache_enable": True,
+ "trt_engine_cache_path": "tmp/trt_cache",
+ }
+ },
+)
+```
+- `pooling_mode`: The pooling mode to use. When `None`, pooling mode will be inferred from the model config.
+- `model_kwargs`: Dictionary containing additional keyword arguments to pass to the model.
+In case of duplication, these kwargs override `model`, `onnx_execution_provider`
+and `token` initialization parameters.
+- `working_dir`: The directory to use for storing intermediate files
+generated during model optimization/quantization. Required
+for optimization and quantization.
+- `optimizer_settings`: Configuration for Optimum Embedder Optimization.
+If `None`, no additional optimization is be applied.
+- `quantizer_settings`: Configuration for Optimum Embedder Quantization.
+If `None`, no quantization is be applied.
+
+
+
+#### OptimumTextEmbedder.warm\_up
+
+```python
+def warm_up()
+```
+
+Initializes the component.
+
+
+
+#### OptimumTextEmbedder.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### OptimumTextEmbedder.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "OptimumTextEmbedder"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+
+
+#### OptimumTextEmbedder.run
+
+```python
+@component.output_types(embedding=list[float])
+def run(text: str) -> dict[str, list[float]]
+```
+
+Embed a string.
+
+**Arguments**:
+
+- `text`: The text to embed.
+
+**Raises**:
+
+- `TypeError`: If the input is not a string.
+
+**Returns**:
+
+The embeddings of the text.
+
+
+
+## Module haystack\_integrations.components.embedders.optimum.pooling
+
+
+
+### OptimumEmbedderPooling
+
+Pooling modes support by the Optimum Embedders.
+
+
+
+#### CLS
+
+Perform CLS Pooling on the output of the embedding model
+using the first token (CLS token).
+
+
+
+#### MEAN
+
+Perform Mean Pooling on the output of the embedding model.
+
+
+
+#### MAX
+
+Perform Max Pooling on the output of the embedding model
+using the maximum value in each dimension over all the tokens.
+
+
+
+#### MEAN\_SQRT\_LEN
+
+Perform mean-pooling on the output of the embedding model but
+divide by the square root of the sequence length.
+
+
+
+#### WEIGHTED\_MEAN
+
+Perform weighted (position) mean pooling on the output of the
+embedding model.
+
+
+
+#### LAST\_TOKEN
+
+Perform Last Token Pooling on the output of the embedding model.
+
+
+
+#### OptimumEmbedderPooling.from\_str
+
+```python
+@classmethod
+def from_str(cls, string: str) -> "OptimumEmbedderPooling"
+```
+
+Create a pooling mode from a string.
+
+**Arguments**:
+
+- `string`: String to convert.
+
+**Returns**:
+
+Pooling mode.
+
+
+
+## Module haystack\_integrations.components.embedders.optimum.quantization
+
+
+
+### OptimumEmbedderQuantizationMode
+
+[Dynamic Quantization modes](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/quantization)
+support by the Optimum Embedders.
+
+
+
+#### ARM64
+
+Quantization for the ARM64 architecture.
+
+
+
+#### AVX2
+
+Quantization with AVX-2 instructions.
+
+
+
+#### AVX512
+
+Quantization with AVX-512 instructions.
+
+
+
+#### AVX512\_VNNI
+
+Quantization with AVX-512 and VNNI instructions.
+
+
+
+#### OptimumEmbedderQuantizationMode.from\_str
+
+```python
+@classmethod
+def from_str(cls, string: str) -> "OptimumEmbedderQuantizationMode"
+```
+
+Create an quantization mode from a string.
+
+**Arguments**:
+
+- `string`: String to convert.
+
+**Returns**:
+
+Quantization mode.
+
+
+
+### OptimumEmbedderQuantizationConfig
+
+Configuration for Optimum Embedder Quantization.
+
+**Arguments**:
+
+- `mode`: Quantization mode.
+- `per_channel`: Whether to apply per-channel quantization.
+
+
+
+#### OptimumEmbedderQuantizationConfig.to\_optimum\_config
+
+```python
+def to_optimum_config() -> QuantizationConfig
+```
+
+Convert the configuration to a Optimum configuration.
+
+**Returns**:
+
+Optimum configuration.
+
+
+
+#### OptimumEmbedderQuantizationConfig.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Convert the configuration to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### OptimumEmbedderQuantizationConfig.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str,
+ Any]) -> "OptimumEmbedderQuantizationConfig"
+```
+
+Create a configuration from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Quantization configuration.
+
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/oracle.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/oracle.md
new file mode 100644
index 0000000000..bd3829b9b7
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/oracle.md
@@ -0,0 +1,760 @@
+---
+title: "Oracle AI Vector Search"
+id: integrations-oracle
+description: "Oracle AI Vector Search integration for Haystack"
+slug: "/integrations-oracle"
+---
+
+
+## haystack_integrations.components.retrievers.oracle.embedding_retriever
+
+### OracleEmbeddingRetriever
+
+Retrieves documents from an OracleDocumentStore using vector similarity.
+
+Use inside a Haystack pipeline after a text embedder::
+
+```
+pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
+pipeline.add_component("retriever", OracleEmbeddingRetriever(
+ document_store=store, top_k=5
+))
+pipeline.connect("embedder.embedding", "retriever.query_embedding")
+```
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by vector similarity.
+
+Args:
+query_embedding: Dense float vector from an embedder component.
+filters: Runtime filters, merged with constructor filters according to filter_policy.
+top_k: Override the constructor top_k for this call.
+
+Returns:
+`{"documents": [Document, ...]}`
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Async variant of :meth:`run`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OracleEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OracleEmbeddingRetriever – Deserialized component.
+
+## haystack_integrations.document_stores.oracle.document_store
+
+### OracleConnectionConfig
+
+Connection parameters for Oracle Database.
+
+Supports both thin (direct TCP) and thick (wallet / ADB-S) modes.
+Thin mode requires no Oracle Instant Client; thick mode is activated
+automatically when *wallet_location* is provided.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OracleConnectionConfig
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OracleConnectionConfig – Deserialized component.
+
+### OracleDocumentStore
+
+Haystack DocumentStore backed by Oracle AI Vector Search.
+
+Requires Oracle Database 23ai or later (for VECTOR data type and
+IF NOT EXISTS DDL support).
+
+Usage::
+
+```
+from haystack.utils import Secret
+from haystack_integrations.document_stores.oracle import (
+ OracleDocumentStore, OracleConnectionConfig,
+)
+
+store = OracleDocumentStore(
+ connection_config=OracleConnectionConfig(
+ user=Secret.from_env_var("ORACLE_USER"),
+ password=Secret.from_env_var("ORACLE_PASSWORD"),
+ dsn=Secret.from_env_var("ORACLE_DSN"),
+ ),
+ embedding_dim=1536,
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ connection_config: OracleConnectionConfig,
+ table_name: str = "haystack_documents",
+ embedding_dim: int,
+ distance_metric: Literal["COSINE", "EUCLIDEAN", "DOT"] = "COSINE",
+ create_table_if_not_exists: bool = True,
+ create_index: bool = False,
+ hnsw_neighbors: int = 32,
+ hnsw_ef_construction: int = 200,
+ hnsw_accuracy: int = 95,
+ hnsw_parallel: int = 4
+) -> None
+```
+
+Initialise the document store and optionally create the backing table and indexes.
+
+**Parameters:**
+
+- **connection_config** (OracleConnectionConfig) – Oracle connection settings (user, password, DSN, optional wallet).
+- **table_name** (str) – Name of the Oracle table used to store documents. Must be a valid Oracle
+ identifier (letters, digits, `_`, `$`, `#`; max 128 chars; cannot start with a digit).
+- **embedding_dim** (int) – Dimensionality of the embedding vectors. Must match the model producing them.
+- **distance_metric** (Literal['COSINE', 'EUCLIDEAN', 'DOT']) – Vector distance function used for similarity search.
+ One of `"COSINE"`, `"EUCLIDEAN"`, or `"DOT"`.
+- **create_table_if_not_exists** (bool) – When `True` (default), creates the table and the DBMS_SEARCH
+ keyword index on first use if they do not already exist. Set to `False` when connecting to a
+ pre-existing table.
+- **create_index** (bool) – When `True`, creates an HNSW vector index on initialisation. Equivalent to
+ calling :meth:`create_hnsw_index` manually. Defaults to `False`.
+- **hnsw_neighbors** (int) – Number of neighbours in the HNSW graph. Higher values improve recall at the
+ cost of index size and build time. Defaults to `32`.
+- **hnsw_ef_construction** (int) – Size of the dynamic candidate list during HNSW index construction.
+ Higher values improve recall at the cost of build time. Defaults to `200`.
+- **hnsw_accuracy** (int) – Target recall accuracy percentage for the HNSW index (0-100).
+ Defaults to `95`.
+- **hnsw_parallel** (int) – Degree of parallelism used when building the HNSW index. Defaults to `4`.
+
+**Raises:**
+
+- ValueError – If `table_name` is not a valid Oracle identifier or `embedding_dim` is not
+ a positive integer.
+
+#### create_keyword_index
+
+```python
+create_keyword_index() -> None
+```
+
+Create the DBMS_SEARCH keyword index on this table.
+
+Safe to call multiple times — silently skips if the index already exists.
+Required for keyword retrieval. Called automatically when
+`create_table_if_not_exists=True`, but must be called explicitly
+when connecting to a pre-existing table.
+
+#### create_hnsw_index
+
+```python
+create_hnsw_index() -> None
+```
+
+Create an HNSW vector index on the embedding column.
+
+Safe to call multiple times — uses IF NOT EXISTS.
+
+#### create_hnsw_index_async
+
+```python
+create_hnsw_index_async() -> None
+```
+
+Asynchronously creates an HNSW vector index on the embedding column.
+
+Safe to call multiple times — uses `IF NOT EXISTS`.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+**Raises:**
+
+- DuplicateDocumentError – If a document with the same id already exists in the document store
+ and the policy is set to `DuplicatePolicy.FAIL` or `DuplicatePolicy.NONE`.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+**Raises:**
+
+- DuplicateDocumentError – If a document with the same id already exists in the document store
+ and the policy is set to `DuplicatePolicy.FAIL` or `DuplicatePolicy.NONE`.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – Number of documents in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – Number of documents in the document store.
+
+#### delete_table
+
+```python
+delete_table() -> None
+```
+
+Permanently drops the document store table and its associated DBMS_SEARCH keyword index.
+
+Uses `DROP TABLE ... PURGE` which bypasses the Oracle recycle bin — the operation is
+irreversible. The keyword index is dropped after the table; if either operation fails a
+:class:`DocumentStoreError` is raised.
+
+**Raises:**
+
+- DocumentStoreError – If the table or keyword index cannot be dropped.
+
+#### delete_table_async
+
+```python
+delete_table_async() -> None
+```
+
+Asynchronously permanently drops the document store table and its DBMS_SEARCH keyword index.
+
+Uses `DROP TABLE ... PURGE` which bypasses the Oracle recycle bin — the operation is
+irreversible.
+
+**Raises:**
+
+- DocumentStoreError – If the table or keyword index cannot be dropped.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Removes all documents from the table using `TRUNCATE`.
+
+`TRUNCATE` is non-recoverable — it cannot be rolled back and bypasses row-level triggers.
+The table structure and indexes are preserved.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async() -> None
+```
+
+Asynchronously removes all documents from the table using `TRUNCATE`.
+
+`TRUNCATE` is non-recoverable — it cannot be rolled back and bypasses row-level triggers.
+The table structure and indexes are preserved.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dict. An empty dict matches all documents.
+ See the `metadata filtering docs int – Count of matching documents.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dict. An empty dict matches all documents.
+ See the `metadata filtering docs int – Count of matching documents.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dict. An empty dict is treated as a no-op and returns `0`
+ without touching the table.
+ See the `metadata filtering docs int – Number of deleted documents.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dict. An empty dict is treated as a no-op and returns `0`
+ without touching the table.
+ See the `metadata filtering docs int – Number of deleted documents.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Merges `meta` into the metadata of all documents that match the provided filters.
+
+Uses Oracle's `JSON_MERGEPATCH` — existing keys are updated, new keys are added,
+and keys set to `null` in `meta` are removed.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dict that selects which documents to update.
+ See the `metadata filtering docs dict\[str, Any\]) – Metadata patch to apply. Must be a non-empty dictionary.
+
+**Returns:**
+
+- int – Number of updated documents.
+
+**Raises:**
+
+- ValueError – If `meta` is empty.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously merges `meta` into the metadata of all documents matching the provided filters.
+
+Uses Oracle's `JSON_MERGEPATCH` — existing keys are updated, new keys are added,
+and keys set to `null` in `meta` are removed.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dict that selects which documents to update.
+ See the `metadata filtering docs dict\[str, Any\]) – Metadata patch to apply. Must be a non-empty dictionary.
+
+**Returns:**
+
+- int – Number of updated documents.
+
+**Raises:**
+
+- ValueError – If `meta` is empty.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the number of distinct values for each requested metadata field among matching documents.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dict that scopes the document set.
+ See the `metadata filtering docs list\[str\]) – List of metadata field names to count distinct values for.
+ Fields may be prefixed with `"meta."` (e.g. `"meta.lang"` or `"lang"`).
+ Must be a non-empty list.
+
+**Returns:**
+
+- dict\[str, int\] – Dict mapping each field name to its distinct-value count.
+
+**Raises:**
+
+- ValueError – If `metadata_fields` is empty.
+- ValueError – If any field name contains characters outside `[A-Za-z0-9_.]`.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously returns the number of distinct values for each metadata field among matching documents.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dict that scopes the document set.
+ See the `metadata filtering docs list\[str\]) – List of metadata field names to count distinct values for.
+ Fields may be prefixed with `"meta."` (e.g. `"meta.lang"` or `"lang"`).
+ Must be a non-empty list.
+
+**Returns:**
+
+- dict\[str, int\] – Dict mapping each field name to its distinct-value count.
+
+**Raises:**
+
+- ValueError – If `metadata_fields` is empty.
+- ValueError – If any field name contains characters outside `[A-Za-z0-9_.]`.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Return a mapping of metadata field names to their detected types.
+
+Uses Oracle's `JSON_DATAGUIDE` aggregate to introspect the stored metadata column.
+Returns an empty dict when the table has no documents.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – Dict of the form `{"field_name": {"type": "str) – Metadata field name. May be prefixed with `"meta."`
+ (e.g. `"meta.year"` or `"year"`).
+
+**Returns:**
+
+- dict\[str, Any\] – `{"min": ValueError – If `metadata_field` contains characters outside `[A-Za-z0-9_.]`.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int | None = None,
+) -> tuple[list[str], int]
+```
+
+Return a paginated list of distinct values for a metadata field, plus the total distinct count.
+
+**Parameters:**
+
+- **metadata_field** (str) – Metadata field name. May be prefixed with `"meta."`
+ (e.g. `"meta.lang"` or `"lang"`).
+- **search_term** (str | None) – Optional substring filter applied to both the document text and the field value.
+- **from\_** (int) – Zero-based offset for pagination. Defaults to `0`.
+- **size** (int | None) – Maximum number of values to return. When `None` all values from `from_` onward
+ are returned.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple `(values, total)` where `values` is the paginated list of distinct field
+ values as strings and `total` is the overall distinct count (before pagination).
+
+**Raises:**
+
+- ValueError – If `metadata_field` contains characters outside `[A-Za-z0-9_.]`.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns a mapping of metadata field names to their detected types.
+
+Uses Oracle's `JSON_DATAGUIDE` aggregate to introspect the stored metadata column.
+Returns an empty dict when the table has no documents.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – Dict of the form `{"field_name": {"type": "str) – Metadata field name. May be prefixed with `"meta."`
+ (e.g. `"meta.year"` or `"year"`).
+
+**Returns:**
+
+- dict\[str, Any\] – `{"min": ValueError – If `metadata_field` contains characters outside `[A-Za-z0-9_.]`.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int | None = None,
+) -> tuple[list[str], int]
+```
+
+Asynchronously returns a paginated list of distinct values for a metadata field, plus the total count.
+
+**Parameters:**
+
+- **metadata_field** (str) – Metadata field name. May be prefixed with `"meta."`
+ (e.g. `"meta.lang"` or `"lang"`).
+- **search_term** (str | None) – Optional substring filter applied to both the document text and the field value.
+- **from\_** (int) – Zero-based offset for pagination. Defaults to `0`.
+- **size** (int | None) – Maximum number of values to return. When `None` all values from `from_` onward
+ are returned.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple `(values, total)` where `values` is the paginated list of distinct field
+ values as strings and `total` is the overall distinct count (before pagination).
+
+**Raises:**
+
+- ValueError – If `metadata_field` contains characters outside `[A-Za-z0-9_.]`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OracleDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OracleDocumentStore – Deserialized component.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/paddleocr.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/paddleocr.md
new file mode 100644
index 0000000000..492d214a40
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/paddleocr.md
@@ -0,0 +1,198 @@
+---
+title: "PaddleOCR"
+id: integrations-paddleocr
+description: "PaddleOCR integration for Haystack"
+slug: "/integrations-paddleocr"
+---
+
+
+
+## Module haystack\_integrations.components.converters.paddleocr.paddleocr\_vl\_document\_converter
+
+
+
+### PaddleOCRVLDocumentConverter
+
+This component extracts text from documents using PaddleOCR's large model
+document parsing API.
+
+PaddleOCR-VL is used behind the scenes. For more information, please
+refer to:
+https://www.paddleocr.ai/latest/en/version3.x/algorithm/PaddleOCR-VL/PaddleOCR-VL.html
+
+**Usage Example:**
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.converters.paddleocr import (
+ PaddleOCRVLDocumentConverter,
+)
+
+converter = PaddleOCRVLDocumentConverter(
+ api_url="http://xxxxx.aistudio-app.com/layout-parsing",
+ access_token=Secret.from_env_var("AISTUDIO_ACCESS_TOKEN"),
+)
+
+result = converter.run(sources=["sample.pdf"])
+
+documents = result["documents"]
+raw_responses = result["raw_paddleocr_responses"]
+```
+
+
+
+#### PaddleOCRVLDocumentConverter.\_\_init\_\_
+
+```python
+def __init__(
+ *,
+ api_url: str,
+ access_token: Secret = Secret.from_env_var("AISTUDIO_ACCESS_TOKEN"),
+ file_type: FileTypeInput = None,
+ use_doc_orientation_classify: bool | None = False,
+ use_doc_unwarping: bool | None = False,
+ use_layout_detection: bool | None = None,
+ use_chart_recognition: bool | None = None,
+ use_seal_recognition: bool | None = None,
+ use_ocr_for_image_block: bool | None = None,
+ layout_threshold: float | dict | None = None,
+ layout_nms: bool | None = None,
+ layout_unclip_ratio: float | tuple[float, float] | dict | None = None,
+ layout_merge_bboxes_mode: str | dict | None = None,
+ layout_shape_mode: str | None = None,
+ prompt_label: str | None = None,
+ format_block_content: bool | None = None,
+ repetition_penalty: float | None = None,
+ temperature: float | None = None,
+ top_p: float | None = None,
+ min_pixels: int | None = None,
+ max_pixels: int | None = None,
+ max_new_tokens: int | None = None,
+ merge_layout_blocks: bool | None = None,
+ markdown_ignore_labels: list[str] | None = None,
+ vlm_extra_args: dict | None = None,
+ prettify_markdown: bool | None = None,
+ show_formula_number: bool | None = None,
+ restructure_pages: bool | None = None,
+ merge_tables: bool | None = None,
+ relevel_titles: bool | None = None,
+ visualize: bool | None = None,
+ additional_params: dict[str, Any] | None = None)
+```
+
+Create a `PaddleOCRVLDocumentConverter` component.
+
+**Arguments**:
+
+- `api_url`: API URL. To obtain the API URL, visit the [PaddleOCR official
+website](https://aistudio.baidu.com/paddleocr), click the
+**API** button, choose the example code for PaddleOCR-VL, and copy
+the `API_URL`.
+- `access_token`: AI Studio access token. You can obtain it from [this
+page](https://aistudio.baidu.com/account/accessToken).
+- `file_type`: File type. Can be "pdf" for PDF files, "image" for
+image files, or `None` for auto-detection. If not specified, the
+file type will be inferred from the file extension.
+- `use_doc_orientation_classify`: Whether to enable the document orientation classification
+function. Enabling this feature allows the input image to be
+automatically rotated to the correct orientation.
+- `use_doc_unwarping`: Whether to enable the text image unwarping function. Enabling
+this feature allows automatic correction of distorted text images.
+- `use_layout_detection`: Whether to enable the layout detection function.
+- `use_chart_recognition`: Whether to enable the chart recognition function.
+- `use_seal_recognition`: Whether to enable the seal recognition function.
+- `use_ocr_for_image_block`: Whether to recognize text in image blocks.
+- `layout_threshold`: Layout detection threshold. Can be a float or a dict with
+page-specific thresholds.
+- `layout_nms`: Whether to perform NMS (Non-Maximum Suppression) on layout
+detection results.
+- `layout_unclip_ratio`: Layout unclip ratio. Can be a float, a tuple of (min, max), or a
+dict with page-specific values.
+- `layout_merge_bboxes_mode`: Layout merge bounding boxes mode. Can be a string or a dict.
+- `layout_shape_mode`: Layout shape mode.
+- `prompt_label`: Prompt type for the VLM. Possible values are "ocr", "formula",
+"table", "chart", "seal", and "spotting".
+- `format_block_content`: Whether to format block content.
+- `repetition_penalty`: Repetition penalty parameter used in VLM sampling.
+- `temperature`: Temperature parameter used in VLM sampling.
+- `top_p`: Top-p parameter used in VLM sampling.
+- `min_pixels`: Minimum number of pixels allowed during VLM preprocessing.
+- `max_pixels`: Maximum number of pixels allowed during VLM preprocessing.
+- `max_new_tokens`: Maximum number of tokens generated by the VLM.
+- `merge_layout_blocks`: Whether to merge the layout detection boxes for cross-column or
+staggered top and bottom columns.
+- `markdown_ignore_labels`: Layout labels that need to be ignored in Markdown.
+- `vlm_extra_args`: Additional configuration parameters for the VLM.
+- `prettify_markdown`: Whether to prettify the output Markdown text.
+- `show_formula_number`: Whether to include formula numbers in the output markdown text.
+- `restructure_pages`: Whether to restructure results across multiple pages.
+- `merge_tables`: Whether to merge tables across pages.
+- `relevel_titles`: Whether to relevel titles.
+- `visualize`: Whether to return visualization results.
+- `additional_params`: Additional parameters for calling the PaddleOCR API.
+
+
+
+#### PaddleOCRVLDocumentConverter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### PaddleOCRVLDocumentConverter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "PaddleOCRVLDocumentConverter"
+```
+
+Deserialize the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### PaddleOCRVLDocumentConverter.run
+
+```python
+@component.output_types(documents=list[Document],
+ raw_paddleocr_responses=list[dict[str, Any]])
+def run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, Any]
+```
+
+Convert image or PDF files to Documents.
+
+**Arguments**:
+
+- `sources`: List of image or PDF file paths or ByteStream objects.
+- `meta`: Optional metadata to attach to the Documents.
+This value can be either a list of dictionaries or a single
+dictionary. If it's a single dictionary, its content is added to
+the metadata of all produced Documents. If it's a list, the length
+of the list must match the number of sources, because the two
+lists will be zipped. If `sources` contains ByteStream objects,
+their `meta` will be added to the output Documents.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `documents`: A list of created Documents.
+- `raw_paddleocr_responses`: A list of raw PaddleOCR API responses.
+
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/pgvector.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/pgvector.md
new file mode 100644
index 0000000000..e68f8d487e
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/pgvector.md
@@ -0,0 +1,890 @@
+---
+title: "Pgvector"
+id: integrations-pgvector
+description: "Pgvector integration for Haystack"
+slug: "/integrations-pgvector"
+---
+
+
+## haystack_integrations.components.retrievers.pgvector.embedding_retriever
+
+### PgvectorEmbeddingRetriever
+
+Retrieves documents from the `PgvectorDocumentStore`, based on their dense embeddings.
+
+Example usage:
+
+```python
+from haystack.document_stores import DuplicatePolicy
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack_integrations.components.retrievers.pgvector import PgvectorEmbeddingRetriever
+
+# Set an environment variable `PG_CONN_STR` with the connection string to your PostgreSQL database.
+# e.g., "postgresql://USER:PASSWORD@HOST:PORT/DB_NAME"
+
+document_store = PgvectorDocumentStore(
+ embedding_dimension=768,
+ vector_function="cosine_similarity",
+ recreate_table=True,
+)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates..."),
+ Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", PgvectorEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+res = query_pipeline.run({"text_embedder": {"text": query}})
+
+assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: PgvectorDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ vector_function: (
+ Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+ ) = None,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+)
+```
+
+**Parameters:**
+
+- **document_store** (PgvectorDocumentStore) – An instance of `PgvectorDocumentStore`.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents.
+- **top_k** (int) – Maximum number of Documents to return.
+- **vector_function** (Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None) – The similarity function to use when searching for similar embeddings.
+ Defaults to the one set in the `document_store` instance.
+ `"cosine_similarity"` and `"inner_product"` are similarity functions and
+ higher scores indicate greater similarity between the documents.
+ `"l2_distance"` returns the straight-line distance between vectors,
+ and the most similar documents are the ones with the smallest score.
+ **Important**: if the document store is using the `"hnsw"` search strategy, the vector function
+ should match the one utilized during index creation to take advantage of the index.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `PgvectorDocumentStore` or if `vector_function`
+ is not one of the valid options.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PgvectorEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- PgvectorEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ vector_function: (
+ Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+ ) = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `PgvectorDocumentStore`, based on their embeddings.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of Documents to return.
+- **vector_function** (Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None) – The similarity function to use when searching for similar embeddings.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s that are similar to `query_embedding`.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ vector_function: (
+ Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+ ) = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the `PgvectorDocumentStore`, based on their embeddings.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of Documents to return.
+- **vector_function** (Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None) – The similarity function to use when searching for similar embeddings.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s that are similar to `query_embedding`.
+
+## haystack_integrations.components.retrievers.pgvector.keyword_retriever
+
+### PgvectorKeywordRetriever
+
+Retrieve documents from the `PgvectorDocumentStore`, based on keywords.
+
+To rank the documents, the `ts_rank_cd` function of PostgreSQL is used.
+It considers how often the query terms appear in the document, how close together the terms are in the document,
+and how important is the part of the document where they occur.
+For more details, see
+[Postgres documentation](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-RANKING).
+
+Usage example:
+
+````python
+from haystack.document_stores import DuplicatePolicy
+from haystack import Document
+
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack_integrations.components.retrievers.pgvector import PgvectorKeywordRetriever
+
+# Set an environment variable `PG_CONN_STR` with the connection string to your PostgreSQL database.
+# e.g., "postgresql://USER:PASSWORD@HOST:PORT/DB_NAME"
+
+document_store = PgvectorDocumentStore(language="english", recreate_table=True)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates..."),
+ Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+retriever = PgvectorKeywordRetriever(document_store=document_store)
+
+result = retriever.run(query="languages")
+
+assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today."
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: PgvectorDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+)
+````
+
+**Parameters:**
+
+- **document_store** (PgvectorDocumentStore) – An instance of `PgvectorDocumentStore`.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents.
+- **top_k** (int) – Maximum number of Documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `PgvectorDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PgvectorKeywordRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- PgvectorKeywordRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `PgvectorDocumentStore`, based on keywords.
+
+**Parameters:**
+
+- **query** (str) – String to search in `Document`s' content.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of Documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s that match the query.
+
+#### run_async
+
+```python
+run_async(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the `PgvectorDocumentStore`, based on keywords.
+
+**Parameters:**
+
+- **query** (str) – String to search in `Document`s' content.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of Documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of `Document`s that match the query.
+
+## haystack_integrations.document_stores.pgvector.document_store
+
+### PgvectorDocumentStore
+
+A Document Store using PostgreSQL with the [pgvector extension](https://github.com/pgvector/pgvector) installed.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ connection_string: Secret = Secret.from_env_var("PG_CONN_STR"),
+ create_extension: bool = True,
+ schema_name: str = "public",
+ table_name: str = "haystack_documents",
+ language: str = "english",
+ embedding_dimension: int = 768,
+ vector_type: Literal["vector", "halfvec"] = "vector",
+ vector_function: Literal[
+ "cosine_similarity", "inner_product", "l2_distance"
+ ] = "cosine_similarity",
+ recreate_table: bool = False,
+ search_strategy: Literal[
+ "exact_nearest_neighbor", "hnsw"
+ ] = "exact_nearest_neighbor",
+ hnsw_recreate_index_if_exists: bool = False,
+ hnsw_index_creation_kwargs: dict[str, int] | None = None,
+ hnsw_index_name: str = "haystack_hnsw_index",
+ hnsw_ef_search: int | None = None,
+ keyword_index_name: str = "haystack_keyword_index"
+)
+```
+
+Creates a new PgvectorDocumentStore instance.
+It is meant to be connected to a PostgreSQL database with the pgvector extension installed.
+A specific table to store Haystack documents will be created if it doesn't exist yet.
+
+**Parameters:**
+
+- **connection_string** (Secret) – The connection string to use to connect to the PostgreSQL database, defined as an
+ environment variable. Supported formats:
+- URI, e.g. `PG_CONN_STR="postgresql://USER:PASSWORD@HOST:PORT/DB_NAME"` (use percent-encoding for special
+ characters)
+- keyword/value format, e.g. `PG_CONN_STR="host=HOST port=PORT dbname=DBNAME user=USER password=PASSWORD"`
+ See [PostgreSQL Documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING)
+ for more details.
+- **create_extension** (bool) – Whether to create the pgvector extension if it doesn't exist.
+ Set this to `True` (default) to automatically create the extension if it is missing.
+ Creating the extension may require superuser privileges.
+ If set to `False`, ensure the extension is already installed; otherwise, an error will be raised.
+- **schema_name** (str) – The name of the schema the table is created in. The schema must already exist.
+- **table_name** (str) – The name of the table to use to store Haystack documents.
+- **language** (str) – The language to be used to parse query and document content in keyword retrieval.
+ To see the list of available languages, you can run the following SQL query in your PostgreSQL database:
+ `SELECT cfgname FROM pg_ts_config;`.
+ More information can be found in this [StackOverflow answer](https://stackoverflow.com/a/39752553).
+- **embedding_dimension** (int) – The dimension of the embedding.
+- **vector_type** (Literal['vector', 'halfvec']) – The type of vector used for embedding storage.
+ "vector" is the default.
+ "halfvec" stores embeddings in half-precision, which is particularly useful for high-dimensional embeddings
+ (dimension greater than 2,000 and up to 4,000). Requires pgvector versions 0.7.0 or later. For more
+ information, see the [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file).
+- **vector_function** (Literal['cosine_similarity', 'inner_product', 'l2_distance']) – The similarity function to use when searching for similar embeddings.
+ `"cosine_similarity"` and `"inner_product"` are similarity functions and
+ higher scores indicate greater similarity between the documents.
+ `"l2_distance"` returns the straight-line distance between vectors,
+ and the most similar documents are the ones with the smallest score.
+ **Important**: when using the `"hnsw"` search strategy, an index will be created that depends on the
+ `vector_function` passed here. Make sure subsequent queries will keep using the same
+ vector similarity function in order to take advantage of the index.
+- **recreate_table** (bool) – Whether to recreate the table if it already exists.
+- **search_strategy** (Literal['exact_nearest_neighbor', 'hnsw']) – The search strategy to use when searching for similar embeddings.
+ `"exact_nearest_neighbor"` provides perfect recall but can be slow for large numbers of documents.
+ `"hnsw"` is an approximate nearest neighbor search strategy,
+ which trades off some accuracy for speed; it is recommended for large numbers of documents.
+ **Important**: when using the `"hnsw"` search strategy, an index will be created that depends on the
+ `vector_function` passed here. Make sure subsequent queries will keep using the same
+ vector similarity function in order to take advantage of the index.
+- **hnsw_recreate_index_if_exists** (bool) – Whether to recreate the HNSW index if it already exists.
+ Only used if search_strategy is set to `"hnsw"`.
+- **hnsw_index_creation_kwargs** (dict\[str, int\] | None) – Additional keyword arguments to pass to the HNSW index creation.
+ Only used if search_strategy is set to `"hnsw"`. You can find the list of valid arguments in the
+ [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw)
+- **hnsw_index_name** (str) – Index name for the HNSW index.
+- **hnsw_ef_search** (int | None) – The `ef_search` parameter to use at query time. Only used if search_strategy is set to
+ `"hnsw"`. You can find more information about this parameter in the
+ [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw).
+- **keyword_index_name** (str) – Index name for the Keyword index.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PgvectorDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- PgvectorDocumentStore – Deserialized component.
+
+#### delete_table
+
+```python
+delete_table()
+```
+
+Deletes the table used to store Haystack documents.
+The name of the schema (`schema_name`) and the name of the table (`table_name`)
+are defined when initializing the `PgvectorDocumentStore`.
+
+#### delete_table_async
+
+```python
+delete_table_async()
+```
+
+Async method to delete the table used to store Haystack documents.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – Number of documents in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – Number of documents in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+**Raises:**
+
+- TypeError – If `filters` is not a dictionary.
+- ValueError – If `filters` syntax is invalid.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+**Raises:**
+
+- TypeError – If `filters` is not a dictionary.
+- ValueError – If `filters` syntax is invalid.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+**Raises:**
+
+- ValueError – If `documents` contains objects that are not of type `Document`.
+- DuplicateDocumentError – If a document with the same id already exists in the document store
+ and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+- DocumentStoreError – If the write operation fails for any other reason.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+**Raises:**
+
+- ValueError – If `documents` contains objects that are not of type `Document`.
+- DuplicateDocumentError – If a document with the same id already exists in the document store
+ and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+- DocumentStoreError – If the write operation fails for any other reason.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents in the document store.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async() -> None
+```
+
+Asynchronously deletes all documents in the document store.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the count of unique values for each specified metadata field,
+considering only documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of metadata field names to count unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping field names to their unique value counts.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously returns the count of unique values for each specified metadata field,
+considering only documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of metadata field names to count unique values for.
+ Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping field names to their unique value counts.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the information about the metadata fields in the document store.
+
+Since metadata is stored in a JSONB field, this method analyzes actual data
+to infer field types.
+
+Example return:
+
+```python
+{
+ 'content': {'type': 'text'},
+ 'category': {'type': 'text'},
+ 'status': {'type': 'text'},
+ 'priority': {'type': 'integer'},
+}
+```
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary mapping field names to their type information.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns the information about the metadata fields in the document store.
+
+Since metadata is stored in a JSONB field, this method analyzes actual data
+to infer field types.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary mapping field names to their type information.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for a given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The name of the metadata field. Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with 'min' and 'max' keys containing the minimum and maximum values.
+ For numeric fields (integer, real), returns numeric min/max.
+ For text fields, returns lexicographic min/max based on database collation.
+
+**Raises:**
+
+- ValueError – If the field doesn't exist or has no values.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously returns the minimum and maximum values for a given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The name of the metadata field. Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with 'min' and 'max' keys containing the minimum and maximum values.
+ For numeric fields (integer, real), returns numeric min/max.
+ For text fields, returns lexicographic min/max based on database collation.
+
+**Raises:**
+
+- ValueError – If the field doesn't exist or has no values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str, search_term: str | None, from_: int, size: int
+) -> tuple[list[str], int]
+```
+
+Returns unique values for a given metadata field, optionally filtered by a search term.
+
+**Parameters:**
+
+- **metadata_field** (str) – The name of the metadata field. Can include or omit the "meta." prefix.
+- **search_term** (str | None) – Optional search term to filter documents by content before extracting unique values.
+ If None, all documents are considered.
+- **from\_** (int) – The offset for pagination (0-based).
+- **size** (int) – The number of unique values to return.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple containing:
+- A list of unique values (as strings)
+- The total count of unique values
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str, search_term: str | None, from_: int, size: int
+) -> tuple[list[str], int]
+```
+
+Asynchronously returns unique values for a given metadata field, optionally filtered by a search term.
+
+**Parameters:**
+
+- **metadata_field** (str) – The name of the metadata field. Can include or omit the "meta." prefix.
+- **search_term** (str | None) – Optional search term to filter documents by content before extracting unique values.
+ If None, all documents are considered.
+- **from\_** (int) – The offset for pagination (0-based).
+- **size** (int) – The number of unique values to return.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple containing:
+- A list of unique values (as strings)
+- The total count of unique values
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/pinecone.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/pinecone.md
new file mode 100644
index 0000000000..8836de2da8
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/pinecone.md
@@ -0,0 +1,702 @@
+---
+title: "Pinecone"
+id: integrations-pinecone
+description: "Pinecone integration for Haystack"
+slug: "/integrations-pinecone"
+---
+
+
+## haystack_integrations.components.retrievers.pinecone.embedding_retriever
+
+### PineconeEmbeddingRetriever
+
+Retrieves documents from the `PineconeDocumentStore`, based on their dense embeddings.
+
+Usage example:
+
+```python
+import os
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack_integrations.components.retrievers.pinecone import PineconeEmbeddingRetriever
+from haystack_integrations.document_stores.pinecone import PineconeDocumentStore
+
+os.environ["PINECONE_API_KEY"] = "YOUR_PINECONE_API_KEY"
+document_store = PineconeDocumentStore(index="my_index", namespace="my_namespace", dimension=768)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates..."),
+ Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", PineconeEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+res = query_pipeline.run({"text_embedder": {"text": query}})
+assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: PineconeDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the PineconeEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (PineconeDocumentStore) – The Pinecone Document Store.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents.
+- **top_k** (int) – Maximum number of Documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `PineconeDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PineconeEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- PineconeEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `PineconeDocumentStore`, based on their dense embeddings.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of `Document`s to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – List of Document similar to `query_embedding`.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the `PineconeDocumentStore`, based on their dense embeddings.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of `Document`s to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – List of Document similar to `query_embedding`.
+
+## haystack_integrations.document_stores.pinecone.document_store
+
+### PineconeDocumentStore
+
+A Document Store using [Pinecone vector database](https://www.pinecone.io/).
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("PINECONE_API_KEY"),
+ index: str = "default",
+ namespace: str = "default",
+ batch_size: int = 100,
+ dimension: int = 768,
+ spec: dict[str, Any] | None = None,
+ metric: Literal["cosine", "euclidean", "dotproduct"] = "cosine",
+ show_progress: bool = True
+) -> None
+```
+
+Creates a new PineconeDocumentStore instance.
+
+It is meant to be connected to a Pinecone index and namespace.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Pinecone API key.
+- **index** (str) – The Pinecone index to connect to. If the index does not exist, it will be created.
+- **namespace** (str) – The Pinecone namespace to connect to. If the namespace does not exist, it will be created
+ at the first write.
+- **batch_size** (int) – The number of documents to write in a single batch. When setting this parameter,
+ consider [documented Pinecone limits](https://docs.pinecone.io/reference/quotas-and-limits).
+- **dimension** (int) – The dimension of the embeddings. This parameter is only used when creating a new index.
+- **spec** (dict\[str, Any\] | None) – The Pinecone spec to use when creating a new index. Allows choosing between serverless and pod
+ deployment options and setting additional parameters. Refer to the
+ [Pinecone documentation](https://docs.pinecone.io/reference/api/control-plane/create_index) for more
+ details.
+ If not provided, a default spec with serverless deployment in the `us-east-1` region will be used
+ (compatible with the free tier).
+- **metric** (Literal['cosine', 'euclidean', 'dotproduct']) – The metric to use for similarity search. This parameter is only used when creating a new index.
+- **show_progress** (bool) – Whether to show a progress bar when upserting documents. Set to False to disable
+ (e.g. in tests or scripts where quiet output is preferred).
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the associated synchronous resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the associated asynchronous resources. To be invoked manually when the Document Store is no longer needed.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PineconeDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- PineconeDocumentStore – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns how many documents are present in the document store.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes Documents to Pinecone.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+ PineconeDocumentStore only supports `DuplicatePolicy.OVERWRITE`.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously writes Documents to Pinecone.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to write to the document store.
+- **policy** (DuplicatePolicy) – The duplicate policy to use when writing documents.
+ PineconeDocumentStore only supports `DuplicatePolicy.OVERWRITE`.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents in the document store.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async() -> None
+```
+
+Asynchronously deletes all documents in the document store.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+Pinecone does not support server-side delete by filter, so this method
+first searches for matching documents, then deletes them by ID.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+Pinecone does not support server-side delete by filter, so this method
+first searches for matching documents, then deletes them by ID.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+Pinecone does not support server-side update by filter, so this method
+first searches for matching documents, then updates their metadata and re-writes them.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+Pinecone does not support server-side update by filter, so this method
+first searches for matching documents, then updates their metadata and re-writes them.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the count of documents that match the provided filters.
+
+Note: Due to Pinecone's limitations, this method fetches documents and counts them.
+For large result sets, this is subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the document list.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the count of documents that match the provided filters.
+
+Note: Due to Pinecone's limitations, this method fetches documents and counts them.
+For large result sets, this is subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to the document list.
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Counts unique values for each specified metadata field in documents matching the filters.
+
+Note: Due to Pinecone's limitations, this method fetches documents and aggregates in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents.
+- **metadata_fields** (list\[str\]) – List of metadata field names to count unique values for.
+
+**Returns:**
+
+- dict\[str, int\] – Dictionary mapping field names to counts of unique values.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously counts unique values for each specified metadata field in documents matching the filters.
+
+Note: Due to Pinecone's limitations, this method fetches documents and aggregates in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents.
+- **metadata_fields** (list\[str\]) – List of metadata field names to count unique values for.
+
+**Returns:**
+
+- dict\[str, int\] – Dictionary mapping field names to counts of unique values.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns information about metadata fields and their types by sampling documents.
+
+Note: Pinecone doesn't provide a schema introspection API, so this method infers field types
+by examining the metadata of documents stored in the index (up to 1000 documents).
+
+Type mappings:
+
+- 'text': Document content field
+- 'keyword': String metadata values
+- 'long': Numeric metadata values (int or float)
+- 'boolean': Boolean metadata values
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – Dictionary mapping field names to type information.
+ Example:
+
+```python
+{
+ 'content': {'type': 'text'},
+ 'category': {'type': 'keyword'},
+ 'priority': {'type': 'long'},
+}
+```
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns information about metadata fields and their types by sampling documents.
+
+Note: Pinecone doesn't provide a schema introspection API, so this method infers field types
+by examining the metadata of documents stored in the index (up to 1000 documents).
+
+Type mappings:
+
+- 'text': Document content field
+- 'keyword': String metadata values
+- 'long': Numeric metadata values (int or float)
+- 'boolean': Boolean metadata values
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – Dictionary mapping field names to type information.
+ Example:
+
+```python
+{
+ 'content': {'type': 'text'},
+ 'category': {'type': 'keyword'},
+ 'priority': {'type': 'long'},
+}
+```
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for a metadata field.
+
+Supports numeric (int, float), boolean, and string (keyword) types:
+
+- Numeric: Returns min/max based on numeric value
+- Boolean: Returns False as min, True as max
+- String: Returns min/max based on alphabetical ordering
+
+Note: This method fetches all documents and computes min/max in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name to analyze.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with 'min' and 'max' keys. Both values are None if the field has no
+ values (empty store, field absent, or unsupported field type).
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously returns the minimum and maximum values for a metadata field.
+
+Supports numeric (int, float), boolean, and string (keyword) types:
+
+- Numeric: Returns min/max based on numeric value
+- Boolean: Returns False as min, True as max
+- String: Returns min/max based on alphabetical ordering
+
+Note: This method fetches all documents and computes min/max in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name to analyze.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with 'min' and 'max' keys. Both values are None if the field has no
+ values (empty store, field absent, or unsupported field type).
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a metadata field with optional search and pagination.
+
+Note: This method fetches documents and extracts unique values in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name to get unique values for.
+- **search_term** (str | None) – Optional search term to filter values (case-insensitive substring match).
+- **from\_** (int) – Starting offset for pagination (default: 0).
+- **size** (int) – Number of values to return (default: 10).
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – Tuple of (list of unique values, total count of matching values).
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously retrieves unique values for a metadata field with optional search and pagination.
+
+Note: This method fetches documents and extracts unique values in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name to get unique values for.
+- **search_term** (str | None) – Optional search term to filter values (case-insensitive substring match).
+- **from\_** (int) – Starting offset for pagination (default: 0).
+- **size** (int) – Number of values to return (default: 10).
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – Tuple of (list of unique values, total count of matching values).
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/presidio.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/presidio.md
new file mode 100644
index 0000000000..3ab6215e0f
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/presidio.md
@@ -0,0 +1,302 @@
+---
+title: "Presidio"
+id: integrations-presidio
+description: "Presidio integration for Haystack"
+slug: "/integrations-presidio"
+---
+
+
+## haystack_integrations.components.extractors.presidio.presidio_entity_extractor
+
+### PresidioEntityExtractor
+
+Detects PII entities in Haystack Documents using Microsoft Presidio Analyzer.
+
+See [Presidio Analyzer](https://microsoft.github.io/presidio/) for details.
+
+Accepts a list of Documents and returns new Documents with detected PII entities stored
+in each Document's metadata under the key `"entities"`. Each entry in the list contains
+the entity type, start/end character offsets, and the confidence score.
+
+Original Documents are not mutated. Documents without text content are passed through unchanged.
+
+The analyzer engine is loaded on the first call to `run()`,
+or by calling `warm_up()` explicitly beforehand.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.extractors.presidio import PresidioEntityExtractor
+
+extractor = PresidioEntityExtractor()
+result = extractor.run(documents=[Document(content="Contact Alice at alice@example.com")])
+print(result["documents"][0].meta["entities"])
+# [{"entity_type": "PERSON", "start": 8, "end": 13, "score": 0.85},
+# {"entity_type": "EMAIL_ADDRESS", "start": 17, "end": 34, "score": 1.0}]
+```
+
+#### SPACY_DEFAULT_MODELS
+
+```python
+SPACY_DEFAULT_MODELS: dict[str, str] = _SPACY_DEFAULT_MODELS
+```
+
+Mapping from ISO 639-1 language code to the largest available spaCy model for that language.
+
+Used to automatically select an NLP model when `models` is not specified.
+See [spaCy documentation](https://spacy.io/models) for the full list of available spaCy models.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ language: str = "en",
+ entities: list[str] | None = None,
+ score_threshold: float = 0.35,
+ models: list[dict[str, str]] | None = None
+) -> None
+```
+
+Initializes the PresidioEntityExtractor.
+
+**Parameters:**
+
+- **language** (str) – ISO 639-1 language code for PII detection. Defaults to `"en"`.
+ For languages in the built-in mapping (e.g. `"de"`, `"fr"`, `"es"`), the appropriate
+ spaCy model is loaded automatically at warm-up time — no need to set `models`.
+ For unsupported languages, use the `models` parameter to configure a custom model.
+ See [Presidio supported languages](https://microsoft.github.io/presidio/analyzer/languages/).
+- **entities** (list\[str\] | None) – List of PII entity types to detect (e.g. `["PERSON", "EMAIL_ADDRESS"]`).
+ If `None`, all supported entity types are detected.
+ See [Presidio supported entities](https://microsoft.github.io/presidio/supported_entities/).
+- **score_threshold** (float) – Minimum confidence score (0-1) for a detected entity to be included. Defaults to `0.35`.
+ See [Presidio analyzer documentation](https://microsoft.github.io/presidio/analyzer/).
+- **models** (list\[dict\[str, str\]\] | None) – Advanced override: list of spaCy model configurations.
+ Each entry must contain `"lang_code"` and `"model_name"` keys,
+ e.g. `[{"lang_code": "fr", "model_name": "fr_core_news_md"}]`.
+ Use this only when you need a specific model variant or a language not covered by the
+ built-in mapping. If `None`, the model is selected automatically from `SPACY_DEFAULT_MODELS`
+ based on `language`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the Presidio analyzer engine.
+
+This method loads the underlying NLP models. In a Haystack Pipeline,
+this is called automatically before the first run.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Detects PII entities in the provided Documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents to analyze for PII entities.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with key `documents` containing Documents with detected entities
+ stored in metadata under the key `"entities"`.
+
+## haystack_integrations.components.preprocessors.presidio.presidio_document_cleaner
+
+### PresidioDocumentCleaner
+
+Anonymizes PII in Haystack Documents using [Microsoft Presidio](https://microsoft.github.io/presidio/).
+
+Accepts a list of Documents, detects personally identifiable information (PII) in their
+text content, and returns new Documents with PII replaced by entity type placeholders
+(e.g. `str) – ISO 639-1 language code for PII detection. Defaults to `"en"`.
+ For languages in the built-in mapping (e.g. `"de"`, `"fr"`, `"es"`), the appropriate
+ spaCy model is loaded automatically at warm-up time — no need to set `models`.
+ For unsupported languages, use the `models` parameter to configure a custom model.
+ See [Presidio supported languages](https://microsoft.github.io/presidio/analyzer/languages/).
+- **entities** (list\[str\] | None) – List of PII entity types to detect and anonymize (e.g. `["PERSON", "EMAIL_ADDRESS"]`).
+ If `None`, all supported entity types are used.
+ See [Presidio supported entities](https://microsoft.github.io/presidio/supported_entities/).
+- **score_threshold** (float) – Minimum confidence score (0-1) for a detected entity to be anonymized. Defaults to `0.35`.
+ See [Presidio analyzer documentation](https://microsoft.github.io/presidio/analyzer/).
+- **models** (list\[dict\[str, str\]\] | None) – Advanced override: list of spaCy model configurations.
+ Each entry must contain `"lang_code"` and `"model_name"` keys,
+ e.g. `[{"lang_code": "fr", "model_name": "fr_core_news_md"}]`.
+ Use this only when you need a specific model variant or a language not covered by the
+ built-in mapping. If `None`, the model is selected automatically from `SPACY_DEFAULT_MODELS`
+ based on `language`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the Presidio analyzer and anonymizer engines.
+
+This method loads the underlying NLP models. In a Haystack Pipeline,
+this is called automatically before the first run.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Anonymizes PII in the provided Documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Documents whose text content will be anonymized.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with key `documents` containing the cleaned Documents.
+
+## haystack_integrations.components.preprocessors.presidio.presidio_text_cleaner
+
+### PresidioTextCleaner
+
+Anonymizes PII in plain strings using [Microsoft Presidio](https://microsoft.github.io/presidio/).
+
+Accepts a list of strings, detects personally identifiable information (PII), and returns
+a new list of strings with PII replaced by entity type placeholders (e.g. `str) – ISO 639-1 language code for PII detection. Defaults to `"en"`.
+ For languages in the built-in mapping (e.g. `"de"`, `"fr"`, `"es"`), the appropriate
+ spaCy model is loaded automatically at warm-up time — no need to set `models`.
+ For unsupported languages, use the `models` parameter to configure a custom model.
+ See [Presidio supported languages](https://microsoft.github.io/presidio/analyzer/languages/).
+- **entities** (list\[str\] | None) – List of PII entity types to detect and anonymize (e.g. `["PERSON", "PHONE_NUMBER"]`).
+ If `None`, all supported entity types are used.
+ See [Presidio supported entities](https://microsoft.github.io/presidio/supported_entities/).
+- **score_threshold** (float) – Minimum confidence score (0-1) for a detected entity to be anonymized. Defaults to `0.35`.
+ See [Presidio analyzer documentation](https://microsoft.github.io/presidio/analyzer/).
+- **models** (list\[dict\[str, str\]\] | None) – Advanced override: list of spaCy model configurations.
+ Each entry must contain `"lang_code"` and `"model_name"` keys,
+ e.g. `[{"lang_code": "fr", "model_name": "fr_core_news_md"}]`.
+ Use this only when you need a specific model variant or a language not covered by the
+ built-in mapping. If `None`, the model is selected automatically from `SPACY_DEFAULT_MODELS`
+ based on `language`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the Presidio analyzer and anonymizer engines.
+
+This method loads the underlying NLP models. In a Haystack Pipeline,
+this is called automatically before the first run.
+
+#### run
+
+```python
+run(texts: list[str]) -> dict[str, list[str]]
+```
+
+Anonymizes PII in the provided strings.
+
+**Parameters:**
+
+- **texts** (list\[str\]) – List of strings to anonymize.
+
+**Returns:**
+
+- dict\[str, list\[str\]\] – A dictionary with key `texts` containing the cleaned strings.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/pyversity.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/pyversity.md
new file mode 100644
index 0000000000..00662bd24c
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/pyversity.md
@@ -0,0 +1,125 @@
+---
+title: "pyversity"
+id: integrations-pyversity
+description: "pyversity integration for Haystack"
+slug: "/integrations-pyversity"
+---
+
+
+## haystack_integrations.components.rankers.pyversity.ranker
+
+Haystack integration for `pyversity 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
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+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
+
+```python
+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].
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/qdrant.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/qdrant.md
new file mode 100644
index 0000000000..5bc7fc3a0e
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/qdrant.md
@@ -0,0 +1,1286 @@
+---
+title: "Qdrant"
+id: integrations-qdrant
+description: "Qdrant integration for Haystack"
+slug: "/integrations-qdrant"
+---
+
+
+## haystack_integrations.components.retrievers.qdrant.retriever
+
+### QdrantEmbeddingRetriever
+
+A component for retrieving documents from an QdrantDocumentStore using dense vectors.
+
+Usage example:
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.retrievers.qdrant import QdrantEmbeddingRetriever
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ return_embedding=True,
+)
+
+document_store.write_documents([Document(content="test", embedding=[0.5]*768)])
+
+retriever = QdrantEmbeddingRetriever(document_store=document_store)
+
+# using a fake vector to keep the example simple
+retriever.run(query_embedding=[0.1]*768)
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: QdrantDocumentStore,
+ filters: dict[str, Any] | models.Filter | None = None,
+ top_k: int = 10,
+ scale_score: bool = False,
+ return_embedding: bool = False,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+ score_threshold: float | None = None,
+ group_by: str | None = None,
+ group_size: int | None = None,
+) -> None
+```
+
+Create a QdrantEmbeddingRetriever component.
+
+**Parameters:**
+
+- **document_store** (QdrantDocumentStore) – An instance of QdrantDocumentStore.
+- **filters** (dict\[str, Any\] | Filter | None) – A dictionary with filters to narrow down the search space.
+- **top_k** (int) – The maximum number of documents to retrieve. If using `group_by` parameters, maximum number of
+ groups to return.
+- **scale_score** (bool) – Whether to scale the scores of the retrieved documents or not.
+- **return_embedding** (bool) – Whether to return the embedding of the retrieved Documents.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+- **score_threshold** (float | None) – A minimal score threshold for the result.
+ Score of the returned result might be higher or smaller than the threshold
+ depending on the `similarity` function specified in the Document Store.
+ E.g. for cosine similarity only higher scores will be returned.
+- **group_by** (str | None) – Payload field to group by, must be a string or number field. If the field contains more than 1
+ value, all values will be used for grouping. One point can be in multiple groups.
+- **group_size** (int | None) – Maximum amount of points to return per group. Default is 3.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `QdrantDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> QdrantEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- QdrantEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | models.Filter | None = None,
+ top_k: int | None = None,
+ scale_score: bool | None = None,
+ return_embedding: bool | None = None,
+ score_threshold: float | None = None,
+ group_by: str | None = None,
+ group_size: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Run the Embedding Retriever on the given input data.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | Filter | None) – A dictionary with filters to narrow down the search space.
+- **top_k** (int | None) – The maximum number of documents to return. If using `group_by` parameters, maximum number of
+ groups to return.
+- **scale_score** (bool | None) – Whether to scale the scores of the retrieved documents or not.
+- **return_embedding** (bool | None) – Whether to return the embedding of the retrieved Documents.
+- **score_threshold** (float | None) – A minimal score threshold for the result.
+- **group_by** (str | None) – Payload field to group by, must be a string or number field. If the field contains more than 1
+ value, all values will be used for grouping. One point can be in multiple groups.
+- **group_size** (int | None) – Maximum amount of points to return per group. Default is 3.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The retrieved documents.
+
+**Raises:**
+
+- ValueError – If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | models.Filter | None = None,
+ top_k: int | None = None,
+ scale_score: bool | None = None,
+ return_embedding: bool | None = None,
+ score_threshold: float | None = None,
+ group_by: str | None = None,
+ group_size: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously run the Embedding Retriever on the given input data.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | Filter | None) – A dictionary with filters to narrow down the search space.
+- **top_k** (int | None) – The maximum number of documents to return. If using `group_by` parameters, maximum number of
+ groups to return.
+- **scale_score** (bool | None) – Whether to scale the scores of the retrieved documents or not.
+- **return_embedding** (bool | None) – Whether to return the embedding of the retrieved Documents.
+- **score_threshold** (float | None) – A minimal score threshold for the result.
+- **group_by** (str | None) – Payload field to group by, must be a string or number field. If the field contains more than 1
+ value, all values will be used for grouping. One point can be in multiple groups.
+- **group_size** (int | None) – Maximum amount of points to return per group. Default is 3.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The retrieved documents.
+
+**Raises:**
+
+- ValueError – If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter.
+
+### QdrantSparseEmbeddingRetriever
+
+A component for retrieving documents from an QdrantDocumentStore using sparse vectors.
+
+Usage example:
+
+```python
+from haystack_integrations.components.retrievers.qdrant import QdrantSparseEmbeddingRetriever
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack.dataclasses import Document, SparseEmbedding
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ use_sparse_embeddings=True,
+ recreate_index=True,
+ return_embedding=True,
+)
+
+doc = Document(content="test", sparse_embedding=SparseEmbedding(indices=[0, 3, 5], values=[0.1, 0.5, 0.12]))
+document_store.write_documents([doc])
+
+retriever = QdrantSparseEmbeddingRetriever(document_store=document_store)
+sparse_embedding = SparseEmbedding(indices=[0, 1, 2, 3], values=[0.1, 0.8, 0.05, 0.33])
+retriever.run(query_sparse_embedding=sparse_embedding)
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: QdrantDocumentStore,
+ filters: dict[str, Any] | models.Filter | None = None,
+ top_k: int = 10,
+ scale_score: bool = False,
+ return_embedding: bool = False,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+ score_threshold: float | None = None,
+ group_by: str | None = None,
+ group_size: int | None = None,
+) -> None
+```
+
+Create a QdrantSparseEmbeddingRetriever component.
+
+**Parameters:**
+
+- **document_store** (QdrantDocumentStore) – An instance of QdrantDocumentStore.
+- **filters** (dict\[str, Any\] | Filter | None) – A dictionary with filters to narrow down the search space.
+- **top_k** (int) – The maximum number of documents to retrieve. If using `group_by` parameters, maximum number of
+ groups to return.
+- **scale_score** (bool) – Whether to scale the scores of the retrieved documents or not.
+- **return_embedding** (bool) – Whether to return the sparse embedding of the retrieved Documents.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied. Defaults to "replace".
+- **score_threshold** (float | None) – A minimal score threshold for the result.
+ Score of the returned result might be higher or smaller than the threshold
+ depending on the Distance function used.
+ E.g. for cosine similarity only higher scores will be returned.
+- **group_by** (str | None) – Payload field to group by, must be a string or number field. If the field contains more than 1
+ value, all values will be used for grouping. One point can be in multiple groups.
+- **group_size** (int | None) – Maximum amount of points to return per group. Default is 3.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `QdrantDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> QdrantSparseEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- QdrantSparseEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_sparse_embedding: SparseEmbedding,
+ filters: dict[str, Any] | models.Filter | None = None,
+ top_k: int | None = None,
+ scale_score: bool | None = None,
+ return_embedding: bool | None = None,
+ score_threshold: float | None = None,
+ group_by: str | None = None,
+ group_size: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Run the Sparse Embedding Retriever on the given input data.
+
+**Parameters:**
+
+- **query_sparse_embedding** (SparseEmbedding) – Sparse Embedding of the query.
+- **filters** (dict\[str, Any\] | Filter | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to return. If using `group_by` parameters, maximum number of
+ groups to return.
+- **scale_score** (bool | None) – Whether to scale the scores of the retrieved documents or not.
+- **return_embedding** (bool | None) – Whether to return the embedding of the retrieved Documents.
+- **score_threshold** (float | None) – A minimal score threshold for the result.
+ Score of the returned result might be higher or smaller than the threshold
+ depending on the Distance function used.
+ E.g. for cosine similarity only higher scores will be returned.
+- **group_by** (str | None) – Payload field to group by, must be a string or number field. If the field contains more than 1
+ value, all values will be used for grouping. One point can be in multiple groups.
+- **group_size** (int | None) – Maximum amount of points to return per group. Default is 3.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The retrieved documents.
+
+**Raises:**
+
+- ValueError – If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter.
+
+#### run_async
+
+```python
+run_async(
+ query_sparse_embedding: SparseEmbedding,
+ filters: dict[str, Any] | models.Filter | None = None,
+ top_k: int | None = None,
+ scale_score: bool | None = None,
+ return_embedding: bool | None = None,
+ score_threshold: float | None = None,
+ group_by: str | None = None,
+ group_size: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously run the Sparse Embedding Retriever on the given input data.
+
+**Parameters:**
+
+- **query_sparse_embedding** (SparseEmbedding) – Sparse Embedding of the query.
+- **filters** (dict\[str, Any\] | Filter | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to return. If using `group_by` parameters, maximum number of
+ groups to return.
+- **scale_score** (bool | None) – Whether to scale the scores of the retrieved documents or not.
+- **return_embedding** (bool | None) – Whether to return the embedding of the retrieved Documents.
+- **score_threshold** (float | None) – A minimal score threshold for the result.
+ Score of the returned result might be higher or smaller than the threshold
+ depending on the Distance function used.
+ E.g. for cosine similarity only higher scores will be returned.
+- **group_by** (str | None) – Payload field to group by, must be a string or number field. If the field contains more than 1
+ value, all values will be used for grouping. One point can be in multiple groups.
+- **group_size** (int | None) – Maximum amount of points to return per group. Default is 3.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The retrieved documents.
+
+**Raises:**
+
+- ValueError – If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter.
+
+### QdrantHybridRetriever
+
+A component for retrieving documents from an QdrantDocumentStore using both dense and sparse vectors
+and fusing the results using Reciprocal Rank Fusion.
+
+Usage example:
+
+```python
+from haystack_integrations.components.retrievers.qdrant import QdrantHybridRetriever
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack.dataclasses import Document, SparseEmbedding
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ use_sparse_embeddings=True,
+ recreate_index=True,
+ return_embedding=True,
+ wait_result_from_api=True,
+)
+
+doc = Document(content="test",
+ embedding=[0.5]*768,
+ sparse_embedding=SparseEmbedding(indices=[0, 3, 5], values=[0.1, 0.5, 0.12]))
+
+document_store.write_documents([doc])
+
+retriever = QdrantHybridRetriever(document_store=document_store)
+embedding = [0.1]*768
+sparse_embedding = SparseEmbedding(indices=[0, 1, 2, 3], values=[0.1, 0.8, 0.05, 0.33])
+retriever.run(query_embedding=embedding, query_sparse_embedding=sparse_embedding)
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: QdrantDocumentStore,
+ filters: dict[str, Any] | models.Filter | None = None,
+ top_k: int = 10,
+ return_embedding: bool = False,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+ score_threshold: float | None = None,
+ group_by: str | None = None,
+ group_size: int | None = None,
+) -> None
+```
+
+Create a QdrantHybridRetriever component.
+
+**Parameters:**
+
+- **document_store** (QdrantDocumentStore) – An instance of QdrantDocumentStore.
+- **filters** (dict\[str, Any\] | Filter | None) – A dictionary with filters to narrow down the search space.
+- **top_k** (int) – The maximum number of documents to retrieve. If using `group_by` parameters, maximum number of
+ groups to return.
+- **return_embedding** (bool) – Whether to return the embeddings of the retrieved Documents.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+- **score_threshold** (float | None) – A minimal score threshold for the result.
+ Score of the returned result might be higher or smaller than the threshold
+ depending on the Distance function used.
+ E.g. for cosine similarity only higher scores will be returned.
+- **group_by** (str | None) – Payload field to group by, must be a string or number field. If the field contains more than 1
+ value, all values will be used for grouping. One point can be in multiple groups.
+- **group_size** (int | None) – Maximum amount of points to return per group. Default is 3.
+
+**Raises:**
+
+- ValueError – If 'document_store' is not an instance of QdrantDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> QdrantHybridRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- QdrantHybridRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ query_sparse_embedding: SparseEmbedding,
+ filters: dict[str, Any] | models.Filter | None = None,
+ top_k: int | None = None,
+ return_embedding: bool | None = None,
+ score_threshold: float | None = None,
+ group_by: str | None = None,
+ group_size: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Run the Sparse Embedding Retriever on the given input data.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Dense embedding of the query.
+- **query_sparse_embedding** (SparseEmbedding) – Sparse embedding of the query.
+- **filters** (dict\[str, Any\] | Filter | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to return. If using `group_by` parameters, maximum number of
+ groups to return.
+- **return_embedding** (bool | None) – Whether to return the embedding of the retrieved Documents.
+- **score_threshold** (float | None) – A minimal score threshold for the result.
+ Score of the returned result might be higher or smaller than the threshold
+ depending on the Distance function used.
+ E.g. for cosine similarity only higher scores will be returned.
+- **group_by** (str | None) – Payload field to group by, must be a string or number field. If the field contains more than 1
+ value, all values will be used for grouping. One point can be in multiple groups.
+- **group_size** (int | None) – Maximum amount of points to return per group. Default is 3.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The retrieved documents.
+
+**Raises:**
+
+- ValueError – If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ query_sparse_embedding: SparseEmbedding,
+ filters: dict[str, Any] | models.Filter | None = None,
+ top_k: int | None = None,
+ return_embedding: bool | None = None,
+ score_threshold: float | None = None,
+ group_by: str | None = None,
+ group_size: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously run the Sparse Embedding Retriever on the given input data.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Dense embedding of the query.
+- **query_sparse_embedding** (SparseEmbedding) – Sparse embedding of the query.
+- **filters** (dict\[str, Any\] | Filter | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to return. If using `group_by` parameters, maximum number of
+ groups to return.
+- **return_embedding** (bool | None) – Whether to return the embedding of the retrieved Documents.
+- **score_threshold** (float | None) – A minimal score threshold for the result.
+ Score of the returned result might be higher or smaller than the threshold
+ depending on the Distance function used.
+ E.g. for cosine similarity only higher scores will be returned.
+- **group_by** (str | None) – Payload field to group by, must be a string or number field. If the field contains more than 1
+ value, all values will be used for grouping. One point can be in multiple groups.
+- **group_size** (int | None) – Maximum amount of points to return per group. Default is 3.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The retrieved documents.
+
+**Raises:**
+
+- ValueError – If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter.
+
+## haystack_integrations.document_stores.qdrant.document_store
+
+### get_batches_from_generator
+
+```python
+get_batches_from_generator(iterable: list, n: int) -> Generator
+```
+
+Batch elements of an iterable into fixed-length chunks or blocks.
+
+### QdrantDocumentStore
+
+A QdrantDocumentStore implementation that you can use with any Qdrant instance: in-memory, disk-persisted,
+Docker-based, and Qdrant Cloud Cluster deployments.
+
+Usage example by creating an in-memory instance:
+
+```python
+from haystack.dataclasses.document import Document
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ embedding_dim=5
+)
+document_store.write_documents([
+ Document(content="This is first", embedding=[0.0]*5),
+ Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5])
+])
+```
+
+Usage example with Qdrant Cloud:
+
+```python
+from haystack.dataclasses.document import Document
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+
+document_store = QdrantDocumentStore(
+ url="https://xxxxxx-xxxxx-xxxxx-xxxx-xxxxxxxxx.us-east.aws.cloud.qdrant.io:6333",
+ api_key="str | None) – If `":memory:"` - use in-memory Qdrant instance.
+ If `str` - use it as a URL parameter.
+ If `None` - use default values for host and port.
+- **url** (str | None) – Either host or str of `Optional[scheme], host, Optional[port], Optional[prefix]`.
+- **port** (int) – Port of the REST API interface.
+- **grpc_port** (int) – Port of the gRPC interface.
+- **prefer_grpc** (bool) – If `True` - use gRPC interface whenever possible in custom methods.
+- **https** (bool | None) – If `True` - use HTTPS(SSL) protocol.
+- **api_key** (Secret | None) – API key for authentication in Qdrant Cloud.
+- **prefix** (str | None) – If not `None` - add prefix to the REST URL path.
+ Example: service/v1 will result in http://localhost:6333/service/v1/{qdrant-endpoint}
+ for REST API.
+- **timeout** (int | None) – Timeout for REST and gRPC API requests.
+- **host** (str | None) – Host name of Qdrant service. If ùrl`and`host`are`None`, set to `localhost\`.
+- **path** (str | None) – Persistence path for QdrantLocal.
+- **force_disable_check_same_thread** (bool) – For QdrantLocal, force disable check_same_thread.
+ Only use this if you can guarantee that you can resolve the thread safety outside QdrantClient.
+- **index** (str) – Name of the index.
+- **embedding_dim** (int) – Dimension of the embeddings.
+- **on_disk** (bool) – Whether to store the collection on disk.
+- **use_sparse_embeddings** (bool) – If set to `True`, enables support for sparse embeddings.
+- **sparse_idf** (bool) – If set to `True`, computes the Inverse Document Frequency (IDF) when using sparse embeddings.
+ It is required to use techniques like BM42. It is ignored if `use_sparse_embeddings` is `False`.
+- **similarity** (str) – The similarity metric to use.
+- **return_embedding** (bool) – Whether to return embeddings in the search results.
+- **progress_bar** (bool) – Whether to show a progress bar or not.
+- **recreate_index** (bool) – Whether to recreate the index.
+- **shard_number** (int | None) – Number of shards in the collection.
+- **replication_factor** (int | None) – Replication factor for the collection.
+ Defines how many copies of each shard will be created. Effective only in distributed mode.
+- **write_consistency_factor** (int | None) – Write consistency factor for the collection. Minimum value is 1.
+ Defines how many replicas should apply to the operation for it to be considered successful.
+ Increasing this number makes the collection more resilient to inconsistencies
+ but will cause failures if not enough replicas are available.
+ Effective only in distributed mode.
+- **on_disk_payload** (bool | None) – If `True`, the point's payload will not be stored in memory and
+ will be read from the disk every time it is requested.
+ This setting saves RAM by slightly increasing response time.
+ Note: indexed payload values remain in RAM.
+- **hnsw_config** (dict | None) – Params for HNSW index.
+- **optimizers_config** (dict | None) – Params for optimizer.
+- **wal_config** (dict | None) – Params for Write-Ahead-Log.
+- **quantization_config** (dict | None) – Params for quantization. If `None`, quantization will be disabled.
+- **wait_result_from_api** (bool) – Whether to wait for the result from the API after each request.
+- **metadata** (dict | None) – Additional metadata to include with the documents.
+- **write_batch_size** (int) – The batch size for writing documents.
+- **scroll_size** (int) – The scroll size for reading documents.
+- **payload_fields_to_index** (list\[dict\] | None) – List of payload fields to index.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns the number of documents present in the Document Store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns the number of documents present in the document dtore.
+
+#### filter_documents
+
+```python
+filter_documents(
+ filters: dict[str, Any] | rest.Filter | None = None,
+) -> list[Document]
+```
+
+Returns the documents that match the provided filters.
+
+For a detailed specification of the filters, refer to the
+[documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | Filter | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of documents that match the given filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(
+ filters: dict[str, Any] | rest.Filter | None = None,
+) -> list[Document]
+```
+
+Asynchronously returns the documents that match the provided filters.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.FAIL
+) -> int
+```
+
+Writes documents to Qdrant using the specified policy.
+The QdrantDocumentStore can handle duplicate documents based on the given policy.
+The available policies are:
+
+- `FAIL`: The operation will raise an error if any document already exists.
+- `OVERWRITE`: Existing documents will be overwritten with the new ones.
+- `SKIP`: Existing documents will be skipped, and only new documents will be added.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Document objects to write to Qdrant.
+- **policy** (DuplicatePolicy) – The policy for handling duplicate documents.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.FAIL
+) -> int
+```
+
+Asynchronously writes documents to Qdrant using the specified policy.
+The QdrantDocumentStore can handle duplicate documents based on the given policy.
+The available policies are:
+
+- `FAIL`: The operation will raise an error if any document already exists.
+- `OVERWRITE`: Existing documents will be overwritten with the new ones.
+- `SKIP`: Existing documents will be skipped, and only new documents will be added.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Document objects to write to Qdrant.
+- **policy** (DuplicatePolicy) – The policy for handling duplicate documents.
+
+**Returns:**
+
+- int – The number of documents written to the document store.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the document ids to delete
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Note**: This operation is not atomic. Documents matching the filter are fetched first,
+then updated. If documents are modified between the fetch and update operations,
+those changes may be lost.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+**Note**: This operation is not atomic. Documents matching the filter are fetched first,
+then updated. If documents are modified between the fetch and update operations,
+those changes may be lost.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### delete_all_documents
+
+```python
+delete_all_documents(recreate_index: bool = False) -> None
+```
+
+Deletes all documents from the document store.
+
+**Parameters:**
+
+- **recreate_index** (bool) – Whether to recreate the index after deleting all documents.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async(recreate_index: bool = False) -> None
+```
+
+Asynchronously deletes all documents from the document store.
+
+**Parameters:**
+
+- **recreate_index** (bool) – Whether to recreate the index after deleting all documents.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for counting.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the information about the metadata fields in the collection.
+
+Since Qdrant may not have a payload schema for unindexed metadata,
+this method scrolls through documents to infer field types from
+payload["meta"].
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary mapping field names to their type information e.g.:
+
+```python
+{"category": {"type": "keyword"}, "priority": {"type": "long"}}
+```
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns the information about the metadata fields in the collection.
+
+Since Qdrant may not have a payload schema for unindexed metadata,
+this method scrolls through documents to infer field types from
+payload["meta"].
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary mapping field names to their type information e.g.:
+
+```python
+{"category": {"type": "keyword"}, "priority": {"type": "long"}}
+```
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field key (inside `meta`) to get the minimum and maximum values for.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the keys "min" and "max", where each value is the minimum or maximum value of the
+ metadata field across all documents. Returns `{"min": None, "max": None}` if no documents have
+ the field.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously returns the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field key (inside `meta`) to get the minimum and maximum values for.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the keys "min" and "max", where each value is the minimum or maximum value of the
+ metadata field across all documents. Returns `{"min": None, "max": None}` if no documents have
+ the field.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the number of unique values for each specified metadata field among documents that match the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to restrict the documents considered.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of metadata field keys (inside `meta`) to count unique values for.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each metadata field name to the count of its unique values among the filtered
+ documents.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously returns the number of unique values for each specified metadata field among documents that
+match the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to restrict the documents considered.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (list\[str\]) – List of metadata field keys (inside `meta`) to count unique values for.
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping each metadata field name to the count of its unique values among the filtered
+ documents.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ filters: dict[str, Any] | None = None,
+ limit: int = 100,
+ offset: int = 0,
+) -> list[Any]
+```
+
+Returns unique values for a metadata field, with optional filters and offset/limit pagination.
+
+Unique values are ordered by first occurrence during scroll. Pagination is offset-based over that order.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field key (inside `meta`) to get unique values for.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **limit** (int) – Maximum number of unique values to return per page. Defaults to 100.
+- **offset** (int) – Number of unique values to skip (for pagination). Defaults to 0.
+
+**Returns:**
+
+- list\[Any\] – A list of unique values for the field (at most `limit` items, starting at `offset`).
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str,
+ filters: dict[str, Any] | None = None,
+ limit: int = 100,
+ offset: int = 0,
+) -> list[Any]
+```
+
+Asynchronously returns unique values for a metadata field, with optional filters and offset/limit pagination.
+
+Unique values are ordered by first occurrence during scroll. Pagination is offset-based over that order.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field key (inside `meta`) to get unique values for.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **limit** (int) – Maximum number of unique values to return per page. Defaults to 100.
+- **offset** (int) – Number of unique values to skip (for pagination). Defaults to 0.
+
+**Returns:**
+
+- list\[Any\] – A list of unique values for the field (at most `limit` items, starting at `offset`).
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> QdrantDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- QdrantDocumentStore – The deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### get_documents_by_id
+
+```python
+get_documents_by_id(ids: list[str]) -> list[Document]
+```
+
+Retrieves documents from Qdrant by their IDs.
+
+**Parameters:**
+
+- **ids** (list\[str\]) – A list of document IDs to retrieve.
+
+**Returns:**
+
+- list\[Document\] – A list of documents.
+
+#### get_documents_by_id_async
+
+```python
+get_documents_by_id_async(ids: list[str]) -> list[Document]
+```
+
+Retrieves documents from Qdrant by their IDs.
+
+**Parameters:**
+
+- **ids** (list\[str\]) – A list of document IDs to retrieve.
+
+**Returns:**
+
+- list\[Document\] – A list of documents.
+
+#### get_distance
+
+```python
+get_distance(similarity: str) -> rest.Distance
+```
+
+Retrieves the distance metric for the specified similarity measure.
+
+**Parameters:**
+
+- **similarity** (str) – The similarity measure to retrieve the distance.
+
+**Returns:**
+
+- Distance – The corresponding rest.Distance object.
+
+**Raises:**
+
+- QdrantStoreError – If the provided similarity measure is not supported.
+
+#### recreate_collection
+
+```python
+recreate_collection(
+ collection_name: str,
+ distance: rest.Distance,
+ embedding_dim: int,
+ on_disk: bool | None = None,
+ use_sparse_embeddings: bool | None = None,
+ sparse_idf: bool = False,
+) -> None
+```
+
+Recreates the Qdrant collection with the specified parameters.
+
+**Parameters:**
+
+- **collection_name** (str) – The name of the collection to recreate.
+- **distance** (Distance) – The distance metric to use for the collection.
+- **embedding_dim** (int) – The dimension of the embeddings.
+- **on_disk** (bool | None) – Whether to store the collection on disk.
+- **use_sparse_embeddings** (bool | None) – Whether to use sparse embeddings.
+- **sparse_idf** (bool) – Whether to compute the Inverse Document Frequency (IDF) when using sparse embeddings. Required for BM42.
+
+#### recreate_collection_async
+
+```python
+recreate_collection_async(
+ collection_name: str,
+ distance: rest.Distance,
+ embedding_dim: int,
+ on_disk: bool | None = None,
+ use_sparse_embeddings: bool | None = None,
+ sparse_idf: bool = False,
+) -> None
+```
+
+Asynchronously recreates the Qdrant collection with the specified parameters.
+
+**Parameters:**
+
+- **collection_name** (str) – The name of the collection to recreate.
+- **distance** (Distance) – The distance metric to use for the collection.
+- **embedding_dim** (int) – The dimension of the embeddings.
+- **on_disk** (bool | None) – Whether to store the collection on disk.
+- **use_sparse_embeddings** (bool | None) – Whether to use sparse embeddings.
+- **sparse_idf** (bool) – Whether to compute the Inverse Document Frequency (IDF) when using sparse embeddings. Required for BM42.
+
+## haystack_integrations.document_stores.qdrant.migrate_to_sparse
+
+### migrate_to_sparse_embeddings_support
+
+```python
+migrate_to_sparse_embeddings_support(
+ old_document_store: QdrantDocumentStore, new_index: str
+) -> None
+```
+
+Utility function to migrate an existing `QdrantDocumentStore` to a new one with support for sparse embeddings.
+
+With qdrant-hasytack v3.3.0, support for sparse embeddings has been added to `QdrantDocumentStore`.
+This feature is disabled by default and can be enabled by setting `use_sparse_embeddings=True` in the init
+parameters. To store sparse embeddings, Document stores/collections created with this feature disabled must be
+migrated to a new collection with the feature enabled.
+
+This utility function applies to on-premise and cloud instances of Qdrant.
+It does not work for local in-memory/disk-persisted instances.
+
+The utility function merely migrates the existing documents so that they are ready to store sparse embeddings.
+It does not compute sparse embeddings. To do this, you need to use a Sparse Embedder component.
+
+Example usage:
+
+```python
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack_integrations.document_stores.qdrant import migrate_to_sparse_embeddings_support
+
+old_document_store = QdrantDocumentStore(url="http://localhost:6333",
+ index="Document",
+ use_sparse_embeddings=False)
+new_index = "Document_sparse"
+
+migrate_to_sparse_embeddings_support(old_document_store, new_index)
+
+# now you can use the new document store with sparse embeddings support
+new_document_store = QdrantDocumentStore(url="http://localhost:6333",
+ index=new_index,
+ use_sparse_embeddings=True)
+```
+
+**Parameters:**
+
+- **old_document_store** (QdrantDocumentStore) – The existing QdrantDocumentStore instance to migrate from.
+- **new_index** (str) – The name of the new index/collection to create with sparse embeddings support.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/ragas.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/ragas.md
new file mode 100644
index 0000000000..3eab5ab02e
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/ragas.md
@@ -0,0 +1,161 @@
+---
+title: "Ragas"
+id: integrations-ragas
+description: "Ragas integration for Haystack"
+slug: "/integrations-ragas"
+---
+
+
+## haystack_integrations.components.evaluators.ragas.evaluator
+
+### RagasEvaluator
+
+A component that uses the Ragas framework to evaluate inputs against specified Ragas metrics.
+
+See the [Ragas framework](https://docs.ragas.io/) for more details.
+
+This component supports the modern Ragas metrics API (`ragas.metrics.collections`).
+Each metric must be a `SimpleBaseMetric` instance with its LLM configured at construction time.
+
+Usage example:
+
+```python
+from openai import AsyncOpenAI
+from ragas.llms import llm_factory
+from ragas.metrics.collections import Faithfulness
+from haystack_integrations.components.evaluators.ragas import RagasEvaluator
+
+client = AsyncOpenAI()
+llm = llm_factory("gpt-4o-mini", client=client)
+
+evaluator = RagasEvaluator(
+ ragas_metrics=[Faithfulness(llm=llm)],
+)
+output = evaluator.run(
+ query="Which is the most popular global sport?",
+ documents=[
+ "Football is undoubtedly the world's most popular sport with"
+ " major events like the FIFA World Cup and sports personalities"
+ " like Ronaldo and Messi, drawing a followership of more than 4"
+ " billion people."
+ ],
+ reference="Football is the most popular sport with around 4 billion"
+ " followers worldwide",
+)
+
+output['result']
+```
+
+#### __init__
+
+```python
+__init__(
+ ragas_metrics: list[SimpleBaseMetric], concurrency_limit: int = 4
+) -> None
+```
+
+Constructs a new Ragas evaluator.
+
+**Parameters:**
+
+- **ragas_metrics** (list\[SimpleBaseMetric\]) – A list of modern Ragas metrics from `ragas.metrics.collections`.
+ Each metric must be fully configured (including its LLM) at construction time.
+ Available metrics can be found in the
+ [Ragas documentation](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/).
+- **concurrency_limit** (int) – The maximum number of metric evaluations that should be allowed to run concurrently.
+ This parameter is only used in the `run_async` method.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> RagasEvaluator
+```
+
+Deserialize this component from a dictionary.
+
+Metrics are reconstructed from their stored class path and LLM/embedding
+configuration. Only the `openai` provider is supported for automatic
+deserialization; the API key is read from the `OPENAI_API_KEY` environment
+variable at load time.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- RagasEvaluator – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str | None = None,
+ response: list[ChatMessage] | str | None = None,
+ documents: list[Document | str] | None = None,
+ reference_contexts: list[str] | None = None,
+ multi_responses: list[str] | None = None,
+ reference: str | None = None,
+ rubrics: dict[str, str] | None = None,
+) -> dict[str, dict[str, MetricResult]]
+```
+
+Evaluates the provided inputs against each metric and returns the results.
+
+**Parameters:**
+
+- **query** (str | None) – The input query from the user.
+- **response** (list\[ChatMessage\] | str | None) – A list of ChatMessage responses (typically from a language model or agent).
+- **documents** (list\[Document | str\] | None) – A list of Haystack Document or strings that were retrieved for the query.
+- **reference_contexts** (list\[str\] | None) – A list of reference contexts that should have been retrieved for the query.
+- **multi_responses** (list\[str\] | None) – List of multiple responses generated for the query.
+- **reference** (str | None) – A string reference answer for the query.
+- **rubrics** (dict\[str, str\] | None) – A dictionary of evaluation rubric, where keys represent the score
+ and the values represent the corresponding evaluation criteria.
+
+**Returns:**
+
+- dict\[str, dict\[str, MetricResult\]\] – A dictionary with key `result` mapping metric names to their `MetricResult`.
+
+#### run_async
+
+```python
+run_async(
+ query: str | None = None,
+ response: list[ChatMessage] | str | None = None,
+ documents: list[Document | str] | None = None,
+ reference_contexts: list[str] | None = None,
+ multi_responses: list[str] | None = None,
+ reference: str | None = None,
+ rubrics: dict[str, str] | None = None,
+) -> dict[str, dict[str, MetricResult]]
+```
+
+Asynchronously evaluates the provided inputs against each metric and returns the results.
+
+**Parameters:**
+
+- **query** (str | None) – The input query from the user.
+- **response** (list\[ChatMessage\] | str | None) – A list of ChatMessage responses (typically from a language model or agent).
+- **documents** (list\[Document | str\] | None) – A list of Haystack Document or strings that were retrieved for the query.
+- **reference_contexts** (list\[str\] | None) – A list of reference contexts that should have been retrieved for the query.
+- **multi_responses** (list\[str\] | None) – List of multiple responses generated for the query.
+- **reference** (str | None) – A string reference answer for the query.
+- **rubrics** (dict\[str, str\] | None) – A dictionary of evaluation rubric, where keys represent the score
+ and the values represent the corresponding evaluation criteria.
+
+**Returns:**
+
+- dict\[str, dict\[str, MetricResult\]\] – A dictionary with key `result` mapping metric names to their `MetricResult`.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/snowflake.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/snowflake.md
new file mode 100644
index 0000000000..bad5f519b8
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/snowflake.md
@@ -0,0 +1,209 @@
+---
+title: "Snowflake"
+id: integrations-snowflake
+description: "Snowflake integration for Haystack"
+slug: "/integrations-snowflake"
+---
+
+
+
+## Module haystack\_integrations.components.retrievers.snowflake.snowflake\_table\_retriever
+
+
+
+### SnowflakeTableRetriever
+
+Connects to a Snowflake database to execute a SQL query using ADBC and Polars.
+Returns the results as a Pandas DataFrame (converted from a Polars DataFrame)
+along with a Markdown-formatted string.
+For more information, see [Polars documentation](https://docs.pola.rs/api/python/dev/reference/api/polars.read_database_uri.html).
+and [ADBC documentation](https://arrow.apache.org/adbc/main/driver/snowflake.html).
+
+### Usage examples:
+
+#### Password Authentication:
+```python
+executor = SnowflakeTableRetriever(
+ user="str) – The SQLAlchemy driver name (e.g., `"sqlite"`,
+ `"postgresql+psycopg2"`).
+- **username** (str | None) – Database username.
+- **password** (Secret | None) – Database password as a Haystack `Secret`.
+- **host** (str | None) – Database host.
+- **port** (int | None) – Database port.
+- **database** (str | None) – Database name or path (e.g., `":memory:"` for SQLite in-memory).
+- **init_script** (list\[str\] | None) – Optional list of SQL statements executed once on `warm_up()`
+ (e.g., to create tables or insert seed data). Each statement should be a
+ separate string in the list.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the database engine and execute `init_script` if provided.
+
+Called automatically by `run()` on first invocation if not already warmed up.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SQLAlchemyTableRetriever
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SQLAlchemyTableRetriever – Deserialized component.
+
+#### run
+
+```python
+run(query: str) -> dict[str, Any]
+```
+
+Execute a SQL query and return the results.
+
+**Parameters:**
+
+- **query** (str) – The SQL query to execute.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with:
+
+- `dataframe`: A Pandas DataFrame with the query results.
+
+- `table`: A Markdown-formatted string of the results.
+
+- `error`: An error message if the query failed, otherwise an empty string.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/stackit.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/stackit.md
new file mode 100644
index 0000000000..2dbf91e712
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/stackit.md
@@ -0,0 +1,295 @@
+---
+title: "STACKIT"
+id: integrations-stackit
+description: "STACKIT integration for Haystack"
+slug: "/integrations-stackit"
+---
+
+
+## haystack_integrations.components.embedders.stackit.document_embedder
+
+### STACKITDocumentEmbedder
+
+Bases: OpenAIDocumentEmbedder
+
+A component for computing Document embeddings using STACKIT as model provider.
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.stackit import STACKITDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = STACKITDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "intfloat/e5-mistral-7b-instruct",
+ "Qwen/Qwen3-VL-Embedding-8B",
+]
+
+```
+
+A non-exhaustive list of embedding models supported by this component.
+See https://docs.stackit.cloud/products/data-and-ai/ai-model-serving/basics/available-shared-models
+for the full list.
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"),
+ api_base_url: (
+ str | None
+ ) = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1",
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ *,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates a STACKITDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The STACKIT API key.
+- **model** (str) – The name of the model to use.
+- **api_base_url** (str | None) – The STACKIT API Base url.
+ For more details, see STACKIT [docs](https://docs.stackit.cloud/stackit/en/basic-concepts-stackit-model-serving-319914567.html).
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **batch_size** (int) – Number of Documents to encode at once.
+- **progress_bar** (bool) – Whether to show a progress bar or not. Can be helpful to disable in production deployments to keep
+ the logs clean.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (str) – Separator used to concatenate the meta fields to the Document text.
+- **timeout** (float | None) – Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+ variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact STACKIT after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+## haystack_integrations.components.embedders.stackit.text_embedder
+
+### STACKITTextEmbedder
+
+Bases: OpenAITextEmbedder
+
+A component for embedding strings using STACKIT as model provider.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.stackit import STACKITTextEmbedder
+
+text_to_embed = "I love pizza!"
+text_embedder = STACKITTextEmbedder()
+print(text_embedder.run(text_to_embed))
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "intfloat/e5-mistral-7b-instruct",
+ "Qwen/Qwen3-VL-Embedding-8B",
+]
+
+```
+
+A non-exhaustive list of embedding models supported by this component.
+See https://docs.stackit.cloud/products/data-and-ai/ai-model-serving/basics/available-shared-models
+for the full list.
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"),
+ api_base_url: (
+ str | None
+ ) = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1",
+ prefix: str = "",
+ suffix: str = "",
+ *,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates a STACKITTextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The STACKIT API key.
+- **model** (str) – The name of the STACKIT embedding model to be used.
+- **api_base_url** (str | None) – The STACKIT API Base url.
+ For more details, see STACKIT [docs](https://docs.stackit.cloud/stackit/en/basic-concepts-stackit-model-serving-319914567.html).
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **timeout** (float | None) – Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+ variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact STACKIT after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+## haystack_integrations.components.generators.stackit.chat.chat_generator
+
+### STACKITChatGenerator
+
+Bases: OpenAIChatGenerator
+
+Enables text generation using STACKIT generative models through their model serving service.
+
+Users can pass any text generation parameters valid for the STACKIT Chat Completion API
+directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage)
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.stackit import STACKITChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = STACKITChatGenerator(model="neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8")
+
+result = generator.run([ChatMessage.from_user("Tell me a joke.")])
+print(result)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "Qwen/Qwen3-VL-235B-A22B-Instruct-FP8",
+ "cortecs/Llama-3.3-70B-Instruct-FP8-Dynamic",
+ "openai/gpt-oss-120b",
+ "google/gemma-3-27b-it",
+ "openai/gpt-oss-20b",
+ "neuralmagic/Mistral-Nemo-Instruct-2407-FP8",
+ "neuralmagic/Meta-Llama-3.1-8B-Instruct-FP8",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+See https://docs.stackit.cloud/products/data-and-ai/ai-model-serving/basics/available-shared-models
+for the full list.
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"),
+ streaming_callback: StreamingCallbackT | None = None,
+ api_base_url: (
+ str | None
+ ) = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1",
+ generation_kwargs: dict[str, Any] | None = None,
+ *,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates an instance of STACKITChatGenerator class.
+
+**Parameters:**
+
+- **model** (str) – The name of the chat completion model to use.
+- **api_key** (Secret) – The STACKIT API key.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+- **api_base_url** (str | None) – The STACKIT API Base url.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the STACKIT endpoint.
+ Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+ Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+ considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+ comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+ events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+ If provided, the output will always be validated against this
+ format (unless the model returns a tool call).
+ For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+ Notes:
+ - For structured outputs with streaming,
+ the `response_format` must be a JSON schema and not a Pydantic model.
+- **timeout** (float | None) – Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+ variable, or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retries to contact STACKIT after an internal error.
+ If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/supabase.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/supabase.md
new file mode 100644
index 0000000000..3d2f1bcead
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/supabase.md
@@ -0,0 +1,340 @@
+---
+title: "Supabase"
+id: integrations-supabase
+description: "Supabase integration for Haystack"
+slug: "/integrations-supabase"
+---
+
+
+## haystack_integrations.components.retrievers.supabase.embedding_retriever
+
+### SupabasePgvectorEmbeddingRetriever
+
+Bases: PgvectorEmbeddingRetriever
+
+Retrieves documents from the `SupabasePgvectorDocumentStore`, based on their dense embeddings.
+
+This is a thin wrapper around `PgvectorEmbeddingRetriever`, adapted for use with
+`SupabasePgvectorDocumentStore`.
+
+Example usage:
+
+# Set an environment variable `SUPABASE_DB_URL` with the connection string to your Supabase database.
+
+```bash
+export SUPABASE_DB_URL=postgresql://postgres:postgres@localhost:5432/postgres
+```
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.types.policy import DuplicatePolicy
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+
+from haystack_integrations.document_stores.supabase import SupabasePgvectorDocumentStore
+from haystack_integrations.components.retrievers.supabase import SupabasePgvectorEmbeddingRetriever
+
+document_store = SupabasePgvectorDocumentStore(
+ embedding_dimension=768,
+ vector_function="cosine_similarity",
+ recreate_table=True,
+)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates..."),
+ Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", SupabasePgvectorEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+res = query_pipeline.run({"text_embedder": {"text": query}})
+print(res['retriever']['documents'][0].content)
+# >> "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: SupabasePgvectorDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ vector_function: (
+ Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+ ) = None,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the SupabasePgvectorEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (SupabasePgvectorDocumentStore) – An instance of `SupabasePgvectorDocumentStore`.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents.
+- **top_k** (int) – Maximum number of Documents to return.
+- **vector_function** (Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None) – The similarity function to use when searching for similar embeddings.
+ Defaults to the one set in the `document_store` instance.
+ `"cosine_similarity"` and `"inner_product"` are similarity functions and
+ higher scores indicate greater similarity between the documents.
+ `"l2_distance"` returns the straight-line distance between vectors,
+ and the most similar documents are the ones with the smallest score.
+ **Important**: if the document store is using the `"hnsw"` search strategy, the vector function
+ should match the one utilized during index creation to take advantage of the index.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `SupabasePgvectorDocumentStore` or if
+ `vector_function` is not one of the valid options.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabasePgvectorEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SupabasePgvectorEmbeddingRetriever – Deserialized component.
+
+## haystack_integrations.components.retrievers.supabase.keyword_retriever
+
+### SupabasePgvectorKeywordRetriever
+
+Bases: PgvectorKeywordRetriever
+
+Retrieves documents from the `SupabasePgvectorDocumentStore`, based on keywords.
+
+This is a thin wrapper around `PgvectorKeywordRetriever`, adapted for use with
+`SupabasePgvectorDocumentStore`.
+
+To rank the documents, the `ts_rank_cd` function of PostgreSQL is used.
+It considers how often the query terms appear in the document, how close together the terms are in the document,
+and how important is the part of the document where they occur.
+
+Example usage:
+
+# Set an environment variable `SUPABASE_DB_URL` with the connection string to your Supabase database.
+
+```bash
+export SUPABASE_DB_URL=postgresql://postgres:postgres@localhost:5432/postgres
+```
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.types.policy import DuplicatePolicy
+
+from haystack_integrations.document_stores.supabase import SupabasePgvectorDocumentStore
+from haystack_integrations.components.retrievers.supabase import SupabasePgvectorKeywordRetriever
+
+document_store = SupabasePgvectorDocumentStore(
+ embedding_dimension=768,
+ recreate_table=True,
+)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates..."),
+ Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_store.write_documents(documents, policy=DuplicatePolicy.OVERWRITE)
+retriever = SupabasePgvectorKeywordRetriever(document_store=document_store)
+result = retriever.run(query="languages")
+
+print(result['documents'][0].content)
+# >> "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: SupabasePgvectorDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the SupabasePgvectorKeywordRetriever.
+
+**Parameters:**
+
+- **document_store** (SupabasePgvectorDocumentStore) – An instance of `SupabasePgvectorDocumentStore`.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents.
+- **top_k** (int) – Maximum number of Documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `SupabasePgvectorDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabasePgvectorKeywordRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SupabasePgvectorKeywordRetriever – Deserialized component.
+
+## haystack_integrations.document_stores.supabase.document_store
+
+### SupabasePgvectorDocumentStore
+
+Bases: PgvectorDocumentStore
+
+A Document Store for Supabase, using PostgreSQL with the pgvector extension.
+
+It should be used with Supabase installed.
+
+This is a thin wrapper around `PgvectorDocumentStore` with Supabase-specific defaults:
+
+- Reads the connection string from the `SUPABASE_DB_URL` environment variable.
+- Defaults `create_extension` to `False` since pgvector is pre-installed on Supabase.
+
+**Connection notes:** Supabase offers two pooler ports — transaction mode (6543) and session mode (5432).
+For best compatibility with pgvector operations, use session mode (port 5432) or a direct connection.
+
+Example usage:
+
+# Set an environment variable `SUPABASE_DB_URL` with the connection string to your Supabase database.
+
+```bash
+export SUPABASE_DB_URL=postgresql://postgres:postgres@localhost:5432/postgres
+```
+
+```python
+from haystack_integrations.document_stores.supabase import SupabasePgvectorDocumentStore
+
+document_store = SupabasePgvectorDocumentStore(
+ embedding_dimension=768,
+ vector_function="cosine_similarity",
+ recreate_table=True,
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ connection_string: Secret = Secret.from_env_var("SUPABASE_DB_URL"),
+ create_extension: bool = False,
+ schema_name: str = "public",
+ table_name: str = "haystack_documents",
+ language: str = "english",
+ embedding_dimension: int = 768,
+ vector_type: Literal["vector", "halfvec"] = "vector",
+ vector_function: Literal[
+ "cosine_similarity", "inner_product", "l2_distance"
+ ] = "cosine_similarity",
+ recreate_table: bool = False,
+ search_strategy: Literal[
+ "exact_nearest_neighbor", "hnsw"
+ ] = "exact_nearest_neighbor",
+ hnsw_recreate_index_if_exists: bool = False,
+ hnsw_index_creation_kwargs: dict[str, int] | None = None,
+ hnsw_index_name: str = "haystack_hnsw_index",
+ hnsw_ef_search: int | None = None,
+ keyword_index_name: str = "haystack_keyword_index"
+) -> None
+```
+
+Creates a new SupabasePgvectorDocumentStore instance.
+
+**Parameters:**
+
+- **connection_string** (Secret) – The connection string for the Supabase PostgreSQL database, defined as an
+ environment variable. Default: `SUPABASE_DB_URL`. Format:
+ `postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres`
+- **create_extension** (bool) – Whether to create the pgvector extension if it doesn't exist.
+ Defaults to `False` since Supabase has pgvector pre-installed.
+- **schema_name** (str) – The name of the schema the table is created in.
+- **table_name** (str) – The name of the table to use to store Haystack documents.
+- **language** (str) – The language to be used to parse query and document content in keyword retrieval.
+- **embedding_dimension** (int) – The dimension of the embedding.
+- **vector_type** (Literal['vector', 'halfvec']) – The type of vector used for embedding storage. `"vector"` or `"halfvec"`.
+- **vector_function** (Literal['cosine_similarity', 'inner_product', 'l2_distance']) – The similarity function to use when searching for similar embeddings.
+- **recreate_table** (bool) – Whether to recreate the table if it already exists.
+- **search_strategy** (Literal['exact_nearest_neighbor', 'hnsw']) – The search strategy to use: `"exact_nearest_neighbor"` or `"hnsw"`.
+- **hnsw_recreate_index_if_exists** (bool) – Whether to recreate the HNSW index if it already exists.
+- **hnsw_index_creation_kwargs** (dict\[str, int\] | None) – Additional keyword arguments for HNSW index creation.
+- **hnsw_index_name** (str) – Index name for the HNSW index.
+- **hnsw_ef_search** (int | None) – The `ef_search` parameter to use at query time for HNSW.
+- **keyword_index_name** (str) – Index name for the Keyword index.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabasePgvectorDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SupabasePgvectorDocumentStore – Deserialized component.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/tavily.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/tavily.md
new file mode 100644
index 0000000000..99e82f1515
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/tavily.md
@@ -0,0 +1,107 @@
+---
+title: "Tavily"
+id: integrations-tavily
+description: "Tavily integration for Haystack"
+slug: "/integrations-tavily"
+---
+
+
+## haystack_integrations.components.websearch.tavily.tavily_websearch
+
+### TavilyWebSearch
+
+A component that uses Tavily to search the web and return results as Haystack Documents.
+
+This component wraps the Tavily Search API, enabling web search queries that return
+structured documents with content and links.
+
+Tavily is an AI-powered search API optimized for LLM applications. You need a Tavily
+API key from [tavily.com](https://tavily.com).
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.tavily import TavilyWebSearch
+from haystack.utils import Secret
+
+websearch = TavilyWebSearch(
+ api_key=Secret.from_env_var("TAVILY_API_KEY"),
+ top_k=5,
+)
+result = websearch.run(query="What is Haystack by deepset?")
+documents = result["documents"]
+links = result["links"]
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("TAVILY_API_KEY"),
+ top_k: int | None = 10,
+ search_params: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the TavilyWebSearch component.
+
+**Parameters:**
+
+- **api_key** (Secret) – API key for Tavily. Defaults to the `TAVILY_API_KEY` environment variable.
+- **top_k** (int | None) – Maximum number of results to return.
+- **search_params** (dict\[str, Any\] | None) – Additional parameters passed to the Tavily search API.
+ See the [Tavily API reference](https://docs.tavily.com/docs/tavily-api/rest_api)
+ for available options. Supported keys include: `search_depth`, `include_answer`,
+ `include_raw_content`, `include_domains`, `exclude_domains`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Tavily sync and async clients.
+
+Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+
+#### run
+
+```python
+run(query: str, search_params: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Search the web using Tavily and return results as Documents.
+
+**Parameters:**
+
+- **query** (str) – Search query string.
+- **search_params** (dict\[str, Any\] | None) – Optional per-run override of search parameters.
+ If provided, fully replaces the init-time `search_params`.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with:
+- `documents`: List of Documents containing search result content.
+- `links`: List of URLs from the search results.
+
+#### run_async
+
+```python
+run_async(
+ query: str, search_params: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously search the web using Tavily and return results as Documents.
+
+**Parameters:**
+
+- **query** (str) – Search query string.
+- **search_params** (dict\[str, Any\] | None) – Optional per-run override of search parameters.
+ If provided, fully replaces the init-time `search_params`.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with:
+- `documents`: List of Documents containing search result content.
+- `links`: List of URLs from the search results.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/togetherai.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/togetherai.md
new file mode 100644
index 0000000000..9604053791
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/togetherai.md
@@ -0,0 +1,294 @@
+---
+title: "Together AI"
+id: integrations-togetherai
+description: "Together AI integration for Haystack"
+slug: "/integrations-togetherai"
+---
+
+
+
+## Module haystack\_integrations.components.generators.togetherai.chat.chat\_generator
+
+
+
+### TogetherAIChatGenerator
+
+Enables text generation using Together AI generative models.
+For supported models, see [Together AI docs](https://docs.together.ai/docs).
+
+Users can pass any text generation parameters valid for the Together AI chat completion API
+directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+Key Features and Compatibility:
+- **Primary Compatibility**: Designed to work seamlessly with the Together AI chat completion endpoint.
+- **Streaming Support**: Supports streaming responses from the Together AI chat completion endpoint.
+- **Customizability**: Supports all parameters supported by the Together AI chat completion endpoint.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage)
+
+For more details on the parameters supported by the Together AI API, refer to the
+[Together AI API Docs](https://docs.together.ai/reference/chat-completions-1).
+
+Usage example:
+```python
+from haystack_integrations.components.generators.togetherai import TogetherAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = TogetherAIChatGenerator()
+response = client.run(messages)
+print(response)
+
+>>{'replies': [ChatMessage(_content='Natural Language Processing (NLP) is a branch of artificial intelligence
+>>that focuses on enabling computers to understand, interpret, and generate human language in a way that is
+>>meaningful and useful.', _role=ValkeyDocumentStore) – The Valkey Document Store.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents.
+- **top_k** (int) – Maximum number of Documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of `ValkeyDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ValkeyEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ValkeyEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `ValkeyDocumentStore`, based on their dense embeddings.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of `Document`s to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – List of Document similar to `query_embedding`.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the `ValkeyDocumentStore`, based on their dense embeddings.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – Maximum number of `Document`s to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – List of Document similar to `query_embedding`.
+
+## haystack_integrations.document_stores.valkey.document_store
+
+### ValkeyDocumentStore
+
+Bases: DocumentStore
+
+A document store implementation using Valkey with vector search capabilities.
+
+This document store provides persistent storage for documents with embeddings and supports
+vector similarity search using the Valkey Search module. It's designed for high-performance
+retrieval applications requiring both semantic search and metadata filtering.
+
+Key features:
+
+- Vector similarity search with HNSW algorithm
+- Metadata filtering on tag and numeric fields
+- Configurable distance metrics (L2, cosine, inner product)
+- Batch operations for efficient document management
+- Both synchronous and asynchronous operations
+- Cluster and standalone mode support
+
+Supported filterable Document metadata fields:
+
+- meta_category (TagField): exact string matches
+- meta_status (TagField): status filtering
+- meta_priority (NumericField): numeric comparisons
+- meta_score (NumericField): score filtering
+- meta_timestamp (NumericField): date/time filtering
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.valkey import ValkeyDocumentStore
+
+# Initialize document store
+document_store = ValkeyDocumentStore(
+ nodes_list=[("localhost", 6379)],
+ index_name="my_documents",
+ embedding_dim=768,
+ distance_metric="cosine"
+)
+
+# Store documents with embeddings
+documents = [
+ Document(
+ content="Valkey is a Redis-compatible database",
+ embedding=[0.1, 0.2, ...], # 768-dim vector
+ meta={"category": "database", "priority": 1}
+ )
+]
+document_store.write_documents(documents)
+
+# Search with filters
+results = document_store._embedding_retrival(
+ embedding=[0.1, 0.15, ...],
+ filters={"field": "meta.category", "operator": "==", "value": "database"},
+ limit=10
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ nodes_list: list[tuple[str, int]] | None = None,
+ *,
+ cluster_mode: bool = False,
+ use_tls: bool = False,
+ username: Secret | None = Secret.from_env_var(
+ "VALKEY_USERNAME", strict=False
+ ),
+ password: Secret | None = Secret.from_env_var(
+ "VALKEY_PASSWORD", strict=False
+ ),
+ request_timeout: int = 500,
+ retry_attempts: int = 3,
+ retry_base_delay_ms: int = 1000,
+ retry_exponent_base: int = 2,
+ batch_size: int = 100,
+ index_name: str = "default",
+ distance_metric: Literal["l2", "cosine", "ip"] = "cosine",
+ embedding_dim: int = 768,
+ metadata_fields: dict[str, type[str] | type[int]] | None = None
+)
+```
+
+Creates a new ValkeyDocumentStore instance.
+
+**Parameters:**
+
+- **nodes_list** (list\[tuple\[str, int\]\] | None) – List of (host, port) tuples for Valkey nodes. Defaults to [("localhost", 6379)].
+- **cluster_mode** (bool) – Whether to connect in cluster mode. Defaults to False.
+- **use_tls** (bool) – Whether to use TLS for connections. Defaults to False.
+- **username** (Secret | None) – Username for authentication. If not provided, reads from VALKEY_USERNAME environment variable.
+ Defaults to None.
+- **password** (Secret | None) – Password for authentication. If not provided, reads from VALKEY_PASSWORD environment variable.
+ Defaults to None.
+- **request_timeout** (int) – Request timeout in milliseconds. Defaults to 500.
+- **retry_attempts** (int) – Number of retry attempts for failed operations. Defaults to 3.
+- **retry_base_delay_ms** (int) – Base delay in milliseconds for exponential backoff. Defaults to 1000.
+- **retry_exponent_base** (int) – Exponent base for exponential backoff calculation. Defaults to 2.
+- **batch_size** (int) – Number of documents to process in a single batch for async operations. Defaults to 100.
+- **index_name** (str) – Name of the search index. Defaults to "haystack_document".
+- **distance_metric** (Literal['l2', 'cosine', 'ip']) – Distance metric for vector similarity. Options: "l2", "cosine", "ip" (inner product).
+ Defaults to "cosine".
+- **embedding_dim** (int) – Dimension of document embeddings. Defaults to 768.
+- **metadata_fields** (dict\[str, type\[str\] | type\[int\]\] | None) – Dictionary mapping metadata field names to Python types for filtering.
+ Supported types: str (for exact matching), int (for numeric comparisons).
+ Example: `{"category": str, "priority": int}`.
+ If not provided, no metadata fields will be indexed for filtering.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes this store to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ValkeyDocumentStore
+```
+
+Deserializes the store from a dictionary.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Return the number of documents stored in the document store.
+
+This method queries the Valkey Search index to get the total count of indexed documents.
+If the index doesn't exist, it returns 0.
+
+**Returns:**
+
+- int – The number of documents in the document store.
+
+**Raises:**
+
+- ValkeyDocumentStoreError – If there's an error accessing the index or counting documents.
+
+Example:
+
+```python
+document_store = ValkeyDocumentStore()
+count = document_store.count_documents()
+print(f"Total documents: {count}")
+```
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously return the number of documents stored in the document store.
+
+This method queries the Valkey Search index to get the total count of indexed documents.
+If the index doesn't exist, it returns 0. This is the async version of count_documents().
+
+**Returns:**
+
+- int – The number of documents in the document store.
+
+**Raises:**
+
+- ValkeyDocumentStoreError – If there's an error accessing the index or counting documents.
+
+Example:
+
+```python
+document_store = ValkeyDocumentStore()
+count = await document_store.count_documents_async()
+print(f"Total documents: {count}")
+```
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Filter documents by metadata without vector search.
+
+This method retrieves documents based on metadata filters without performing vector similarity search.
+Since Valkey Search requires vector queries, this method uses a dummy vector internally and removes
+the similarity scores from results.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Optional metadata filters in Haystack format. Supports filtering on:
+- meta.category (string equality)
+- meta.status (string equality)
+- meta.priority (numeric comparisons)
+- meta.score (numeric comparisons)
+- meta.timestamp (numeric comparisons)
+
+**Returns:**
+
+- list\[Document\] – List of documents matching the filters, with score set to None.
+
+**Raises:**
+
+- ValkeyDocumentStoreError – If there's an error filtering documents.
+
+Example:
+
+```python
+# Filter by category
+docs = document_store.filter_documents(
+ filters={"field": "meta.category", "operator": "==", "value": "news"}
+)
+
+# Filter by numeric range
+docs = document_store.filter_documents(
+ filters={"field": "meta.priority", "operator": ">=", "value": 5}
+)
+```
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously filter documents by metadata without vector search.
+
+This is the async version of filter_documents(). It retrieves documents based on metadata filters
+without performing vector similarity search. Since Valkey Search requires vector queries, this method
+uses a dummy vector internally and removes the similarity scores from results.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Optional metadata filters in Haystack format. Supports filtering on:
+- meta.category (string equality)
+- meta.status (string equality)
+- meta.priority (numeric comparisons)
+- meta.score (numeric comparisons)
+- meta.timestamp (numeric comparisons)
+
+**Returns:**
+
+- list\[Document\] – List of documents matching the filters, with score set to None.
+
+**Raises:**
+
+- ValkeyDocumentStoreError – If there's an error filtering documents.
+
+Example:
+
+```python
+# Filter by category
+docs = await document_store.filter_documents_async(
+ filters={"field": "meta.category", "operator": "==", "value": "news"}
+)
+
+# Filter by numeric range
+docs = await document_store.filter_documents_async(
+ filters={"field": "meta.priority", "operator": ">=", "value": 5}
+)
+```
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to the document store.
+
+This method stores documents with their embeddings and metadata in Valkey. The search index is
+automatically created if it doesn't exist. Documents without embeddings will be assigned a
+dummy vector for indexing purposes.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Document objects to store. Each document should have:
+- content: The document text
+- embedding: Vector representation (optional, dummy vector used if missing)
+- meta: Optional metadata dict with supported fields (category, status, priority, score, timestamp)
+- **policy** (DuplicatePolicy) – How to handle duplicate documents. Only NONE and OVERWRITE are supported.
+ Defaults to DuplicatePolicy.NONE.
+
+**Returns:**
+
+- int – Number of documents successfully written.
+
+**Raises:**
+
+- ValkeyDocumentStoreError – If there's an error writing documents.
+- ValueError – If documents list contains invalid objects.
+
+Example:
+
+```python
+documents = [
+ Document(
+ content="First document",
+ embedding=[0.1, 0.2, 0.3],
+ meta={"category": "news", "priority": 1}
+ ),
+ Document(
+ content="Second document",
+ embedding=[0.4, 0.5, 0.6],
+ meta={"category": "blog", "priority": 2}
+ )
+]
+count = document_store.write_documents(documents)
+print(f"Wrote {count} documents")
+```
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously write documents to the document store.
+
+This is the async version of write_documents(). It stores documents with their embeddings and
+metadata in Valkey using batch processing for improved performance. The search index is
+automatically created if it doesn't exist.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of Document objects to store. Each document should have:
+- content: The document text
+- embedding: Vector representation (optional, dummy vector used if missing)
+- meta: Optional metadata dict with supported fields (category, status, priority, score, timestamp)
+- **policy** (DuplicatePolicy) – How to handle duplicate documents. Only NONE and OVERWRITE are supported.
+ Defaults to DuplicatePolicy.NONE.
+
+**Returns:**
+
+- int – Number of documents successfully written.
+
+**Raises:**
+
+- ValkeyDocumentStoreError – If there's an error writing documents.
+- ValueError – If documents list contains invalid objects.
+
+Example:
+
+```python
+documents = [
+ Document(
+ content="First document",
+ embedding=[0.1, 0.2, 0.3],
+ meta={"category": "news", "priority": 1}
+ ),
+ Document(
+ content="Second document",
+ embedding=[0.4, 0.5, 0.6],
+ meta={"category": "blog", "priority": 2}
+ )
+]
+count = await document_store.write_documents_async(documents)
+print(f"Wrote {count} documents")
+```
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents from the document store by their IDs.
+
+This method removes documents from both the Valkey database and the search index.
+If some documents are not found, a warning is logged but the operation continues.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – List of document IDs to delete. These should be the same IDs
+ used when the documents were originally stored.
+
+**Raises:**
+
+- ValkeyDocumentStoreError – If there's an error deleting documents.
+
+Example:
+
+```python
+# Delete specific documents
+document_store.delete_documents(["doc1", "doc2", "doc3"])
+
+# Delete a single document
+document_store.delete_documents(["single_doc_id"])
+```
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously delete documents from the document store by their IDs.
+
+This is the async version of delete_documents(). It removes documents from both the Valkey
+database and the search index. If some documents are not found, a warning is logged but
+the operation continues.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – List of document IDs to delete. These should be the same IDs
+ used when the documents were originally stored.
+
+**Raises:**
+
+- ValkeyDocumentStoreError – If there's an error deleting documents.
+
+Example:
+
+```python
+# Delete specific documents
+await document_store.delete_documents_async(["doc1", "doc2", "doc3"])
+
+# Delete a single document
+await document_store.delete_documents_async(["single_doc_id"])
+```
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Delete all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dictionary to select documents to delete.
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+- ValkeyDocumentStoreError – If deletion fails.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously delete all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dictionary to select documents to delete.
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+- ValkeyDocumentStoreError – If deletion fails.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Update metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dictionary to select documents to update.
+- **meta** (dict\[str, Any\]) – Metadata key-value pairs to set on matching documents (merged with existing meta).
+
+**Returns:**
+
+- int – The number of documents updated.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+- ValkeyDocumentStoreError – If update or write fails.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously update metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dictionary to select documents to update.
+- **meta** (dict\[str, Any\]) – Metadata key-value pairs to set on matching documents (merged with existing meta).
+
+**Returns:**
+
+- int – The number of documents updated.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+- ValkeyDocumentStoreError – If update or write fails.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Return the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dictionary to apply.
+
+**Returns:**
+
+- int – The number of matching documents.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+- ValkeyDocumentStoreError – If counting fails.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously return the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dictionary to apply.
+
+**Returns:**
+
+- int – The number of matching documents.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+- ValkeyDocumentStoreError – If counting fails.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Count unique values for each specified metadata field in documents matching the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dictionary to select documents.
+- **metadata_fields** (list\[str\]) – List of metadata field names (e.g. "category" or "meta.category").
+
+**Returns:**
+
+- dict\[str, int\] – Dictionary mapping each field name to the count of its unique values.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+- ValueError – If a field in metadata_fields is not configured for filtering.
+- ValkeyDocumentStoreError – If the operation fails.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously count unique values for each specified metadata field in documents matching the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dictionary to select documents.
+- **metadata_fields** (list\[str\]) – List of metadata field names (e.g. "category" or "meta.category").
+
+**Returns:**
+
+- dict\[str, int\] – Dictionary mapping each field name to the count of its unique values.
+
+**Raises:**
+
+- FilterError – If the filter structure is invalid.
+- ValueError – If a field in metadata_fields is not configured for filtering.
+- ValkeyDocumentStoreError – If the operation fails.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Return information about metadata fields configured for filtering.
+
+Returns the store's configured metadata field names and their types (as used in the index).
+Field names are returned without the "meta." prefix (e.g. "category", "priority").
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – Dictionary mapping field name to a dict with "type" key ("keyword" for tag, "long" for numeric).
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Return the minimum and maximum values for a numeric metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – Metadata field name (e.g. "priority" or "meta.priority"). Must be a configured
+ numeric field.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with "min" and "max" keys (values are int/float or None if no values).
+
+**Raises:**
+
+- ValueError – If the field is not configured or is not numeric.
+- ValkeyDocumentStoreError – If the operation fails.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously return the minimum and maximum values for a numeric metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – Metadata field name (e.g. "priority" or "meta.priority"). Must be a configured
+ numeric field.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with "min" and "max" keys (values are int/float or None if no values).
+
+**Raises:**
+
+- ValueError – If the field is not configured or is not numeric.
+- ValkeyDocumentStoreError – If the operation fails.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Return unique values for a metadata field with optional search and pagination.
+
+Values are stringified. For tag fields the distinct values are returned; for numeric fields
+the string representation of each distinct value is returned.
+
+**Parameters:**
+
+- **metadata_field** (str) – Metadata field name (e.g. "category" or "meta.category").
+- **search_term** (str | None) – Optional case-insensitive substring filter on the value.
+- **from\_** (int) – Start index for pagination (default 0).
+- **size** (int) – Number of values to return (default 10).
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – Tuple of (list of unique values for the requested page, total count of unique values).
+
+**Raises:**
+
+- ValueError – If the field is not configured for filtering.
+- ValkeyDocumentStoreError – If the operation fails.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously return unique values for a metadata field with optional search and pagination.
+
+**Parameters:**
+
+- **metadata_field** (str) – Metadata field name (e.g. "category" or "meta.category").
+- **search_term** (str | None) – Optional case-insensitive substring filter on the value.
+- **from\_** (int) – Start index for pagination (default 0).
+- **size** (int) – Number of values to return (default 10).
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – Tuple of (list of unique values for the requested page, total count of unique values).
+
+**Raises:**
+
+- ValueError – If the field is not configured for filtering.
+- ValkeyDocumentStoreError – If the operation fails.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Delete all documents from the document store.
+
+This method removes all documents by dropping the entire search index. This is an efficient
+way to clear all data but requires recreating the index for future operations. If the index
+doesn't exist, the operation completes without error.
+
+**Raises:**
+
+- ValkeyDocumentStoreError – If there's an error dropping the index.
+
+Warning:
+This operation is irreversible and will permanently delete all documents and the search index.
+
+Example:
+
+```python
+# Clear all documents from the store
+document_store.delete_all_documents()
+
+# The index will be automatically recreated on next write operation
+document_store.write_documents(new_documents)
+```
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async() -> None
+```
+
+Asynchronously delete all documents from the document store.
+
+This is the async version of delete_all_documents(). It removes all documents by dropping
+the entire search index. This is an efficient way to clear all data but requires recreating
+the index for future operations. If the index doesn't exist, the operation completes without error.
+
+**Raises:**
+
+- ValkeyDocumentStoreError – If there's an error dropping the index.
+
+Warning:
+This operation is irreversible and will permanently delete all documents and the search index.
+
+Example:
+
+```python
+# Clear all documents from the store
+await document_store.delete_all_documents_async()
+
+# The index will be automatically recreated on next write operation
+await document_store.write_documents_async(new_documents)
+```
+
+## haystack_integrations.document_stores.valkey.filters
+
+Valkey document store filtering utilities.
+
+This module provides filter conversion from Haystack's filter format to Valkey Search query syntax.
+It supports both tag-based exact matching and numeric range filtering with logical operators.
+
+Supported filter operations:
+
+- TagField filters: ==, !=, in, not in (exact string matches)
+- NumericField filters: ==, !=, >, >=, \<, \<=, in, not in (numeric comparisons)
+- Logical operators: AND, OR for combining conditions
+
+Filter syntax examples:
+
+```python
+# Simple equality filter
+filters = {"field": "meta.category", "operator": "==", "value": "tech"}
+
+# Numeric range filter
+filters = {"field": "meta.priority", "operator": ">=", "value": 5}
+
+# List membership filter
+filters = {"field": "meta.status", "operator": "in", "value": ["active", "pending"]}
+
+# Complex logical filter
+filters = {
+ "operator": "AND",
+ "conditions": [
+ {"field": "meta.category", "operator": "==", "value": "tech"},
+ {"field": "meta.priority", "operator": ">=", "value": 3}
+ ]
+}
+```
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/vllm.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/vllm.md
new file mode 100644
index 0000000000..f193b82068
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/vllm.md
@@ -0,0 +1,697 @@
+---
+title: "vLLM"
+id: integrations-vllm
+description: "vLLM integration for Haystack"
+slug: "/integrations-vllm"
+---
+
+
+## haystack_integrations.components.embedders.vllm.document_embedder
+
+### VLLMDocumentEmbedder
+
+A component for computing Document embeddings using models served with [vLLM](https://docs.vllm.ai/).
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+It expects a vLLM server to be running and accessible at the `api_base_url` parameter and uses the
+OpenAI-compatible Embeddings API exposed by vLLM.
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server with an embedding model:
+
+```bash
+vllm serve google/embeddinggemma-300m
+```
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.vllm import VLLMDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = VLLMDocumentEmbedder(model="google/embeddinggemma-300m")
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+```
+
+### Usage example with vLLM-specific parameters
+
+Pass vLLM-specific parameters via the `extra_parameters` dictionary. They are forwarded as `extra_body`
+to the OpenAI-compatible endpoint.
+
+```python
+document_embedder = VLLMDocumentEmbedder(
+ model="google/embeddinggemma-300m",
+ extra_parameters={"truncate_prompt_tokens": 256, "truncation_side": "right"},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str,
+ api_key: Secret | None = Secret.from_env_var("VLLM_API_KEY", strict=False),
+ api_base_url: str = "http://localhost:8000/v1",
+ prefix: str = "",
+ suffix: str = "",
+ dimensions: int | None = None,
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None,
+ raise_on_failure: bool = False,
+ extra_parameters: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of VLLMDocumentEmbedder.
+
+**Parameters:**
+
+- **model** (str) – The name of the model served by vLLM. Check
+ [vLLM documentation](https://docs.vllm.ai/en/stable/models/pooling_models) for more information.
+- **api_key** (Secret | None) – The vLLM API key. Defaults to the `VLLM_API_KEY` environment variable.
+ Only required if the vLLM server was started with `--api-key`.
+- **api_base_url** (str) – The base URL of the vLLM server.
+- **prefix** (str) – A string to add at the beginning of each text.
+- **suffix** (str) – A string to add at the end of each text.
+- **dimensions** (int | None) – The number of dimensions of the resulting embedding. Only models trained with
+ Matryoshka Representation Learning support this parameter. See
+ [vLLM documentation](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#matryoshka-embeddings)
+ for more information.
+- **batch_size** (int) – Number of documents to encode at once.
+- **progress_bar** (bool) – Whether to show a progress bar.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields to embed along with the document text.
+- **embedding_separator** (str) – Separator used to concatenate the meta fields to the document text.
+- **timeout** (float | None) – Timeout in seconds for vLLM client calls. If not set, the OpenAI client default applies.
+- **max_retries** (int | None) – Maximum number of retries for failed requests. If not set, the OpenAI client
+ default applies.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client` or
+ `httpx.AsyncClient`. For more information, see the
+ [HTTPX documentation](https://www.python-httpx.org/api/#client).
+- **raise_on_failure** (bool) – Whether to raise an exception if the embedding request fails. If `False`,
+ the component logs the error and continues processing the remaining documents.
+- **extra_parameters** (dict\[str, Any\] | None) – Additional parameters forwarded as `extra_body` to the vLLM embeddings
+ endpoint. Use this to pass parameters not part of the standard OpenAI Embeddings API, such as
+ `truncate_prompt_tokens`, `truncation_side`, etc. See the
+ [vLLM Embeddings API docs](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#openai-compatible-embeddings-api).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the OpenAI clients.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Embed a list of Documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with:
+- `documents`: The input documents with their `embedding` field populated.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(
+ documents: list[Document],
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Asynchronously embed a list of Documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with:
+- `documents`: The input documents with their `embedding` field populated.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.embedders.vllm.text_embedder
+
+### VLLMTextEmbedder
+
+A component for embedding strings using models served with [vLLM](https://docs.vllm.ai/).
+
+It expects a vLLM server to be running and accessible at the `api_base_url` parameter and uses the
+OpenAI-compatible Embeddings API exposed by vLLM.
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server with an embedding model:
+
+```bash
+vllm serve google/embeddinggemma-300m
+```
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### Usage example
+
+```python
+from haystack_integrations.components.embedders.vllm import VLLMTextEmbedder
+
+text_embedder = VLLMTextEmbedder(model="google/embeddinggemma-300m")
+print(text_embedder.run("I love pizza!"))
+```
+
+### Usage example with vLLM-specific parameters
+
+Pass vLLM-specific parameters via the `extra_parameters` dictionary. They are forwarded as `extra_body`
+to the OpenAI-compatible endpoint.
+
+```python
+text_embedder = VLLMTextEmbedder(
+ model="google/embeddinggemma-300m",
+ extra_parameters={"truncate_prompt_tokens": 256, "truncation_side": "right"},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str,
+ api_key: Secret | None = Secret.from_env_var("VLLM_API_KEY", strict=False),
+ api_base_url: str = "http://localhost:8000/v1",
+ prefix: str = "",
+ suffix: str = "",
+ dimensions: int | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None,
+ extra_parameters: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of VLLMTextEmbedder.
+
+**Parameters:**
+
+- **model** (str) – The name of the model served by vLLM (e.g., "intfloat/e5-mistral-7b-instruct").
+- **api_key** (Secret | None) – The vLLM API key. Defaults to the `VLLM_API_KEY` environment variable.
+ Only required if the vLLM server was started with `--api-key`.
+- **api_base_url** (str) – The base URL of the vLLM server.
+- **prefix** (str) – A string to add at the beginning of each text to embed.
+- **suffix** (str) – A string to add at the end of each text to embed.
+- **dimensions** (int | None) – The number of dimensions of the resulting embedding. Only models trained with
+ Matryoshka Representation Learning support this parameter. See
+ [vLLM documentation](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#matryoshka-embeddings)
+ for more information.
+- **timeout** (float | None) – Timeout in seconds for vLLM client calls. If not set, the OpenAI client default applies.
+- **max_retries** (int | None) – Maximum number of retries for failed requests. If not set, the OpenAI client
+ default applies.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client` or
+ `httpx.AsyncClient`. For more information, see the
+ [HTTPX documentation](https://www.python-httpx.org/api/#client).
+- **extra_parameters** (dict\[str, Any\] | None) – Additional parameters forwarded as `extra_body` to the vLLM embeddings
+ endpoint. Use this to pass parameters not part of the standard OpenAI Embeddings API, such as
+ `truncate_prompt_tokens`, `truncation_side`, `additional_data`, `use_activation`, etc. See the
+ [vLLM Embeddings API docs](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#openai-compatible-embeddings-api).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the OpenAI clients.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Embed a single string.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\] | dict\[str, Any\]\] – A dictionary with:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Asynchronously embed a single string.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\] | dict\[str, Any\]\] – A dictionary with:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.generators.vllm.chat.chat_generator
+
+### VLLMChatGenerator
+
+A component for generating chat completions using models served with [vLLM](https://docs.vllm.ai/).
+
+It expects a vLLM server to be running and accessible at the `api_base_url` parameter.
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server:
+
+```bash
+vllm serve Qwen/Qwen3-4B-Instruct-2507
+```
+
+For reasoning models, start the server with the appropriate reasoning parser:
+
+```bash
+vllm serve Qwen/Qwen3-0.6B --reasoning-parser qwen3
+```
+
+For tool calling, the server must be started with `--enable-auto-tool-choice` and `--tool-call-parser`:
+
+```bash
+vllm serve Qwen/Qwen3-0.6B --enable-auto-tool-choice --tool-call-parser hermes
+```
+
+The available tool call parsers depend on the model. See the
+[vLLM tool calling docs](https://docs.vllm.ai/en/stable/features/tool_calling/) for the full list.
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### Usage example
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+generator = VLLMChatGenerator(
+ model="Qwen/Qwen3-0.6B",
+ generation_kwargs={"max_tokens": 512, "temperature": 0.7},
+)
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+response = generator.run(messages=messages)
+print(response["replies"][0].text)
+```
+
+### Usage example with vLLM-specific parameters
+
+Pass the vLLM-specific parameters inside the `generation_kwargs`["extra_body"] dictionary.
+
+```python
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+generator = VLLMChatGenerator(
+ model="Qwen/Qwen3-0.6B",
+ generation_kwargs={
+ "max_tokens": 512,
+ "extra_body": {
+ "top_k": 50,
+ "min_tokens": 10,
+ "repetition_penalty": 1.1,
+ },
+ },
+)
+```
+
+### Usage example with tool calling
+
+To use tool calling, start the vLLM server with `--enable-auto-tool-choice` and `--tool-call-parser`.
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.tools import tool
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+@tool
+def weather(city: str) -> str:
+ """Get the weather in a given city."""
+ return f"The weather in {city} is sunny"
+
+generator = VLLMChatGenerator(model="Qwen/Qwen3-0.6B", tools=[weather])
+
+messages = [ChatMessage.from_user("What is the weather in Paris?")]
+response = generator.run(messages=messages)
+print(response["replies"][0].tool_calls)
+```
+
+### Usage example with reasoning models
+
+To use reasoning models, start the vLLM server with `--reasoning-parser`.
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+generator = VLLMChatGenerator(model="Qwen/Qwen3-0.6B")
+
+messages = [ChatMessage.from_user("Solve step by step: what is 15 * 37?")]
+response = generator.run(messages=messages)
+reply = response["replies"][0]
+if reply.reasoning:
+ print("Reasoning:", reply.reasoning.reasoning_text)
+print("Answer:", reply.text)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str,
+ api_key: Secret | None = Secret.from_env_var("VLLM_API_KEY", strict=False),
+ streaming_callback: StreamingCallbackT | None = None,
+ api_base_url: str = "http://localhost:8000/v1",
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ tools: ToolsType | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of VLLMChatGenerator.
+
+**Parameters:**
+
+- **model** (str) – The name of the model served by vLLM (e.g., "Qwen/Qwen3-0.6B").
+- **api_key** (Secret | None) – The vLLM API key. Defaults to the `VLLM_API_KEY` environment variable.
+ Only required if the vLLM server was started with `--api-key`.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts
+ [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk)
+ as an argument.
+- **api_base_url** (str) – The base URL of the vLLM server.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional parameters for text generation. These parameters are sent directly to
+ the vLLM OpenAI-compatible endpoint. See
+ [vLLM documentation](https://docs.vllm.ai/en/stable/serving/openai_compatible_server/)
+ for more details.
+ Some of the supported parameters:
+- `max_tokens`: Maximum number of tokens to generate.
+- `temperature`: Sampling temperature.
+- `top_p`: Nucleus sampling parameter.
+- `n`: Number of completions to generate for each prompt.
+- `stop`: One or more sequences after which the model should stop generating tokens.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the response.
+- `extra_body`: A dictionary of vLLM-specific parameters not part of the standard OpenAI API
+ (e.g., `top_k`, `min_tokens`, `repetition_penalty`).
+- **timeout** (float | None) – Timeout for vLLM client calls. If not set, it defaults to the default set by the OpenAI client.
+- **max_retries** (int | None) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default
+ set by the OpenAI client.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ Each tool should have a unique name. Not all models support tools.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client` or `httpx.AsyncClient`.
+ For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the OpenAI clients and warm up tools.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> VLLMChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- VLLMChatGenerator – The deserialized component instance.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ *,
+ tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Run the VLLM chat generator on the given input data.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will
+ override the parameters passed during component initialization.
+ For details on vLLM API parameters, see
+ [vLLM documentation](https://docs.vllm.ai/en/stable/serving/openai_compatible_server/).
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage],
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ *,
+ tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Run the VLLM chat generator on the given input data asynchronously.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ Must be a coroutine.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will
+ override the parameters passed during component initialization.
+ For details on vLLM API parameters, see
+ [vLLM documentation](https://docs.vllm.ai/en/stable/serving/openai_compatible_server/).
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+## haystack_integrations.components.rankers.vllm.ranker
+
+### VLLMRanker
+
+Ranks Documents based on their similarity to a query using models served with [vLLM](https://docs.vllm.ai/).
+
+It expects a vLLM server to be running and accessible at the `api_base_url` parameter and uses the
+`/rerank` endpoint exposed by vLLM.
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server with a reranker model:
+
+```bash
+vllm serve BAAI/bge-reranker-base
+```
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.vllm import VLLMRanker
+
+ranker = VLLMRanker(model="BAAI/bge-reranker-base")
+docs = [
+ Document(content="The capital of Brazil is Brasilia."),
+ Document(content="The capital of France is Paris."),
+]
+result = ranker.run(query="What is the capital of France?", documents=docs)
+print(result["documents"][0].content)
+```
+
+### Usage example with vLLM-specific parameters
+
+Pass vLLM-specific parameters via the `extra_parameters` dictionary. They are merged into the
+request body sent to the `/rerank` endpoint.
+
+```python
+ranker = VLLMRanker(
+ model="BAAI/bge-reranker-base",
+ extra_parameters={"truncate_prompt_tokens": 256},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str,
+ api_key: Secret | None = Secret.from_env_var("VLLM_API_KEY", strict=False),
+ api_base_url: str = "http://localhost:8000/v1",
+ top_k: int | None = None,
+ score_threshold: float | None = None,
+ meta_fields_to_embed: list[str] | None = None,
+ meta_data_separator: str = "\n",
+ http_client_kwargs: dict[str, Any] | None = None,
+ extra_parameters: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of VLLMRanker.
+
+**Parameters:**
+
+- **model** (str) – The name of the reranker model served by vLLM. Check
+ [vLLM documentation](https://docs.vllm.ai/en/stable/models/pooling_models/scoring/#supported-models) for
+ information on supported models.
+- **api_key** (Secret | None) – The vLLM API key. Defaults to the `VLLM_API_KEY` environment variable.
+ Only required if the vLLM server was started with `--api-key`.
+- **api_base_url** (str) – The base URL of the vLLM server.
+- **top_k** (int | None) – The maximum number of Documents to return. If `None`, all documents are returned.
+- **score_threshold** (float | None) – If set, documents with a relevance score below this value are dropped.
+ Applied after `top_k`, so the output may contain fewer than `top_k` documents.
+- **meta_fields_to_embed** (list\[str\] | None) – List of meta fields that should be concatenated with the document
+ content before reranking.
+- **meta_data_separator** (str) – Separator used to concatenate the meta fields to the document content.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client` or
+ `httpx.AsyncClient`. For more information, see the
+ [HTTPX documentation](https://www.python-httpx.org/api/#client).
+- **extra_parameters** (dict\[str, Any\] | None) – Additional parameters merged into the request body sent to the vLLM
+ `/rerank` endpoint. Use this to pass parameters not part of the standard rerank API, such as
+ `truncate_prompt_tokens`. See the
+ [vLLM docs](https://docs.vllm.ai/en/stable/models/pooling_models/scoring/#rerank-api) for more information.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the httpx clients.
+
+#### run
+
+```python
+run(
+ query: str,
+ documents: list[Document],
+ top_k: int | None = None,
+ score_threshold: float | None = None,
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Returns a list of Documents ranked by their similarity to the given query.
+
+**Parameters:**
+
+- **query** (str) – Query string.
+- **documents** (list\[Document\]) – List of Documents to rank.
+- **top_k** (int | None) – The maximum number of Documents to return. Overrides the value set at initialization.
+- **score_threshold** (float | None) – Minimum relevance score required for a document to be returned. Overrides
+ the value set at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with:
+- `documents`: Documents sorted from most to least relevant.
+- `meta`: Information about the model and usage.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ documents: list[Document],
+ top_k: int | None = None,
+ score_threshold: float | None = None,
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Asynchronously returns a list of Documents ranked by their similarity to the given query.
+
+**Parameters:**
+
+- **query** (str) – Query string.
+- **documents** (list\[Document\]) – List of Documents to rank.
+- **top_k** (int | None) – The maximum number of Documents to return. Overrides the value set at initialization.
+- **score_threshold** (float | None) – Minimum relevance score required for a document to be returned. Overrides
+ the value set at initialization.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with:
+- `documents`: Documents sorted from most to least relevant.
+- `meta`: Information about the model and usage.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/watsonx.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/watsonx.md
new file mode 100644
index 0000000000..81319779b5
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/watsonx.md
@@ -0,0 +1,699 @@
+---
+title: "IBM watsonx.ai"
+id: integrations-watsonx
+description: "IBM watsonx.ai integration for Haystack"
+slug: "/integrations-watsonx"
+---
+
+
+## haystack_integrations.components.embedders.watsonx.document_embedder
+
+### WatsonxDocumentEmbedder
+
+Computes document embeddings using IBM watsonx.ai models.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.watsonx.document_embedder import WatsonxDocumentEmbedder
+
+documents = [
+ Document(content="I love pizza!"),
+ Document(content="Pasta is great too"),
+]
+
+document_embedder = WatsonxDocumentEmbedder(
+ model="ibm/slate-30m-english-rtrvr-v2",
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ api_base_url="https://us-south.ml.cloud.ibm.com",
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+
+result = document_embedder.run(documents=documents)
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "ibm/slate-30m-english-rtrvr-v2",
+ api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"),
+ api_base_url: str = "https://us-south.ml.cloud.ibm.com",
+ project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"),
+ truncate_input_tokens: int | None = None,
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 1000,
+ concurrency_limit: int = 5,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n"
+)
+```
+
+Creates a WatsonxDocumentEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – The name of the model to use for calculating embeddings.
+ Default is "ibm/slate-30m-english-rtrvr-v2".
+- **api_key** (Secret) – The WATSONX API key. Can be set via environment variable WATSONX_API_KEY.
+- **api_base_url** (str) – The WATSONX URL for the watsonx.ai service.
+ Default is "https://us-south.ml.cloud.ibm.com".
+- **project_id** (Secret) – The ID of the Watson Studio project.
+ Can be set via environment variable WATSONX_PROJECT_ID.
+- **truncate_input_tokens** (int | None) – Maximum number of tokens to use from the input text.
+ If set to `None` (or not provided), the full input text is used, up to the model's maximum token limit.
+- **prefix** (str) – A string to add at the beginning of each text.
+- **suffix** (str) – A string to add at the end of each text.
+- **batch_size** (int) – Number of documents to embed in one API call. Default is 1000.
+- **concurrency_limit** (int) – Number of parallel requests to make. Default is 5.
+- **timeout** (float | None) – Timeout for API requests in seconds.
+- **max_retries** (int | None) – Maximum number of retries for API requests.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> 'WatsonxDocumentEmbedder'
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- 'WatsonxDocumentEmbedder' – The deserialized component instance.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with:
+- 'documents': List of Documents with embeddings added
+- 'meta': Information about the model usage
+
+## haystack_integrations.components.embedders.watsonx.text_embedder
+
+### WatsonxTextEmbedder
+
+Embeds strings using IBM watsonx.ai foundation models.
+
+You can use it to embed user query and send it to an embedding Retriever.
+
+### Usage example
+
+```python
+from haystack_integrations.components.embedders.watsonx.text_embedder import WatsonxTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = WatsonxTextEmbedder(
+ model="ibm/slate-30m-english-rtrvr-v2",
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ api_base_url="https://us-south.ml.cloud.ibm.com",
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+# 'meta': {'model': 'ibm/slate-30m-english-rtrvr-v2',
+# 'truncated_input_tokens': 3}}
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "ibm/slate-30m-english-rtrvr-v2",
+ api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"),
+ api_base_url: str = "https://us-south.ml.cloud.ibm.com",
+ project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"),
+ truncate_input_tokens: int | None = None,
+ prefix: str = "",
+ suffix: str = "",
+ timeout: float | None = None,
+ max_retries: int | None = None
+)
+```
+
+Creates an WatsonxTextEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – The name of the IBM watsonx model to use for calculating embeddings.
+ Default is "ibm/slate-30m-english-rtrvr-v2".
+- **api_key** (Secret) – The WATSONX API key. Can be set via environment variable WATSONX_API_KEY.
+- **api_base_url** (str) – The WATSONX URL for the watsonx.ai service.
+ Default is "https://us-south.ml.cloud.ibm.com".
+- **project_id** (Secret) – The ID of the Watson Studio project.
+ Can be set via environment variable WATSONX_PROJECT_ID.
+- **truncate_input_tokens** (int | None) – Maximum number of tokens to use from the input text.
+ If set to `None` (or not provided), the full input text is used, up to the model's maximum token limit.
+- **prefix** (str) – A string to add at the beginning of each text to embed.
+- **suffix** (str) – A string to add at the end of each text to embed.
+- **timeout** (float | None) – Timeout for API requests in seconds.
+- **max_retries** (int | None) – Maximum number of retries for API requests.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WatsonxTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- WatsonxTextEmbedder – The deserialized component instance.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Embeds a single string.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\] | dict\[str, Any\]\] – A dictionary with:
+- 'embedding': The embedding of the input text
+- 'meta': Information about the model usage
+
+## haystack_integrations.components.generators.watsonx.chat.chat_generator
+
+### WatsonxChatGenerator
+
+Enables chat completions using IBM's watsonx.ai foundation models.
+
+This component interacts with IBM's watsonx.ai platform to generate chat responses using various foundation
+models. It supports the [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage) format for both input
+and output, including multimodal inputs with text and images.
+
+The generator works with IBM's foundation models that are listed
+[here](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx&audience=wdp).
+
+You can customize the generation behavior by passing parameters to the watsonx.ai API through the
+`generation_kwargs` argument. These parameters are passed directly to the watsonx.ai inference endpoint.
+
+For details on watsonx.ai API parameters, see
+[IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-parameters.html).
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.watsonx.chat.chat_generator import WatsonxChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+messages = [ChatMessage.from_user("Explain quantum computing in simple terms")]
+
+client = WatsonxChatGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ model="ibm/granite-4-h-small",
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+response = client.run(messages)
+print(response)
+```
+
+### Multimodal usage example
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+
+# Create an image from file path or base64
+image_content = ImageContent.from_file_path("path/to/your/image.jpg")
+
+# Create a multimodal message with both text and image
+messages = [ChatMessage.from_user(content_parts=["What's in this image?", image_content])]
+
+# Use a multimodal model
+client = WatsonxChatGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ model="meta-llama/llama-3-2-11b-vision-instruct",
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+response = client.run(messages)
+print(response)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "ibm/granite-3-1-8b-base",
+ "ibm/granite-3-8b-instruct",
+ "ibm/granite-4-h-small",
+ "ibm/granite-8b-code-instruct",
+ "ibm/granite-guardian-3-8b",
+ "meta-llama/llama-3-1-70b-gptq",
+ "meta-llama/llama-3-1-8b",
+ "meta-llama/llama-3-2-11b-vision-instruct",
+ "meta-llama/llama-3-2-90b-vision-instruct",
+ "meta-llama/llama-3-3-70b-instruct",
+ "meta-llama/llama-3-405b-instruct",
+ "meta-llama/llama-4-maverick-17b-128e-instruct-fp8",
+ "meta-llama/llama-guard-3-11b-vision",
+ "mistral-large-2512",
+ "mistralai/mistral-medium-2505",
+ "mistralai/mistral-small-3-1-24b-instruct-2503",
+ "openai/gpt-oss-120b",
+]
+
+```
+
+A non-exhaustive list of models supported by this component.
+
+See https://www.ibm.com/docs/en/watsonx/saas?topic=solutions-supported-foundation-models for the
+full list of models and up-to-date model IDs.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"),
+ model: str = "ibm/granite-4-h-small",
+ project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"),
+ api_base_url: str = "https://us-south.ml.cloud.ibm.com",
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ verify: bool | str | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ tools: ToolsType | None = None
+) -> None
+```
+
+Creates an instance of WatsonxChatGenerator.
+
+Before initializing the component, you can set environment variables:
+
+- `WATSONX_TIMEOUT` to override the default timeout
+- `WATSONX_MAX_RETRIES` to override the default retry count
+
+**Parameters:**
+
+- **api_key** (Secret) – IBM Cloud API key for watsonx.ai access.
+ Can be set via `WATSONX_API_KEY` environment variable or passed directly.
+- **model** (str) – The model ID to use for completions. Defaults to "ibm/granite-4-h-small".
+ Available models can be found in your IBM Cloud account.
+- **project_id** (Secret) – IBM Cloud project ID
+- **api_base_url** (str) – Custom base URL for the API endpoint.
+ Defaults to "https://us-south.ml.cloud.ibm.com".
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional parameters to control text generation.
+ These parameters are passed directly to the watsonx.ai inference endpoint.
+ Supported parameters include:
+- `temperature`: Controls randomness (lower = more deterministic)
+- `max_new_tokens`: Maximum number of tokens to generate
+- `min_new_tokens`: Minimum number of tokens to generate
+- `top_p`: Nucleus sampling probability threshold
+- `top_k`: Number of highest probability tokens to consider
+- `repetition_penalty`: Penalty for repeated tokens
+- `length_penalty`: Penalty based on output length
+- `stop_sequences`: List of sequences where generation should stop
+- `random_seed`: Seed for reproducible results
+- **timeout** (float | None) – Timeout in seconds for API requests.
+ Defaults to environment variable `WATSONX_TIMEOUT` or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retry attempts for failed requests.
+ Defaults to environment variable `WATSONX_MAX_RETRIES` or 5.
+- **verify** (bool | str | None) – SSL verification setting. Can be:
+- True: Verify SSL certificates (default)
+- False: Skip verification (insecure)
+- Path to CA bundle for custom certificates
+- **streaming_callback** (StreamingCallbackT | None) – A callback function for streaming responses.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WatsonxChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- WatsonxChatGenerator – The deserialized component instance.
+
+#### run
+
+```python
+run(
+ *,
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Generate chat completions synchronously.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+ passed in the `__init__` method.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ If provided this will override the `streaming_callback` set in the `__init__` method.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+#### run_async
+
+```python
+run_async(
+ *,
+ messages: list[ChatMessage],
+ generation_kwargs: dict[str, Any] | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Generate chat completions asynchronously.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+ passed in the `__init__` method.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ If provided this will override the `streaming_callback` set in the `__init__` method.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+ If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+## haystack_integrations.components.generators.watsonx.generator
+
+### WatsonxGenerator
+
+Bases: WatsonxChatGenerator
+
+Enables text completions using IBM's watsonx.ai foundation models.
+
+This component extends WatsonxChatGenerator to provide the standard Generator interface that works with prompt
+strings instead of ChatMessage objects.
+
+The generator works with IBM's foundation models that are listed
+[here](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx&audience=wdp).
+
+You can customize the generation behavior by passing parameters to the watsonx.ai API through the
+`generation_kwargs` argument. These parameters are passed directly to the watsonx.ai inference endpoint.
+
+For details on watsonx.ai API parameters, see
+[IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-parameters.html).
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.watsonx.generator import WatsonxGenerator
+from haystack.utils import Secret
+
+generator = WatsonxGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ model="ibm/granite-4-h-small",
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+
+response = generator.run(
+ prompt="Explain quantum computing in simple terms",
+ system_prompt="You are a helpful physics teacher.",
+)
+print(response)
+```
+
+Output:
+
+```
+{
+ "replies": ["Quantum computing uses quantum-mechanical phenomena like...."],
+ "meta": [
+ {
+ "model": "ibm/granite-4-h-small",
+ "project_id": "your-project-id",
+ "usage": {
+ "prompt_tokens": 12,
+ "completion_tokens": 45,
+ "total_tokens": 57,
+ },
+ }
+ ],
+}
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "ibm/granite-3-1-8b-base",
+ "ibm/granite-3-8b-instruct",
+ "ibm/granite-4-h-small",
+ "ibm/granite-8b-code-instruct",
+ "ibm/granite-guardian-3-8b",
+ "meta-llama/llama-3-1-70b-gptq",
+ "meta-llama/llama-3-1-8b",
+ "meta-llama/llama-3-2-11b-vision-instruct",
+ "meta-llama/llama-3-2-90b-vision-instruct",
+ "meta-llama/llama-3-3-70b-instruct",
+ "meta-llama/llama-3-405b-instruct",
+ "meta-llama/llama-4-maverick-17b-128e-instruct-fp8",
+ "meta-llama/llama-guard-3-11b-vision",
+ "mistral-large-2512",
+ "mistralai/mistral-medium-2505",
+ "mistralai/mistral-small-3-1-24b-instruct-2503",
+ "openai/gpt-oss-120b",
+]
+
+```
+
+A non-exhaustive list of models supported by this component.
+
+See https://www.ibm.com/docs/en/watsonx/saas?topic=solutions-supported-foundation-models for the
+full list of models and up-to-date model IDs.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"),
+ model: str = "ibm/granite-4-h-small",
+ project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"),
+ api_base_url: str = "https://us-south.ml.cloud.ibm.com",
+ system_prompt: str | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ verify: bool | str | None = None,
+ streaming_callback: StreamingCallbackT | None = None
+) -> None
+```
+
+Creates an instance of WatsonxGenerator.
+
+Before initializing the component, you can set environment variables:
+
+- `WATSONX_TIMEOUT` to override the default timeout
+- `WATSONX_MAX_RETRIES` to override the default retry count
+
+**Parameters:**
+
+- **api_key** (Secret) – IBM Cloud API key for watsonx.ai access.
+ Can be set via `WATSONX_API_KEY` environment variable or passed directly.
+- **model** (str) – The model ID to use for completions. Defaults to "ibm/granite-4-h-small".
+ Available models can be found in your IBM Cloud account.
+- **project_id** (Secret) – IBM Cloud project ID
+- **api_base_url** (str) – Custom base URL for the API endpoint.
+ Defaults to "https://us-south.ml.cloud.ibm.com".
+- **system_prompt** (str | None) – The system prompt to use for text generation.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional parameters to control text generation.
+ These parameters are passed directly to the watsonx.ai inference endpoint.
+ Supported parameters include:
+- `temperature`: Controls randomness (lower = more deterministic)
+- `max_new_tokens`: Maximum number of tokens to generate
+- `min_new_tokens`: Minimum number of tokens to generate
+- `top_p`: Nucleus sampling probability threshold
+- `top_k`: Number of highest probability tokens to consider
+- `repetition_penalty`: Penalty for repeated tokens
+- `length_penalty`: Penalty based on output length
+- `stop_sequences`: List of sequences where generation should stop
+- `random_seed`: Seed for reproducible results
+- **timeout** (float | None) – Timeout in seconds for API requests.
+ Defaults to environment variable `WATSONX_TIMEOUT` or 30 seconds.
+- **max_retries** (int | None) – Maximum number of retry attempts for failed requests.
+ Defaults to environment variable `WATSONX_MAX_RETRIES` or 5.
+- **verify** (bool | str | None) – SSL verification setting. Can be:
+- True: Verify SSL certificates (default)
+- False: Skip verification (insecure)
+- Path to CA bundle for custom certificates
+- **streaming_callback** (StreamingCallbackT | None) – A callback function for streaming responses.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WatsonxGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- WatsonxGenerator – The deserialized component instance.
+
+#### run
+
+```python
+run(
+ *,
+ prompt: str,
+ system_prompt: str | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Generate text completions synchronously.
+
+**Parameters:**
+
+- **prompt** (str) – The input prompt string for text generation.
+- **system_prompt** (str | None) – An optional system prompt to provide context or instructions for the generation.
+ If not provided, the system prompt set in the `__init__` method will be used.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ If provided, this will override the `streaming_callback` set in the `__init__` method.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+ passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `replies`: A list of generated text completions as strings.
+- `meta`: A list of metadata dictionaries containing information about each generation,
+ including model name, finish reason, and token usage statistics.
+
+#### run_async
+
+```python
+run_async(
+ *,
+ prompt: str,
+ system_prompt: str | None = None,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Generate text completions asynchronously.
+
+**Parameters:**
+
+- **prompt** (str) – The input prompt string for text generation.
+- **system_prompt** (str | None) – An optional system prompt to provide context or instructions for the generation.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+ If provided, this will override the `streaming_callback` set in the `__init__` method.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+ passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `replies`: A list of generated text completions as strings.
+- `meta`: A list of metadata dictionaries containing information about each generation,
+ including model name, finish reason, and token usage statistics.
diff --git a/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/weave.md b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/weave.md
new file mode 100644
index 0000000000..73537caa5c
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-2.29-unstable/integrations-api/weave.md
@@ -0,0 +1,248 @@
+---
+title: "Weave"
+id: integrations-weave
+description: "Weights & Bias integration for Haystack"
+slug: "/integrations-weave"
+---
+
+
+
+## Module haystack\_integrations.components.connectors.weave.weave\_connector
+
+
+
+### WeaveConnector
+
+Collects traces from your pipeline and sends them to Weights & Biases.
+
+Add this component to your pipeline to integrate with the Weights & Biases Weave framework for tracing and
+monitoring your pipeline components.
+
+Note that you need to have the `WANDB_API_KEY` environment variable set to your Weights & Biases API key.
+
+NOTE: If you don't have a Weights & Biases account it will interactively ask you to set one and your input
+will then be stored in ~/.netrc
+
+In addition, you need to set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true` in order to
+enable Haystack tracing in your pipeline.
+
+To use this connector simply add it to your pipeline without any connections, and it will automatically start
+sending traces to Weights & Biases.
+
+**Example**:
+
+```python
+import os
+
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.components.connectors import WeaveConnector
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", OpenAIChatGenerator(model="gpt-3.5-turbo"))
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+connector = WeaveConnector(pipeline_name="test_pipeline")
+pipe.add_component("weave", connector)
+
+messages = [
+ ChatMessage.from_system(
+ "Always respond in German even if some input data is in other languages."
+ ),
+ ChatMessage.from_user("Tell me about {{location}}"),
+]
+
+response = pipe.run(
+ data={
+ "prompt_builder": {
+ "template_variables": {"location": "Berlin"},
+ "template": messages,
+ }
+ }
+)
+print(response["llm"]["replies"][0])
+```
+
+ You should then head to `https://wandb.ai/WeaviateDocumentStore) – Instance of WeaviateDocumentStore that will be used from this retriever.
+- **filters** (dict\[str, Any\] | None) – Custom filters applied when running the retriever
+- **top_k** (int) – Maximum number of documents to return
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WeaviateBM25Retriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- WeaviateBM25Retriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieves documents from Weaviate using the BM25 algorithm.
+
+**Parameters:**
+
+- **query** (str) – The query text.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+#### run_async
+
+```python
+run_async(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieves documents from Weaviate using the BM25 algorithm.
+
+**Parameters:**
+
+- **query** (str) – The query text.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+## haystack_integrations.components.retrievers.weaviate.embedding_retriever
+
+### WeaviateEmbeddingRetriever
+
+A retriever that uses Weaviate's vector search to find similar documents based on the embeddings of the query.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: WeaviateDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ distance: float | None = None,
+ certainty: float | None = None,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Creates a new instance of WeaviateEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (WeaviateDocumentStore) – Instance of WeaviateDocumentStore that will be used from this retriever.
+- **filters** (dict\[str, Any\] | None) – Custom filters applied when running the retriever.
+- **top_k** (int) – Maximum number of documents to return.
+- **distance** (float | None) – The maximum allowed distance between Documents' embeddings.
+- **certainty** (float | None) – Normalized distance between the result item and the search vector.
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- ValueError – If both `distance` and `certainty` are provided.
+ See https://weaviate.io/developers/weaviate/api/graphql/search-operators#variables to learn more about
+ `distance` and `certainty` parameters.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WeaviateEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- WeaviateEmbeddingRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ distance: float | None = None,
+ certainty: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieves documents from Weaviate using the vector search.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **distance** (float | None) – The maximum allowed distance between Documents' embeddings.
+- **certainty** (float | None) – Normalized distance between the result item and the search vector.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+**Raises:**
+
+- ValueError – If both `distance` and `certainty` are provided.
+ See https://weaviate.io/developers/weaviate/api/graphql/search-operators#variables to learn more about
+ `distance` and `certainty` parameters.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ distance: float | None = None,
+ certainty: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieves documents from Weaviate using the vector search.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **distance** (float | None) – The maximum allowed distance between Documents' embeddings.
+- **certainty** (float | None) – Normalized distance between the result item and the search vector.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+**Raises:**
+
+- ValueError – If both `distance` and `certainty` are provided.
+ See https://weaviate.io/developers/weaviate/api/graphql/search-operators#variables to learn more about
+ `distance` and `certainty` parameters.
+
+## haystack_integrations.components.retrievers.weaviate.hybrid_retriever
+
+### WeaviateHybridRetriever
+
+A retriever that uses Weaviate's hybrid search to find similar documents based on the embeddings of the query.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: WeaviateDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ alpha: float = 0.7,
+ max_vector_distance: float | None = None,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Creates a new instance of WeaviateHybridRetriever.
+
+**Parameters:**
+
+- **document_store** (WeaviateDocumentStore) – Instance of WeaviateDocumentStore that will be used from this retriever.
+- **filters** (dict\[str, Any\] | None) – Custom filters applied when running the retriever.
+- **top_k** (int) – Maximum number of documents to return.
+- **alpha** (float) – Blending factor for hybrid retrieval in Weaviate. Must be in the range `[0.0, 1.0]`.
+
+Weaviate hybrid search combines keyword (BM25) and vector scores into a single ranking. `alpha` controls
+how much each part contributes to the final score:
+
+- `alpha = 0.0`: only keyword (BM25) scoring is used.
+- `alpha = 1.0`: only vector similarity scoring is used.
+- Values in between blend the two; higher values favor the vector score, lower values favor BM25.
+
+By default, 0.7 is used which is the Weaviate server default.
+
+See the official Weaviate docs on Hybrid Search parameters for more details:
+
+- [Hybrid search parameters](https://weaviate.io/developers/weaviate/search/hybrid#parameters)
+- [Hybrid Search](https://docs.weaviate.io/weaviate/concepts/search/hybrid-search)
+- **max_vector_distance** (float | None) – Optional threshold that restricts the vector part of the hybrid search to candidates within a maximum
+ vector distance. Candidates with a distance larger than this threshold are excluded from the vector portion
+ before blending.
+
+Use this to prune low-quality vector matches while still benefitting from keyword recall. Leave `None` to
+use Weaviate's default behavior without an explicit cutoff.
+
+See the official Weaviate docs on Hybrid Search parameters for more details:
+
+- [Hybrid search parameters](https://weaviate.io/developers/weaviate/search/hybrid#parameters)
+- [Hybrid Search](https://docs.weaviate.io/weaviate/concepts/search/hybrid-search)
+- **filter_policy** (str | FilterPolicy) – Policy to determine how filters are applied.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WeaviateHybridRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- WeaviateHybridRetriever – Deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ alpha: float | None = None,
+ max_vector_distance: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieves documents from Weaviate using hybrid search.
+
+**Parameters:**
+
+- **query** (str) – The query text.
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **alpha** (float | None) – Blending factor for hybrid retrieval in Weaviate. Must be in the range `[0.0, 1.0]`.
+
+Weaviate hybrid search combines keyword (BM25) and vector scores into a single ranking. `alpha` controls
+how much each part contributes to the final score:
+
+- `alpha = 0.0`: only keyword (BM25) scoring is used.
+- `alpha = 1.0`: only vector similarity scoring is used.
+- Values in between blend the two; higher values favor the vector score, lower values favor BM25.
+
+If `None`, the Weaviate server default is used.
+
+See the official Weaviate docs on Hybrid Search parameters for more details:
+
+- [Hybrid search parameters](https://weaviate.io/developers/weaviate/search/hybrid#parameters)
+- [Hybrid Search](https://docs.weaviate.io/weaviate/concepts/search/hybrid-search)
+- **max_vector_distance** (float | None) – Optional threshold that restricts the vector part of the hybrid search to candidates within a maximum
+ vector distance. Candidates with a distance larger than this threshold are excluded from the vector portion
+ before blending.
+
+Use this to prune low-quality vector matches while still benefitting from keyword recall. Leave `None` to
+use Weaviate's default behavior without an explicit cutoff.
+
+See the official Weaviate docs on Hybrid Search parameters for more details:
+
+- [Hybrid search parameters](https://weaviate.io/developers/weaviate/search/hybrid#parameters)
+- [Hybrid Search](https://docs.weaviate.io/weaviate/concepts/search/hybrid-search)
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ alpha: float | None = None,
+ max_vector_distance: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieves documents from Weaviate using hybrid search.
+
+**Parameters:**
+
+- **query** (str) – The query text.
+- **query_embedding** (list\[float\]) – Embedding of the query.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+ the `filter_policy` chosen at retriever initialization. See init method docstring for more
+ details.
+- **top_k** (int | None) – The maximum number of documents to return.
+- **alpha** (float | None) – Blending factor for hybrid retrieval in Weaviate. Must be in the range `[0.0, 1.0]`.
+
+Weaviate hybrid search combines keyword (BM25) and vector scores into a single ranking. `alpha` controls
+how much each part contributes to the final score:
+
+- `alpha = 0.0`: only keyword (BM25) scoring is used.
+- `alpha = 1.0`: only vector similarity scoring is used.
+- Values in between blend the two; higher values favor the vector score, lower values favor BM25.
+
+If `None`, the Weaviate server default is used.
+
+See the official Weaviate docs on Hybrid Search parameters for more details:
+
+- [Hybrid search parameters](https://weaviate.io/developers/weaviate/search/hybrid#parameters)
+- [Hybrid Search](https://docs.weaviate.io/weaviate/concepts/search/hybrid-search)
+- **max_vector_distance** (float | None) – Optional threshold that restricts the vector part of the hybrid search to candidates within a maximum
+ vector distance. Candidates with a distance larger than this threshold are excluded from the vector portion
+ before blending.
+
+Use this to prune low-quality vector matches while still benefitting from keyword recall. Leave `None` to
+use Weaviate's default behavior without an explicit cutoff.
+
+See the official Weaviate docs on Hybrid Search parameters for more details:
+
+- [Hybrid search parameters](https://weaviate.io/developers/weaviate/search/hybrid#parameters)
+- [Hybrid Search](https://docs.weaviate.io/weaviate/concepts/search/hybrid-search)
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+## haystack_integrations.document_stores.weaviate.auth
+
+### SupportedAuthTypes
+
+Bases: Enum
+
+Supported auth credentials for WeaviateDocumentStore.
+
+#### from_class
+
+```python
+from_class(auth_class: type[AuthCredentials]) -> SupportedAuthTypes
+```
+
+Return the SupportedAuthTypes enum value corresponding to the given auth credentials class.
+
+### AuthCredentials
+
+Bases: ABC
+
+Base class for all auth credentials supported by WeaviateDocumentStore.
+
+Can be used to deserialize from dict any of the supported auth credentials.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Converts the object to a dictionary representation for serialization.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AuthCredentials
+```
+
+Converts a dictionary representation to an auth credentials object.
+
+#### resolve_value
+
+```python
+resolve_value() -> (
+ WeaviateAuthApiKey
+ | WeaviateAuthBearerToken
+ | WeaviateAuthClientCredentials
+ | WeaviateAuthClientPassword
+)
+```
+
+Resolves all the secrets in the auth credentials object and returns the corresponding Weaviate object.
+
+All subclasses must implement this method.
+
+### AuthApiKey
+
+Bases: AuthCredentials
+
+AuthCredentials for API key authentication.
+
+By default it will load `api_key` from the environment variable `WEAVIATE_API_KEY`.
+
+#### resolve_value
+
+```python
+resolve_value() -> WeaviateAuthApiKey
+```
+
+Resolve the API key secret and return the corresponding Weaviate auth object.
+
+### AuthBearerToken
+
+Bases: AuthCredentials
+
+AuthCredentials for Bearer token authentication.
+
+By default it will load `access_token` from the environment variable `WEAVIATE_ACCESS_TOKEN`,
+and `refresh_token` from the environment variable
+`WEAVIATE_REFRESH_TOKEN`.
+`WEAVIATE_REFRESH_TOKEN` environment variable is optional.
+
+#### resolve_value
+
+```python
+resolve_value() -> WeaviateAuthBearerToken
+```
+
+Resolve the bearer token secrets and return the corresponding Weaviate auth object.
+
+### AuthClientCredentials
+
+Bases: AuthCredentials
+
+AuthCredentials for client credentials authentication.
+
+By default it will load `client_secret` from the environment variable `WEAVIATE_CLIENT_SECRET`, and
+`scope` from the environment variable `WEAVIATE_SCOPE`.
+`WEAVIATE_SCOPE` environment variable is optional, if set it can either be a string or a list of space
+separated strings. e.g "scope1" or "scope1 scope2".
+
+#### resolve_value
+
+```python
+resolve_value() -> WeaviateAuthClientCredentials
+```
+
+Resolve the client credentials secrets and return the corresponding Weaviate auth object.
+
+### AuthClientPassword
+
+Bases: AuthCredentials
+
+AuthCredentials for username and password authentication.
+
+By default it will load `username` from the environment variable `WEAVIATE_USERNAME`,
+`password` from the environment variable `WEAVIATE_PASSWORD`, and
+`scope` from the environment variable `WEAVIATE_SCOPE`.
+`WEAVIATE_SCOPE` environment variable is optional, if set it can either be a string or a list of space
+separated strings. e.g "scope1" or "scope1 scope2".
+
+#### resolve_value
+
+```python
+resolve_value() -> WeaviateAuthClientPassword
+```
+
+Resolve the username and password secrets and return the corresponding Weaviate auth object.
+
+## haystack_integrations.document_stores.weaviate.document_store
+
+### WeaviateDocumentStore
+
+A WeaviateDocumentStore instance you can use with Weaviate Cloud Services or self-hosted instances.
+
+Usage example with Weaviate Cloud Services:
+
+```python
+import os
+from haystack_integrations.document_stores.weaviate.auth import AuthApiKey
+from haystack_integrations.document_stores.weaviate.document_store import (
+ WeaviateDocumentStore,
+)
+
+os.environ["WEAVIATE_API_KEY"] = "MY_API_KEY"
+
+document_store = WeaviateDocumentStore(
+ url="rAnD0mD1g1t5.something.weaviate.cloud",
+ auth_client_secret=AuthApiKey(),
+)
+```
+
+Usage example with self-hosted Weaviate:
+
+```python
+from haystack_integrations.document_stores.weaviate.document_store import (
+ WeaviateDocumentStore,
+)
+
+document_store = WeaviateDocumentStore(url="http://localhost:8080")
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ url: str | None = None,
+ collection_settings: dict[str, Any] | None = None,
+ auth_client_secret: AuthCredentials | None = None,
+ additional_headers: dict | None = None,
+ embedded_options: EmbeddedOptions | None = None,
+ additional_config: AdditionalConfig | None = None,
+ grpc_port: int = 50051,
+ grpc_secure: bool = False
+) -> None
+```
+
+Create a new instance of WeaviateDocumentStore and connects to the Weaviate instance.
+
+**Parameters:**
+
+- **url** (str | None) – The URL to the weaviate instance.
+- **collection_settings** (dict\[str, Any\] | None) – The collection settings to use. If `None`, it will use a collection named `default` with the following
+ properties:
+- \_original_id: text
+- content: text
+- blob_data: blob
+- blob_mime_type: text
+- score: number
+ The Document `meta` fields are omitted in the default collection settings as we can't make assumptions
+ on the structure of the meta field.
+ We heavily recommend to create a custom collection with the correct meta properties
+ for your use case.
+ Another option is relying on the automatic schema generation, but that's not recommended for
+ production use.
+ See the official [Weaviate documentation](https://weaviate.io/developers/weaviate/manage-data/collections)
+ for more information on collections and their properties.
+- **auth_client_secret** (AuthCredentials | None) – Authentication credentials. Can be one of the following types depending on the authentication mode:
+- `AuthBearerToken` to use existing access and (optionally, but recommended) refresh tokens
+- `AuthClientPassword` to use username and password for oidc Resource Owner Password flow
+- `AuthClientCredentials` to use a client secret for oidc client credential flow
+- `AuthApiKey` to use an API key
+- **additional_headers** (dict | None) – Additional headers to include in the requests. Can be used to set OpenAI/HuggingFace keys.
+ OpenAI/HuggingFace key looks like this:
+
+```
+{"X-OpenAI-Api-Key": "EmbeddedOptions | None) – If set, create an embedded Weaviate cluster inside the client. For a full list of options see
+ `weaviate.embedded.EmbeddedOptions`.
+- **additional_config** (AdditionalConfig | None) – Additional and advanced configuration options for weaviate.
+- **grpc_port** (int) – The port to use for the gRPC connection.
+- **grpc_secure** (bool) – Whether to use a secure channel for the underlying gRPC API.
+
+#### client
+
+```python
+client: weaviate.WeaviateClient
+```
+
+Return the synchronous Weaviate client, creating and connecting it if necessary.
+
+#### async_client
+
+```python
+async_client: weaviate.WeaviateAsyncClient
+```
+
+Return the asynchronous Weaviate client, creating and connecting it if necessary.
+
+#### collection
+
+```python
+collection: Collection[dict[str, Any], None]
+```
+
+Return the synchronous Weaviate collection, initializing it via the client if necessary.
+
+#### async_collection
+
+```python
+async_collection: CollectionAsync[dict[str, Any], None]
+```
+
+Return the asynchronous Weaviate collection, initializing it via the async client if necessary.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Weaviate client connection.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Weaviate client connection.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WeaviateDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- WeaviateDocumentStore – The deserialized component.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns the number of documents present in the DocumentStore.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns the number of documents present in the DocumentStore.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see
+ [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to count documents.
+ For filter syntax, see
+ [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Returns:**
+
+- int – The number of documents that match the filters.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns metadata field names and their types, excluding special fields.
+
+Special fields (content, blob_data, blob_mime_type, \_original_id, score) are excluded
+as they are not user metadata fields.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary where keys are field names and values are dictionaries
+ containing type information, e.g.:
+
+```python
+{
+ 'number': {'type': 'int'},
+ 'date': {'type': 'date'},
+ 'category': {'type': 'text'},
+ 'status': {'type': 'text'}
+}
+```
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns metadata field names and their types, excluding special fields.
+
+Special fields (content, blob_data, blob_mime_type, \_original_id, score) are excluded
+as they are not user metadata fields.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – A dictionary where keys are field names and values are dictionaries
+ containing type information, e.g.:
+
+```python
+{
+ 'number': {'type': 'int'},
+ 'date': {'type': 'date'},
+ 'category': {'type': 'text'},
+ 'status': {'type': 'text'}
+}
+```
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for a numeric or date metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name to get min/max for.
+ Can be prefixed with 'meta.' (e.g., 'meta.year' or 'year').
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with 'min' and 'max' keys containing the respective values.
+
+**Raises:**
+
+- ValueError – If the field is not found or doesn't support min/max operations.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously returns the minimum and maximum values for a numeric or date metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name to get min/max for.
+ Can be prefixed with 'meta.' (e.g., 'meta.year' or 'year').
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with 'min' and 'max' keys containing the respective values.
+
+**Raises:**
+
+- ValueError – If the field is not found or doesn't support min/max operations.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the count of unique values for each specified metadata field.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply when counting unique values.
+ For filter syntax, see
+ [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+- **metadata_fields** (list\[str\]) – List of metadata field names to count unique values for.
+ Field names can be prefixed with 'meta.' (e.g., 'meta.category' or 'category').
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping field names to counts of unique values.
+
+**Raises:**
+
+- ValueError – If any of the requested fields don't exist in the collection schema.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously returns the count of unique values for each specified metadata field.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply when counting unique values.
+ For filter syntax, see
+ [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+- **metadata_fields** (list\[str\]) – List of metadata field names to count unique values for.
+ Field names can be prefixed with 'meta.' (e.g., 'meta.category' or 'category').
+
+**Returns:**
+
+- dict\[str, int\] – A dictionary mapping field names to counts of unique values.
+
+**Raises:**
+
+- ValueError – If any of the requested fields don't exist in the collection schema.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10000,
+) -> tuple[list[str], int]
+```
+
+Returns unique values for a metadata field with pagination support.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name to get unique values for.
+ Can be prefixed with 'meta.' (e.g., 'meta.category' or 'category').
+- **search_term** (str | None) – Optional term to filter documents by content before
+ extracting unique values. If provided, only documents whose content
+ contains this term will be considered.
+ Note: Uses substring matching (case-sensitive, no stemming).
+- **from\_** (int) – The starting offset for pagination (0-indexed). Defaults to 0.
+- **size** (int) – The maximum number of unique values to return. Defaults to 10000.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple of (list of unique values, total count of unique values).
+
+**Raises:**
+
+- ValueError – If the field is not found in the collection schema.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10000,
+) -> tuple[list[str], int]
+```
+
+Asynchronously returns unique values for a metadata field with pagination support.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name to get unique values for.
+ Can be prefixed with 'meta.' (e.g., 'meta.category' or 'category').
+- **search_term** (str | None) – Optional term to filter documents by content before
+ extracting unique values. If provided, only documents whose content
+ contains this term will be considered.
+ Note: Uses substring matching (case-sensitive, no stemming).
+- **from\_** (int) – The starting offset for pagination (0-indexed). Defaults to 0.
+- **size** (int) – The maximum number of unique values to return. Defaults to 10000.
+
+**Returns:**
+
+- tuple\[list\[str\], int\] – A tuple of (list of unique values, total count of unique values).
+
+**Raises:**
+
+- ValueError – If the field is not found in the collection schema.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters, refer to the
+DocumentStore.filter_documents() protocol documentation.
+
+Note: The `contains` filter operator is case-sensitive (substring
+matching). For case-insensitive matching, normalize the value before
+building the filter.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+For a detailed specification of the filters, refer to the
+DocumentStore.filter_documents() protocol documentation.
+
+Note: The `contains` filter operator is case-sensitive (substring
+matching). For case-insensitive matching, normalize the value before
+building the filter.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – The filters to apply to the document list.
+
+**Returns:**
+
+- list\[Document\] – A list of Documents that match the given filters.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents to Weaviate using the specified policy.
+
+We recommend using a OVERWRITE policy as it's faster than other policies for Weaviate since it uses
+the batch API.
+We can't use the batch API for other policies as it doesn't return any information whether the document
+already exists or not. That prevents us from returning errors when using the FAIL policy or skipping a
+Document when using the SKIP policy.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to write into the document store.
+- **policy** (DuplicatePolicy) – DuplicatePolicy to apply when a document with the same ID already exists in the document store.
+
+**Returns:**
+
+- int – The number of documents written.
+
+**Raises:**
+
+- ValueError – When input is not valid.
+- DuplicateDocumentError – When duplicate documents are found and using a FAIL policy.
+- DocumentStoreError – When documents have failed to be batch written.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously writes documents to Weaviate using the specified policy.
+
+We recommend using a OVERWRITE policy as it's faster than other policies for Weaviate since it uses
+the batch API.
+We can't use the batch API for other policies as it doesn't return any information whether the document
+already exists or not. That prevents us from returning errors when using the FAIL policy or skipping a
+Document when using the SKIP policy.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to write into the document store.
+- **policy** (DuplicatePolicy) – DuplicatePolicy to apply when a document with the same ID already exists in the document store.
+
+**Returns:**
+
+- int – The number of documents written.
+
+**Raises:**
+
+- ValueError – When input is not valid.
+- DuplicateDocumentError – When duplicate documents are found and using a FAIL policy.
+- DocumentStoreError – When documents have failed to be batch written.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with matching document_ids from the DocumentStore.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – The object_ids to delete.
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes all documents with matching document_ids from the DocumentStore.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – The object_ids to delete.
+
+#### delete_all_documents
+
+```python
+delete_all_documents(
+ *, recreate_index: bool = False, batch_size: int = 1000
+) -> None
+```
+
+Deletes all documents in a collection.
+
+If recreate_index is False, it keeps the collection but deletes documents iteratively.
+If recreate_index is True, the collection is dropped and faithfully recreated.
+This is recommended for performance reasons.
+
+**Parameters:**
+
+- **recreate_index** (bool) – Use drop and recreate strategy. (recommended for performance)
+- **batch_size** (int) – Only relevant if recreate_index is false. Defines the deletion batch size.
+ Note that this parameter needs to be less or equal to the set `QUERY_MAXIMUM_RESULTS` variable
+ set for the weaviate deployment (default is 10000).
+ Reference: https://docs.weaviate.io/weaviate/manage-objects/delete#delete-all-objects
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async(
+ *, recreate_index: bool = False, batch_size: int = 1000
+) -> None
+```
+
+Asynchronously deletes all documents in a collection.
+
+If recreate_index is False, it keeps the collection but deletes documents iteratively.
+If recreate_index is True, the collection is dropped and faithfully recreated.
+This is recommended for performance reasons.
+
+**Parameters:**
+
+- **recreate_index** (bool) – Use drop and recreate strategy. (recommended for performance)
+- **batch_size** (int) – Only relevant if recreate_index is false. Defines the deletion batch size.
+ Note that this parameter needs to be less or equal to the set `QUERY_MAXIMUM_RESULTS` variable
+ set for the weaviate deployment (default is 10000).
+ Reference: https://docs.weaviate.io/weaviate/manage-objects/delete#delete-all-objects
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for deletion.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update. These will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – The filters to apply to select documents for updating.
+ For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (dict\[str, Any\]) – The metadata fields to update. These will be merged with existing metadata.
+
+**Returns:**
+
+- int – The number of documents updated.
diff --git a/docs-website/reference_versioned_sidebars/version-2.29-unstable-sidebars.json b/docs-website/reference_versioned_sidebars/version-2.29-unstable-sidebars.json
new file mode 100644
index 0000000000..726c83871d
--- /dev/null
+++ b/docs-website/reference_versioned_sidebars/version-2.29-unstable-sidebars.json
@@ -0,0 +1,51 @@
+{
+ "reference": [
+ {
+ "type": "doc",
+ "id": "api-index",
+ "label": "API Overview"
+ },
+ {
+ "type": "category",
+ "label": "Haystack API",
+ "link": {
+ "type": "generated-index",
+ "title": "Haystack API"
+ },
+ "items": [
+ {
+ "type": "autogenerated",
+ "dirName": "haystack-api"
+ }
+ ]
+ },
+ {
+ "type": "category",
+ "label": "Integrations API",
+ "link": {
+ "type": "generated-index",
+ "title": "Integrations API"
+ },
+ "items": [
+ {
+ "type": "autogenerated",
+ "dirName": "integrations-api"
+ }
+ ]
+ },
+ {
+ "type": "category",
+ "label": "Experiments API",
+ "link": {
+ "type": "generated-index",
+ "title": "Experiments API"
+ },
+ "items": [
+ {
+ "type": "autogenerated",
+ "dirName": "experiments-api"
+ }
+ ]
+ }
+ ]
+}
\ No newline at end of file
diff --git a/docs-website/reference_versions.json b/docs-website/reference_versions.json
index bb5a412fad..07c6f0553f 100644
--- a/docs-website/reference_versions.json
+++ b/docs-website/reference_versions.json
@@ -1 +1 @@
-["2.28", "2.27", "2.26", "2.25", "2.24", "2.23", "2.22", "2.21", "2.20", "2.19", "2.18"]
\ No newline at end of file
+["2.29-unstable", "2.28", "2.27", "2.26", "2.25", "2.24", "2.23", "2.22", "2.21", "2.20", "2.19", "2.18"]
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.29-unstable/_templates/component-template.mdx b/docs-website/versioned_docs/version-2.29-unstable/_templates/component-template.mdx
new file mode 100644
index 0000000000..f1c5c42fb6
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/_templates/component-template.mdx
@@ -0,0 +1,44 @@
+---
+title: "Component Name"
+id: "component-name"
+description: "A short description of the component"
+slug: "/component-name"
+---
+
+# Component Name
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | |
+| **Mandatory init variables** | |
+| **Mandatory run variables** | |
+| **Output variables** | |
+| **API reference** | |
+| **GitHub link** | |
+| **Package name** | |
+
+
+
+## Overview
+
+*What does it do in general? For example,..?*
+
+*How does it work more specifically? Are there any pitfalls to pay attention to?*
+
+*(if applicable) How is it different from this other very similar component? Which one do you choose?*
+
+## Usage
+
+*Any mandatory imports?*
+
+### On its own
+
+*Code snippet on how to run a component*
+
+### In a pipeline
+
+*Code snippet of a component being introduced in a pipeline*
+
+*There can be more than one example. Add examples of pipelines where this component would be most useful, for example RAG, doc retrieval, etc.*
diff --git a/docs-website/versioned_docs/version-2.29-unstable/_templates/document-store-template.mdx b/docs-website/versioned_docs/version-2.29-unstable/_templates/document-store-template.mdx
new file mode 100644
index 0000000000..6418824a44
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/_templates/document-store-template.mdx
@@ -0,0 +1,30 @@
+---
+title: "Document Store Name"
+id: "document-store-name"
+description: "A short description of the document store"
+slug: "/document-store-name"
+---
+
+# Document Store Name
+
+## Description
+
+*What are this Document Store features? When would a user select it, and when not?*
+
+*Are there any limitations?*
+
+*Users are often curious to know if a document store supports metadata filtering and sparse vectors.*
+
+## Initialization
+
+*Describe how to get this Document Store to work, with code samples.*
+
+## Supported Retrievers
+
+*Name of the supported Retriever(s).*
+
+*If several – describe how to choose an appropriate one for user’s goals (perhaps, one is faster and the other is more accurate).*
+
+## Link to GitHub
+
+*for example [https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/gradient](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/gradient)*
diff --git a/docs-website/versioned_docs/version-2.29-unstable/concepts/agents.mdx b/docs-website/versioned_docs/version-2.29-unstable/concepts/agents.mdx
new file mode 100644
index 0000000000..05adf2955d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/concepts/agents.mdx
@@ -0,0 +1,121 @@
+---
+title: "Agents"
+id: agents
+slug: "/agents"
+description: "This page explains how to create an AI agent in Haystack capable of retrieving information, generating responses, and taking actions using various Haystack components."
+---
+
+# Agents
+
+This page explains how to create an AI agent in Haystack capable of retrieving information, generating responses, and taking actions using various Haystack components.
+
+## What’s an AI Agent?
+
+An AI agent is a system that can:
+
+- Understand user input (text, image, audio, and other queries),
+- Retrieve relevant information (documents or structured data),
+- Generate intelligent responses (using LLMs like OpenAI or Hugging Face models),
+- Perform actions (calling APIs, fetching live data, executing functions).
+
+AI agents are autonomous systems that use large language models (LLMs) to make decisions and solve complex tasks.
+They interact with their environment using tools, memory, and reasoning.
+An AI agent is more than a chatbot — it actively plans, chooses the right tools, and executes tasks to achieve a goal.
+Unlike traditional software, it adapts to new information and refines its process as needed.
+
+1. **LLM as the Brain**: The agent’s core is an LLM, which understands context, processes natural language and serves as the central intelligence system.
+2. **Tools for Interaction**: Agents connect to external tools, APIs, and databases to gather information and take action.
+3. **Memory for Context**: Short-term memory helps track conversations, while long-term memory stores knowledge for future interactions.
+4. **Reasoning and Planning**: Agents break down complex problems, come up with step-by-step action plans, and adapt based on new data and feedback.
+
+An AI agent starts with a prompt that defines its role and objectives.
+It decides when to use tools, gathers data, and refines its approach through loops of reasoning and action.
+For example, a customer service agent answers queries using a database — if it lacks an answer, it fetches real-time data, summarizes it, and responds.
+A coding assistant understands project requirements, suggests solutions, and writes code.
+
+## Key Components
+
+### Agent Component
+
+Haystack has a built-in [Agent](../pipeline-components/agents-1/agent.mdx) component that manages the full tool-calling loop — it calls the LLM, invokes tools, updates state, and continues until a stopping condition is met.
+Key capabilities include:
+
+- **State management**: Share typed data between tools, accumulate results across iterations, and surface them in the result dict using `state_schema`. See [State](../pipeline-components/agents-1/state.mdx).
+- **Streaming**: Stream token-by-token output with a `streaming_callback`.
+- **Human-in-the-loop**: Intercept tool calls for human review before execution. See [Human in the Loop](../pipeline-components/agents-1/human-in-the-loop.mdx).
+- **Multi-agent systems**: Wrap an `Agent` as a `ComponentTool` to build coordinator/specialist architectures. See [Multi-Agent Systems](./agents/multi-agent-systems.mdx).
+- **MCP server exposure**: Expose your agent as an MCP server using [Hayhooks](../development/hayhooks.mdx), making it callable from any MCP-compatible client such as Claude Desktop or Cursor.
+- **Multimodal inputs**: Pass images alongside text using `ImageContent` in `ChatMessage` content parts, or return `ImageContent` from tools for dynamic image analysis. Requires a vision-capable model such as `gpt-5` or `gemini-2.5-flash`. See [Multimodal Inputs](../pipeline-components/agents-1/agent.mdx#multimodal-inputs).
+
+Check out the [Agent](../pipeline-components/agents-1/agent.mdx) documentation, or the [example](#tool-calling-agent) below to get started.
+
+### State
+
+[`State`](../pipeline-components/agents-1/state.mdx) is Haystack's built-in mechanism for sharing data between tools and accumulating results across multiple tool calls.
+You define a `state_schema` on the `Agent`, and any keys declared there are returned alongside `messages` and `last_message` in the agent's result dict.
+
+### Tools
+
+Haystack provides several ways to create and manage tools:
+
+- [`Tool`](../tools/tool.mdx) class / [`@tool`](../tools/tool.mdx#tool-decorator) decorator – Define a tool from a Python function. The `@tool` decorator automatically uses the function's name and docstring; the `Tool` class gives full control over the name, description, and schema.
+- [`ComponentTool`](../tools/componenttool.mdx) – Wraps any Haystack component as a callable tool.
+- [`PipelineTool`](../tools/pipelinetool.mdx) – Wraps a full Haystack pipeline as a callable tool.
+- [`MCPTool`](../tools/mcptool.mdx) / [`MCPToolset`](../tools/mcptoolset.mdx) – Connects to Model Context Protocol (MCP) servers to load external tools.
+- [`Toolset`](../tools/toolset.mdx) – Groups multiple tools into a single unit to pass to an Agent or Generator.
+- [`SearchableToolset`](../tools/searchabletoolset.mdx) – Enables keyword-based tool discovery for large catalogs, so the LLM only sees relevant tools at each step.
+
+## Example
+
+### Tool-Calling Agent
+
+Create a tool-calling agent with the `Agent` component. This example requires `OPENAI_API_KEY` and `SERPERDEV_API_KEY` to be set as environment variables:
+
+```shell
+export OPENAI_API_KEY=
+
+
+## Coordinator / Specialist Pattern
+
+The coordinator/specialist pattern cleanly splits responsibilities: the coordinator handles planning and delegation, while each specialist owns a focused toolset and a targeted system prompt.
+
+This is also a form of **context engineering**: deliberately controlling what each agent sees.
+A specialist accumulates its own tool call trace, but the coordinator only needs the final answer.
+Returning just `result["last_message"].text` (with `@tool`) or using `outputs_to_string` (with `ComponentTool`) surfaces only the specialist's final reply, keeping the coordinator's context lean.
+
+When covering multiple topics, the coordinator can call the same specialist tool several times in a single response.
+All tool calls from one LLM response are executed concurrently using a thread pool.
+Control the level of parallelism with `max_workers` in `tool_invoker_kwargs` (default: `4`).
+
+The example below asks the coordinator about two topics: it calls `research` twice and both specialists run in parallel.
+
+`HTMLToDocument` uses [Trafilatura](https://trafilatura.readthedocs.io) to extract clean text from HTML pages.
+Install it before running:
+
+```shell
+pip install trafilatura
+```
+
+```python
+from typing import Annotated
+from haystack.components.agents import Agent
+from haystack.components.converters import HTMLToDocument
+from haystack.components.fetchers.link_content import LinkContentFetcher
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.dataclasses import ChatMessage
+from haystack.tools import ComponentTool, tool
+from haystack.utils import Secret
+
+
+search_tool = ComponentTool(
+ component=SerperDevWebSearch(
+ api_key=Secret.from_env_var("SERPERDEV_API_KEY"),
+ top_k=3,
+ ),
+ name="web_search",
+ description="Search the web for current information on any topic",
+)
+
+
+@tool
+def fetch_page(url: Annotated[str, "The URL of the web page to fetch"]) -> str:
+ """Fetch the content of a web page given its URL."""
+ try:
+ streams = LinkContentFetcher().run(urls=[url])["streams"]
+ if not streams:
+ return "No content found."
+ documents = HTMLToDocument().run(sources=streams)["documents"]
+ return documents[0].content if documents else "No content extracted."
+ except Exception as e:
+ return f"Failed to fetch page: {e}"
+
+
+research_agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[search_tool, fetch_page],
+ system_prompt=(
+ "You are a research specialist. Search the web to find relevant pages, "
+ "then fetch their full content for detailed information. "
+ "Return a concise summary of your findings in 3-5 sentences."
+ ),
+)
+
+
+@tool
+def research(query: Annotated[str, "The research question to investigate"]) -> str:
+ """Research a topic and return a summary of findings."""
+ try:
+ result = research_agent.run(messages=[ChatMessage.from_user(query)])
+ return result["last_message"].text
+ except Exception as e:
+ return f"Research failed: {e}"
+
+
+coordinator = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[research],
+ system_prompt=(
+ "You are a coordinator. Delegate research tasks to the research tool. "
+ "For questions covering multiple topics, research each one independently. "
+ "Keep your final answer concise."
+ ),
+ streaming_callback=print_streaming_chunk,
+ tool_invoker_kwargs={"max_workers": 4}, # run up to 4 specialist calls in parallel
+)
+
+result = coordinator.run(
+ messages=[
+ ChatMessage.from_user(
+ "What are the latest developments in large language models and retrieval-augmented generation?",
+ ),
+ ],
+)
+```
+
+## Additional References
+
+📖 Related docs:
+
+- [Agent](../../pipeline-components/agents-1/agent.mdx)
+- [State](../../pipeline-components/agents-1/state.mdx)
+- [ComponentTool](../../tools/componenttool.mdx)
+
+📚 Tutorials:
+
+- [Creating a Multi-Agent System](https://haystack.deepset.ai/tutorials/45_creating_a_multi_agent_system)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/concepts/components.mdx b/docs-website/versioned_docs/version-2.29-unstable/concepts/components.mdx
new file mode 100644
index 0000000000..d067ad5e03
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/concepts/components.mdx
@@ -0,0 +1,59 @@
+---
+title: "Components"
+id: components
+slug: "/components"
+description: "Components are the building blocks of a pipeline. They perform tasks such as preprocessing, retrieving, or summarizing text while routing queries through different branches of a pipeline. This page is a summary of all component types available in Haystack."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# Components
+
+Components are the building blocks of a pipeline. They perform tasks such as preprocessing, retrieving, or summarizing text while routing queries through different branches of a pipeline. This page is a summary of all component types available in Haystack.
+
+Components are connected to each other using a [pipeline](pipelines.mdx), and they function like building blocks that can be easily switched out for each other. A component can take the selected outputs of other components as input. You can also provide input to a component when you call `pipeline.run()`.
+
+## Stand-Alone or In a Pipeline
+
+You can integrate components in a pipeline to perform a specific task. But you can also use some of them stand-alone, outside of a pipeline. For example, you can run `DocumentWriter` on its own, to write documents into a Document Store. To check how to use a component and if it's usable outside of a pipeline, check the _Usage_ section on the component's documentation page.
+
+Each component has a `run()` method. When you connect components in a pipeline, and you run the pipeline by calling `Pipeline.run()`, it invokes the `run()` method for each component sequentially.
+
+## Input and Output
+
+To connect components in a pipeline, you need to know the names of the inputs and outputs they accept. The output of one component must be compatible with the input the subsequent component accepts. For example, to connect Retriever and Ranker in a pipeline, you must know that the Retriever outputs `documents` and the Ranker accepts `documents` as input.
+
+The mandatory inputs and outputs are listed in a table at the top of each component's documentation page so that you can quickly check them:
+View YAML
+ +```yaml +components: + coordinator: + init_parameters: + chat_generator: + init_parameters: + api_base_url: null + api_key: + env_vars: + - OPENAI_API_KEY + strict: true + type: env_var + generation_kwargs: {} + http_client_kwargs: null + max_retries: null + model: gpt-5.4-nano + organization: null + streaming_callback: null + timeout: null + tools: null + tools_strict: false + type: haystack.components.generators.chat.openai.OpenAIChatGenerator + confirmation_strategies: null + exit_conditions: + - text + max_agent_steps: 100 + raise_on_tool_invocation_failure: false + required_variables: null + state_schema: {} + streaming_callback: null + system_prompt: You are a coordinator. Delegate research tasks to the research + specialist. Keep your final answer concise. + tool_invoker_kwargs: null + tools: + - data: + component: + init_parameters: + chat_generator: + init_parameters: + api_base_url: null + api_key: + env_vars: + - OPENAI_API_KEY + strict: true + type: env_var + generation_kwargs: {} + http_client_kwargs: null + max_retries: null + model: gpt-5.4-nano + organization: null + streaming_callback: null + timeout: null + tools: null + tools_strict: false + type: haystack.components.generators.chat.openai.OpenAIChatGenerator + confirmation_strategies: null + exit_conditions: + - text + max_agent_steps: 100 + raise_on_tool_invocation_failure: false + required_variables: null + state_schema: {} + streaming_callback: null + system_prompt: You are a research specialist. Search the web to find + information. Return a concise summary of your findings in 3-5 sentences. + tool_invoker_kwargs: null + tools: + - data: + component: + init_parameters: + allowed_domains: null + api_key: + env_vars: + - SERPERDEV_API_KEY + strict: true + type: env_var + exclude_subdomains: false + search_params: {} + top_k: 3 + type: haystack.components.websearch.serper_dev.SerperDevWebSearch + description: Search the web for current information on any topic + inputs_from_state: null + name: web_search + outputs_to_state: null + outputs_to_string: null + parameters: null + type: haystack.tools.component_tool.ComponentTool + user_prompt: null + type: haystack.components.agents.agent.Agent + description: A specialist that researches topics on the web + inputs_from_state: null + name: research_specialist + outputs_to_state: null + outputs_to_string: + source: last_message + parameters: null + type: haystack.tools.component_tool.ComponentTool + user_prompt: null + type: haystack.components.agents.agent.Agent +connection_type_validation: true +connections: [] +max_runs_per_component: 100 +metadata: {} +``` + +
+
+| | |
+| --- | --- |
+| Type | Best for |
+| Vector libraries | Managing hardware resources effectively. |
+| Pure vector DBs | Managing lots of high-dimensional data. |
+| Vector-capable SQL DBs | Lower maintenance costs with focus on structured data and less on vectors. |
+| Vector-capable NoSQL DBs | Combining vectors with structured data without the limitations of the traditional relational model. |
+| Full-text search DBs | Superior full-text search, reliable for production. |
+| In-memory | Fast, minimal prototypes on small datasets. |
+
+
+
+#### Vector libraries
+
+Vector libraries are often included in the “vector database” category improperly, as they are limited to handling only vectors, are designed to work in-memory, and normally don’t have a clean way to store data on disk. Still, they are the way to go every time performance and speed are the top requirements for your AI application, as these libraries can use hardware resources very effectively.
+
+:::warning[In progress]
+
+We are currently developing the support for vector libraries in Haystack.
+:::
+
+#### Pure vector databases
+
+Pure vector databases, also known as just “vector databases”, offer efficient similarity search capabilities through advanced indexing techniques. Most of them support metadata, and despite a recent trend to add more text-search features on top of it, you should consider pure vector databases closer to vector libraries than a regular database. Pick a pure vector database when your application needs to manage huge amounts of high-dimensional data effectively: they are designed to be highly scalable and highly available. Most are open source, but companies usually provide them “as a service” through paid subscriptions.
+
+- [Chroma](../../document-stores/chromadocumentstore.mdx)
+- [Pinecone](../../document-stores/pinecone-document-store.mdx)
+- [Qdrant](../../document-stores/qdrant-document-store.mdx)
+- [Weaviate](../../document-stores/weaviatedocumentstore.mdx)
+- [Milvus](https://haystack.deepset.ai/integrations/milvus-document-store) (external integration)
+
+#### Vector-capable SQL databases
+
+This category is relatively small but growing fast and includes well-known relational databases where vector capabilities were added through plugins or extensions. They are not as performant as the previous categories, but the main advantage of these databases is the opportunity to easily combine vectors with structured data, having a one-stop data shop for your application. You should pick a vector-capable SQL database when the performance trade-off is paid off by the lower cost of maintaining a single database instance for your application or when the structured data plays a more fundamental role in your business logic, with vectors being more of a nice-to-have.
+
+- [Pgvector](../../document-stores/pgvectordocumentstore.mdx)
+
+#### Vector-capable NoSQL databases
+
+Historically, the killer features of NoSQL databases were the ability to scale horizontally and the adoption of a flexible data model to overcome certain limitations of the traditional relational model. This stays true for databases in this category, where the vector capabilities are added on top of the existing features. Similarly to the previous category, vector support might not be as good as pure vector databases, but once again, there is a tradeoff that might be convenient to bear depending on the use case. For example, if a certain NoSQL database is already part of the stack of your application and a lower performance is not a show-stopper, you might give it a shot.
+
+- [Astra](../../document-stores/astradocumentstore.mdx)
+- [MongoDB](../../document-stores/mongodbatlasdocumentstore.mdx)
+- [Neo4j](https://haystack.deepset.ai/integrations/neo4j-document-store) (external)
+
+#### Full-text search databases
+
+The main advantage of full-text search databases is they are already designed to work with text, so you can expect a high level of support for text data along with good performance and the opportunity to scale both horizontally and vertically. Initially, vector capabilities were subpar and provided through plugins or extensions, but this is rapidly changing. You can see how the market leaders in this category have recently added first-class support for vectors. Pick a full-text search database if text data plays a central role in your business logic so that you can easily and effectively implement techniques like hybrid search with a good level of support for similarity search and state-of-the-art support for full-text search.
+
+- [Elasticsearch](../../document-stores/elasticsearch-document-store.mdx)
+- [OpenSearch](../../document-stores/opensearch-document-store.mdx)
+
+#### The in-memory Document Store
+
+Haystack ships with an ephemeral document store that relies on pure Python data structures stored in memory, so it doesn’t fall into any of the vector database categories above. This special Document Store is ideal for creating quick prototypes with small datasets. It doesn’t require any special setup, and it can be used right away without installing additional dependencies.
+
+- [InMemory](../../document-stores/inmemorydocumentstore.mdx)
+
+### Final considerations
+
+It can be very challenging to pick one vector database over another by only looking at pure performance, as even the slightest difference in the benchmark can produce a different leaderboard (for example, some benchmarks test the cloud services while others work on a reference machine). Thinking about including features like filtering or not can bring in a whole new set of complexities that make the comparison even harder.
+
+What’s important for you to know is that the Document Store interface doesn’t add much to the costs, and the relative performance of one vector database over another should stay the same when used within Haystack pipelines.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/concepts/document-store/creating-custom-document-stores.mdx b/docs-website/versioned_docs/version-2.29-unstable/concepts/document-store/creating-custom-document-stores.mdx
new file mode 100644
index 0000000000..d00579b620
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/concepts/document-store/creating-custom-document-stores.mdx
@@ -0,0 +1,174 @@
+---
+title: "Creating Custom Document Stores"
+id: creating-custom-document-stores
+slug: "/creating-custom-document-stores"
+description: "Create your own Document Stores to manage your documents."
+---
+
+# Creating Custom Document Stores
+
+Create your own Document Stores to manage your documents.
+
+Custom Document Stores are resources that you can build and leverage in situations where a ready-made solution is not available in Haystack. For example:
+
+- You’re working with a vector store that’s not yet supported in Haystack.
+- You need a very specific retrieval strategy to search for your documents.
+- You want to customize the way Haystack reads and writes documents.
+
+Similar to [custom components](../components/custom-components.mdx), you can use a custom Document Store in a Haystack pipeline as long as you can import its code into your Python program. The best practice is distributing a custom Document Store as a standalone integration package.
+
+## Recommendations
+
+Before you start, there are a few recommendations we provide to ensure a custom Document Store behaves consistently with the rest of the Haystack ecosystem. At the end of the day, a Document Store is just Python code written in a way that Haystack can understand, but the way you name it, organize it, and distribute it can make a difference. None of these recommendations are mandatory, but we encourage you to follow as many as you can.
+
+### Naming Convention
+
+We recommend naming your Document Store following the format `+
+
+
+
+```python
+from haystack import Pipeline
+from haystack.components.converters import HTMLToDocument, TextFileToDocument
+from haystack.components.routers import FileTypeRouter
+from haystack.components.writers import DocumentWriter
+from haystack.dataclasses import ByteStream
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+sources = [
+ ByteStream.from_string(text="Text file content", mime_type="text/plain"),
+ ByteStream.from_string(
+ text="Some content",
+ mime_type="text/html",
+ ),
+]
+
+doc_store = InMemoryDocumentStore()
+
+pipe = Pipeline()
+pipe.add_component("router", FileTypeRouter(mime_types=["text/plain", "text/html"]))
+pipe.add_component("txt_converter", TextFileToDocument())
+pipe.add_component("html_converter", HTMLToDocument())
+pipe.add_component("writer", DocumentWriter(doc_store))
+pipe.connect("router.text/plain", "txt_converter.sources")
+pipe.connect("router.text/html", "html_converter.sources")
+pipe.connect("txt_converter.documents", "writer.documents")
+pipe.connect("html_converter.documents", "writer.documents")
+
+result = pipe.run({"router": {"sources": sources}})
+```
+
+This pattern is especially useful when routing files, documents, or results across multiple parallel branches.
+
+## Flexible Type Connections
+
+To further streamline pipeline definitions, Haystack pipelines support limited implicit type adaptation at connection time.
+This makes pipeline connections more flexible and reduces the need for `OutputAdapter` components.
+
+**Supported adaptations**
+
+| Source Type | Target Type | Behavior |
+|--------------------------|--------------------|---------------------------------------------------------------|
+| `str` | `ChatMessage` | Wrapped into a `ChatMessage` with user role. |
+| `ChatMessage` | `str` | Extracts `ChatMessage.text`; raises `PipelineRuntimeError` if `None`. |
+| `T` | `list[T]` | Wraps the item into a single-element list. |
+| `list[str] or list[ChatMessage]`| `str` or `ChatMessage` | Extracts the first item; raises `PipelineRuntimeError` if the list is empty. |
+
+
+All adaptations are checked at connection time to ensure type safety, but applied at runtime during pipeline execution.
+
+When multiple connections are possible, strict type matching is prioritized over implicit conversion.
+This preserves backward compatibility with earlier versions of Haystack, where flexible type connections were not supported.
+
+### Example
+
+Pipeline connecting the Chat Generator `messages` output (`list[ChatMessage]`) to the retriever `query` input (`str`)
+without using an `OutputAdapter`:
+
+```python
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.dataclasses import Document
+from haystack.components.retrievers import InMemoryBM25Retriever
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+document_store = InMemoryDocumentStore()
+
+documents = [
+ Document(content="Bob lives in Paris."),
+ Document(content="Alice lives in London."),
+ Document(content="Ivy lives in Melbourne."),
+ Document(content="Kate lives in Brisbane."),
+ Document(content="Liam lives in Adelaide."),
+]
+
+document_store.write_documents(documents)
+
+template = """{% message role="user" %}
+Rewrite the following query to be used for keyword search.
+{{ query }}
+{% endmessage %}
+"""
+
+p = Pipeline()
+p.add_component("prompt_builder", ChatPromptBuilder(template=template))
+p.add_component("llm", OpenAIChatGenerator(model="gpt-4.1-mini"))
+p.add_component(
+ "retriever",
+ InMemoryBM25Retriever(document_store=document_store, top_k=3),
+)
+
+p.connect("prompt_builder", "llm")
+# implicitly converts list[ChatMessage] -> str
+p.connect("llm", "retriever")
+
+query = """Someday I'd love to visit Brisbane, but for now I just want
+to know the names of the people who live there."""
+
+result = p.run(data={"prompt_builder": {"query": query}})
+```
+
+## When You Still Need `Joiners` or `OutputAdapters`
+
+Explicit `Joiners` or `OutputAdapters` are still useful when you need:
+
+- Custom aggregation logic beyond simple list concatenation
+- Type conversions not covered by implicit adaptation
+- Explicit control over formatting or ordering
+
+Smart connections reduce the need for glue components, but they do not remove them entirely.
+When in doubt, explicit components provide clarity and more control.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/concepts/pipelines/visualizing-pipelines.mdx b/docs-website/versioned_docs/version-2.29-unstable/concepts/pipelines/visualizing-pipelines.mdx
new file mode 100644
index 0000000000..0d5c0cd5fe
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/concepts/pipelines/visualizing-pipelines.mdx
@@ -0,0 +1,88 @@
+---
+title: "Visualizing Haystack Pipelines"
+id: visualizing-pipelines
+slug: "/visualizing-pipelines"
+description: "You can visualize your Haystack AI pipelines as graphs to better understand how the components are connected."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# Visualizing Haystack Pipelines
+
+You can visualize your pipelines as graphs to better understand how the components are connected.
+
+Haystack pipelines have `draw()` and `show()` methods that enable you to visualize the pipeline as a graph using Mermaid graphs.
+
+:::note[Data Privacy Notice]
+
+Exercise caution with sensitive data when using pipeline visualization.
+
+This feature is based on Mermaid graphs web service that doesn't have clear terms of data retention or privacy policy.
+:::
+
+## Prerequisites
+
+To use Mermaid graphs, you must have an internet connection to reach the Mermaid graph renderer at https://mermaid.ink.
+
+## Displaying a Graph
+
+Use the pipeline's `show()` method to display the diagram in Jupyter notebooks.
+
+```python
+my_pipeline.show()
+```
+
+## Saving a Graph
+
+Use the pipeline's `draw()` method passing the path where you want to save the diagram and the diagram format. Possible formats are: `mermaid-text` and `mermaid-image` (default).
+
+```python
+my_pipeline.draw(path=local_path)
+```
+
+## Visualizing SuperComponents
+
+To show the internal structure of [SuperComponents](../components/supercomponents.mdx) in your digram instead of a black box component, set the `super_component_expansion` parameter to `True`:
+
+```python
+my_pipeline.show(super_component_expansion=True)
+
+## or
+
+my_pipeline.draw(path=local_path, super_component_expansion=True)
+```
+
+## Visualizing Locally
+
+If you don't have an internet connection or don't want to send your pipeline data to the remote https://mermaid.ink, you can install a local mermaid.ink server and use it to render your pipeline.
+
+Let's run a local mermaid.ink server using their official Docker images from https://github.com/jihchi/mermaid.ink/pkgs/container/mermaid.ink.
+
+In this case, let's install one for a system running a MacOS M3 chip and expose it on port 3000:
+
+```dockerfile
+docker run --platform linux/amd64 --publish 3000:3000 --cap-add=SYS_ADMIN ghcr.io/jihchi/mermaid.ink
+```
+
+Check that the local mermaid.ink server is running by going to http://localhost:3000/.
+
+You should see a local server running, and now you can simply render the image using your local mermaid.ink server by specifying the URL when calling the`show()`or `draw()` method:
+
+```python
+my_pipeline.show(server_url="http://localhost:3000")
+## or
+my_pipeline.draw("my_pipeline.png", server_url="http://localhost:3000")
+```
+
+## Example
+
+This is an example of what a pipeline graph may look like:
+Expand to see the pipeline graph
++ +## Importing a Pipeline to Haystack Enterprise Platform + +You can import your Haystack pipeline into Haystack Enterprise Platform and continue visually building your pipeline + +To do that, follow the steps described in Haystack Enterprise Platform [documentation](https://docs.cloud.deepset.ai/docs/import-a-pipeline#import-your-pipeline). diff --git a/docs-website/versioned_docs/version-2.29-unstable/concepts/secret-management.mdx b/docs-website/versioned_docs/version-2.29-unstable/concepts/secret-management.mdx new file mode 100644 index 0000000000..288ea8367e --- /dev/null +++ b/docs-website/versioned_docs/version-2.29-unstable/concepts/secret-management.mdx @@ -0,0 +1,195 @@ +--- +title: "Secret Management" +id: secret-management +slug: "/secret-management" +description: "This page emphasizes secret management in Haystack components and introduces the `Secret` type for structured secret handling. It explains the drawbacks of hard-coding secrets in code and suggests using environment variables instead." +--- + +# Secret Management + +This page emphasizes secret management in Haystack components and introduces the `Secret` type for structured secret handling. It explains the drawbacks of hard-coding secrets in code and suggests using environment variables instead. + +Many Haystack components interact with third-party frameworks and service providers such as Azure, Google Vertex AI, and OpenAI. Their libraries often require the user to authenticate themselves to ensure they receive access to the underlying product. The authentication process usually works with a secret value that acts as an opaque identifier to the third-party backend. + +This page describes the two main types of secrets: token-based and environment variable-based, and how to handle them when using Haystack. + +You can find additional details for the `Secret` class in our [API reference](/reference/utils-api). + +
+
+
+
+### Import
+
+To use Haystack secrets within the code, first import with:
+
+```python
+from haystack.utils import Secret
+```
+
+### Token-Based Secrets
+
+You can paste tokens directly as a string using the `from_token` method:
+
+```python
+llm = OpenAIGenerator(api_key=Secret.from_token("sk-randomAPIkeyasdsa32ekasd32e"))
+```
+
+Note that this type of code cannot be serialized, meaning you can't convert the above component to a dictionary or save a pipeline containing it to a YAML file. This is a security feature to prevent accidental exposure of sensitive data.
+
+### Environment Variable-Based Secrets
+
+Environment variable-based secrets are more flexible. They allow you to specify one or more environment variables that may contain your secret.
+
+Existing Haystack components that require an API Key (like OpenAIGenerator) have a default value for `Secret.from_env_var` (in this case, `OPENAI_API_KEY`). This means that the `OpenAIGenerator` will look for the value of the environment variable `OPENAI_API_KEY` (if it exists) and use it for authentication. And when pipelines are serialized to YAML, only the name of the environment variable is save to the YAML file. In doing so, this method ensures that there are no security leaks and is therefore strongly recommended.
+
+```bash
+## First, export an environment variable name `OPENAI_API_KEY` with its value
+export OPENAI_API_KEY=sk-randomAPIkeyasdsa32ekasd32e
+
+## or alternatively, using Python
+## import os
+## os.environ[”OPENAI_API_KEY”]=sk-randomAPIkeyasdsa32ekasd32e
+```
+
+```python
+llm_generator = (
+ OpenAIGenerator()
+) # Uses the default value from the env var for the component
+```
+
+Alternatively, in components where a Secret is expected, you can customize the name of the environment variable from which the API Key is to be read.
+
+```python
+## Export an environment variable with custom name and its value
+llm_generator = OpenAIGenerator(api_key=Secret.from_env_var("YOUR_ENV_VAR"))
+```
+
+When `OpenAIGenerator` is serialized within a pipeline, this is what the YAML code will look like, using the custom variable name:
+
+```yaml
+components:
+ llm:
+ init_parameters:
+ api_base_url: null
+ api_key:
+ env_vars:
+ - YOUR_ENV_VAR
+ strict: true
+ type: env_var
+ generation_kwargs: {}
+ model: gpt-4o-mini
+ organization: null
+ streaming_callback: null
+ system_prompt: null
+ type: haystack.components.generators.openai.OpenAIGenerator
+ ...
+```
+
+### Serialization
+
+While token-based secrets cannot be serialized, environment variable-based secrets can be converted to and from dictionaries:
+
+```python
+## Convert to dictionary
+env_secret_dict = env_secret.to_dict()
+
+## Create from dictionary
+new_env_secret = Secret.from_dict(env_secret_dict)
+```
+
+### Resolving Secrets
+
+Both types of secrets can be resolved to their actual values using the `resolve_value` method. This method returns the token or the value of the environment variable.
+
+```python
+## Resolve the token-based secret
+token_value = api_key_secret.resolve_value()
+
+## Resolve the environment variable-based secret
+env_value = env_secret.resolve_value()
+```
+
+### Custom Component Example
+
+Here is a complete example that shows how to create a component that uses the `Secret` class in Haystack, highlighting the differences between token-based and environment variable-based authentication, and showing that token-based secrets cannot be serialized:
+
+```python
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+@component
+class MyComponent:
+ def __init__(self, api_key: Optional[Secret] = None, **kwargs):
+ self.api_key = api_key
+ self.backend = None
+
+ def warm_up(self):
+ # Call resolve_value to yield a single result. The semantics of the result is policy-dependent.
+ # Currently, all supported policies will return a single string token.
+ self.backend = SomeBackend(
+ api_key=self.api_key.resolve_value() if self.api_key else None, ...
+ )
+
+ def to_dict(self):
+ # Serialize the policy like any other (custom) data. If the policy is token-based, it will
+ # raise an error.
+ return default_to_dict(
+ self, api_key=self.api_key.to_dict() if self.api_key else None, ...
+ )
+
+ @classmethod
+ def from_dict(cls, data):
+ # Deserialize the policy data before passing it to the generic from_dict function.
+ api_key_data = data["init_parameters"]["api_key"]
+ api_key = Secret.from_dict(api_key_data) if api_key_data is not None else None
+ data["init_parameters"]["api_key"] = api_key
+ # Alternatively, use the helper function.
+ # deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+ return default_from_dict(cls, data)
+
+## No authentication.
+component = MyComponent(api_key=None)
+
+## Token based authentication
+component = MyComponent(api_key=Secret.from_token("sk-randomAPIkeyasdsa32ekasd32e"))
+component.to_dict() # Error! Can't serialize authentication tokens
+
+## Environment variable based authentication
+component = MyComponent(api_key=Secret.from_env_var("OPENAI_API_KEY"))
+component.to_dict() # This is fine
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/development/deployment.mdx b/docs-website/versioned_docs/version-2.29-unstable/development/deployment.mdx
new file mode 100644
index 0000000000..1e9ef32e13
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/development/deployment.mdx
@@ -0,0 +1,36 @@
+---
+title: "Deployment"
+id: deployment
+slug: "/deployment"
+description: "Deploy your Haystack pipelines through various services such as Docker, Kubernetes, Ray, or a variety of Serverless options."
+---
+
+# Deployment
+
+Deploy your Haystack pipelines through various services such as Docker, Kubernetes, Ray, or a variety of Serverless options.
+
+As a framework, Haystack is typically integrated into a variety of applications and environments, and there is no single, specific deployment strategy to follow. However, it is very common to make Haystack pipelines accessible through a service that can be easily called from other software systems.
+
+These guides focus on tools and techniques that can be used to run Haystack pipelines in common scenarios. While these suggestions should not be considered the only way to do so, they should provide inspiration and the ability to customize them according to your needs.
+
+### Guides
+
+Here are the currently available guides on Haystack pipeline deployment:
+
+- [Deploying with Docker](deployment/docker.mdx)
+- [Deploying with Kubernetes](deployment/kubernetes.mdx)
+- [Deploying with OpenShift](deployment/openshift.mdx)
+
+### Hayhooks
+
+Haystack can be easily integrated into any HTTP application, but if you don’t have one, you can use Hayhooks, a ready-made application that serves Haystack pipelines as REST endpoints. We’ll be using Hayhooks throughout this guide to streamline the code examples. Refer to the Hayhooks [overview](hayhooks.mdx) for a quick start, or the [official Hayhooks documentation](https://deepset-ai.github.io/hayhooks/) for comprehensive guides and reference.
+
+:::note[Looking to scale with confidence?]
+
+If your team needs **enterprise-grade support, best practices, and deployment guidance** to run Haystack in production, check out **Haystack Enterprise Starter**.
+
+📜 [Learn more about Haystack Enterprise Starter](https://haystack.deepset.ai/blog/announcing-haystack-enterprise)
+🤝 [Get in touch with our team](https://www.deepset.ai/products-and-services/haystack-enterprise-starter)
+
+👉 For platform tooling to **manage data, pipelines, testing, and governance at scale**, explore the [Haystack Enterprise Platform](https://www.deepset.ai/products-and-services/haystack-enterprise-platform).
+:::
diff --git a/docs-website/versioned_docs/version-2.29-unstable/development/deployment/docker.mdx b/docs-website/versioned_docs/version-2.29-unstable/development/deployment/docker.mdx
new file mode 100644
index 0000000000..76312f4cd7
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/development/deployment/docker.mdx
@@ -0,0 +1,117 @@
+---
+title: "Docker"
+id: docker
+slug: "/docker"
+description: "Learn how to deploy your Haystack pipelines through Docker starting from the basic Docker container to a complex application using Hayhooks."
+---
+
+# Docker
+
+Learn how to deploy your Haystack pipelines through Docker starting from the basic Docker container to a complex application using Hayhooks.
+
+## Running Haystack in Docker
+
+The most basic form of Haystack deployment happens through Docker containers. Becoming familiar with running and customizing Haystack Docker images is useful as they form the basis for more advanced deployment.
+
+Haystack releases are officially distributed through the [`deepset/haystack`](https://hub.docker.com/r/deepset/haystack) Docker image. Haystack images come in different flavors depending on the specific components they ship and the Haystack version.
+
+:::info
+At the moment, the only flavor available for Haystack is `base`, which ships exactly what you would get by installing Haystack locally with `pip install haystack-ai`.
+:::
+
+You can pull a specific Haystack flavor using Docker tags: for example, to pull the image containing Haystack `2.12.1`, you can run the command:
+
+```shell
+docker pull deepset/haystack:base-v2.12.1
+```
+
+Although the `base` flavor is meant to be customized, it can also be used to quickly run Haystack scripts locally without the need to set up a Python environment and its dependencies. For example, this is how you would print Haystack’s version running a Docker container:
+
+```shell
+docker run -it --rm deepset/haystack:base-v2.12.1 python -c"from haystack.version import __version__; print(__version__)"
+```
+
+## Customizing the Haystack Docker Image
+
+Chances are your application will be more complex than a simple script, and you’ll need to install additional dependencies inside the Docker image along with Haystack.
+
+For example, you might want to run a simple indexing pipeline using [Chroma](../../document-stores/chromadocumentstore.mdx) as your Document Store using a Docker container. The `base` image only contains a basic install of Haystack, but you need to install the Chroma integration (`chroma-haystack`) package additionally. The best approach would be to create a custom Docker image shipping the extra dependency.
+
+Assuming you have a `main.py` script in your current folder, the Dockerfile would look like this:
+
+```shell
+FROM deepset/haystack:base-v2.12.1
+
+RUN pip install chroma-haystack
+
+COPY ./main.py /usr/src/myapp/main.py
+
+ENTRYPOINT ["python", "/usr/src/myapp/main.py"]
+```
+
+Then you can create your custom Haystack image with:
+
+```shell
+docker build . -t my-haystack-image
+```
+
+## Complex Application with Docker Compose
+
+A Haystack application running in Docker can go pretty far: with an internet connection, the container can reach external services providing vector databases, inference endpoints, and observability features.
+
+Still, you might want to orchestrate additional services for your Haystack container locally, for example, to reduce costs or increase performance. When your application runtime depends on more than one Docker container, [Docker Compose](https://docs.docker.com/compose/) is a great tool to keep everything together.
+
+As an example, let’s say your application wraps two pipelines: one to _index_ documents into a Qdrant instance and the other to _query_ those documents at a later time. This setup would require two Docker containers: one to run the pipelines as REST APIs using [Hayhooks](../hayhooks.mdx) and a second to run a Qdrant instance. For more information on configuring Hayhooks using Docker Compose, see the [official Hayhooks documentation](https://deepset-ai.github.io/hayhooks/getting-started/quick-start-docker/).
+
+For building the Hayhooks image, we can easily customize the base image of one of the latest versions of Hayhooks, adding required dependencies required by [`QdrantDocumentStore`](../../document-stores/qdrant-document-store.mdx). The Dockerfile would look like this:
+
+```dockerfile Dockerfile
+FROM deepset/hayhooks:v1.16.0
+
+RUN pip install qdrant-haystack sentence-transformers
+
+CMD ["hayhooks", "run", "--host", "0.0.0.0"]
+
+```
+
+We wouldn’t need to customize Qdrant, so their official Docker image would work perfectly. The `docker-compose.yml` file would then look like this:
+
+```yaml
+services:
+ qdrant:
+ image: qdrant/qdrant:latest
+ restart: always
+ container_name: qdrant
+ ports:
+ - 6333:6333
+ - 6334:6334
+ expose:
+ - 6333
+ - 6334
+ - 6335
+ configs:
+ - source: qdrant_config
+ target: /qdrant/config/production.yaml
+ volumes:
+ - ./qdrant_data:/qdrant_data
+
+ hayhooks:
+ build: . # Build from local Dockerfile
+ container_name: hayhooks
+ ports:
+ - "1416:1416"
+ volumes:
+ - ./pipelines:/pipelines
+ environment:
+ - HAYHOOKS_PIPELINES_DIR=/pipelines
+ - LOG=DEBUG
+ depends_on:
+ - qdrant
+
+configs:
+ qdrant_config:
+ content: |
+ log_level: INFO
+```
+
+For a functional example of a Docker Compose deployment, check out the [“RAG indexing and querying with Elasticsearch”](https://github.com/deepset-ai/hayhooks/tree/main/examples/rag_indexing_query) example from GitHub.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/development/deployment/kubernetes.mdx b/docs-website/versioned_docs/version-2.29-unstable/development/deployment/kubernetes.mdx
new file mode 100644
index 0000000000..929ca4a99e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/development/deployment/kubernetes.mdx
@@ -0,0 +1,269 @@
+---
+title: "Kubernetes"
+id: kubernetes
+slug: "/kubernetes"
+description: "Learn how to deploy your Haystack pipelines through Kubernetes."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# Kubernetes
+
+Learn how to deploy your Haystack pipelines through Kubernetes.
+
+The best way to get Haystack running as a workload in a container orchestrator like Kubernetes is to create a service to expose one or more [Hayhooks](../hayhooks.mdx) instances.
+
+## Create a Haystack Kubernetes Service using Hayhooks
+
+As a first step, we recommend to create a local [KinD](https://github.com/kubernetes-sigs/kind) or [Minikube](https://github.com/kubernetes/minikube) Kubernetes cluster. You can manage your cluster from CLI, but tools like [k9s](https://k9scli.io/) or [Lens](https://k8slens.dev/) can ease the process.
+
+When done, start with a very simple Kubernetes Service running a single Hayhooks Pod:
+
+```yaml
+kind: Pod
+apiVersion: v1
+metadata:
+ name: hayhooks
+ labels:
+ app: haystack
+spec:
+ containers:
+ - image: deepset/hayhooks:v1.16.0
+ name: hayhooks
+ imagePullPolicy: IfNotPresent
+ resources:
+ limits:
+ memory: "512Mi"
+ cpu: "500m"
+ requests:
+ memory: "256Mi"
+ cpu: "250m"
+
+---
+
+kind: Service
+apiVersion: v1
+metadata:
+ name: haystack-service
+spec:
+ selector:
+ app: haystack
+ type: ClusterIP
+ ports:
+ # Default port used by the Hayhooks Docker image
+ - port: 1416
+
+```
+
+After applying the above to an existing Kubernetes cluster, a `hayhooks` Pod will show up as a Service called `haystack-service`.
+Example Use Case - Problem Statement
+ +### Problem Statement + +Let’s consider an example RAG pipeline that embeds a query, uses a Retriever component to locate documents relevant to the query, and then leverages an LLM to generate an answer based on the retrieved documents. + +The `OpenAIGenerator` component used in the pipeline below expects an API key to authenticate with OpenAI’s servers and perform the generation. Let’s assume that the component accepts a `str` value for it: + +```python +generator = OpenAIGenerator(model="gpt-4", api_key="sk-xxxxxxxxxxxxxxxxxx") +pipeline.add_component("generator", generator) +``` + +This works in a pinch, but this is bad practice - we shouldn’t hard-code such secrets in the codebase. An alternative would be to store the key in an environment variable externally, read from it in Python, and pass that to the component: + +```python +import os + +api_key = os.environ.get("OPENAI_API_KEY") +generator = OpenAIGenerator(model="gpt-4", api_key=api_key) +pipeline.add_component("generator", generator) +``` + +This is better – the pipeline works as intended, and we aren’t hard-coding any secrets in the code. + +Remember that pipelines are serializable. Since the API key is a secret, we should definitely avoid saving it to disk. Let’s modify the component’s `to_dict` method to exclude the key: + +```python +def to_dict(self) -> Dict[str, Any]: + # Do not pass the `api_key` init parameter. + return default_to_dict(self, model=self.model) +``` + +But what happens when the pipeline is loaded from disk? In the best-case scenario, the component’s backend will automatically try to read the key from a hard-coded environment variable, and that key is the same as the one that was passed to the component before it was serialized. But in a worse case, the backend doesn’t look up the key in a hard-coded environment variable and fails when it gets called inside a `pipeline.run()` invocation. + +
+
+| | |
+| --- | --- |
+| API reference | [ArcadeDB](/reference/integrations-arcadedb) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/arcadedb |
+
+
+
+ArcadeDB is a multi-model database that supports vector search via its LSM_VECTOR (HNSW) index. The `ArcadeDBDocumentStore` uses ArcadeDB's HTTP/JSON API for all operations—no special drivers required. It supports dense embedding retrieval and SQL-based metadata filtering.
+
+For more information, see the [ArcadeDB documentation](https://docs.arcadedb.com/).
+
+## Installation
+
+Run ArcadeDB with Docker and update the password according to your setup:
+
+```shell
+docker run -d -p 2480:2480 \
+ -e JAVA_OPTS="-Darcadedb.server.rootPassword=arcadedb" \
+ arcadedata/arcadedb:latest
+```
+
+Install the Haystack integration:
+
+```shell
+pip install arcadedb-haystack
+```
+
+## Usage
+
+Set credentials via environment variables (recommended) or pass them explicitly:
+
+```shell
+export ARCADEDB_USERNAME=root
+export ARCADEDB_PASSWORD=arcadedb
+```
+
+Initialize the document store and write documents:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore
+
+document_store = ArcadeDBDocumentStore(
+ url="http://localhost:2480",
+ database="haystack",
+ embedding_dimension=768,
+ recreate_type=True,
+)
+
+document_store.write_documents([
+ Document(content="This is first", embedding=[0.0] * 768),
+ Document(content="This is second", embedding=[0.1, 0.2, 0.3] + [0.0] * 765),
+])
+print(document_store.count_documents())
+```
+
+To learn more about the initialization parameters, see the [API docs](/reference/integrations-arcadedb#arcadedbdocumentstore).
+
+Documents without embeddings or with a different dimension are stored with a zero-padded vector so they can be written and filtered; use an [Embedder](../pipeline-components/embedders/sentencetransformersdocumentembedder.mdx) for real embeddings.
+
+### Supported Retrievers
+
+- [ArcadeDBEmbeddingRetriever](../pipeline-components/retrievers/arcadedbembeddingretriever.mdx): An embedding-based Retriever that fetches documents from the Document Store by vector similarity (HNSW).
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/astradocumentstore.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/astradocumentstore.mdx
new file mode 100644
index 0000000000..6212989c72
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/astradocumentstore.mdx
@@ -0,0 +1,82 @@
+---
+title: "AstraDocumentStore"
+id: astradocumentstore
+slug: "/astradocumentstore"
+---
+
+# AstraDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Astra](/reference/integrations-astra) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/astra |
+
+
+
+DataStax Astra DB is a serverless vector database built on Apache Cassandra, and it supports vector-based search and auto-scaling. You can deploy it on AWS, GCP, or Azure and easily expand to one or more regions within those clouds for multi-region availability, low latency data access, data sovereignty, and to avoid cloud vendor lock-in. For more information, see the [DataStax documentation](https://docs.datastax.com/en/home/docs/index.html).
+
+### Initialization
+
+Once you have an AstraDB account and have created a database, install the `astra-haystack` integration:
+
+```shell
+pip install astra-haystack
+```
+
+From the configuration in AstraDB’s web UI, you need the database ID and a generated token.
+
+You will additionally need a collection name and a namespace. When you create the collection name, you also need to set the embedding dimensions and the similarity metric. The namespace organizes data in a database and is called a keyspace in Apache Cassandra.
+
+Then, in Haystack, initialize an `AstraDocumentStore` object that’s connected to the AstraDB instance, and write documents to it.
+
+We strongly encourage passing authentication data through environment variables: make sure to populate the environment variables `ASTRA_DB_API_ENDPOINT` and `ASTRA_DB_APPLICATION_TOKEN` before running the following example.
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.astra import AstraDocumentStore
+
+document_store = AstraDocumentStore()
+
+document_store.write_documents(
+ [Document(content="This is first"), Document(content="This is second")],
+)
+print(document_store.count_documents())
+```
+
+### Supported Retrievers
+
+[AstraEmbeddingRetriever](../pipeline-components/retrievers/astraretriever.mdx): An embedding-based Retriever that fetches documents from the Document Store based on a query embedding provided to the Retriever.
+
+### Indexing Warnings
+
+When you create an Astra DB Document Store, you might see one of these warnings:
+
+> Astra DB collection `...` is detected as having indexing turned on for all fields (either created manually or by older versions of this plugin). This implies stricter limitations on the amount of text each string in a document can store. Consider indexing anew on a fresh collection to be able to store longer texts.
+
+Or:
+
+> Astra DB collection `...` is detected as having the following indexing policy: `{...}`. This does not match the requested indexing policy for this object: `{...}`. In particular, there may be stricter limitations on the amount of text each string in a document can store. Consider indexing anew on a fresh collection to be able to store longer texts.
+
+#### Why You See This Warning
+
+The collection already exists and is configured to [index all fields for search](https://docs.datastax.com/en/astra-db-serverless/api-reference/collections.html#the-indexing-option), possibly because you created it earlier or an older plugin did. When Haystack tries to create the collection, it applies an indexing policy optimized for your intended use. This policy lets you store longer texts and avoids indexing fields you won’t filter on, which also reduces write overhead.
+
+#### Common Causes
+
+1. You created the collection outside Haystack (for example, in the Astra UI or with AstraPy’s `Database.create_collection()`).
+2. You created the collection with an older version of the plugin.
+
+#### Impact
+
+This is only a warning. Your application keeps running unless you try to store very long text fields. If you do, Astra DB returns an indexing error.
+
+#### Solutions
+
+- **Recommended:** _Drop and recreate the collection_ if you can repopulate it. Then rerun your Haystack application so it creates the collection with the optimized indexing policy.
+- _Ignore the warning_ if you’re sure you won’t store very long text fields.
+
+## Additional References
+
+🧑🍳 Cookbook: [Using AstraDB as a data store in your Haystack pipelines](https://haystack.deepset.ai/cookbook/astradb_haystack_integration)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/azureaisearchdocumentstore.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/azureaisearchdocumentstore.mdx
new file mode 100644
index 0000000000..21532869c2
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/azureaisearchdocumentstore.mdx
@@ -0,0 +1,70 @@
+---
+title: "AzureAISearchDocumentStore"
+id: azureaisearchdocumentstore
+slug: "/azureaisearchdocumentstore"
+description: "A Document Store for storing and retrieval from Azure AI Search Index."
+---
+
+# AzureAISearchDocumentStore
+
+A Document Store for storing and retrieval from Azure AI Search Index.
+
+
+
+| | |
+| --- | --- |
+| **API reference** | [Azure AI Search](/reference/integrations-azure_ai_search) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_ai_search |
+
+
+
+[Azure AI Search](https://learn.microsoft.com/en-us/azure/search/search-what-is-azure-search) is an enterprise-ready search and retrieval system to build RAG-based applications on Azure, with native LLM integrations.
+
+`AzureAISearchDocumentStore` supports semantic reranking and metadata/content filtering. The Document Store is useful for various tasks such as generating knowledge base insights (catalog or document search), information discovery (data exploration), RAG, and automation.
+
+### Initialization
+
+This integration requires you to have an active Azure subscription with a deployed [Azure AI Search](https://azure.microsoft.com/en-us/products/ai-services/ai-search) service.
+
+Once you have the subscription, install the `azure-ai-search-haystack` integration:
+
+```python
+pip install azure-ai-search-haystack
+```
+
+To use the `AzureAISearchDocumentStore`, you need to provide a search service endpoint as an `AZURE_AI_SEARCH_ENDPOINT` and an API key as `AZURE_AI_SEARCH_API_KEY` for authentication. If the API key is not provided, the `DefaultAzureCredential` will attempt to authenticate you through the browser.
+
+During initialization the Document Store will either retrieve the existing search index for the given `index_name` or create a new one if it doesn't already exist. Note that one of the limitations of `AzureAISearchDocumentStore` is that the fields of the Azure search index cannot be modified through the API after creation. Therefore, any additional fields beyond the default ones must be provided as `metadata_fields` during the Document Store's initialization. However, if needed, [Azure AI portal](https://azure.microsoft.com/) can be used to modify the fields without deleting the index.
+
+It is recommended to pass authentication data through `AZURE_AI_SEARCH_API_KEY` and `AZURE_AI_SEARCH_ENDPOINT` before running the following example.
+
+```python
+from haystack_integrations.document_stores.azure_ai_search import (
+ AzureAISearchDocumentStore,
+)
+from haystack import Document
+
+document_store = AzureAISearchDocumentStore(index_name="haystack-docs")
+document_store.write_documents(
+ [
+ Document(content="This is the first document."),
+ Document(content="This is the second document."),
+ ],
+)
+print(document_store.count_documents())
+```
+
+:::info[Latency Notice]
+
+Due to Azure search index latency, the document count returned in the example might be zero if executed immediately. To ensure accurate results, be mindful of this latency when retrieving documents from the search index.
+:::
+
+You can enable semantic reranking in `AzureAISearchDocumentStore` by providing [SemanticSearch](https://learn.microsoft.com/en-us/python/api/azure-search-documents/azure.search.documents.indexes.models.semanticsearch?view=azure-python) configuration in `index_creation_kwargs` during initialization and calling it from one of the Retrievers. For more information, refer to the [Azure AI tutorial](https://learn.microsoft.com/en-us/azure/search/search-get-started-semantic) on this feature.
+
+### Supported Retrievers
+
+The Haystack Azure AI Search integration includes three Retriever components. Each Retriever leverages the Azure AI Search API and you can select the one that best suits your pipeline:
+
+- [`AzureAISearchEmbeddingRetriever`](../pipeline-components/retrievers/azureaisearchembeddingretriever.mdx): This Retriever accepts the embeddings of a single query as input and returns a list of matching documents. The query must be embedded beforehand, which can be done using an [Embedder](../pipeline-components/embedders.mdx) component.
+- [`AzureAISearchBM25Retriever`](../pipeline-components/retrievers/azureaisearchbm25retriever.mdx): A keyword-based Retriever that retrieves documents matching a query from the Azure AI Search index.
+- [`AzureAISearchHybridRetriever`](../pipeline-components/retrievers/azureaisearchhybridretriever.mdx): This Retriever combines embedding-based retrieval and keyword search to find matching documents in the search index to get more relevant results.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/chromadocumentstore.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/chromadocumentstore.mdx
new file mode 100644
index 0000000000..7fe5c144b6
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/chromadocumentstore.mdx
@@ -0,0 +1,97 @@
+---
+title: "ChromaDocumentStore"
+id: chromadocumentstore
+slug: "/chromadocumentstore"
+---
+
+# ChromaDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Chroma](/reference/integrations-chroma) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chroma |
+
+
+
+[Chroma](https://docs.trychroma.com/) is an open source vector database capable of storing collections of documents along with their metadata, creating embeddings for documents and queries, and searching the collections filtering by document metadata or content. Additionally, Chroma supports multi-modal embedding functions.
+
+Chroma can be used in-memory, as an embedded database, or in a client-server fashion. When running in-memory, Chroma can still keep its contents on disk across different sessions. This allows users to quickly put together prototypes using the in-memory version and later move to production, where the client-server version is deployed.
+
+## Initialization
+
+First, install the Chroma integration, which will install Haystack and Chroma if they are not already present. The following command is all you need to start:
+
+```shell
+pip install chroma-haystack
+```
+
+To store data in Chroma, create a `ChromaDocumentStore` instance and write documents with:
+
+```python
+from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+from haystack import Document
+
+document_store = ChromaDocumentStore()
+document_store.write_documents(
+ [
+ Document(content="This is the first document."),
+ Document(content="This is the second document."),
+ ],
+)
+print(document_store.count_documents())
+```
+
+In this case, since we didn’t pass any embeddings along with our documents, Chroma will create them for us using its [default embedding function](https://docs.trychroma.com/embeddings#default-all-minilm-l6-v2).
+
+### Connection Options
+
+1. **In-Memory Mode (Local)**: Chroma can be set up as a local Document Store for fast and lightweight usage. You can use this option during development or small-scale experiments. Set up a local in-memory instance of `ChromaDocumentStore` like this:
+
+ ```python
+ from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+
+ document_store = ChromaDocumentStore()
+ ```
+2. **Persistent Storage**: If you need to retain the documents between sessions, Chroma supports persistent storage by specifying a path to store data on disk:
+
+ ```python
+ from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+
+ document_store = ChromaDocumentStore(persist_path="your_directory_path")
+ ```
+3. **Remote Connection**: You can connect to a remote Chroma database through HTTP. This is suitable for distributed setups where multiple clients might interact with the same remote Chroma instance.
+
+ Note that this option is incompatible with in-memory or persistent storage modes.
+
+ First, start a Chroma server:
+
+ ```shell
+ chroma run --path /db_path
+ ```
+
+ Or using docker:
+
+ ```shell
+ docker run -p 8000:8000 chromadb/chroma
+ ```
+
+ Then, initialize the Document Store with `host` and `port` parameters:
+
+ ```python
+ from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+
+ document_store = ChromaDocumentStore(host="localhost", port="8000")
+ ```
+
+## Supported Retrievers
+
+The Haystack Chroma integration comes with three Retriever components. They all rely on the Chroma [query API](https://docs.trychroma.com/reference/Collection#query), but they have different inputs and outputs so that you can pick the one that best fits your pipeline:
+
+- [`ChromaQueryTextRetriever`](../pipeline-components/retrievers/chromaqueryretriever.mdx): This Retriever takes a plain-text query string in input and returns a list of matching documents. Chroma will create the embeddings for the query using its [default embedding function](https://docs.trychroma.com/embeddings#default-all-minilm-l6-v2).
+- [`ChromaEmbeddingRetriever`](../pipeline-components/retrievers/chromaembeddingretriever.mdx): This Retriever takes the embeddings of a single query in input and returns a list of matching documents. The query needs to be embedded before being passed to this component. For example, you can use an [embedder](../pipeline-components/embedders.mdx) component.
+
+## Additional References
+
+🧑🍳 Cookbook: [Use Chroma for RAG and Indexing](https://haystack.deepset.ai/cookbook/chroma-indexing-and-rag-examples)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/elasticsearch-document-store.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/elasticsearch-document-store.mdx
new file mode 100644
index 0000000000..eab82b2b06
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/elasticsearch-document-store.mdx
@@ -0,0 +1,67 @@
+---
+title: "ElasticsearchDocumentStore"
+id: elasticsearch-document-store
+slug: "/elasticsearch-document-store"
+description: "Use an Elasticsearch database with Haystack."
+---
+
+# ElasticsearchDocumentStore
+
+Use an Elasticsearch database with Haystack.
+
+
+
+| | |
+| --- | --- |
+| API reference | [Elasticsearch](/reference/integrations-elasticsearch) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/elasticsearch |
+
+
+
+ElasticsearchDocumentStore is excellent if you want to evaluate the performance of different retrieval options (dense vs. sparse) and aim for a smooth transition from PoC to production.
+
+It features the approximate nearest neighbours (ANN) search.
+
+### Initialization
+
+[Install](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html) Elasticsearch and then [start](https://www.elastic.co/guide/en/elasticsearch/reference/current/starting-elasticsearch.html) an instance. Haystack supports Elasticsearch 8.
+
+If you have Docker set up, we recommend pulling the Docker image and running it.
+
+```shell
+docker pull docker.elastic.co/elasticsearch/elasticsearch:8.11.1
+docker run -p 9200:9200 -e "discovery.type=single-node" -e "ES_JAVA_OPTS=-Xms1024m -Xmx1024m" -e "xpack.security.enabled=false" elasticsearch:8.11.1
+```
+
+As an alternative, you can go to [Elasticsearch integration GitHub](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/elasticsearch) and start a Docker container running Elasticsearch using the provided `docker-compose.yml`:
+
+```shell
+docker compose up
+```
+
+Once you have a running Elasticsearch instance, install the `elasticsearch-haystack` integration:
+
+```shell
+pip install elasticsearch-haystack
+```
+
+Then, initialize an `ElasticsearchDocumentStore` object that’s connected to the Elasticsearch instance and writes documents to it:
+
+```python
+from haystack_integrations.document_stores.elasticsearch import (
+ ElasticsearchDocumentStore,
+)
+from haystack import Document
+
+document_store = ElasticsearchDocumentStore(hosts="http://localhost:9200")
+document_store.write_documents(
+ [Document(content="This is first"), Document(content="This is second")],
+)
+print(document_store.count_documents())
+```
+
+### Supported Retrievers
+
+[`ElasticsearchBM25Retriever`](../pipeline-components/retrievers/elasticsearchbm25retriever.mdx): A keyword-based Retriever that fetches documents matching a query from the Document Store.
+
+[`ElasticsearchEmbeddingRetriever`](../pipeline-components/retrievers/elasticsearchembeddingretriever.mdx): Compares the query and document embeddings and fetches the documents most relevant to the query.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/faissdocumentstore.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/faissdocumentstore.mdx
new file mode 100644
index 0000000000..fbaf4ba200
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/faissdocumentstore.mdx
@@ -0,0 +1,152 @@
+---
+title: "FAISSDocumentStore"
+id: faissdocumentstore
+slug: "/faissdocumentstore"
+---
+
+# FAISSDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [FAISS](/reference/integrations-faiss) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/faiss |
+
+
+
+`FAISSDocumentStore` is a local Document Store backed by [FAISS](https://github.com/facebookresearch/faiss) for vector similarity search.
+It keeps vectors in a FAISS index and stores document data in memory, with optional persistence to disk.
+
+`FAISSDocumentStore` is a good fit for local development and small to medium-sized datasets where you want a lightweight setup without running an external database service.
+
+## Installation
+
+Install the FAISS integration:
+
+```shell
+pip install faiss-haystack
+```
+
+## Initialization
+
+Create a `FAISSDocumentStore` instance and write embedded documents:
+
+```python
+from haystack import Document
+from haystack.document_stores.types import DuplicatePolicy
+from haystack_integrations.document_stores.faiss import FAISSDocumentStore
+
+document_store = FAISSDocumentStore(
+ index_path="my_faiss_index", # Optional: enables persistence on disk
+ index_string="Flat",
+ embedding_dim=768,
+)
+
+document_store.write_documents(
+ [
+ Document(content="This is first", embedding=[0.1] * 768),
+ Document(content="This is second", embedding=[0.2] * 768),
+ ],
+ policy=DuplicatePolicy.OVERWRITE,
+)
+
+print(document_store.count_documents())
+
+# Persist index and metadata files (`.faiss` and `.json`)
+document_store.save("my_faiss_index")
+```
+
+### Persistence
+
+If you provide `index_path` when initializing `FAISSDocumentStore`, it tries to load existing persisted files (`.faiss` and `.json`) from that path.
+You can also explicitly call:
+
+- `save(index_path)` to write index and metadata to disk.
+- `load(index_path)` to load them later.
+
+Example of loading from a previously saved folder/path:
+
+```python
+from haystack_integrations.document_stores.faiss import FAISSDocumentStore
+
+# This loads `my_faiss_index.faiss` and `my_faiss_index.json` if they exist
+document_store = FAISSDocumentStore(index_path="my_faiss_index")
+
+# Alternatively, initialize first and then load explicitly
+another_store = FAISSDocumentStore(embedding_dim=768)
+another_store.load("my_faiss_index")
+```
+
+## Supported Retrievers
+
+[`FAISSEmbeddingRetriever`](../pipeline-components/retrievers/faissembeddingretriever.mdx): Retrieves documents from `FAISSDocumentStore` based on query embeddings.
+
+
+### Fixing OpenMP Runtime Conflicts on macOS
+
+#### Symptoms
+
+You may encounter one or both of the following errors at runtime:
+
+```
+OMP: Error #15: Initializing libomp.dylib, but found libomp.dylib already initialized.
+OMP: Hint This means that multiple copies of the OpenMP runtime have been linked into the program.
+```
+
+```
+resource_tracker: There appear to be 1 leaked semaphore objects to clean up at shutdown
+```
+
+If setting `OMP_NUM_THREADS=1` prevents the crash, the root cause is **multiple OpenMP runtimes loaded simultaneously**. Each runtime maintains its own thread pool and thread-local storage (TLS). When two runtimes spin up worker threads at the same time, they corrupt each other's memory — causing segfaults at `N > 1` threads.
+
+---
+
+#### Diagnosis
+
+First, find how many copies of `libomp.dylib` exist in your virtual environment:
+
+```bash
+find /path/to/your/.venv -name "libomp.dylib" 2>/dev/null
+```
+
+If you see more than one, e.g.:
+
+```
+.venv/lib/pythonX.Y/site-packages/torch/lib/libomp.dylib
+.venv/lib/pythonX.Y/site-packages/sklearn/.dylibs/libomp.dylib
+.venv/lib/pythonX.Y/site-packages/faiss/.dylibs/libomp.dylib
+```
+
+you need to consolidate them into a single runtime.
+
+---
+
+#### Fix
+
+The solution is to pick one canonical `libomp.dylib` (torch's is a good choice) and replace all other copies with symlinks pointing to it.
+
+For each duplicate, delete the copy and replace it with a symlink:
+
+```bash
+# Delete the duplicate
+rm /path/to/.venv/lib/pythonX.Y/site-packages/
+
+| | |
+| --- | --- |
+| API reference | [FalkorDB](/reference/integrations-falkordb) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/falkordb |
+
+
+
+FalkorDB is a high-performance graph database optimized for GraphRAG workloads. The `FalkorDBDocumentStore` stores documents as graph nodes and supports native vector search — no APOC is required. Documents and their `meta` fields are stored flat on each node, and all bulk writes use `UNWIND` + `MERGE` for safe OpenCypher upserts.
+
+For more information, see the [FalkorDB documentation](https://docs.falkordb.com/).
+
+## Installation
+
+Run FalkorDB with Docker:
+
+```shell
+docker run -d -p 6379:6379 falkordb/falkordb:latest
+```
+
+Install the Haystack integration:
+
+```shell
+pip install falkordb-haystack
+```
+
+## Usage
+
+Initialize the document store and write documents:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.falkordb import FalkorDBDocumentStore
+
+document_store = FalkorDBDocumentStore(
+ host="localhost",
+ port=6379,
+ embedding_dim=768,
+ recreate_graph=True,
+)
+
+document_store.write_documents(
+ [
+ Document(
+ content="There are over 7,000 languages spoken around the world today.",
+ ),
+ Document(
+ content="Elephants have been observed to recognize themselves in mirrors.",
+ ),
+ ],
+)
+print(document_store.count_documents())
+```
+
+To learn more about the initialization parameters, see the [API docs](/reference/integrations-falkordb#falkordbdocumentstore).
+
+To compute real embeddings for your documents, use a Document Embedder such as the [`SentenceTransformersDocumentEmbedder`](../pipeline-components/embedders/sentencetransformersdocumentembedder.mdx).
+
+### Authentication
+
+To connect to a password-protected FalkorDB instance, pass the password via `Secret`:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.document_stores.falkordb import FalkorDBDocumentStore
+
+document_store = FalkorDBDocumentStore(
+ host="localhost",
+ port=6379,
+ password=Secret.from_env_var("FALKORDB_PASSWORD"),
+)
+```
+
+### Similarity Functions
+
+`FalkorDBDocumentStore` supports two similarity functions for vector search:
+
+- `"cosine"` (default): cosine similarity, best for normalized embeddings.
+- `"euclidean"`: Euclidean distance, useful when embedding magnitude matters.
+
+```python
+document_store = FalkorDBDocumentStore(
+ host="localhost",
+ port=6379,
+ embedding_dim=768,
+ similarity="euclidean",
+)
+```
+
+### Supported Retrievers
+
+- [`FalkorDBEmbeddingRetriever`](../pipeline-components/retrievers/falkordbembeddingretriever.mdx): Retrieves documents from the `FalkorDBDocumentStore` based on vector similarity using FalkorDB's native vector index.
+- [`FalkorDBCypherRetriever`](../pipeline-components/retrievers/falkordbcypherretriever.mdx): Retrieves documents by executing arbitrary OpenCypher queries, enabling graph traversal and multi-hop queries for GraphRAG pipelines.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/inmemorydocumentstore.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/inmemorydocumentstore.mdx
new file mode 100644
index 0000000000..8e69b44e65
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/inmemorydocumentstore.mdx
@@ -0,0 +1,27 @@
+---
+title: "InMemoryDocumentStore"
+id: inmemorydocumentstore
+slug: "/inmemorydocumentstore"
+---
+
+# InMemoryDocumentStore
+
+The `InMemoryDocumentStore` is a very simple document store with no extra services or dependencies.
+
+It is great for experimenting with Haystack, however we do not recommend using it for production.
+
+### Initialization
+
+`InMemoryDocumentStore` requires no external setup. Simply use this code:
+
+```python
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+```
+
+### Supported Retrievers
+
+[`InMemoryBM25Retriever`](../pipeline-components/retrievers/inmemorybm25retriever.mdx): A keyword-based Retriever that fetches documents matching a query from a temporary in-memory database.
+
+[`InMemoryEmbeddingRetriever`](../pipeline-components/retrievers/inmemoryembeddingretriever.mdx): Compares the query and document embeddings and fetches the documents most relevant to the query.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/mongodbatlasdocumentstore.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/mongodbatlasdocumentstore.mdx
new file mode 100644
index 0000000000..a051dd8794
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/mongodbatlasdocumentstore.mdx
@@ -0,0 +1,59 @@
+---
+title: "MongoDBAtlasDocumentStore"
+id: mongodbatlasdocumentstore
+slug: "/mongodbatlasdocumentstore"
+---
+
+# MongoDBAtlasDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [MongoDB Atlas](/reference/integrations-mongodb-atlas) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mongodb_atlas |
+
+
+
+`MongoDBAtlasDocumentStore` can be used to manage documents using [MongoDB Atlas](https://www.mongodb.com/atlas), a multi-cloud database service by the same people who build MongoDB. Atlas simplifies deploying and managing your databases while offering the versatility you need to build resilient and performant global applications on the cloud providers of your choice. You can use MongoDB Atlas on cloud providers such as AWS, Azure, or Google Cloud, all without leaving Atlas' web UI.
+
+MongoDB Atlas supports embeddings and can therefore be used for embedding retrieval.
+
+## Installation
+
+To use MongoDB Atlas with Haystack, install the integration first:
+
+```shell
+pip install mongodb-atlas-haystack
+```
+
+## Initialization
+
+To use MongoDB Atlas with Haystack, you will need to create your MongoDB Atlas account: check the [MongoDB Atlas documentation](https://www.mongodb.com/docs/atlas/getting-started/) for help. You also need to [create a vector search index](https://www.mongodb.com/docs/atlas/atlas-vector-search/create-index/#std-label-avs-create-index) and [a full-text search index](https://www.mongodb.com/docs/atlas/atlas-search/manage-indexes/#create-an-atlas-search-index) for the collection you plan to use.
+
+Once you have your connection string, you should export it in an environment variable called `MONGO_CONNECTION_STRING`. It should look something like this:
+
+```python
+export MONGO_CONNECTION_STRING="mongodb+srv://
+
+| | |
+| --- | --- |
+| API reference | [OpenSearch](/reference/integrations-opensearch) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opensearch |
+
+
+
+OpenSearch is a fully open source search and analytics engine for use cases such as log analytics, real-time application monitoring, and clickstream analysis. For more information, see the [OpenSearch documentation](https://opensearch.org/docs/).
+
+This Document Store is great if you want to evaluate the performance of different retrieval options (dense vs. sparse). It’s compatible with the Amazon OpenSearch Service.
+
+OpenSearch provides support for vector similarity comparisons and approximate nearest neighbors algorithms.
+
+### Initialization
+
+[Install](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/index/) and run an OpenSearch instance.
+
+If you have Docker set up, we recommend pulling the Docker image and running it.
+
+```shell
+docker pull opensearchproject/opensearch:3.5.0
+docker run \
+ -p 9200:9200 \
+ -p 9600:9600 \
+ -e "discovery.type=single-node" \
+ -e "ES_JAVA_OPTS=-Xms1024m -Xmx1024m" \
+ -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=SecureHaystack*2026" \
+ opensearchproject/opensearch:3.5.0
+```
+
+As an alternative, you can go to [OpenSearch integration GitHub](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opensearch) and start a Docker container running OpenSearch using the provided `docker-compose.yml`:
+
+```shell
+docker compose up
+```
+
+Once you have a running OpenSearch instance, install the `opensearch-haystack` integration:
+
+```shell
+pip install opensearch-haystack
+```
+
+Then, initialize an `OpenSearchDocumentStore` object that’s connected to the OpenSearch instance and writes documents to it:
+
+```python
+from haystack_integrations.document_stores.opensearch import OpenSearchDocumentStore
+from haystack import Document
+
+document_store = OpenSearchDocumentStore(
+ hosts="http://localhost:9200",
+ use_ssl=True,
+ verify_certs=False,
+ http_auth=("admin", "SecureHaystack*2026"),
+)
+document_store.write_documents(
+ [Document(content="This is first"), Document(content="This is second")],
+)
+print(document_store.count_documents())
+```
+
+### Supported Retrievers
+
+[`OpenSearchBM25Retriever`](../pipeline-components/retrievers/opensearchbm25retriever.mdx): A keyword-based Retriever that fetches documents matching a query from the Document Store.
+
+[`OpenSearchEmbeddingRetriever`](../pipeline-components/retrievers/opensearchembeddingretriever.mdx): Compares the query and document embeddings and fetches the documents most relevant to the query.
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/pgvectordocumentstore.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/pgvectordocumentstore.mdx
new file mode 100644
index 0000000000..ac5400e342
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/pgvectordocumentstore.mdx
@@ -0,0 +1,109 @@
+---
+title: "PgvectorDocumentStore"
+id: pgvectordocumentstore
+slug: "/pgvectordocumentstore"
+---
+
+# PgvectorDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Pgvector](/reference/integrations-pgvector) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/pgvector/ |
+
+
+
+Pgvector is an extension for PostgreSQL that enhances its capabilities with vector similarity search. It builds upon the classic features of PostgreSQL, such as ACID compliance and point-in-time recovery, and introduces the ability to perform exact and approximate nearest neighbor search using vectors.
+
+For more information, see the [pgvector repository](https://github.com/pgvector/pgvector).
+
+Pgvector Document Store supports embedding retrieval and metadata filtering.
+
+## Installation
+
+To quickly set up a PostgreSQL database with pgvector, you can use Docker:
+
+```shell
+docker run -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres ankane/pgvector
+```
+
+For more information on installing pgvector, visit the [pgvector GitHub repository](https://github.com/pgvector/pgvector).
+
+To use pgvector with Haystack, install the `pgvector-haystack` integration:
+
+```shell
+pip install pgvector-haystack
+```
+
+## Usage
+
+### Connection String
+
+Define the connection string to your PostgreSQL database in the `PG_CONN_STR` environment variable. Two formats are supported:
+
+**URI format:**
+
+```shell
+export PG_CONN_STR="postgresql://USER:PASSWORD@HOST:PORT/DB_NAME"
+```
+
+**Keyword/value format:**
+
+```shell
+export PG_CONN_STR="host=HOST port=PORT dbname=DB_NAME user=USER password=PASSWORD"
+```
+
+:::caution[Special Characters in Connection URIs]
+
+When using the URI format, special characters in the password must be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding). Otherwise, connection errors may occur. A password like `p=ssword` would cause the error `psycopg.OperationalError: [Errno -2] Name or service not known`.
+
+For example, if your password is `p=ssword`, the connection string should be:
+
+```shell
+export PG_CONN_STR="postgresql://postgres:p%3Dssword@localhost:5432/postgres"
+```
+
+Alternatively, use the keyword/value format, which does not require percent-encoding:
+
+```shell
+export PG_CONN_STR="host=localhost port=5432 dbname=postgres user=postgres password=p=ssword"
+```
+
+:::
+
+For more details, see the [PostgreSQL connection string documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING).
+
+## Initialization
+
+Initialize a `PgvectorDocumentStore` object that’s connected to the PostgreSQL database and writes documents to it:
+
+```python
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack import Document
+
+document_store = PgvectorDocumentStore(
+ embedding_dimension=768,
+ vector_function="cosine_similarity",
+ recreate_table=True,
+ search_strategy="hnsw",
+)
+
+document_store.write_documents(
+ [
+ Document(content="This is first", embedding=[0.1] * 768),
+ Document(content="This is second", embedding=[0.3] * 768),
+ ],
+)
+print(document_store.count_documents())
+```
+
+To learn more about the initialization parameters, see our [API docs](/reference/integrations-pgvector#pgvectordocumentstore).
+
+To properly compute embeddings for your documents, you can use a Document Embedder (for instance, the [`SentenceTransformersDocumentEmbedder`](../pipeline-components/embedders/sentencetransformersdocumentembedder.mdx)).
+
+### Supported Retrievers
+
+- [`PgvectorEmbeddingRetriever`](../pipeline-components/retrievers/pgvectorembeddingretriever.mdx): An embedding-based Retriever that fetches documents from the Document Store based on a query embedding provided to the Retriever.
+- [`PgvectorKeywordRetriever`](../pipeline-components/retrievers/pgvectorembeddingretriever.mdx): A keyword-based Retriever that fetches documents matching a query from the Pgvector Document Store.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/pinecone-document-store.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/pinecone-document-store.mdx
new file mode 100644
index 0000000000..e570d9b0d0
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/pinecone-document-store.mdx
@@ -0,0 +1,67 @@
+---
+title: "PineconeDocumentStore"
+id: pinecone-document-store
+slug: "/pinecone-document-store"
+description: "Use a Pinecone vector database with Haystack."
+---
+
+# PineconeDocumentStore
+
+Use a Pinecone vector database with Haystack.
+
+
+
+| | |
+| --- | --- |
+| API reference | [Pinecone](/reference/integrations-pinecone) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/pinecone |
+
+
+
+[Pinecone](https://www.pinecone.io/) is a cloud-based vector database. It is fast and easy to use.
+Unlike other solutions (such as Qdrant and Weaviate), it can’t run locally on the user's machine but provides a generous free tier.
+
+### Installation
+
+You can simply install the Pinecone Haystack integration with:
+
+```shell
+pip install pinecone-haystack
+```
+
+### Initialization
+
+- To use Pinecone as a Document Store in Haystack, sign up for a free Pinecone [account](https://app.pinecone.io/) and get your API key.
+ The Pinecone API key can be explicitly provided or automatically read from the environment variable `PINECONE_API_KEY` (recommended).
+- In Haystack, each `PineconeDocumentStore` operates in a specific namespace of an index. If not provided, both index and namespace are `default`.
+ If the index already exists, the Document Store connects to it. Otherwise, it creates a new index.
+- When creating a new index, you can provide a `spec` in the form of a dictionary. This allows choosing between serverless and pod deployment options and setting additional parameters. Refer to the [Pinecone documentation](https://docs.pinecone.io/reference/api/control-plane/create_index) for more details. If not provided, a default spec with serverless deployment in the `us-east-1` region will be used (compatible with the free tier).
+- You can provide `dimension` and `metric`, but they are only taken into account if the Pinecone index does not already exist.
+
+Then, you can use the Document Store like this:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.pinecone import PineconeDocumentStore
+
+## Make sure you have the PINECONE_API_KEY environment variable set
+document_store = PineconeDocumentStore(
+ index="default",
+ namespace="default",
+ dimension=5,
+ metric="cosine",
+ spec={"serverless": {"region": "us-east-1", "cloud": "aws"}},
+)
+
+document_store.write_documents(
+ [
+ Document(content="This is first", embedding=[0.1] * 5),
+ Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5]),
+ ],
+)
+print(document_store.count_documents())
+```
+
+### Supported Retrievers
+
+[`PineconeEmbeddingRetriever`](../pipeline-components/retrievers/pineconedenseretriever.mdx): Retrieves documents from the `PineconeDocumentStore` based on their dense embeddings (vectors).
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/qdrant-document-store.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/qdrant-document-store.mdx
new file mode 100644
index 0000000000..773d1aec5e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/qdrant-document-store.mdx
@@ -0,0 +1,103 @@
+---
+title: "QdrantDocumentStore"
+id: qdrant-document-store
+slug: "/qdrant-document-store"
+description: "Use the Qdrant vector database with Haystack."
+---
+
+# QdrantDocumentStore
+
+Use the Qdrant vector database with Haystack.
+
+
+
+| | |
+| --- | --- |
+| API reference | [Qdrant](/reference/integrations-qdrant) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/qdrant |
+
+
+
+Qdrant is a powerful high-performance, massive-scale vector database. The `QdrantDocumentStore` can be used with any Qdrant instance, in-memory, locally persisted, hosted, and the official Qdrant Cloud.
+
+### Installation
+
+You can simply install the Qdrant Haystack integration with:
+
+```shell
+pip install qdrant-haystack
+```
+
+### Initialization
+
+The quickest way to use `QdrantDocumentStore` is to create an in-memory instance of it:
+
+```python
+from haystack.dataclasses.document import Document
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ return_embedding=True,
+ wait_result_from_api=True,
+)
+document_store.write_documents(
+ [
+ Document(content="This is first", embedding=[0.0] * 768),
+ Document(content="This is second", embedding=[0.1] * 768),
+ ],
+)
+print(document_store.count_documents())
+```
+
+:::warning[Collections Created Outside Haystack]
+
+When you create a `QdrantDocumentStore` instance, Haystack takes care of setting up the collection. In general, you cannot use a Qdrant collection created without Haystack with Haystack. If you want to migrate your existing collection, see the sample script at https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/qdrant/src/haystack_integrations/document_stores/qdrant/migrate_to_sparse.py.
+:::
+
+You can also connect directly to [Qdrant Cloud](https://cloud.qdrant.io/login) directly. Once you have your API key and your cluster URL from the Qdrant dashboard, you can connect like this:
+
+```python
+from haystack.dataclasses.document import Document
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack.utils import Secret
+
+document_store = QdrantDocumentStore(
+ url="https://XXXXXXXXX.us-east4-0.gcp.cloud.qdrant.io:6333",
+ index="your_index_name",
+ embedding_dim=1024, # based on the embedding model
+ recreate_index=True, # enable only to recreate the index and not connect to the existing one
+ api_key=Secret.from_token("YOUR_TOKEN"),
+)
+
+document_store.write_documents(
+ [
+ Document(content="This is first", embedding=[0.0] * 5),
+ Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5]),
+ ],
+)
+print(document_store.count_documents())
+```
+
+:::tip[More information]
+
+You can find more ways to initialize and use QdrantDocumentStore on our [integration page](https://haystack.deepset.ai/integrations/qdrant-document-store).
+:::
+
+### Supported Retrievers
+
+- [`QdrantEmbeddingRetriever`](../pipeline-components/retrievers/qdrantembeddingretriever.mdx): Retrieves documents from the `QdrantDocumentStore` based on their dense embeddings (vectors).
+- [`QdrantSparseEmbeddingRetriever`](../pipeline-components/retrievers/qdrantsparseembeddingretriever.mdx): Retrieves documents from the `QdrantDocumentStore` based on their sparse embeddings.
+- [`QdrantHybridRetriever`](../pipeline-components/retrievers/qdranthybridretriever.mdx): Retrieves documents from the `QdrantDocumentStore` based on both dense and sparse embeddings.
+
+:::note[Sparse Embedding Support]
+
+To use Sparse Embedding support, you need to initialize the `QdrantDocumentStore` with `use_sparse_embeddings=True`, which is `False` by default.
+
+If you want to use Document Store or collection previously created with this feature disabled, you must migrate the existing data. You can do this by taking advantage of the `migrate_to_sparse_embeddings_support` utility function.
+:::
+
+## Additional References
+
+🧑🍳 Cookbook: [Sparse Embedding Retrieval with Qdrant and FastEmbed](https://haystack.deepset.ai/cookbook/sparse_embedding_retrieval)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/valkeydocumentstore.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/valkeydocumentstore.mdx
new file mode 100644
index 0000000000..66b607fad3
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/valkeydocumentstore.mdx
@@ -0,0 +1,150 @@
+---
+title: "ValkeyDocumentStore"
+id: valkeydocumentstore
+slug: "/valkeydocumentstore"
+description: "Use a Valkey database with Haystack."
+---
+
+# ValkeyDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Valkey](/reference/integrations-valkey) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/valkey |
+
+
+
+[Valkey](https://valkey.io/) is a high-performance, in-memory data structure store that you can use in Haystack pipelines with the `ValkeyDocumentStore`. Valkey operates in-memory by default for maximum performance, but can be configured with persistence options for data durability.
+
+The `ValkeyDocumentStore` connects to a Valkey server with the search module running and supports vector similarity search for RAG and other retrieval use cases. For a detailed overview of all the available methods and settings, visit the [API Reference](/reference/integrations-valkey#valkeydocumentstore).
+
+## Installation
+
+You can install the Valkey Haystack integration with:
+
+```shell
+pip install valkey-haystack
+```
+
+## Initialization
+
+To use Valkey as your data storage for Haystack pipelines, you need a Valkey server with the search module running. Initialize a `ValkeyDocumentStore` like this:
+
+```python
+from haystack_integrations.document_stores.valkey import ValkeyDocumentStore
+
+document_store = ValkeyDocumentStore(
+ nodes_list=[("localhost", 6379)],
+ index_name="my_documents",
+ embedding_dim=768,
+ distance_metric="cosine"
+)
+```
+
+### Running Valkey locally
+
+For development and testing, you can start a Valkey server with Docker:
+
+```shell
+docker run -d -p 6379:6379 valkey/valkey-bundle:latest
+```
+
+Then connect with the same initialization code above, using `nodes_list=[("localhost", 6379)]`.
+
+For more advanced configurations and clustering setups, refer to the [Valkey documentation](https://valkey.io/docs/).
+
+## Writing documents
+
+To write documents to your `ValkeyDocumentStore`, create an indexing pipeline or use the `write_documents()` method. You can use [Converters](../pipeline-components/converters.mdx), [PreProcessors](../pipeline-components/preprocessors.mdx), and other integrations to fetch and prepare data. Below is an example that indexes Markdown files into Valkey.
+
+### Indexing pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.converters import MarkdownToDocument
+from haystack.components.writers import DocumentWriter
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+from haystack.components.preprocessors import DocumentSplitter
+from haystack_integrations.document_stores.valkey import ValkeyDocumentStore
+
+document_store = ValkeyDocumentStore(
+ nodes_list=[("localhost", 6379)],
+ index_name="my_documents",
+ embedding_dim=768,
+ distance_metric="cosine"
+)
+
+indexing = Pipeline()
+indexing.add_component("converter", MarkdownToDocument())
+indexing.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=2))
+indexing.add_component("embedder", SentenceTransformersDocumentEmbedder())
+indexing.add_component("writer", DocumentWriter(document_store))
+indexing.connect("converter", "splitter")
+indexing.connect("splitter", "embedder")
+indexing.connect("embedder", "writer")
+
+indexing.run({"converter": {"sources": ["filename.md"]}})
+```
+
+## Using Valkey in a RAG pipeline
+
+Once documents are in your `ValkeyDocumentStore`, you can use [`ValkeyEmbeddingRetriever`](../pipeline-components/retrievers/valkeyembeddingretriever.mdx) to retrieve them. The following example builds a RAG pipeline with a custom prompt:
+
+```python
+from haystack import Pipeline
+from haystack.utils import Secret
+from haystack.dataclasses import ChatMessage
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack_integrations.document_stores.valkey import ValkeyDocumentStore
+from haystack_integrations.components.retrievers.valkey import ValkeyEmbeddingRetriever
+
+document_store = ValkeyDocumentStore(
+ nodes_list=[("localhost", 6379)],
+ index_name="my_documents",
+ embedding_dim=768,
+ distance_metric="cosine"
+)
+
+prompt_template = [
+ ChatMessage.from_system("Answer the question based on the provided context. If the context does not include an answer, reply with 'I don't know'."),
+ ChatMessage.from_user(
+ "Query: {{query}}\n"
+ "Documents:\n{% for doc in documents %}{{ doc.content }}\n{% endfor %}\n"
+ "Answer:",
+ ),
+]
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", ValkeyEmbeddingRetriever(document_store=document_store))
+query_pipeline.add_component("prompt_builder", ChatPromptBuilder(template=prompt_template, required_variables=["query", "documents"]))
+query_pipeline.add_component("generator", OpenAIChatGenerator(api_key=Secret.from_token("YOUR_OPENAI_API_KEY"), model="gpt-4o"))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+query_pipeline.connect("retriever.documents", "prompt_builder.documents")
+query_pipeline.connect("prompt_builder.messages", "generator.messages")
+
+query = "What is Valkey?"
+results = query_pipeline.run(
+ {
+ "text_embedder": {"text": query},
+ "prompt_builder": {"query": query},
+ }
+)
+```
+
+For more examples, see the [examples folder](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/valkey/examples) in the repository.
+
+## Performance benefits
+
+- **In-memory storage**: Fast read and write operations.
+- **High throughput**: Handles many operations per second.
+- **Low latency**: Minimal response times for document operations.
+- **Scalability**: Supports clustering for horizontal scaling.
+
+## Supported Retrievers
+
+[`ValkeyEmbeddingRetriever`](../pipeline-components/retrievers/valkeyembeddingretriever.mdx): Compares the query and document embeddings and fetches the documents most relevant to the query from the `ValkeyDocumentStore`.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/document-stores/weaviatedocumentstore.mdx b/docs-website/versioned_docs/version-2.29-unstable/document-stores/weaviatedocumentstore.mdx
new file mode 100644
index 0000000000..fdcd9b7d0d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/document-stores/weaviatedocumentstore.mdx
@@ -0,0 +1,155 @@
+---
+title: "WeaviateDocumentStore"
+id: weaviatedocumentstore
+slug: "/weaviatedocumentstore"
+---
+
+# WeaviateDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Weaviate](/reference/integrations-weaviate) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/weaviate |
+
+
+
+Weaviate is a multi-purpose vector DB that can store both embeddings and data objects, making it a good choice for multi-modality.
+
+The `WeaviateDocumentStore` can connect to any Weaviate instance, whether it's running on Weaviate Cloud Services, Kubernetes, or a local Docker container.
+
+## Installation
+
+You can simply install the Weaviate Haystack integration with:
+
+```shell
+pip install weaviate-haystack
+```
+
+## Initialization
+
+### Weaviate Embedded
+
+To use `WeaviateDocumentStore` as a temporary instance, initialize it as ["Embedded"](https://weaviate.io/developers/weaviate/installation/embedded):
+
+```python
+from haystack_integrations.document_stores.weaviate import WeaviateDocumentStore
+from weaviate.embedded import EmbeddedOptions
+
+document_store = WeaviateDocumentStore(embedded_options=EmbeddedOptions())
+```
+
+### Docker
+
+You can use `WeaviateDocumentStore` in a local Docker container. This is what a minimal `docker-compose.yml` could look like:
+
+```yaml
+---
+version: '3.4'
+services:
+ weaviate:
+ command:
+ - --host
+ - 0.0.0.0
+ - --port
+ - '8080'
+ - --scheme
+ - http
+ image: semitechnologies/weaviate:1.30.17
+ ports:
+ - 8080:8080
+ - 50051:50051
+ volumes:
+ - weaviate_data:/var/lib/weaviate
+ restart: 'no'
+ environment:
+ QUERY_DEFAULTS_LIMIT: 25
+ AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
+ PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
+ DEFAULT_VECTORIZER_MODULE: 'none'
+ ENABLE_MODULES: ''
+ CLUSTER_HOSTNAME: 'node1'
+volumes:
+ weaviate_data:
+...
+```
+
+:::warning
+With this example, we explicitly enable access without authentication, so you don't need to set any username, password, or API key to connect to our local instance. That is strongly discouraged for production use. See the [authorization](#authorization) section for detailed information.
+
+:::
+
+Start your container with `docker compose up -d` and then initialize the Document Store with:
+
+```python
+from haystack_integrations.document_stores.weaviate.document_store import (
+ WeaviateDocumentStore,
+)
+from haystack import Document
+
+document_store = WeaviateDocumentStore(url="http://localhost:8080")
+document_store.write_documents(
+ [Document(content="This is first"), Document(content="This is second")],
+)
+print(document_store.count_documents())
+```
+
+### Weaviate Cloud Service
+
+To use the [Weaviate managed cloud service](https://weaviate.io/developers/wcs), first, create your Weaviate cluster.
+
+Then, initialize the `WeaviateDocumentStore` using the API Key and URL found in your [Weaviate account](https://console.weaviate.cloud/):
+
+```python
+from haystack_integrations.document_stores.weaviate import (
+ WeaviateDocumentStore,
+ AuthApiKey,
+)
+from haystack import Document
+
+import os
+
+os.environ["WEAVIATE_API_KEY"] = "YOUR-API-KEY"
+
+auth_client_secret = AuthApiKey()
+
+document_store = WeaviateDocumentStore(
+ url="YOUR-WEAVIATE-URL",
+ auth_client_secret=auth_client_secret,
+)
+```
+
+## Authorization
+
+We provide some utility classes in the `auth` package to handle authorization using different credentials. Every class stores distinct [secrets](../concepts/secret-management.mdx) and retrieves them from the environment variables when required.
+
+The default environment variables for the classes are:
+
+- **`AuthApiKey`**
+ - `WEAVIATE_API_KEY`
+- **`AuthBearerToken`**
+ - `WEAVIATE_ACCESS_TOKEN`
+ - `WEAVIATE_REFRESH_TOKEN`
+- **`AuthClientCredentials`**
+ - `WEAVIATE_CLIENT_SECRET`
+ - `WEAVIATE_SCOPE`
+- **`AuthClientPassword`**
+ - `WEAVIATE_USERNAME`
+ - `WEAVIATE_PASSWORD`
+ - `WEAVIATE_SCOPE`
+
+You can easily change environment variables if needed. In the following snippet, we instruct `AuthApiKey` to look for `MY_ENV_VAR`.
+
+```python
+from haystack_integrations.document_stores.weaviate.auth import AuthApiKey
+from haystack.utils.auth import Secret
+
+AuthApiKey(api_key=Secret.from_env_var("MY_ENV_VAR"))
+```
+
+## Supported Retrievers
+
+[`WeaviateBM25Retriever`](../pipeline-components/retrievers/weaviatebm25retriever.mdx): A keyword-based Retriever that fetches documents matching a query from the Document Store.
+
+[`WeaviateEmbeddingRetriever`](../pipeline-components/retrievers/weaviateembeddingretriever.mdx): Compares the query and document embeddings and fetches the documents most relevant to the query.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/intro.mdx b/docs-website/versioned_docs/version-2.29-unstable/intro.mdx
new file mode 100644
index 0000000000..7d46841cb9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/intro.mdx
@@ -0,0 +1,32 @@
+---
+title: "Introduction to Haystack"
+id: intro
+description: "Haystack is an open-source AI framework to build production-ready LLM applications such as AI Agents, powerful RAG applications and scalable multimodal search systems. Learn more about Haystack and how it works."
+---
+
+# Introduction to Haystack
+
+Haystack is an **open-source AI framework** for building production-ready **AI Agents**, **powerful RAG applications** and **scalable multimodal search systems**. Build pipelines using reusable components, each responsible for specific tasks. Customize and extend pipelines to match your requirements. Learn more about Haystack and how it works.
+
+:::tip[Welcome to Haystack]
+
+To skip the introductions and go directly to installing and creating a search app, see [Get Started](overview/get-started.mdx).
+:::
+
+Haystack is an open-source AI orchestration framework that you can use to build powerful, production-ready applications with Large Language Models (LLMs) for various use cases. Whether you’re creating autonomous agents, multimodal apps, or scalable RAG systems, Haystack provides the tools to move from idea to production easily.
+
+Haystack is designed in a modular way, allowing you to combine the best technology from OpenAI, Google, Anthropic, and open-source projects like Hugging Face's Transformers.
+
+The core foundation of Haystack consists of components and pipelines, along with Document Stores, Agents, Tools, and many integrations. Read more about Haystack concepts in the [Haystack Concepts Overview](concepts/concepts-overview.mdx).
+
+Supported by an engaged community of developers, Haystack has grown into a comprehensive and user-friendly framework for LLM-based development.
+
+:::note[Looking to scale with confidence?]
+
+If your team needs **enterprise-grade support, best practices, and deployment guidance** to run Haystack in production, check out **Haystack Enterprise Starter**.
+
+📜 [Learn more about Haystack Enterprise Starter](https://haystack.deepset.ai/blog/announcing-haystack-enterprise)
+🤝 [Get in touch with our team](https://www.deepset.ai/products-and-services/haystack-enterprise-starter)
+
+👉 For platform tooling to **manage data, pipelines, testing, and governance at scale**, explore the [Haystack Enterprise Platform](https://www.deepset.ai/products-and-services/haystack-enterprise-platform).
+:::
diff --git a/docs-website/versioned_docs/version-2.29-unstable/optimization/advanced-rag-techniques.mdx b/docs-website/versioned_docs/version-2.29-unstable/optimization/advanced-rag-techniques.mdx
new file mode 100644
index 0000000000..e7edb8fe4c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/optimization/advanced-rag-techniques.mdx
@@ -0,0 +1,20 @@
+---
+title: "Advanced RAG Techniques"
+id: advanced-rag-techniques
+slug: "/advanced-rag-techniques"
+---
+
+# Advanced RAG Techniques
+
+This section of documentation talks about advanced RAQ techniques you can implement with Haystack.
+
+Read more about [Hypothetical Document Embeddings (HyDE)](advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx),
+
+or check out one of our cookbooks 🧑🍳:
+
+- [Using Hypothetical Document Embedding (HyDE) to Improve Retrieval](https://haystack.deepset.ai/cookbook/using_hyde_for_improved_retrieval)
+- [Query Decomposition and Reasoning](https://haystack.deepset.ai/cookbook/query_decomposition)
+- [Improving Retrieval by Embedding Meaningful Metadata](https://haystack.deepset.ai/cookbook/improve-retrieval-by-embedding-metadata)
+- [Query Expansion](https://haystack.deepset.ai/cookbook/query-expansion)
+- [Automated Structured Metadata Enrichment](https://haystack.deepset.ai/cookbook/metadata_enrichment)
+- [Auto-Merging and Hierarchical Document Retrieval](https://haystack.deepset.ai/cookbook/auto_merging_retriever)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/optimization/advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx b/docs-website/versioned_docs/version-2.29-unstable/optimization/advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx
new file mode 100644
index 0000000000..b1c1829a5a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/optimization/advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx
@@ -0,0 +1,110 @@
+---
+title: "Hypothetical Document Embeddings (HyDE)"
+id: hypothetical-document-embeddings-hyde
+slug: "/hypothetical-document-embeddings-hyde"
+description: "Enhance the retrieval in Haystack using HyDE method by generating a mock-up hypothetical document for an initial query."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# Hypothetical Document Embeddings (HyDE)
+
+Enhance the retrieval in Haystack using HyDE method by generating a mock-up hypothetical document for an initial query.
+
+## When Is It Helpful?
+
+The HyDE method is highly useful when:
+
+- The performance of the retrieval step in your pipeline is not good enough (for example, low Recall metric).
+- Your retrieval step has a query as input and returns documents from a larger document base.
+- Particularly worth a try if your data (documents or queries) come from a special domain that is very different from the typical datasets that Retrievers are trained on.
+
+## How Does It Work?
+
+Many embedding retrievers generalize poorly to new, unseen domains. This approach tries to tackle this problem. Given a query, the Hypothetical Document Embeddings (HyDE) first zero-shot prompts an instruction-following language model to generate a “fake” hypothetical document that captures relevant textual patterns from the initial query - in practice, this is done five times. Then, it encodes each hypothetical document into an embedding vector and averages them. The resulting, single embedding can be used to identify a neighbourhood in the document embedding space from which similar actual documents are retrieved based on vector similarity. As with any other retriever, these retrieved documents can then be used downstream in a pipeline (for example, in a Generator for RAG). Refer to the paper “[Precise Zero-Shot Dense Retrieval without Relevance Labels](https://aclanthology.org/2023.acl-long.99/)” for more details.
+Google VertexAI Models
Azure OpenAI Models
Amazon Bedrock Models | All GPT models from OpenAI | +| Supported metrics | ANSWER_CORRECTNESS, FAITHFULNESS, ANSWER_SIMILARITY, CONTEXT_PRECISION, CONTEXT_UTILIZATION,CONTEXT_RECALL, ASPECT_CRITIQUE, CONTEXT_RELEVANCY, ANSWER_RELEVANCY | ANSWER_RELEVANCY, FAITHFULNESS, CONTEXTUAL_PRECISION, CONTEXTUAL_RECALL, CONTEXTUAL_RELEVANCE | +| Customizable prompt for response evaluation | ✅, with ASPECT_CRITIQUE metric | ❌ | +| Explanations of scores | ❌ | ✅ | +| Monitoring dashboard | ❌ | ❌ | + +:::info[Framework Documentation] + +You can find more information about the metrics in the documentation of the respective evaluation frameworks: + +- Ragas metrics: https://docs.ragas.io/en/latest/concepts/metrics/index.html +- DeepEval metrics: https://docs.confident-ai.com/docs/metrics-introduction +::: + +## Additional References + +:notebook: Tutorial: [Evaluating RAG Pipelines](https://haystack.deepset.ai/tutorials/35_evaluating_rag_pipelines) diff --git a/docs-website/versioned_docs/version-2.29-unstable/optimization/evaluation/statistical-evaluation.mdx b/docs-website/versioned_docs/version-2.29-unstable/optimization/evaluation/statistical-evaluation.mdx new file mode 100644 index 0000000000..5fc39c80ed --- /dev/null +++ b/docs-website/versioned_docs/version-2.29-unstable/optimization/evaluation/statistical-evaluation.mdx @@ -0,0 +1,49 @@ +--- +title: "Statistical Evaluation" +id: statistical-evaluation +slug: "/statistical-evaluation" +description: "Haystack supports various statistical evaluation metrics. This page explains what statistical evaluation is and discusses the various options available within Haystack." +--- + +# Statistical Evaluation + +Haystack supports various statistical evaluation metrics. This page explains what statistical evaluation is and discusses the various options available within Haystack. + +## Introduction + +Statistical evaluation in Haystack compares ground truth labels with pipeline predictions, typically using metrics such as precision or recall. It's often used to evaluate the Retriever component within Retrieval-Augmented Generative (RAG) pipelines, but this methodology can be adapted for any pipeline if ground truth labels of relevant documents are available. + +When evaluating answers, such as those predicted by an extractive question answering pipeline, the ground truth labels of expected answers are compared to the pipeline's predictions. + +For assessing answers generated by LLMs with one of Haystack’s Generator components, we recommend model-based evaluation instead. It can incorporate measures of semantic similarity or coherence and is better suited to evaluate predictions that might differ in wording from the ground truth labels. + +## Statistical Evaluation Pipelines in Haystack + +There are two ways of performing model-based evaluation in Haystack, both of which leverage [pipelines](../../concepts/pipelines.mdx) and [Evaluator](../../pipeline-components/evaluators.mdx) components: + +- You can create and run an evaluation pipeline independently. This means you’ll have to provide the required inputs to the evaluation pipeline manually. We recommend this way because the separation of your RAG pipeline and your evaluation pipeline allows you to store the results of your RAG pipeline and try out different evaluation metrics afterward without needing to re-run your pipeline every time. +- As another option, you can add an Evaluator to the end of a RAG pipeline. This means you run both a RAG pipeline and evaluation on top of it in a single `pipeline.run()` call. + +## Statistical Evaluation of Retrieved Documents + +### [DocumentRecallEvaluator](../../pipeline-components/evaluators/documentrecallevaluator.mdx) + +Recall measures how often the correct document was among the retrieved documents over a set of queries. For a single query, the output is binary: either the correct document is contained in the selection, or it is not. Over the entire dataset, the recall score amounts to a number between zero (no query retrieved the right document) and one (all queries retrieved the right documents). + +In some scenarios, there can be multiple correct documents for one query. The metric `recall_single_hit` considers whether at least one of the correct documents is retrieved, whereas `recall_multi_hit` takes into account how many of the multiple correct documents for one query are retrieved. + +Note that recall is affected by the number of documents that the Retriever returns. If the Retriever returns few documents, it means that it is difficult to retrieve the correct documents. Make sure to set the Retriever's `top_k` to an appropriate value in the pipeline that you're evaluating. + +### [DocumentMRREvaluator](../../pipeline-components/evaluators/documentmrrevaluator.mdx) (Mean Reciprocal Rank) + +In contrast to the recall metric, mean reciprocal rank takes the position of the top correctly retrieved document (the “rank”) into account. It does this to account for the fact that a query elicits multiple responses of varying relevance. Like recall, MRR can be a value between zero (no matches) and one (the system retrieved a correct document for all queries as the top result). For more details, check out [Mean Reciprocal Rank wiki page](https://en.wikipedia.org/wiki/Mean_reciprocal_rank). + +### [DocumentMAPEvaluator](../../pipeline-components/evaluators/documentmapevaluator.mdx) (Mean Average Precision) + +Mean average precision is similar to mean reciprocal rank but takes into account the position of every correctly retrieved document. Like MRR, mAP can be a value between zero (no matches) and one (the system retrieved correct documents for all top results). mAP is particularly useful in cases where there is more than one correct answer to be retrieved. For more details, check out [Mean Average Precision wiki page](https://en.wikipedia.org/wiki/Evaluation_measures_(information_retrieval)#Mean_average_precision). + +## Statistical Evaluation of Extracted or Generated Answers + +### [AnswerExactMatchEvaluator](../../pipeline-components/evaluators/answerexactmatchevaluator.mdx) + +Exact match measures the proportion of cases where the predicted Answer is identical to the correct Answer. For example, for the annotated question-answer pair “What is Haystack?" + "A question answering library in Python”, even a predicted answer like “A Python question answering library” would yield a zero score because it does not match the expected answer 100%. \ No newline at end of file diff --git a/docs-website/versioned_docs/version-2.29-unstable/overview/breaking-change-policy.mdx b/docs-website/versioned_docs/version-2.29-unstable/overview/breaking-change-policy.mdx new file mode 100644 index 0000000000..c3fb3a7e6d --- /dev/null +++ b/docs-website/versioned_docs/version-2.29-unstable/overview/breaking-change-policy.mdx @@ -0,0 +1,88 @@ +--- +title: "Breaking Change Policy" +id: breaking-change-policy +slug: "/breaking-change-policy" +description: "This document outlines the breaking change policy for Haystack, including the definition of breaking changes, versioning conventions, and the deprecation process for existing features." +--- + +# Breaking Change Policy + +This document outlines the breaking change policy for Haystack, including the definition of breaking changes, versioning conventions, and the deprecation process for existing features. + +Haystack is under active development, which means that functionalities are being added, deprecated, or removed rather frequently. This policy aims to minimize the impact of these changes on current users and deployments. It provides a clear schedule and outlines the necessary steps before upgrading to a new Haystack version. + +## Breaking Change Definition + +A breaking change occurs when: + +- A Component is removed, renamed, or the Python import path is changed. +- A parameter is renamed, removed, or changed from optional to mandatory. +- A new mandatory parameter is added. + +Existing deployments might break, and the change is deemed a _breaking change_. The decision to declare a change as breaking has nothing to do with its potential impact: while the change might only impact a tiny subset of applications using a specific Haystack feature, it would still be treated as a breaking change. + +The following cases are **not** considered a breaking change: + +- A new functionality is added (for example, a new Component). +- A component, class, or utility function gets a new optional parameter. +- An existing parameter gets changed from mandatory to optional. + +Existing deployments are not impacted, and the change is deemed non-breaking. Release notes will mention the change and possibly provide an upgrade path, but upgrading Haystack won’t break existing applications. + +## Versioning + +Haystack releases are labeled with a series of three numbers separated by dots, for example, `2.0.1`. Each number has a specific meaning: + +- `2` is the Major version +- `0` is the Minor version +- `1` is the Patch version + +:::info +Albeit similar, Haystack DOES NOT follow the principles of [Semantic Versioning](https://semver.org). Read on to see the differences. +::: + +Given a Haystack release with a version number of type `MAJOR.MINOR.PATCH`, you should expect: + +1. **For Major version change:** fundamental, incompatible API changes. In this case, you would most likely need a migration process before being able to update Haystack. Major releases happen no more than once a year, changes are extensively documented, and a migration path is provided. +2. **For Minor version change:** addition or removal of functionalities that might not be backward compatible. Most of the time, you will be able to upgrade your Haystack installation seamlessly, but always refer to the [release notes](https://github.com/deepset-ai/haystack/releases) for guidance. Deprecated components are the most common breaking change shipped in a Minor version release. +3. **For Patch version change:** bugfixes. You can safely upgrade Haystack to the new version without concerns that your program will break. + +## Deprecation of Existing Features + +Haystack strives for robustness. To achieve this, we clean up our code by removing old features that are no longer used. This helps us maintain the codebase, improve security, and make it easier to keep everything running smoothly. Before we remove a feature, component, class, or utility function, we go through a process called deprecation. + +A Major or Minor (but not Patch) version may deprecate certain features from previous releases, and this is what you should expect: + +- If a feature is deprecated in Haystack version `X.Y`, it will continue to work but the Python code will raise warnings detailing the steps to take in order to upgrade. +- Features deprecated in Haystack version `X.Y` will be removed in Haystack `X.Y+1`, giving affected users a timeframe of roughly a month to prepare the upgrade. + +### Example + +To clarify the process, here’s an example: + +At some point, we decide to remove a `FooComponent` and declare it deprecated in Haystack version `2.99.0`. This is what will happen: + +1. `FooComponent` keeps working as usual In Haystack `2.99.0`, but using the component raises a `FutureWarning` message in the code. +2. In Haystack version `2.100.0`, we remove the `FooComponent` from the codebase. Trying to use it produces an error. + +## Discontinuing an Integration + +When existing features are changed or removed, integrations go through the same deprecation process as detailed on this page for Haystack. It’s important to note that integrations are independent and distributed with their own packages. In certain cases, a special form of deprecation may occur where the integration is discontinued and subsequently removed from the Core Integrations repository. + +To give our community the opportunity to take over the integration and keep it maintained before being discontinued Core Integrations gradually go through different states, as detailed below: + +- **Staged** + - The source code of the integration is moved from `main` to a special `staging` branch of the Core Integrations repository. + - The documentation pages are removed from the Haystack documentation website. + - The main README of the Core Integrations repository shows a disclaimer explaining how the integration can be adopted from the community. + - The integration tile is removed (it can be re-added later by the maintainer who adopted the integration). + - The integration package on PyPI remains available. + - A grace period of 3 months starts. +- **Adopted** + - An organization or an individual from the community accepts to take over the ownership of the Staged integration. + - The adopter creates their own repository, and the source code of the discontinued integration is removed from the `staging` branch. + - Ownership of the PyPI package is transferred to the new maintainer. + - The adopter will create a new integration tile in [haystack-integrations](https://github.com/deepset-ai/haystack-integrations). +- **Discontinued** + - If the grace period expires and nobody adopts the Staged Integration, its source code is removed from the `staging` branch. + - The PyPI package of the integration won’t be removed but won’t be further updated. \ No newline at end of file diff --git a/docs-website/versioned_docs/version-2.29-unstable/overview/faq.mdx b/docs-website/versioned_docs/version-2.29-unstable/overview/faq.mdx new file mode 100644 index 0000000000..760a6a3c92 --- /dev/null +++ b/docs-website/versioned_docs/version-2.29-unstable/overview/faq.mdx @@ -0,0 +1,44 @@ +--- +title: "FAQ" +id: faq +slug: "/faq" +description: "Here are the answers to the questions people frequently ask about Haystack." +--- + +# FAQ + +Here are the answers to the questions people frequently ask about Haystack. + +### How can I make sure that my GPU is being engaged when I use Haystack? + +You will want to ensure that a CUDA enabled GPU is being engaged when Haystack is running (you can check by running `nvidia-smi -l` on your command line). Components which can be sped up by GPU have a `device` argument in their constructor. For more details, check the [Device Management](../concepts/device-management.mdx) page. + +### Are you tracking my Haystack usage? + +We only collect _anonymous_ usage statistics of Haystack pipeline components. Read more about telemetry in Haystack or how you can opt out on the [Telemetry](telemetry.mdx) page. + +### How can I ask my questions around Haystack? + +For general questions, we recommend joining the [Haystack Discord ](https://discord.com/invite/xYvH6drSmA)or using [GitHub discussions](https://github.com/deepset-ai/haystack/discussions), where the community and maintainers can help. You can also explore [tutorials](https://haystack.deepset.ai/tutorials/40_building_chat_application_with_function_calling) and [examples](https://haystack.deepset.ai/cookbook/tools_support) on website to find more info. + +### How can I get expert support for Haystack? + +If you’re a team running Haystack in production or want to move faster and scale with confidence, we recommend [Haystack Enterprise Starter](https://haystack.deepset.ai/blog/announcing-haystack-enterprise). It gives you direct access to the Haystack team, proven best practices, and hands-on support to help you go from prototype to production smoothly. + +👉 [Get in touch with our team to explore Haystack Enterprise Starter](https://www.deepset.ai/products-and-services/haystack-enterprise) + +### Where can I find documentation for older Haystack versions? + +The website only hosts documentation for the 5 most recent Haystack versions. + +For older versions (up to 2.18), you can access the documentation on GitHub: https://github.com/deepset-ai/haystack/tree/main/docs-website/versioned_docs. + +### Where can I find tutorials and documentation for Haystack 1.x? + +You can access old tutorials in the [GitHub history](https://github.com/deepset-ai/haystack-tutorials/tree/5917718cbfbb61410aab4121ee6fe754040a5dc7) and download the Haystack 1.x documentation as a [ZIP file](https://core-engineering.s3.eu-central-1.amazonaws.com/public/docs/haystack-v1-docs.zip). + +The ZIP file contains documentation for all minor releases from version 1.0 to 1.26. + +To download documentation for a specific release, replace the version number in the following URL: `https://core-engineering.s3.eu-central-1.amazonaws.com/public/docs/v1.26.zip`. + +Learn how to migrate to Haystack version 2.x with our [migration guide](migration.mdx). diff --git a/docs-website/versioned_docs/version-2.29-unstable/overview/get-started.mdx b/docs-website/versioned_docs/version-2.29-unstable/overview/get-started.mdx new file mode 100644 index 0000000000..e3bce8b76d --- /dev/null +++ b/docs-website/versioned_docs/version-2.29-unstable/overview/get-started.mdx @@ -0,0 +1,571 @@ +--- +title: "Get Started" +id: get-started +slug: "/get-started" +description: "Learn how to quickly get up and running with Haystack. Build your first RAG pipeline and tool-calling Agent with step-by-step examples for multiple LLM providers." +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Get Started + +Have a look at this page to learn how to quickly get up and running with Haystack. It contains instructions for installing Haystack, building your first RAG pipeline, and creating a tool-calling Agent. + +## Build your first RAG application + +Let's build your first Retrieval Augmented Generation (RAG) pipeline and see how Haystack answers questions. + +First, install the minimal form of Haystack: + +```shell +pip install haystack-ai +``` + +In the examples below, we show how to set an API key using a Haystack [Secret](../concepts/secret-management.mdx). Choose your preferred LLM provider from the tabs below. For easier use, you can also set the API key as an environment variable. + +
+
+Haystack supports many more model providers including **Cohere**, **Mistral**, **NVIDIA**, **Ollama**, and others—both cloud-hosted and local options.
+
+Browse the full list of supported models and chat generators in the [Generators documentation](../pipeline-components/generators.mdx).
+
+You can also explore all available integrations on the [Haystack Integrations](https://haystack.deepset.ai/integrations) page.
+
+
+
+
+
+Haystack supports many more model providers including **Cohere**, **Mistral**, **NVIDIA**, **Ollama**, and others—both cloud-hosted and local options.
+
+Browse the full list of supported models and chat generators in the [Generators documentation](../pipeline-components/generators.mdx).
+
+You can also explore all available integrations on the [Haystack Integrations](https://haystack.deepset.ai/integrations) page.
+
+
+
+
+
+
+**Step 2: Initialize the LLM with tools**
+
+Both frameworks connect tools to the LLM, but with different APIs. In Haystack, tools are passed directly to the `ChatGenerator` component during initialization. In LangGraph, you first initialize the model, then bind tools using `.bind_tools()` to create a tool-enabled LLM instance.
+
+
+ {`# pip install haystack-ai anthropic-haystack
+
+from haystack.tools import tool
+
+# Define tools
+@tool
+def multiply(a: int, b: int) -> int:
+ """Multiply \`a\` and \`b\`.
+
+ Args:
+ a: First int
+ b: Second int
+ """
+ return a * b
+
+@tool
+def add(a: int, b: int) -> int:
+ """Adds \`a\` and \`b\`.
+
+ Args:
+ a: First int
+ b: Second int
+ """
+ return a + b
+
+@tool
+def divide(a: int, b: int) -> float:
+ """Divide \`a\` and \`b\`.
+
+ Args:
+ a: First int
+ b: Second int
+ """
+ return a / b`}
+
+
+ {`# pip install langchain-anthropic langgraph langchain
+
+from langchain.tools import tool
+
+# Define tools
+@tool
+def multiply(a: int, b: int) -> int:
+ """Multiply \`a\` and \`b\`.
+
+ Args:
+ a: First int
+ b: Second int
+ """
+ return a * b
+
+@tool
+def add(a: int, b: int) -> int:
+ """Adds \`a\` and \`b\`.
+
+ Args:
+ a: First int
+ b: Second int
+ """
+ return a + b
+
+@tool
+def divide(a: int, b: int) -> float:
+ """Divide \`a\` and \`b\`.
+
+ Args:
+ a: First int
+ b: Second int
+ """
+ return a / b`}
+
+
+
+
+**Step 3: Set up message handling and LLM invocation**
+
+This is where the frameworks diverge more significantly. In Haystack you'll use a custom component (`MessageCollector`) to accumulate conversation history across the agentic loop. LangGraph instead defines a node function (`llm_call`) that operates on `MessagesState` - a built-in state container that automatically manages message history.
+
+
+ {`from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+
+# Augment the LLM with tools
+tools = [add, multiply, divide]
+model = AnthropicChatGenerator(
+ model="claude-sonnet-4-5-20250929",
+ generation_kwargs={"temperature": 0},
+ tools=tools,
+)`}
+
+
+ {`from langchain.chat_models import init_chat_model
+
+# Augment the LLM with tools
+model = init_chat_model(
+ "claude-sonnet-4-5-20250929",
+ temperature=0,
+)
+tools = [add, multiply, divide]
+tools_by_name = {tool.name: tool for tool in tools}
+llm_with_tools = model.bind_tools(tools)`}
+
+
+
+
+**Step 4: Execute tool calls**
+
+When the LLM decides to use a tool, it must be invoked and its result returned. Haystack provides a built-in `ToolInvoker` component that handles this automatically. LangGraph requires you to define a custom node function that iterates over tool calls, invokes each tool, and wraps the results in `ToolMessage` objects.
+
+
+ {`from typing import Any, Dict, List
+
+from haystack import component
+from haystack.core.component.types import Variadic
+from haystack.dataclasses import ChatMessage
+
+# Components
+
+# Custom component to temporarily store the messages
+@component()
+class MessageCollector:
+ def __init__(self):
+ self._messages = []
+
+ @component.output_types(messages=List[ChatMessage])
+ def run(self, messages: Variadic[List[ChatMessage]]) -> Dict[str, Any]:
+ self._messages.extend([msg for inner in messages for msg in inner])
+ return {"messages": self._messages}
+
+ def clear(self):
+ self._messages = []
+
+message_collector = MessageCollector()`}
+
+
+ {`from langgraph.graph import MessagesState
+from langchain.messages import SystemMessage, ToolMessage
+from typing import Literal
+
+# Nodes
+def llm_call(state: MessagesState):
+ # LLM decides whether to call a tool or not
+
+ return {
+ "messages": [
+ llm_with_tools.invoke(
+ [
+ SystemMessage(
+ content="You are a helpful assistant tasked with performing arithmetic on a set of inputs."
+ )
+ ]
+ + state["messages"]
+ )
+ ]
+ }`}
+
+
+
+
+**Step 5: Implement conditional routing logic**
+
+After the LLM responds, we need to decide whether to continue the loop (if tools were called) or finish (if the LLM provided a final answer). Haystack uses a `ConditionalRouter` component with declarative route conditions written in Jinja2 templates. LangGraph uses a conditional edge function (`should_continue`) that inspects the state and returns the next node or `END`.
+
+
+ {`from haystack.components.tools import ToolInvoker
+
+# Tool invoker component to execute a tool call
+tool_invoker = ToolInvoker(tools=tools)`}
+
+
+ {`def tool_node(state: dict):
+ # Performs the tool call
+ result = []
+ for tool_call in state["messages"][-1].tool_calls:
+ tool = tools_by_name[tool_call["name"]]
+ observation = tool.invoke(tool_call["args"])
+ result.append(ToolMessage(content=observation, tool_call_id=tool_call["id"]))
+ return {"messages": result}`}
+
+
+
+
+**Step 6: Assemble the workflow**
+
+This is where you wire together all the components or nodes. Haystack uses a `Pipeline` where you explicitly add components and connect their inputs and outputs, creating a directed graph with loops. LangGraph uses a `StateGraph` where you add nodes and edges, then compile the graph into an executable agent. Both approaches achieve the same agentic loop, but with different levels of explicitness.
+
+
+ {`from haystack.components.routers import ConditionalRouter
+
+# ConditionalRouter component to route to the tool invoker or end user based upon whether the LLM made a tool call
+routes = [
+ {
+ "condition": "{{replies[0].tool_calls | length > 0}}",
+ "output": "{{replies}}",
+ "output_name": "there_are_tool_calls",
+ "output_type": List[ChatMessage],
+ },
+ {
+ "condition": "{{replies[0].tool_calls | length == 0}}",
+ "output": "{{replies}}",
+ "output_name": "final_replies",
+ "output_type": List[ChatMessage],
+ },
+]
+router = ConditionalRouter(routes, unsafe=True)`}
+
+
+ {`from langgraph.graph import END
+
+# Conditional edge function to route to the tool node or end based upon whether the LLM made a tool call
+def should_continue(state: MessagesState) -> Literal["tool_node", END]:
+ # Decide if we should continue the loop or stop based upon whether the LLM made a tool call
+
+ messages = state["messages"]
+ last_message = messages[-1]
+
+ # If the LLM makes a tool call, then perform an action
+ if last_message.tool_calls:
+ return "tool_node"
+
+ # Otherwise, we stop (reply to the user)
+ return END`}
+
+
+
+
+**Step 7: Run the agent**
+
+Finally, we execute the agent with a user message. Haystack calls `.run()` on the pipeline with initial messages, while LangGraph calls `.invoke()` on the compiled agent. Both return the conversation history.
+
+
+ {`from haystack import Pipeline
+
+# Build pipeline
+agent_pipe = Pipeline()
+
+# Add components
+agent_pipe.add_component("message_collector", message_collector)
+agent_pipe.add_component("llm", model)
+agent_pipe.add_component("router", router)
+agent_pipe.add_component("tool_invoker", tool_invoker)
+
+# Add connections
+agent_pipe.connect("message_collector", "llm.messages")
+agent_pipe.connect("llm.replies", "router")
+agent_pipe.connect("router.there_are_tool_calls", "tool_invoker") # If there are tool calls, send them to the ToolInvoker
+agent_pipe.connect("router.there_are_tool_calls", "message_collector")
+agent_pipe.connect("tool_invoker.tool_messages", "message_collector")`}
+
+
+ {`from langgraph.graph import StateGraph, START
+
+# Build workflow
+agent_builder = StateGraph(MessagesState)
+
+# Add nodes
+agent_builder.add_node("llm_call", llm_call)
+agent_builder.add_node("tool_node", tool_node)
+
+# Add edges to connect nodes
+agent_builder.add_edge(START, "llm_call")
+agent_builder.add_conditional_edges(
+ "llm_call",
+ should_continue,
+ ["tool_node", END]
+)
+agent_builder.add_edge("tool_node", "llm_call")
+
+# Compile the agent
+agent = agent_builder.compile()`}
+
+
+
+
+### Creating Agents
+
+The [Agentic Flows](#agentic-flows-with-haystack-vs-langgraph) walkthrough above showed how to assemble an agent loop manually from pipeline primitives. Haystack also provides a high-level `Agent` class that wraps the full loop - LLM calls, tool invocation, and iteration - into a single component. LangGraph offers an equivalent shortcut through `create_react_agent` in `langgraph.prebuilt`. Both produce a ReAct-style agent that handles tool calling and multi-step reasoning automatically.
+
+
+ {`# Run the pipeline
+messages = [
+ ChatMessage.from_system(text="You are a helpful assistant tasked with performing arithmetic on a set of inputs."),
+ ChatMessage.from_user(text="Add 3 and 4.")
+]
+result = agent_pipe.run({"messages": messages})
+result`}
+
+
+ {`from langchain.messages import HumanMessage
+
+# Invoke
+messages = [
+ HumanMessage(content="Add 3 and 4.")
+]
+messages = agent.invoke({"messages": messages})
+for m in messages["messages"]:
+ m.pretty_print()`}
+
+
+
+
+### Connecting to Document Stores
+
+Document stores are the foundation of retrieval-augmented generation (RAG). In Haystack, document stores integrate natively with pipeline components like Retrievers and Prompt Builders via explicit typed connections. LangChain centers retrieval around its vector store abstraction composed using LCEL (LangChain Expression Language).
+
+Both frameworks offer in-memory stores for prototyping and a wide range of production backends (Elasticsearch, Qdrant, Weaviate, Pinecone, and more) via integrations.
+
+**Step 1: Create a document store and add documents**
+
+
+ {`# pip install haystack-ai anthropic-haystack
+
+from haystack.components.agents import Agent
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import tool
+
+@tool
+def multiply(a: int, b: int) -> int:
+ """Multiply \`a\` and \`b\`."""
+ return a * b
+
+@tool
+def add(a: int, b: int) -> int:
+ """Add \`a\` and \`b\`."""
+ return a + b
+
+# Create an agent - the agentic loop is handled automatically
+agent = Agent(
+ chat_generator=AnthropicChatGenerator(
+ model="claude-sonnet-4-5-20250929",
+ generation_kwargs={"temperature": 0},
+ ),
+ tools=[multiply, add],
+ system_prompt="You are a helpful assistant that performs arithmetic.",
+)
+
+result = agent.run(messages=[
+ ChatMessage.from_user("What is 3 multiplied by 7, then add 5?")
+])
+print(result["messages"][-1].text) # or print(result["last_message"].text)`}
+
+
+ {`# pip install langchain-anthropic langgraph
+
+from langchain_anthropic import ChatAnthropic
+from langchain_core.tools import tool
+from langchain.agents import create_agent
+from langchain_core.messages import HumanMessage, SystemMessage
+
+@tool
+def multiply(a: int, b: int) -> int:
+ """Multiply \`a\` and \`b\`."""
+ return a * b
+
+@tool
+def add(a: int, b: int) -> int:
+ """Add \`a\` and \`b\`."""
+ return a + b
+
+# Create an agent - the agentic loop is handled automatically
+model = ChatAnthropic(
+ model="claude-sonnet-4-5-20250929",
+ temperature=0,
+)
+agent = create_agent(
+ model,
+ tools=[multiply, add],
+ system_prompt=SystemMessage(
+ content="You are a helpful assistant that performs arithmetic."
+ ),
+)
+
+result = agent.invoke({
+ "messages": [HumanMessage(content="What is 3 multiplied by 7, then add 5?")]
+})
+print(result["messages"][-1].content)`}
+
+
+
+
+**Step 2: Build a RAG pipeline**
+
+
+ {`# pip install haystack-ai sentence-transformers
+
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+
+# Embed and write documents to the document store
+document_store = InMemoryDocumentStore()
+
+doc_embedder = SentenceTransformersDocumentEmbedder(
+ model="sentence-transformers/all-MiniLM-L6-v2"
+)
+
+docs = [
+ Document(content="Paris is the capital of France."),
+ Document(content="Berlin is the capital of Germany."),
+ Document(content="Tokyo is the capital of Japan."),
+]
+docs_with_embeddings = doc_embedder.run(docs)["documents"]
+document_store.write_documents(docs_with_embeddings)`}
+
+
+ {`# pip install langchain-community langchain-huggingface sentence-transformers
+
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_community.vectorstores import InMemoryVectorStore
+from langchain_core.documents import Document
+
+# Embed and add documents to the vector store
+embeddings = HuggingFaceEmbeddings(
+ model_name="sentence-transformers/all-MiniLM-L6-v2"
+)
+vectorstore = InMemoryVectorStore(embedding=embeddings)
+vectorstore.add_documents([
+ Document(page_content="Paris is the capital of France."),
+ Document(page_content="Berlin is the capital of Germany."),
+ Document(page_content="Tokyo is the capital of Japan."),
+])`}
+
+
+
+
+### Using MCP Tools
+
+Both frameworks support the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), letting agents connect to external tools and services exposed by MCP servers. Haystack provides [`MCPTool`](https://docs.haystack.deepset.ai/docs/mcptool) and [`MCPToolset`](https://docs.haystack.deepset.ai/docs/mcptoolset) through the `mcp-haystack` integration package, which plug directly into the `Agent` component. LangChain's MCP support relies on the separate `langchain-mcp-adapters` package and requires an async workflow throughout.
+
+
+ {`from haystack import Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+
+# ChatPromptBuilder expects a List[ChatMessage] as template
+template = [ChatMessage.from_user("""
+Given the following documents, answer the question.
+{% for doc in documents %}{{ doc.content }}{% endfor %}
+Question: {{ question }}
+""")]
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(
+ "text_embedder",
+ SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+)
+rag_pipeline.add_component(
+ "retriever", InMemoryEmbeddingRetriever(document_store=document_store)
+)
+rag_pipeline.add_component(
+ "prompt_builder", ChatPromptBuilder(template=template)
+)
+rag_pipeline.add_component(
+ "llm", AnthropicChatGenerator(model="claude-sonnet-4-5-20250929")
+)
+
+rag_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+rag_pipeline.connect("retriever.documents", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder.prompt", "llm.messages")
+
+result = rag_pipeline.run({
+ "text_embedder": {"text": "What is the capital of France?"},
+ "prompt_builder": {"question": "What is the capital of France?"},
+})
+print(result["llm"]["replies"][0].text)`}
+
+
+ {`from langchain_anthropic import ChatAnthropic
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.runnables import RunnablePassthrough
+
+def format_docs(docs):
+ return "\\n".join(doc.page_content for doc in docs)
+
+retriever = vectorstore.as_retriever()
+model = ChatAnthropic(model="claude-sonnet-4-5-20250929")
+
+template = """
+Given the following documents, answer the question.
+{context}
+Question: {question}
+"""
+prompt = ChatPromptTemplate.from_template(template)
+
+rag_chain = (
+ {"context": retriever | format_docs, "question": RunnablePassthrough()}
+ | prompt
+ | model
+ | StrOutputParser()
+)
+
+result = rag_chain.invoke("What is the capital of France?")
+print(result)`}
+
+
+
+
+## Hear from Haystack Users
+
+See how teams across industries use Haystack to power their production AI systems, from RAG applications to agentic workflows.
+
+> "_Haystack allows its users a production ready, easy to use framework that covers just about all of your needs, and allows you to write integrations easily for those it doesn't._"
+> **- Josh Longenecker, GenAI Specialist at AWS**
+>
+> _"Haystack's design philosophy significantly accelerates development and improves the robustness of AI applications, especially when heading towards production. The emphasis on explicit, modular components truly pays off in the long run."_
+> **- Rima Hajou, Data & AI Technical Lead at Accenture**
+
+### Featured Stories
+
+* [TELUS Agriculture & Consumer Goods Built an Agentic Chatbot with Haystack to Transform Trade Promotions Workflows](https://haystack.deepset.ai/blog/telus-user-story)
+* [Lufthansa Industry Solutions Uses Haystack to Power Enterprise RAG](https://haystack.deepset.ai/blog/lufthansa-user-story)
+
+## Start Building with Haystack
+
+**👉 Thinking about migrating or evaluating Haystack?** Jump right in with the [Haystack Get Started guide](https://haystack.deepset.ai/overview/quick-start) or [contact our team](https://www.deepset.ai/products-and-services/haystack-enterprise-starter), we'd love to support you.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/overview/migration.mdx b/docs-website/versioned_docs/version-2.29-unstable/overview/migration.mdx
new file mode 100644
index 0000000000..932b6917c0
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/overview/migration.mdx
@@ -0,0 +1,508 @@
+---
+title: "Migration Guide"
+id: migration
+slug: "/migration"
+description: "Learn how to make the move to Haystack 2.x from Haystack 1.x."
+---
+
+# Migration Guide
+
+Learn how to make the move to Haystack 2.x from Haystack 1.x.
+
+This guide is designed for those with previous experience with Haystack and who are interested in understanding the differences between Haystack 1.x and Haystack 2.x. If you're new to Haystack, skip this page and proceed directly to Haystack 2.x [documentation](get-started.mdx).
+
+## Major Changes
+
+Haystack 2.x represents a significant overhaul of Haystack 1.x, and it's important to note that certain key concepts outlined in this section don't have a direct correlation between the two versions.
+
+### Package Name
+
+Haystack 1.x was distributed with a package called `farm-haystack`. To migrate your application, you must uninstall `farm-haystack` and install the new `haystack-ai` package for Haystack 2.x.
+
+:::warning
+Two versions of the project cannot coexist in the same Python environment.
+
+One of the options is to remove both packages if they are installed in the same environment, followed by installing only one of them:
+
+```bash
+pip uninstall -y farm-haystack haystack-ai
+pip install haystack-ai
+```
+:::
+
+### Nodes
+
+While Haystack 2.x continues to rely on the `Pipeline` abstraction, the elements linked in a pipeline graph are now referred to as just _components_, replacing the terms _nodes_ and _pipeline components_ used in the previous versions. The [_Migrating Components_](#migrating-components) paragraph below outlines which component in Haystack 2.x can be used as a replacement for a specific 1.x node.
+
+### Pipelines
+
+Pipelines continue to serve as the fundamental structure of all Haystack applications. While the concept of `Pipeline` abstraction remains consistent, Haystack 2.x introduces significant enhancements that address various limitations of its predecessor. For instance, the pipelines now support loops. Pipelines also offer greater flexibility in their input, which is no longer restricted to queries. The pipeline now allows to route the output of a component to multiple recipients. This increases flexibility, however, comes with notable differences in the pipeline definition process in Haystack 2.x compared to the previous version.
+
+In Haystack 1.x, a pipeline was built by adding one node after the other. In the resulting pipeline graph, edges are automatically added to connect those nodes in the order they were added.
+
+Building a pipeline in Haystack 2.x is a two-step process:
+
+1. Initially, components are added to the pipeline without any specific order by calling the `add_component` method.
+2. Subsequently, the components must be explicitly connected by calling the `connect` method to define the final graph.
+
+To migrate an existing pipeline, the first step is to go through the nodes and identify their counterparts in Haystack 2.x (see the following section, [_Migrating Components_](#migrating-components), for guidance). If all the nodes can be replaced by corresponding components, they have to be added to the pipeline with `add_component` and explicitly connected with the appropriate calls to `connect`. Here is an example:
+
+**Haystack 1.x**
+
+```python
+pipeline = Pipeline()
+
+node_1 = SomeNode()
+node_2 = AnotherNode()
+
+pipeline.add_node(node_1, name="Node_1", inputs=["Query"])
+pipeline.add_node(node_2, name="Node_2", inputs=["Node_1"])
+```
+
+**Haystack 2.x**
+
+```python
+pipeline = Pipeline()
+
+component_1 = SomeComponent()
+component_2 = AnotherComponent()
+
+pipeline.add_component("Comp_1", component_1)
+pipeline.add_component("Comp_2", component_2)
+
+pipeline.connect("Comp_1", "Comp_2")
+```
+
+In case a specific replacement component is not available for one of your nodes, migrating the pipeline might still be possible by:
+
+- Either [creating a custom component](../concepts/components/custom-components.mdx), or
+- Changing the pipeline logic, as the last resort.
+
+:::info
+Check out the [Pipelines](../concepts/pipelines.mdx) section of our 2.x documentation to understand how new pipelines work more granularly.
+:::
+
+### Document Stores
+
+The fundamental concept of Document Stores as gateways to access text and metadata stored in a database didn’t change in Haystack 2.x, but there are significant differences against Haystack 1.x.
+
+In Haystack 1.x, Document Stores were a special type of node that you can use in two ways:
+
+- As the last node in an indexing pipeline (such as a pipeline whose ultimate goal is storing data in a database).
+- As a normal Python instance passed to a Retriever node.
+
+In Haystack 2.x, the Document Store is not a component, so to migrate the two use cases above to version 2.x, you can respectively:
+
+- Replace the Document Store at the end of the pipeline with a [`DocumentWriter`](../pipeline-components/writers/documentwriter.mdx) component.
+- Identify the right Retriever component and create it passing the Document Store instance, same as it is in Haystack 1.x.
+
+### Retrievers
+
+Haystack 1.x provided a set of nodes that filter relevant documents from different data sources according to a given query. Each of those nodes implements a certain retrieval algorithm and supports one or more types of Document Stores. For example, the `BM25Retriever` node in Haystack 1.x can work seamlessly with OpenSearch and Elasticsearch but not with Qdrant; the `EmbeddingRetriever`, on the contrary, can work with all the three databases.
+
+In Haystack 2.x, the concept is flipped, and each Document Store provides one or more retriever components, depending on which retrieval methods the underlying vector database supports. For example, the `OpenSearchDocumentStore` comes with [two Retriever components](../document-stores/opensearch-document-store.mdx#supported-retrievers), one relying on BM25, and the other on vector similarity.
+
+To migrate a 1.x retrieval pipeline to 2.x, the first step is to identify the Document Store being used and replace the Retriever node with the corresponding Retriever component from Haystack 2.x with the Document Store of choice. For example, a `BM25Retriever` node using Elasticsearch in a Haystack 1.x pipeline should be replaced with the [`ElasticsearchBM25Retriever`](../pipeline-components/retrievers/elasticsearchbm25retriever.mdx) component.
+
+### PromptNode
+
+The `PromptNode` in Haystack 1.x represented the gateway to any Large Language Model (LLM) inference provider, whether it is locally available or remote. Based on the name of the model, Haystack infers the right provider to call and forward the query.
+
+In Haystack 2.x, the task of using LLMs is assigned to [Generators](../pipeline-components/generators.mdx). These are a set of components that are highly specialized and tailored for each inference provider.
+
+The first step when migrating a pipeline with a `PromptNode` is to identify the model provider used and to replace the node with two components:
+
+- A Generator component for the model provider of choice,
+- A `PromptBuilder` or `ChatPromptBuilder` component to build the prompt to be used.
+
+The [_Migration examples_](#migration-examples) section below shows how to port a `PromptNode` using OpenAI with a prompt template to a corresponding Haystack 2.x pipeline using the `OpenAIGenerator` in conjunction with a `PromptBuilder` component.
+
+### Agents
+
+The agentic approach facilitates the answering of questions that are significantly more complex than those typically addressed by extractive or generative question answering techniques.
+
+Haystack 1.x provided Agents, enabling the use of LLMs in a loop.
+
+Currently in Haystack 2.x, you can build Agents using three main elements in a pipeline: Chat Generators, ToolInvoker component, and Tools. A standalone Agent abstraction in Haystack 2.x is in an experimental phase.
+
+:::note[Agents Documentation Page]
+
+Take a look at our 2.x [Agents](../concepts/agents.mdx) documentation page for more information and detailed examples.
+:::
+
+### REST API
+
+Haystack 1.x enabled the deployment of pipelines through a RESTful API over HTTP. This feature is facilitated by a separate application named `rest_api` which is exclusively accessible in the form of a [source code on GitHub](https://github.com/deepset-ai/haystack/tree/v1.x/rest_api).
+
+Haystack 2.x takes the same RESTful approach, but in this case, the application to be used to deploy pipelines is called [Hayhooks](../development/hayhooks.mdx) and can be installed with `pip install hayhooks`.
+
+At the moment, porting an existing Haystack 1.x deployment using the `rest_api` project to Hayhooks would require a complete rewrite of the application.
+
+## Dependencies
+
+In order to minimize runtime errors, Haystack 1.x was distributed in a package that’s quite large, as it tries to set up the Python environment with as many dependencies as possible.
+
+In contrast, Haystack 2.x strives for a more streamlined approach, offering a minimal set of dependencies right out of the box. It features a system that issues a warning when an additional dependency is required, thereby providing the user with the necessary instructions.
+
+To make sure all the dependencies are satisfied when migrating a Haystack 1.x application to version 2.x, a good strategy is to run end-to-end tests and cover all the execution paths to ensure all the required dependencies are available in the target Python environment.
+
+## Migrating Components
+
+This table outlines which component (or a group of components) can be used to replace a certain node when porting a Haystack 1.x pipeline to the latest 2.x version. It’s important to note that when a Haystack 2.x replacement is not available, this doesn’t necessarily mean we are planning this feature.
+
+If you need help migrating a 1.x node without a 2.x counterpart, open an [issue](https://github.com/deepset-ai/haystack/issues) in Haystack GitHub repository.
+
+### Data Handling
+
+| Haystack 1.x | Description | Haystack 2.x |
+| --- | --- | --- |
+| Crawler | Scrapes text from websites. **Example usage:** To run searches on your website content. | Not Available |
+| DocumentClassifier | Classifies documents by attaching metadata to them. **Example usage:** Labeling documents by their characteristic (for example, sentiment). | [TransformersZeroShotDocumentClassifier](../pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx) |
+| DocumentLanguageClassifier | Detects the language of the documents you pass to it and adds it to the document metadata. | [DocumentLanguageClassifier](../pipeline-components/classifiers/documentlanguageclassifier.mdx) |
+| EntityExtractor | Extracts predefined entities out of a piece of text. **Example usage:** Named entity extraction (NER). | [NamedEntityExtractor](../pipeline-components/extractors/namedentityextractor.mdx) |
+| FileClassifier | Distinguishes between text, PDF, Markdown, Docx, and HTML files. **Example usage:** Routing files to appropriate converters (for example, it routes PDF files to `PDFToTextConverter`). | [FileTypeRouter](../pipeline-components/routers/filetyperouter.mdx) |
+| FileConverter | Cleans and splits documents in different formats. **Example usage:** In indexing pipelines, extracting text from a file and casting it into the Document class format. | [Converters](../pipeline-components/converters.mdx) |
+| PreProcessor | Cleans and splits documents. **Example usage:** Normalizing white spaces, getting rid of headers and footers, splitting documents into smaller ones. | [PreProcessors](../pipeline-components/preprocessors.mdx) |
+
+### Semantic Search
+
+| Haystack 1.x | Description | Haystack 2.x |
+| --- | --- | --- |
+| Ranker | Orders documents based on how relevant they are to the query. **Example usage:** In a query pipeline, after a keyword-based Retriever to rank the documents it returns. | [Rankers](../pipeline-components/rankers.mdx) |
+| Reader | Finds an answer by selecting a text span in documents. **Example usage:** In a query pipeline when you want to know the location of the answer. | [ExtractiveReader](../pipeline-components/readers/extractivereader.mdx) |
+| Retriever | Fetches relevant documents from the Document Store. **Example usage:** Coupling Retriever with a Reader in a query pipeline to speed up the search (the Reader only goes through the documents it gets from the Retriever). | [Retrievers](../pipeline-components/retrievers.mdx) |
+| QuestionGenerator | When given a document, it generates questions this document can answer. **Example usage:** Auto-suggested questions in your search app. | Prompt [Builders](../pipeline-components/builders.mdx) with dedicated prompt, [Generators](../pipeline-components/generators.mdx) |
+
+### Prompts and LLMs
+
+| Haystack 1.x | Description | Haystack 2.x |
+| --- | --- | --- |
+| PromptNode | Uses large language models to perform various NLP tasks in a pipeline or on its own. **Example usage:** It's a very versatile component that can perform tasks like summarization, question answering, translation, and more. | Prompt [Builders](../pipeline-components/builders.mdx),[Generators](../pipeline-components/generators.mdx) |
+
+### Routing
+
+| Haystack 1.x | Description | Haystack 2.x |
+| --- | --- | --- |
+| QueryClassifier | Categorizes queries. **Example usage:** Distinguishing between keyword queries and natural language questions and routing them to the Retrievers that can handle them best. | [TransformersZeroShotTextRouter](../pipeline-components/routers/transformerszeroshottextrouter.mdx)
+ {`# pip install haystack-ai mcp-haystack anthropic-haystack
+
+from haystack_integrations.tools.mcp import MCPToolset, StdioServerInfo
+from haystack.components.agents import Agent
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+from haystack.dataclasses import ChatMessage
+
+# Connect to an MCP server - tools are auto-discovered
+toolset = MCPToolset(
+ server_info=StdioServerInfo(
+ command="uvx",
+ args=["mcp-server-fetch"],
+ )
+)
+
+agent = Agent(
+ chat_generator=AnthropicChatGenerator(model="claude-sonnet-4-5-20250929"),
+ tools=toolset,
+ system_prompt="You are a helpful assistant that can fetch web content.",
+)
+
+result = agent.run(messages=[
+ ChatMessage.from_user("Fetch the content from https://haystack.deepset.ai")
+])
+print(result["messages"][-1].text) # or print(result["last_message"].text)`}
+
+
+ {`# pip install langchain-mcp-adapters langgraph langchain-anthropic
+
+import asyncio
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain.agents import create_agent
+from langchain_anthropic import ChatAnthropic
+from langchain_core.messages import HumanMessage, SystemMessage
+
+model = ChatAnthropic(model="claude-sonnet-4-5-20250929")
+
+async def run():
+ client = MultiServerMCPClient(
+ {
+ "fetch": {
+ "command": "uvx",
+ "args": ["mcp-server-fetch"],
+ "transport": "stdio",
+ }
+ }
+ )
+ tools = await client.get_tools()
+ agent = create_agent(
+ model,
+ tools,
+ system_prompt=SystemMessage(
+ content="You are a helpful assistant that can fetch web content."
+ ),
+ )
+ result = await agent.ainvoke(
+ {
+ "messages": [
+ HumanMessage(content="Fetch the content from https://haystack.deepset.ai")
+ ]
+ }
+ )
+ print(result["messages"][-1].content)
+
+
+asyncio.run(run())`}
+
+[TransformersTextRouter](../pipeline-components/routers/transformerstextrouter.mdx) | +| RouteDocuments | Routes documents to different branches of your pipeline based on their content type or metadata field. **Example usage:** Routing table data to `TableReader` and text data to `TransfomersReader` for better handling. | [Routers](../pipeline-components/routers.mdx) | + +### Utility Components + +| Haystack 1.x | Description | Haystack 2.x | +| --- | --- | --- | +| DocumentMerger | Concatenates multiple documents into a single one. **Example usage: **Merge the documents to summarize in a summarization pipeline. | Prompt [Builders](../pipeline-components/builders.mdx) | +| Docs2Answers | Converts Documents into Answers. **Example usage:** When using REST API for document retrieval. REST API expects Answer as output, you can use `Doc2Answer` as the last node to convert the retrieved documents to answers. | [AnswerBuilder](../pipeline-components/builders/answerbuilder.mdx) | +| JoinAnswers | Takes answers returned by multiple components and joins them in a single list of answers. **Example usage:** For running queries on different document types (for example, tables and text), where the documents are routed to different readers, and each reader returns a separate list of answers. | [AnswerJoiner](../pipeline-components/joiners/answerjoiner.mdx) | +| JoinDocuments | Takes documents returned by different components and joins them to form one list of documents. **Example usage:** In document retrieval pipelines, where there are different types of documents, each routed to a different Retriever. Each Retriever returns a separate list of documents, and you can join them into one list using `JoinDocuments`. | [DocumentJoiner](../pipeline-components/joiners/documentjoiner.mdx) | +| Shaper | Currently functions mostly as `PromptNode` helper making sure the `PromptNode` input or output is correct. **Example usage:** In a question answering pipeline using `PromptNode`, where the `PromptTemplate` expects questions as input, while Haystack pipelines use query. You can use Shaper to rename queries to questions. | Prompt [Builders](../pipeline-components/builders.mdx) | +| Summarizer | Creates an overview of a document. **Example usage:** To get a glimpse of the documents the Retriever is returning. | Prompt [Builders](../pipeline-components/builders.mdx) with dedicated prompt, [Generators](../pipeline-components/generators.mdx) | +| TransformersImageToText | Generates captions for images. **Example usage:** Automatically generate captions for a list of images that you can later use in your knowledge base. | [VertexAIImageQA](../pipeline-components/generators/vertexaiimageqa.mdx) | +| Translator | Translates text from one language into another. **Example usage:** Running searches on documents in other languages. | Prompt [Builders](../pipeline-components/builders.mdx) with dedicated prompt, [Generators](../pipeline-components/generators.mdx) | + +### Extras + +| Haystack 1.x | Description | Haystack 2.x | +| --- | --- | --- | +| AnswerToSpeech | Converts text answers into speech answers. **Example usage:** Improving accessibility of your search system by providing a way to have the answer and its context read out loud. | [ElevenLabs](https://haystack.deepset.ai/integrations/elevenlabs) Integration | +| DocumentToSpeech | Converts text documents to speech documents. **Example usage:** Improving accessibility of a document retrieval pipeline by providing the option to read documents out loud. | [ElevenLabs](https://haystack.deepset.ai/integrations/elevenlabs) Integration | + +## Migration examples + +:::info +This section might grow as we assist users with their use cases. +::: + +### Indexing Pipeline + +
+
+
+
+Haystack 1.x
+ +```python +from haystack.document_stores import InMemoryDocumentStore +from haystack.nodes.file_classifier import FileTypeClassifier +from haystack.nodes.file_converter import TextConverter +from haystack.nodes.preprocessor import PreProcessor +from haystack.pipelines import Pipeline + +## Initialize a DocumentStore +document_store = InMemoryDocumentStore() + +## Indexing Pipeline +indexing_pipeline = Pipeline() + +## Makes sure the file is a TXT file (FileTypeClassifier node) +classifier = FileTypeClassifier() +indexing_pipeline.add_node(classifier, name="Classifier", inputs=["File"]) + +## Converts a file into text and performs basic cleaning (TextConverter node) +text_converter = TextConverter(remove_numeric_tables=True) +indexing_pipeline.add_node( + text_converter, + name="Text_converter", + inputs=["Classifier.output_1"], +) + +## Pre-processes the text by performing splits and adding metadata to the text (Preprocessor node) +preprocessor = PreProcessor( + clean_whitespace=True, + clean_empty_lines=True, + split_length=100, + split_overlap=50, + split_respect_sentence_boundary=True, +) +indexing_pipeline.add_node(preprocessor, name="Preprocessor", inputs=["Text_converter"]) + +## - Writes the resulting documents into the document store +indexing_pipeline.add_node( + document_store, + name="Document_Store", + inputs=["Preprocessor"], +) + +## Then we run it with the documents and their metadata as input +result = indexing_pipeline.run(file_paths=file_paths, meta=files_metadata) +``` + +
+
+
+
+### Query Pipeline
+
+Haystack 2.x
+ +```python +from haystack import Pipeline +from haystack.components.routers import FileTypeRouter +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.components.converters import TextFileToDocument +from haystack.components.preprocessors import DocumentCleaner, DocumentSplitter +from haystack.components.writers import DocumentWriter + +## Initialize a DocumentStore +document_store = InMemoryDocumentStore() + +## Indexing Pipeline +indexing_pipeline = Pipeline() + +## Makes sure the file is a TXT file (FileTypeRouter component) +classifier = FileTypeRouter(mime_types=["text/plain"]) +indexing_pipeline.add_component("file_type_router", classifier) + +## Converts a file into a Document (TextFileToDocument component) +text_converter = TextFileToDocument() +indexing_pipeline.add_component("text_converter", text_converter) + +## Performs basic cleaning (DocumentCleaner component) +cleaner = DocumentCleaner( + remove_empty_lines=True, + remove_extra_whitespaces=True, +) +indexing_pipeline.add_component("cleaner", cleaner) + +## Pre-processes the text by performing splits and adding metadata to the text (DocumentSplitter component) +preprocessor = DocumentSplitter(split_by="passage", split_length=100, split_overlap=50) +indexing_pipeline.add_component("preprocessor", preprocessor) + +## - Writes the resulting documents into the document store +indexing_pipeline.add_component("writer", DocumentWriter(document_store)) + +## Connect all the components +indexing_pipeline.connect("file_type_router.text/plain", "text_converter") +indexing_pipeline.connect("text_converter", "cleaner") +indexing_pipeline.connect("cleaner", "preprocessor") +indexing_pipeline.connect("preprocessor", "writer") + +## Then we run it with the documents and their metadata as input +result = indexing_pipeline.run({"file_type_router": {"sources": file_paths}}) +``` + +
+
+
+
+Haystack 1.x
+ +```python +from haystack.document_stores import InMemoryDocumentStore +from haystack.pipelines import ExtractiveQAPipeline +from haystack import Document +from haystack.nodes import BM25Retriever +from haystack.nodes import FARMReader + +document_store = InMemoryDocumentStore(use_bm25=True) +document_store.write_documents( + [ + Document(content="Paris is the capital of France."), + Document(content="Berlin is the capital of Germany."), + Document(content="Rome is the capital of Italy."), + Document(content="Madrid is the capital of Spain."), + ], +) + +retriever = BM25Retriever(document_store=document_store) +reader = FARMReader(model_name_or_path="deepset/roberta-base-squad2") +extractive_qa_pipeline = ExtractiveQAPipeline(reader, retriever) + +query = "What is the capital of France?" +result = extractive_qa_pipeline.run( + query=query, + params={"Retriever": {"top_k": 10}, "Reader": {"top_k": 5}}, +) +``` + +
+
+
+
+### RAG Pipeline
+
+Haystack 2.x
+ +```python +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack import Document, Pipeline +from haystack.components.retrievers.in_memory import InMemoryBM25Retriever +from haystack.components.readers import ExtractiveReader + +document_store = InMemoryDocumentStore() +document_store.write_documents( + [ + Document(content="Paris is the capital of France."), + Document(content="Berlin is the capital of Germany."), + Document(content="Rome is the capital of Italy."), + Document(content="Madrid is the capital of Spain."), + ], +) + +retriever = InMemoryBM25Retriever(document_store) +reader = ExtractiveReader(model="deepset/roberta-base-squad2") +extractive_qa_pipeline = Pipeline() +extractive_qa_pipeline.add_component("retriever", retriever) +extractive_qa_pipeline.add_component("reader", reader) +extractive_qa_pipeline.connect("retriever", "reader") + +query = "What is the capital of France?" +result = extractive_qa_pipeline.run( + data={ + "retriever": {"query": query, "top_k": 3}, + "reader": {"query": query, "top_k": 2}, + }, +) +``` + +
+
+
+
+Haystack 1.x
+ +```python +from datasets import load_dataset + +from haystack.pipelines import Pipeline +from haystack.document_stores import InMemoryDocumentStore +from haystack.nodes import EmbeddingRetriever, PromptNode, PromptTemplate, AnswerParser + +document_store = InMemoryDocumentStore(embedding_dim=384) +dataset = load_dataset("bilgeyucel/seven-wonders", split="train") +document_store.write_documents(dataset) +retriever = EmbeddingRetriever( + embedding_model="sentence-transformers/all-MiniLM-L6-v2", + document_store=document_store, + top_k=2, +) +document_store.update_embeddings(retriever) + +rag_prompt = PromptTemplate( + prompt="""Synthesize a comprehensive answer from the following text for the given question. + Provide a clear and concise response that summarizes the key points and information presented in the text. + Your answer should be in your own words and be no longer than 50 words. + \n\n Related text: {join(documents)} \n\n Question: {query} \n\n Answer:""", + output_parser=AnswerParser(), +) + +prompt_node = PromptNode( + model_name_or_path="gpt-3.5-turbo", + api_key=OPENAI_API_KEY, + default_prompt_template=rag_prompt, +) + +pipe = Pipeline() +pipe.add_node(component=retriever, name="retriever", inputs=["Query"]) +pipe.add_node(component=prompt_node, name="prompt_node", inputs=["retriever"]) + +output = pipe.run(query="What does Rhodes Statue look like?") +``` + +
+
+
+
+## Documentation and Tutorials for Haystack 1.x
+
+You can access old tutorials in the [GitHub history](https://github.com/deepset-ai/haystack-tutorials/tree/5917718cbfbb61410aab4121ee6fe754040a5dc7) and download the Haystack 1.x documentation as a [ZIP file](https://core-engineering.s3.eu-central-1.amazonaws.com/public/docs/haystack-v1-docs.zip).
+
+The ZIP file contains documentation for all minor releases from version 1.0 to 1.26.
+
+To download documentation for a specific release, replace the version number in the following URL: `https://core-engineering.s3.eu-central-1.amazonaws.com/public/docs/v1.26.zip`.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/overview/telemetry.mdx b/docs-website/versioned_docs/version-2.29-unstable/overview/telemetry.mdx
new file mode 100644
index 0000000000..206d12fa73
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/overview/telemetry.mdx
@@ -0,0 +1,76 @@
+---
+title: "Telemetry"
+id: telemetry
+slug: "/telemetry"
+description: "Haystack relies on anonymous usage statistics to continuously improve. That's why some basic information, like the type of Document Store used, is shared automatically."
+---
+
+# Telemetry
+
+Haystack relies on anonymous usage statistics to continuously improve. That's why some basic information, like the type of Document Store used, is shared automatically.
+
+## What Information Is Shared?
+
+Telemetry in Haystack comprises anonymous usage statistics of base components, such as `DocumentStore`, `Retriever`, `Reader`, or any other pipeline component. We receive an event every time these components are initialized. This way, we know which components are most relevant to our community. For the same reason, an event is also sent when one of the tutorials is executed.
+
+Each event contains an anonymous, randomly generated user ID (`uuid`) and a collection of properties about your execution environment. They **never** contain properties that can be used to identify you, such as:
+
+- IP addresses
+- Hostnames
+- File paths
+- Queries
+- Document contents
+
+By taking the above steps, we ensure that only anonymized data is transmitted to our telemetry server.
+
+Here is an exemplary event that is sent when tutorial 1 is executed by running `Tutorial1_Basic_QA_Pipeline.py`:
+
+```json
+{
+ "event": "tutorial 1 executed",
+ "distinct_id": "9baab867-3bc8-438c-9974-a192c9d53cd1",
+ "properties": {
+ "os_family": "Darwin",
+ "os_machine": "arm64",
+ "os_version": "21.3.0",
+ "haystack_version": "1.0.0",
+ "python_version": "3.9.6",
+ "torch_version": "1.9.0",
+ "transformers_version": "4.13.0",
+ "execution_env": "script",
+ "n_gpu": 0,
+ },
+}
+```
+
+Our telemetry code can be directly inspected on [GitHub](https://github.com/deepset-ai/haystack/blob/5d66d040cc303ab49225587cd61290f1987a5d1f/haystack/telemetry/_telemetry.py).
+
+## How Does Telemetry Help?
+
+Thanks to telemetry, we can understand the needs of the community: _"What pipeline nodes are most popular?", "Should we focus on supporting one specific Document Store?", "How many people use Haystack on Windows?"_ are some of the questions telemetry helps us answer. Metadata about the operating system and installed dependencies allows us to quickly identify and address issues caused by specific setups.
+
+In short, by sharing this information, you enable us to continuously improve Haystack for everyone.
+
+## How Can I Opt Out?
+
+You can disable telemetry with one of the following methods:
+
+### Through an Environment Variable
+
+You can disable telemetry by setting the environment variable `HAYSTACK_TELEMETRY_ENABLED` to `"False"` .
+
+### Using a Bash Shell
+
+If you are using a bash shell, add the following line to the file `~/.bashrc` to disable telemetry: `export HAYSTACK_TELEMETRY_ENABLED=False`.
+
+### Using zsh
+
+If you are using zsh as your shell, for example, on macOS, add the following line to the file `~/.zshrc`: `export HAYSTACK_TELEMETRY_ENABLED=False`.
+
+### On Windows
+
+To disable telemetry on Windows, set a user-level environment variable by running this command in the standard command prompt: `setx HAYSTACK_TELEMETRY_ENABLED "False"`.
+
+Alternatively, run the following command in Windows PowerShell: `[Environment]::SetEnvironmentVariable("HAYSTACK_TELEMETRY_ENABLED","False","User")`.
+
+You might need to restart the operating system for the command to take effect.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/agents-1/agent.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/agents-1/agent.mdx
new file mode 100644
index 0000000000..fef0f17e64
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/agents-1/agent.mdx
@@ -0,0 +1,470 @@
+---
+title: "Agent"
+id: agent
+slug: "/agent"
+description: "The `Agent` component is a tool-using agent that interacts with chat-based LLMs and tools to solve complex queries iteratively. It can execute external tools, manage state across multiple LLM calls, and stop execution based on configurable `exit_conditions`."
+---
+
+# Agent
+
+The `Agent` component is a tool-using agent that interacts with chat-based LLMs and tools to solve complex queries iteratively. It can execute external tools, manage state across multiple LLM calls, and stop execution based on configurable `exit_conditions`.
+
+Haystack 2.x
+ +```python +from datasets import load_dataset + +from haystack import Document, Pipeline +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.components.builders import PromptBuilder +from haystack.components.generators import OpenAIGenerator +from haystack.components.embedders import SentenceTransformersDocumentEmbedder +from haystack.components.embedders import SentenceTransformersTextEmbedder +from haystack.components.retrievers import InMemoryEmbeddingRetriever + +document_store = InMemoryDocumentStore() +dataset = load_dataset("bilgeyucel/seven-wonders", split="train") +embedder = SentenceTransformersDocumentEmbedder( + "sentence-transformers/all-MiniLM-L6-v2", +) +embedder.warm_up() +output = embedder.run([Document(**ds) for ds in dataset]) +document_store.write_documents(output.get("documents")) + +template = """ +Given the following information, answer the question. + +Context: +{% for document in documents %} + {{ document.content }} +{% endfor %} + +Question: {{question}} +Answer: +""" +prompt_builder = PromptBuilder(template=template) + +retriever = InMemoryEmbeddingRetriever(document_store=document_store, top_k=2) +generator = OpenAIGenerator(model="gpt-3.5-turbo") +query_embedder = SentenceTransformersTextEmbedder( + model="sentence-transformers/all-MiniLM-L6-v2", +) + +basic_rag_pipeline = Pipeline() +basic_rag_pipeline.add_component("text_embedder", query_embedder) +basic_rag_pipeline.add_component("retriever", retriever) +basic_rag_pipeline.add_component("prompt_builder", prompt_builder) +basic_rag_pipeline.add_component("llm", generator) + +basic_rag_pipeline.connect("text_embedder.embedding", "retriever.query_embedding") +basic_rag_pipeline.connect("retriever", "prompt_builder.documents") +basic_rag_pipeline.connect("prompt_builder", "llm") + +query = "What does Rhodes Statue look like?" +output = basic_rag_pipeline.run( + {"text_embedder": {"text": query}, "prompt_builder": {"question": query}}, +) +``` + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) or user input |
+| **Mandatory init variables** | `chat_generator`: An instance of a Chat Generator that supports tools |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx)s |
+| **Output variables** | `messages`: Chat history with tool and model responses |
+| **API reference** | [Agents](/reference/agents-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/agents/agent.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `Agent` component is a loop-based system that uses a chat-based large language model (LLM) and external tools to solve complex user queries.
+It works iteratively—calling tools, updating state, and generating prompts—until one of the configurable `exit_conditions` is met.
+
+It can:
+
+- Dynamically select tools based on user input,
+- Maintain and validate runtime state using a schema,
+- Stream token-level outputs from the LLM.
+
+The `Agent` returns a dictionary containing:
+
+- `messages`: the full conversation history,
+- `last_message`: the final `ChatMessage` from the agent,
+- Additional dynamic keys based on `state_schema`.
+
+## Parameters
+
+`chat_generator` is the only mandatory parameter — an instance of a Chat Generator that supports tools. All other parameters are optional.
+
+- `tools`: A list of tool or toolset instances the agent can call. Supported types: [`Tool`](../../tools/tool.mdx), [`ComponentTool`](../../tools/componenttool.mdx), [`PipelineTool`](../../tools/pipelinetool.mdx), [`MCPTool`](../../tools/mcptool.mdx), [`Toolset`](../../tools/toolset.mdx), [`MCPToolset`](../../tools/mcptoolset.mdx), [`SearchableToolset`](../../tools/searchabletoolset.mdx).
+- `system_prompt`: A plain string or Jinja2 template used as the system message for every run. If the template contains Jinja2 variables, those variables become additional inputs to `run()`.
+- `user_prompt`: A Jinja2 template appended to the user-provided messages on each run. Template variables become additional inputs to `run()`. Use `required_variables` to enforce which variables must be provided.
+- `exit_conditions`: List of conditions that cause the agent to stop. Use `”text”` to stop when the LLM replies without a tool call, or a tool name to stop once that tool has been executed. Defaults to `[“text”]`.
+- `state_schema`: Defines the agent's runtime state — a dict mapping key names to type configs (e.g. `{“docs”: {“type”: list[Document]}}`). Tools can read from and write to state keys via `inputs_from_state` and `outputs_to_state`. See [State](./state.mdx) for full details.
+- `streaming_callback`: A callback invoked for each streamed token. Use the built-in `print_streaming_chunk` for console output.
+- `max_agent_steps`: Maximum number of LLM + tool call iterations before the agent stops. Defaults to `100`.
+- `raise_on_tool_invocation_failure`: If `True`, raises an exception when a tool call fails. If `False` (default), the error is passed back to the LLM as a message so it can recover.
+- `confirmation_strategies`: A dict mapping tool names (or tuples of tool names) to a `ConfirmationStrategy`, enabling human review of tool calls before execution. See [Human in the Loop](./human-in-the-loop.mdx).
+- `tool_invoker_kwargs`: Additional keyword arguments forwarded to the internal `ToolInvoker`.
+
+### Runtime overrides
+
+`run()` also accepts parameters that override the init-time configuration for a single call:
+
+- `tools`: Pass a list of `Tool`/`Toolset` objects, or a list of tool name strings to select a subset of the agent's configured tools for this run.
+- `generation_kwargs`: Additional keyword arguments forwarded to the LLM, overriding any set at init time (e.g. `{“temperature”: 0.2}`).
+
+:::info
+For the full parameter reference, see the [Agents API Documentation](/reference/agents-api).
+:::
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import tool
+from haystack.components.agents import Agent
+from typing import Annotated
+
+
+@tool(outputs_to_state={"calc_result": {"source": "result"}})
+def calculator(
+ expression: Annotated[str, "Math expression to evaluate, e.g. '7 * (4 + 2)'"],
+) -> dict:
+ """Evaluate basic math expressions."""
+ try:
+ result = eval(expression, {"__builtins__": {}})
+ return {"result": result}
+ except Exception as e:
+ return {"error": str(e)}
+
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[calculator],
+ system_prompt="You are a helpful assistant. Always use the calculator tool to evaluate math expressions.",
+ state_schema={"calc_result": {"type": int}},
+)
+
+response = agent.run(messages=[ChatMessage.from_user("What is 7 * (4 + 2)?")])
+
+print(response["last_message"].text)
+print("Calc Result:", response.get("calc_result"))
+```
+
+### In a pipeline
+
+The example pipeline below creates a database assistant using `OpenAIChatGenerator`, `LinkContentFetcher`, and custom database tool.
+It reads the given URL and processes the page content, then builds a prompt for the AI.
+The assistant uses this information to write people's names and titles from the given page to the database.
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.converters.html import HTMLToDocument
+from haystack.components.fetchers.link_content import LinkContentFetcher
+from haystack import Document, Pipeline
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.tools import tool
+from typing import Annotated, Optional
+
+document_store = InMemoryDocumentStore() # create a document store or an SQL database
+
+
+@tool
+def add_database_tool(
+ name: Annotated[str, "First name of the person"],
+ surname: Annotated[str, "Last name of the person"],
+ job_title: Annotated[Optional[str], "Job title or role of the person"] = None,
+ other: Annotated[Optional[str], "Any other relevant information"] = None,
+) -> str:
+ """Add a person to the database with information about them."""
+ document_store.write_documents(
+ [
+ Document(
+ content=name + " " + surname + " " + (job_title or ""),
+ meta={"other": other},
+ ),
+ ],
+ )
+ # Returning a confirmation lets the agent know the tool call succeeded
+ return f"Successfully added {name} {surname} to the database."
+
+
+database_assistant = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[add_database_tool],
+ system_prompt="""
+ You are a database assistant.
+ Your task is to extract the names of people mentioned in the given context and add them to a knowledge base,
+ along with additional relevant information about them that can be extracted from the context.
+ Do not use your own knowledge, stay grounded to the given context.
+ Do not ask the user for confirmation.
+ Instead, automatically update the knowledge base and return a brief summary of the people added,
+ including the information stored for each.
+ """,
+)
+
+extraction_agent = Pipeline()
+extraction_agent.add_component("fetcher", LinkContentFetcher())
+extraction_agent.add_component("converter", HTMLToDocument())
+extraction_agent.add_component(
+ "builder",
+ ChatPromptBuilder(
+ template=[
+ ChatMessage.from_user("""
+ {% for doc in docs %}
+ {{ doc.content|default|truncate(25000) }}
+ {% endfor %}
+ """),
+ ],
+ required_variables=["docs"],
+ ),
+)
+
+extraction_agent.add_component("database_agent", database_assistant)
+extraction_agent.connect("fetcher.streams", "converter.sources")
+extraction_agent.connect("converter.documents", "builder.docs")
+extraction_agent.connect("builder", "database_agent")
+
+agent_output = extraction_agent.run(
+ {
+ "fetcher": {
+ "urls": ["https://github.com/deepset-ai/haystack/releases/tag/v2.27.0"],
+ },
+ },
+)
+
+print(agent_output["database_agent"]["last_message"].text)
+
+# Inspect what was written to the document store
+written_docs = document_store.filter_documents()
+print(f"\n{len(written_docs)} people added to the database:")
+for doc in written_docs:
+ print(f" - {doc.content}")
+```
+
+### In YAML
+The example pipeline below fetches a webpage, converts its HTML to text, and builds a chat prompt combining the page content with a user query.
+The `Agent` then answers the question based on the provided content and can use its web search tool to find additional information if needed.
+
+
+
+
+## Streaming
+
+You can stream output as it's generated. Pass a callback to `streaming_callback`.
+Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[...],
+ system_prompt="...",
+ streaming_callback=print_streaming_chunk,
+)
+```
+
+See our [Streaming Support](../generators/guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default.
+Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+## Multimodal Inputs
+
+Agents support multimodal inputs when paired with a vision-capable model such as `gpt-5` (OpenAI) or `gemini-2.5-flash` (Google).
+Pass images alongside text by including `ImageContent` objects in the `content_parts` of a `ChatMessage`:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+
+image = ImageContent.from_url("https://example.com/chart.png")
+result = agent.run(
+ messages=[
+ ChatMessage.from_user(content_parts=["What does this chart show?", image]),
+ ],
+)
+```
+
+Tools can also return `ImageContent` directly, letting the agent fetch and reason about images dynamically during its loop.
+Two things are required: set `outputs_to_string={"raw_result": True}` so the `ToolInvoker` skips string conversion, and return a `list[ImageContent]` (the tool result type is `str | Sequence[TextContent | ImageContent]`).
+
+The standard Chat Completions API doesn't support images in tool results — use `OpenAIResponsesChatGenerator` (OpenAI's Responses API) instead:
+
+```python
+from typing import Annotated
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack.tools import tool
+
+
+@tool(outputs_to_string={"raw_result": True})
+def fetch_image(
+ url: Annotated[str, "URL of the image to fetch and analyze"],
+) -> list[ImageContent]:
+ """Fetch an image from a URL so the agent can analyze its contents."""
+ return [ImageContent.from_url(url)]
+
+
+agent = Agent(
+ chat_generator=OpenAIResponsesChatGenerator(model="gpt-5"),
+ tools=[fetch_image],
+ system_prompt="You are a helpful assistant that can fetch and analyze images from URLs.",
+)
+
+result = agent.run(
+ messages=[
+ ChatMessage.from_user(
+ "Fetch the image at https://picsum.photos/seed/haystack/640/480 and describe what you see.",
+ ),
+ ],
+)
+print(result["last_message"].text)
+```
+
+`ImageContent` can be created from a URL, a local file path, or a PDF page using the `PDFToImageContent` converter.
+
+### In a pipeline
+
+When an `Agent` sits inside a pipeline, use `ChatPromptBuilder` with its string template format and the `| templatize_part` filter to pass images as structured content parts:
+
+```python
+from haystack import Pipeline
+from haystack.components.agents import Agent
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ImageContent
+
+template = """
+{% message role="user" %}
+{{ question }}
+{{ image | templatize_part }}
+{% endmessage %}
+"""
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5"),
+ system_prompt="You are a helpful assistant that can analyze images.",
+)
+prompt_builder = ChatPromptBuilder(
+ template=template,
+ required_variables=["question", "image"],
+)
+
+pipeline = Pipeline()
+pipeline.add_component("prompt_builder", prompt_builder)
+pipeline.add_component("agent", agent)
+pipeline.connect("prompt_builder.prompt", "agent.messages")
+
+# Download or provide your own chart image as "chart.png"
+image = ImageContent.from_file_path("chart.png")
+result = pipeline.run(
+ {
+ "prompt_builder": {"question": "What does this chart show?", "image": image},
+ },
+)
+print(result["agent"]["last_message"].text)
+```
+
+:::tip
+See these cookbooks for complete multimodal agent examples:
+- [Multimodal Agents](https://haystack.deepset.ai/cookbook/multimodal_intro#multimodal-agent) — image inputs and tool use with agents
+- [Gemma Chat RAG](https://haystack.deepset.ai/cookbook/gemma_chat_rag) — vision model in a RAG pipeline
+:::
+
+## Multi-Agent Systems
+
+You can wrap an `Agent` as a tool to build multi-agent systems where specialist agents handle focused subtasks and a coordinator agent plans and delegates.
+
+See [Multi-Agent Systems](../../concepts/agents/multi-agent-systems.mdx) for a full guide, including the recommended `@tool` decorator approach for full interface control and `ComponentTool` for declarative configuration.
+
+## MCP Integration
+
+Agents work with MCP in two directions:
+
+- **Consuming MCP tools**: Pass `MCPTool` or `MCPToolset` instances in the `tools` list to call tools on any MCP-compatible server (filesystem, browser, databases, and more). See [MCPTool](../../tools/mcptool.mdx) and [MCPToolset](../../tools/mcptoolset.mdx).
+- **Exposing as an MCP server**: Use [Hayhooks](../../development/hayhooks.mdx) to deploy your agent and expose it as an MCP server, making it callable from any MCP-compatible client such as Claude Desktop or Cursor.
+
+## Additional References
+
+📖 Related docs:
+
+- [State](./state.mdx) — managing shared data between tools
+- [Human in the Loop](./human-in-the-loop.mdx) — intercepting tool calls for human review
+
+📚 Tutorials:
+
+- [Build a Tool-Calling Agent](https://haystack.deepset.ai/tutorials/43_building_a_tool_calling_agent)
+- [Creating a Multi-Agent System](https://haystack.deepset.ai/tutorials/45_creating_a_multi_agent_system)
+- [Human-in-the-Loop with Haystack Agents](https://haystack.deepset.ai/tutorials/47_human_in_the_loop_agent/)
+
+🧑🍳 Cookbook:
+
+- [Build a GitHub Issue Resolver Agent](https://haystack.deepset.ai/cookbook/github_issue_resolver_agent)
+- [Multimodal Agents](https://haystack.deepset.ai/cookbook/multimodal_intro#multimodal-agent)
+- [Gemma Chat RAG](https://haystack.deepset.ai/cookbook/gemma_chat_rag)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/agents-1/human-in-the-loop.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/agents-1/human-in-the-loop.mdx
new file mode 100644
index 0000000000..3899fc6106
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/agents-1/human-in-the-loop.mdx
@@ -0,0 +1,305 @@
+---
+title: "Human in the Loop"
+id: human-in-the-loop
+slug: "/human-in-the-loop"
+description: "Human-in-the-loop allows you to intercept agent tool calls before execution, letting a human confirm, reject, or modify the tool parameters."
+---
+
+# Human in the Loop
+
+Human-in-the-loop (HITL) lets you intercept an agent's tool calls before they are executed.
+A human can **confirm**, **reject**, or **modify** the parameters of each tool call in real time.
+This is useful for high-stakes operations - such as sending emails, modifying databases, or making API calls - where you want a human to review the action first.
+
+View YAML
+ +```yaml +components: + agent: + init_parameters: + chat_generator: + init_parameters: + api_base_url: null + api_key: + env_vars: + - OPENAI_API_KEY + strict: true + type: env_var + generation_kwargs: {} + http_client_kwargs: null + max_retries: null + model: gpt-5.4-nano + organization: null + streaming_callback: null + timeout: null + tools: null + tools_strict: false + type: haystack.components.generators.chat.openai.OpenAIChatGenerator + confirmation_strategies: null + exit_conditions: + - text + max_agent_steps: 5 + raise_on_tool_invocation_failure: false + required_variables: null + state_schema: {} + streaming_callback: null + system_prompt: You are a helpful assistant. Use the web search tool to find + information when needed. + tool_invoker_kwargs: null + tools: + - data: + component: + init_parameters: + allowed_domains: null + api_key: + env_vars: + - SERPERDEV_API_KEY + strict: true + type: env_var + exclude_subdomains: false + search_params: {} + top_k: 3 + type: haystack.components.websearch.serper_dev.SerperDevWebSearch + description: Search the web for current information on any topic + inputs_from_state: null + name: web_search + outputs_to_state: null + outputs_to_string: null + parameters: null + type: haystack.tools.component_tool.ComponentTool + user_prompt: null + type: haystack.components.agents.agent.Agent + converter: + init_parameters: + extraction_kwargs: {} + store_full_path: false + type: haystack.components.converters.html.HTMLToDocument + fetcher: + init_parameters: + client_kwargs: + follow_redirects: true + timeout: 3 + http2: false + raise_on_failure: true + request_headers: {} + retry_attempts: 2 + timeout: 3 + user_agents: + - haystack/LinkContentFetcher/2.27.0rc0 + type: haystack.components.fetchers.link_content.LinkContentFetcher + prompt_builder: + init_parameters: + required_variables: + - docs + - query + template: + - content: + - text: 'Based on the following content: + + {% for doc in docs %} + + {{ doc.content }} + + {% endfor %} + + Answer this question: {{ query }}' + meta: {} + name: null + role: user + variables: null + type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder +connection_type_validation: true +connections: +- receiver: converter.sources + sender: fetcher.streams +- receiver: prompt_builder.docs + sender: converter.documents +- receiver: agent.messages + sender: prompt_builder.prompt +max_runs_per_component: 100 +metadata: {} +``` + +
+
+| | |
+| --- | --- |
+| **Configured on** | The [`Agent`](./agent.mdx) component via `confirmation_strategies` |
+| **Key classes** | `BlockingConfirmationStrategy`, `AlwaysAskPolicy`, `AskOncePolicy`, `NeverAskPolicy`, `RichConsoleUI`, `SimpleConsoleUI` |
+| **Import path** | `haystack.human_in_the_loop` |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/human_in_the_loop/ |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The HITL system is composed of three layers:
+
+- **Strategy** - decides what to do when a tool is about to be called. The built-in `BlockingConfirmationStrategy` pauses execution and asks a human.
+- **Policy** - decides *when* to ask. Built-in policies: `AlwaysAskPolicy`, `NeverAskPolicy`, `AskOncePolicy`.
+- **UI** - the interface used to ask the human. Built-in UIs: `RichConsoleUI` (requires `rich`) and `SimpleConsoleUI` (stdlib only).
+
+When the agent is about to invoke a tool, the strategy checks the policy.
+If the policy says to ask, the UI prompts the human with the tool name, description, and parameters. The human can:
+
+- **Confirm** (`y`) - execute as-is
+- **Reject** (`n`) - skip execution and feed rejection feedback back to the LLM
+- **Modify** (`m`) - edit the parameters before execution
+
+The agent then continues with the human's decision.
+
+## Usage
+
+### Basic setup
+
+```python
+from typing import Annotated
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.human_in_the_loop import (
+ AlwaysAskPolicy,
+ BlockingConfirmationStrategy,
+ SimpleConsoleUI,
+)
+from haystack.tools import tool
+
+
+@tool
+def send_email(
+ to: Annotated[str, "The recipient email address"],
+ subject: Annotated[str, "The email subject line"],
+ body: Annotated[str, "The email body"],
+) -> str:
+ """Send an email to a recipient."""
+ return f"Email sent to {to}."
+
+
+strategy = BlockingConfirmationStrategy(
+ confirmation_policy=AlwaysAskPolicy(),
+ confirmation_ui=SimpleConsoleUI(),
+)
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-mini"),
+ tools=[send_email],
+ confirmation_strategies={"send_email": strategy},
+)
+
+result = agent.run(
+ messages=[ChatMessage.from_user("Send a welcome email to alice@example.com")],
+)
+```
+
+When the agent calls `send_email`, the terminal will pause and show:
+
+```
+--- Tool Execution Request ---
+Tool: send_email
+Description: Send an email to a recipient.
+Arguments:
+ to: alice@example.com
+ subject: Welcome!
+ body: Hi Alice, welcome aboard!
+------------------------------
+Confirm execution? (y=confirm / n=reject / m=modify):
+```
+
+### Using RichConsoleUI
+
+`RichConsoleUI` provides a styled terminal prompt using the [`rich`](https://github.com/Textualize/rich) library:
+
+```shell
+pip install rich
+```
+
+```python
+from haystack.human_in_the_loop import RichConsoleUI
+
+strategy = BlockingConfirmationStrategy(
+ confirmation_policy=AlwaysAskPolicy(),
+ confirmation_ui=RichConsoleUI(),
+)
+```
+
+### Applying strategies to multiple tools
+
+You can configure different strategies per tool, or share one strategy across a group of tools using a tuple key:
+
+```python
+@tool
+def delete_record(record_id: Annotated[str, "The ID of the record to delete"]) -> str:
+ """Delete a record from the database."""
+ return f"Record {record_id} deleted."
+
+
+@tool
+def update_record(
+ record_id: Annotated[str, "The ID of the record to update"],
+ data: Annotated[str, "The new data as a JSON string"],
+) -> str:
+ """Update a record in the database."""
+ return f"Record {record_id} updated."
+
+
+@tool
+def search(query: Annotated[str, "The search query"]) -> str:
+ """Search the knowledge base."""
+ return f"Results for: {query}"
+
+
+ask_strategy = BlockingConfirmationStrategy(
+ confirmation_policy=AlwaysAskPolicy(),
+ confirmation_ui=SimpleConsoleUI(),
+)
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-mini"),
+ tools=[send_email, delete_record, update_record, search],
+ confirmation_strategies={
+ # Share one strategy across multiple sensitive tools using a tuple key
+ ("send_email", "delete_record", "update_record"): ask_strategy,
+ # search has no strategy - always executes without asking
+ },
+)
+```
+
+### Customizing feedback messages
+
+When a tool call is rejected or modified, `BlockingConfirmationStrategy` sends a message back to the LLM explaining what happened. Three optional template parameters control these messages — each has a sensible default, so you only need to set them if you want different wording:
+
+- `reject_template`: Sent to the LLM when the user rejects a tool call. Must include a `{tool_name}` placeholder. Default: `"Tool execution for '{tool_name}' was rejected by the user."`
+- `modify_template`: Sent when the user modifies the parameters. Must include `{tool_name}` and `{final_tool_params}` placeholders. Default: `"The parameters for tool '{tool_name}' were updated by the user to:\n{final_tool_params}"`
+- `user_feedback_template`: Appends the user's optional free-text feedback to either message. Must include a `{feedback}` placeholder. Default: `"With user feedback: {feedback}"`
+
+```python
+strategy = BlockingConfirmationStrategy(
+ confirmation_policy=AlwaysAskPolicy(),
+ confirmation_ui=SimpleConsoleUI(),
+ reject_template="Skipping '{tool_name}' — rejected by operator.",
+ modify_template="Updated parameters for '{tool_name}': {final_tool_params}",
+ user_feedback_template="Reason: {feedback}",
+)
+```
+
+## Policies
+
+Policies control *when* the human is asked.
+
+| Policy | Behavior |
+| --- | --- |
+| `AlwaysAskPolicy` | Ask every time the tool is called |
+| `NeverAskPolicy` | Never ask - always proceed (useful for toggling HITL off without removing the strategy) |
+| `AskOncePolicy` | Ask once per unique `(tool_name, parameters)` combination. Remembers confirmed calls and skips asking on repeats. |
+
+### Custom policy
+
+You can implement your own policy by subclassing `ConfirmationPolicy` from `haystack.human_in_the_loop.types`:
+
+```python
+from haystack.human_in_the_loop.types import ConfirmationPolicy, ConfirmationUIResult
+from typing import Any
+
+
+class AskForSensitiveParamsPolicy(ConfirmationPolicy):
+ """Only ask when the 'to' parameter looks like an external email domain."""
+
+ def should_ask(
+ self,
+ tool_name: str,
+ tool_description: str,
+ tool_params: dict[str, Any],
+ ) -> bool:
+ to = tool_params.get("to", "")
+ return not to.endswith("@mycompany.com")
+```
+
+For stateful policies, also implement `update_after_confirmation`.
+It is called after the user responds and receives the full `ConfirmationUIResult`, letting you update internal state based on the outcome.
+The following policy asks once per tool name and skips re-asking for any tool the user has already confirmed:
+
+```python
+from haystack.human_in_the_loop.types import ConfirmationPolicy
+from haystack.human_in_the_loop import ConfirmationUIResult
+from typing import Any
+
+
+class AskOncePerToolPolicy(ConfirmationPolicy):
+ """Ask once per tool name, regardless of parameters. Skip on repeat confirmed calls."""
+
+ def __init__(self) -> None:
+ self._confirmed_tools: set[str] = set()
+
+ def should_ask(
+ self,
+ tool_name: str,
+ tool_description: str,
+ tool_params: dict[str, Any],
+ ) -> bool:
+ return tool_name not in self._confirmed_tools
+
+ def update_after_confirmation(
+ self,
+ tool_name: str,
+ tool_description: str,
+ tool_params: dict[str, Any],
+ confirmation_result: ConfirmationUIResult,
+ ) -> None:
+ if confirmation_result.action == "confirm":
+ self._confirmed_tools.add(tool_name)
+```
+
+## Dataclasses
+
+### `ConfirmationUIResult`
+
+Returned by the UI after the human responds.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `action` | `str` | `"confirm"`, `"reject"`, or `"modify"` |
+| `feedback` | `str \| None` | Optional free-text feedback from the human |
+| `new_tool_params` | `dict \| None` | Replacement parameters when action is `"modify"` |
+
+### `ToolExecutionDecision`
+
+Returned by the strategy to the agent.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tool_name` | `str` | Name of the tool |
+| `execute` | `bool` | Whether to execute the tool |
+| `tool_call_id` | `str \| None` | ID of the tool call |
+| `feedback` | `str \| None` | Feedback message passed back to the LLM on rejection or modification |
+| `final_tool_params` | `dict \| None` | Final parameters to use for execution |
+
+## Example: HITL with Hayhooks and Open WebUI
+
+The [hitl-hayhooks-redis-openwebui](https://github.com/deepset-ai/hitl-hayhooks-redis-openwebui) repository shows a full production-style HITL setup using a Haystack Agent served via [Hayhooks](https://github.com/deepset-ai/hayhooks) with approval dialogs rendered in [Open WebUI](https://github.com/open-webui/open-webui).
+
+The key pattern it demonstrates is a custom `RedisConfirmationStrategy` that uses `confirmation_strategy_context` to pass per-request resources - a Redis client and an async event queue - into the strategy at runtime:
+
+- When a tool call is about to execute, the strategy emits a `tool_call_start` SSE event and blocks on `Redis BLPOP` waiting for an approval decision.
+- The Open WebUI Pipe function receives the SSE event, shows the user a confirmation dialog, then writes `approved` or `rejected` to Redis via `LPUSH`.
+- Once Redis unblocks, the strategy returns a `ToolExecutionDecision` and the agent continues.
+
+This is a good reference if you need non-blocking HITL in a web or server environment where `SimpleConsoleUI` and `RichConsoleUI` are not suitable.
+
+## Custom UI
+
+Implement `ConfirmationUI` from `haystack.human_in_the_loop.types` to build your own interface - for example, a web-based approval queue:
+
+```python
+from haystack.human_in_the_loop.types import ConfirmationUI
+from haystack.human_in_the_loop import ConfirmationUIResult
+from typing import Any
+
+
+class WebhookApprovalUI(ConfirmationUI):
+ """Sends a webhook and waits for an async approval response."""
+
+ def get_user_confirmation(
+ self,
+ tool_name: str,
+ tool_description: str,
+ tool_params: dict[str, Any],
+ ) -> ConfirmationUIResult:
+ # Send approval request to your system and wait for response
+ response = send_approval_request_and_wait(tool_name, tool_params)
+ return ConfirmationUIResult(
+ action=response["action"],
+ feedback=response.get("feedback"),
+ )
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/agents-1/state.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/agents-1/state.mdx
new file mode 100644
index 0000000000..1a124636dc
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/agents-1/state.mdx
@@ -0,0 +1,415 @@
+---
+title: "State"
+id: state
+slug: "/state"
+description: "`State` is a container for storing shared information during Agent and Tool execution. It provides a structured way to share data between tools, accumulate results across multiple tool calls, and surface them alongside the agent's final answer."
+---
+
+# State
+
+`State` is a container for storing shared information during Agent and Tool execution.
+It provides a structured way to share data between tools, accumulate results across multiple tool calls, and surface them alongside the agent's final answer.
+
+## Overview
+
+When building agents that use multiple tools, you often need tools to share information or accumulate results across iterations.
+State provides centralized storage that all tools can read from and write to.
+For example, a search tool called multiple times can append its results to a shared `documents` list, which is then returned alongside the agent's final answer for source inspection.
+
+State uses a schema-based approach where you define:
+
+- What data can be stored,
+- The type of each piece of data,
+- How values are merged when updated.
+
+The Agent creates and manages the `State` object internally. You shouldn't need to instantiate it directly.
+You interact with it through tool definitions (`inputs_from_state`, `outputs_to_state`, or a `state: State` parameter) and read results from the agent's output dict.
+
+### Supported Types
+
+State supports standard Python types:
+
+- Basic types: `str`, `int`, `float`, `bool`, `dict`
+- List types: `list`, `list[str]`, `list[int]`, `list[Document]`
+- Union types: `str | int`, `str | None`
+- Custom classes and data classes.
+
+### Automatic Message Handling
+
+State automatically includes a `messages` field that stores the full conversation history during execution.
+You don't need to define this in your schema.
+It uses `list[ChatMessage]` type with the `merge_lists` handler, so new messages are appended on each iteration.
+
+### State API
+
+| Method | Description |
+| --- | --- |
+| `state.get(key, default=None)` | Read a value; returns `default` if the key doesn't exist |
+| `state.set(key, value)` | Write a value, merged using the schema's handler |
+| `state.has(key)` | Returns `True` if the key exists in state |
+| `state.data` | Returns a snapshot of all current state as a `dict` |
+
+## Schema Definition
+
+The schema defines what data can be stored and how values are updated. Each schema entry consists of:
+
+- `type` (required): The Python type for this field (for example, `str`, `int`, `list`)
+- `handler` (optional): A callable that determines how new values are merged when `set()` is called
+
+```python
+{
+ "parameter_name": {
+ "type": SomeType, # Required: expected Python type
+ "handler": some_func, # Optional: merge function
+ },
+}
+```
+
+If you don't specify a handler, State automatically assigns a default based on the type.
+
+### Default Handlers
+
+State provides two built-in merge behaviors (importable from `haystack.components.agents.state`):
+
+- **`merge_lists`**: Appends to the existing list (default for list types)
+- **`replace_values`**: Overwrites the existing value (default for non-list types)
+
+```python
+from haystack.components.agents import State
+
+schema = {
+ "documents": {"type": list}, # uses merge_lists by default
+ "user_name": {"type": str}, # uses replace_values by default
+}
+
+state = State(schema=schema)
+
+state.set("documents", [1, 2])
+state.set("documents", [3, 4])
+print(state.get("documents")) # [1, 2, 3, 4]
+
+state.set("user_name", "Alice")
+state.set("user_name", "Bob")
+print(state.get("user_name")) # "Bob"
+```
+
+### Custom Handlers
+
+Custom handlers are useful when the default `merge_lists` or `replace_values` behaviors don't fit your needs.
+A handler takes the current state value and the new value and returns the merged result.
+
+The example below uses a deduplication handler, useful when multiple tool calls might return overlapping results and you want to avoid accumulating duplicates in state:
+
+```python
+def deduplicate(current_value: list | None, new_value: list) -> list:
+ """Append new items, skipping any already in the list."""
+ existing = set(current_value or [])
+ return (current_value or []) + [item for item in new_value if item not in existing]
+
+
+schema = {"doc_ids": {"type": list, "handler": deduplicate}}
+
+state = State(schema=schema)
+state.set("doc_ids", ["doc-1", "doc-2"])
+state.set("doc_ids", ["doc-2", "doc-3"])
+print(state.get("doc_ids")) # ["doc-1", "doc-2", "doc-3"]
+```
+
+You can also override the handler for a single `set()` call:
+
+```python
+from haystack.components.agents import State
+
+
+def concatenate_strings(current: str | None, new: str) -> str:
+ return f"{current}-{new}" if current else new
+
+
+state = State(schema={"user_name": {"type": str}})
+state.set("user_name", "Alice")
+state.set("user_name", "Bob", handler_override=concatenate_strings)
+print(state.get("user_name")) # "Alice-Bob"
+```
+
+## Using State
+
+Define a `state_schema` when creating the Agent.
+State keys declared in `state_schema` are exposed as output keys on the agent's result dict alongside `messages` and `last_message`.
+
+Tools interact with State through three mechanisms:
+
+- **`outputs_to_state`**: Write tool results to state keys after the tool runs.
+- **`inputs_from_state`**: Inject state values into tool parameters before the tool runs.
+- **Direct `State` injection**: Add a `state: State` parameter to your tool function's signature. The Agent detects the `State` annotation and injects the live `State` object automatically, so you can read or write any key defined in the schema. The `State` object is never exposed to the LLM's parameter schema.
+
+### Reading from State: `inputs_from_state`
+
+`inputs_from_state` maps state keys to function parameter names using the format `{"state_key": "param_name"}`.
+The value is injected from state before the tool runs, so the LLM never needs to provide it.
+
+Parameters mapped via `inputs_from_state` are automatically excluded from the LLM's parameter schema.
+The model never sees or provides them:
+
+```python
+from typing import Annotated
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage
+from haystack.tools import tool
+
+
+@tool(inputs_from_state={"user_name": "user_context"})
+def search_documents(
+ query: Annotated[str, "The search query"],
+ user_context: str, # injected from state; excluded from LLM schema
+) -> dict:
+ """Search documents using query and user context."""
+ return {"results": [f"Found results for '{query}' (user: {user_context})"]}
+
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[search_documents],
+ system_prompt="Use the search_documents tool to find information.",
+ streaming_callback=print_streaming_chunk,
+ state_schema={"user_name": {"type": str}},
+)
+
+result = agent.run(
+ messages=[ChatMessage.from_user("Search for Python tutorials")],
+ user_name="Alice", # state key "user_name" is pre-populated by passing user_name= to agent.run()
+)
+
+print(result["last_message"].text)
+```
+
+### Writing to State: `outputs_to_state`
+
+The `outputs_to_state` parameter maps tool output keys to state keys. Each entry supports two optional fields:
+
+```python
+{
+ "state_key": {
+ "source": "tool_output_key", # which key to read from the tool's return dict; omit to store the entire dict
+ "handler": some_func, # override the schema's merge handler for this mapping only
+ },
+}
+```
+
+```python
+from typing import Annotated
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage
+from haystack.tools import tool
+
+
+@tool(
+ outputs_to_state={
+ "documents": {"source": "documents"},
+ "result_count": {"source": "count"},
+ "last_query": {"source": "query"},
+ },
+)
+def retrieve_documents(
+ query: Annotated[str, "The search query"],
+) -> dict:
+ """Retrieve relevant documents."""
+ return {
+ "documents": [
+ {"title": "Doc 1", "content": "Content about Python"},
+ {"title": "Doc 2", "content": "More about Python"},
+ ],
+ "count": 2,
+ "query": query,
+ }
+
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[retrieve_documents],
+ system_prompt="Use the retrieve_documents tool to find information.",
+ streaming_callback=print_streaming_chunk,
+ state_schema={
+ "documents": {"type": list},
+ "result_count": {"type": int},
+ "last_query": {"type": str},
+ },
+)
+
+result = agent.run(messages=[ChatMessage.from_user("Find information about Python")])
+
+print(f"Documents: {result['documents']}")
+print(f"Result count: {result['result_count']}")
+print(f"Last query: {result['last_query']}")
+```
+
+If you omit `source`, the entire tool result dict is stored under the state key:
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage
+from haystack.tools import tool
+
+
+@tool(outputs_to_state={"user_info": {}})
+def get_user_info() -> dict:
+ """Get user information."""
+ return {"name": "Alice", "email": "alice@example.com", "role": "admin"}
+
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[get_user_info],
+ system_prompt="Use the get_user_info tool to look up user details.",
+ streaming_callback=print_streaming_chunk,
+ state_schema={"user_info": {"type": dict}},
+)
+
+result = agent.run(messages=[ChatMessage.from_user("What are the user's details?")])
+
+print(result["last_message"].text)
+print(f"User info: {result['user_info']}")
+```
+
+### Combining Inputs and Outputs
+
+Tools can both read from and write to State, enabling tool chaining across iterations.
+This example builds on `retrieve_documents` from the previous section:
+
+```python
+@tool(
+ inputs_from_state={"documents": "documents"},
+ outputs_to_state={
+ "final_docs": {"source": "processed_docs"},
+ "final_count": {"source": "processed_count"},
+ },
+)
+def process_documents(
+ max_results: Annotated[int, "Maximum number of documents to return"],
+ documents: list = None, # injected from state; LLM does not provide this
+) -> dict:
+ """Process retrieved documents and return a filtered subset."""
+ processed = (documents or [])[:max_results]
+ return {"processed_docs": processed, "processed_count": len(processed)}
+
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[retrieve_documents, process_documents], # chained through state
+ system_prompt="Use the available tools to retrieve and process documents.",
+ streaming_callback=print_streaming_chunk,
+ state_schema={
+ "documents": {"type": list},
+ "result_count": {"type": int},
+ "last_query": {"type": str},
+ "final_docs": {"type": list},
+ "final_count": {"type": int},
+ },
+)
+
+result = agent.run(
+ messages=[ChatMessage.from_user("Find and process 3 documents about Python")],
+)
+print(f"Processed {result['final_count']} documents")
+```
+
+### Injecting State Directly into Tools
+
+As an alternative to `inputs_from_state` and `outputs_to_state`, a tool can declare a `state: State` parameter to receive the live `State` object at invocation time.
+This lets the tool read from and write to any number of state keys without declaring mappings upfront.
+
+The ToolInvoker detects the `State` annotation and injects the object automatically.
+It is excluded from the LLM-facing schema. The model is never asked to supply it.
+Both `State` and `State | None` annotations are supported.
+
+For function-based tools, add the `state` parameter and use the `@tool` decorator:
+
+```python
+from typing import Annotated
+from haystack.components.agents import Agent, State
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage, Document
+from haystack.tools import tool
+
+
+@tool
+def retrieve_and_store(
+ query: Annotated[str, "The search query"],
+ state: State,
+) -> str:
+ """Retrieve documents and store them directly in state."""
+ documents = [Document(content=f"Result for '{query}'")]
+ state.set("documents", documents)
+ user_name = state.get("user_name", "unknown")
+ return f"Retrieved {len(documents)} document(s) for {user_name}"
+
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[retrieve_and_store],
+ system_prompt="Use the retrieve_and_store tool to find documents.",
+ streaming_callback=print_streaming_chunk,
+ state_schema={"documents": {"type": list[Document]}, "user_name": {"type": str}},
+)
+
+result = agent.run(
+ messages=[ChatMessage.from_user("Find documents about Python")],
+ user_name="Alice",
+)
+
+print(result["last_message"].text)
+print(result["documents"])
+```
+
+For component-based tools, declare a `State` input socket on the `run` method and wrap it with `ComponentTool`:
+
+```python
+from haystack import component
+from haystack.components.agents import Agent, State
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage, Document
+from haystack.tools import ComponentTool
+
+
+@component
+class DocumentRetriever:
+ """Retrieve documents and store them in state."""
+
+ @component.output_types(reply=str)
+ def run(self, query: str, state: State) -> dict[str, str]:
+ """
+ Retrieve documents based on query and store them in state.
+
+ :param query: The search query
+ """
+ documents = [Document(content=f"Result for '{query}'")]
+ state.set("documents", documents)
+ return {"reply": f"Retrieved {len(documents)} document(s)"}
+
+
+retriever_tool = ComponentTool(
+ component=DocumentRetriever(),
+ name="retrieve",
+ description="Retrieve documents based on a search query",
+)
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[retriever_tool],
+ system_prompt="Use the retrieve tool to find documents.",
+ streaming_callback=print_streaming_chunk,
+ state_schema={"documents": {"type": list[Document]}},
+)
+
+result = agent.run(messages=[ChatMessage.from_user("Find documents about Python")])
+
+print(result["last_message"].text)
+print(result["documents"])
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio.mdx
new file mode 100644
index 0000000000..4cf9c334ea
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio.mdx
@@ -0,0 +1,15 @@
+---
+title: "Audio"
+id: audio
+slug: "/audio"
+description: "Use these components to work with audio in Haystack by transcribing files or converting text to audio."
+---
+
+# Audio
+
+Use these components to work with audio in Haystack by transcribing files or converting text to audio.
+
+| Name | Description |
+| --- | --- |
+| [LocalWhisperTranscriber](audio/localwhispertranscriber.mdx) | Transcribe audio files using OpenAI's Whisper model using your local installation of Whisper. |
+| [RemoteWhisperTranscriber](audio/remotewhispertranscriber.mdx) | Transcribe audio files using OpenAI's Whisper model. |
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio/external-integrations-audio.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio/external-integrations-audio.mdx
new file mode 100644
index 0000000000..c1ac4ce894
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio/external-integrations-audio.mdx
@@ -0,0 +1,15 @@
+---
+title: "External Integrations"
+id: external-integrations-audio
+slug: "/external-integrations-audio"
+description: "External integrations that enable working with audio in Haystack by transcribing files or converting text to audio."
+---
+
+# External Integrations
+
+External integrations that enable working with audio in Haystack by transcribing files or converting text to audio.
+
+| Name | Description |
+| --- | --- |
+| [AssemblyAI](https://haystack.deepset.ai/integrations/assemblyai) | Perform speech recognition, speaker diarization and summarization. |
+| [Elevenlabs](https://haystack.deepset.ai/integrations/elevenlabs) | Convert text to speech using ElevenLabs’ API. |
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio/localwhispertranscriber.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio/localwhispertranscriber.mdx
new file mode 100644
index 0000000000..a050bebcb5
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio/localwhispertranscriber.mdx
@@ -0,0 +1,90 @@
+---
+title: "LocalWhisperTranscriber"
+id: localwhispertranscriber
+slug: "/localwhispertranscriber"
+description: "Use `LocalWhisperTranscriber` to transcribe audio files using OpenAI's Whisper model using your local installation of Whisper."
+---
+
+# LocalWhisperTranscriber
+
+Use `LocalWhisperTranscriber` to transcribe audio files using OpenAI's Whisper model using your local installation of Whisper.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | As the first component in an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of paths or binary streams that you want to transcribe |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Audio](/reference/audio-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/audio/whisper_local.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The component also needs to know which Whisper model to work with. Specify this in the `model` parameter when initializing the component. All transcription is completed on the executing machine, and the audio is never sent to a third-party provider.
+
+See other optional parameters you can specify in our [API documentation](/reference/audio-api).
+
+See the [Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper [GitHub repo](https://github.com/openai/whisper) for the supported audio formats and languages.
+
+To work with the `LocalWhisperTranscriber`, install torch and [Whisper](https://github.com/openai/whisper) first with the following commands:
+
+```python
+pip install 'transformers[torch]'
+pip install -U openai-whisper
+```
+
+## Usage
+
+### On its own
+
+Here’s an example of how to use `LocalWhisperTranscriber` on its own:
+
+```python
+import requests
+from haystack.components.audio import LocalWhisperTranscriber
+
+response = requests.get(
+ "https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3",
+)
+with open("kennedy_speech.mp3", "wb") as file:
+ file.write(response.content)
+
+transcriber = LocalWhisperTranscriber(model="tiny")
+
+transcription = transcriber.run(sources=["./kennedy_speech.mp3"])
+print(transcription["documents"][0].content)
+```
+
+### In a pipeline
+
+The pipeline below fetches an audio file from a specified URL and transcribes it. It first retrieves the audio file using `LinkContentFetcher`, then transcribes the audio into text with `LocalWhisperTranscriber`, and finally outputs the transcription text.
+
+```python
+from haystack.components.audio import LocalWhisperTranscriber
+from haystack.components.fetchers import LinkContentFetcher
+from haystack import Pipeline
+
+pipe = Pipeline()
+pipe.add_component("fetcher", LinkContentFetcher())
+pipe.add_component("transcriber", LocalWhisperTranscriber(model="tiny"))
+
+pipe.connect("fetcher", "transcriber")
+result = pipe.run(
+ data={
+ "fetcher": {
+ "urls": [
+ "https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3",
+ ],
+ },
+ },
+)
+print(result["transcriber"]["documents"][0].content)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Multilingual RAG from a podcast with Whisper, Qdrant and Mistral](https://haystack.deepset.ai/cookbook/multilingual_rag_podcast)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio/remotewhispertranscriber.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio/remotewhispertranscriber.mdx
new file mode 100644
index 0000000000..c7e1704b55
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/audio/remotewhispertranscriber.mdx
@@ -0,0 +1,98 @@
+---
+title: "RemoteWhisperTranscriber"
+id: remotewhispertranscriber
+slug: "/remotewhispertranscriber"
+description: "Use `RemoteWhisperTranscriber` to transcribe audio files using OpenAI's Whisper model."
+---
+
+# RemoteWhisperTranscriber
+
+Use `RemoteWhisperTranscriber` to transcribe audio files using OpenAI's Whisper model.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | As the first component in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with an environment variable `OPENAI_API_KEY`. |
+| **Mandatory run variables** | `sources`: A list of paths or binary streams that you want to transcribe |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Audio](/reference/audio-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/audio/whisper_remote.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`RemoteWhisperTranscriber` works with OpenAI-compatible clients and isn't limited to just OpenAI as a provider. For example, [Groq](https://console.groq.com/docs/speech-text) offers a drop-in replacement that can be used as well. You can set the API key in one of two ways:
+
+1. Through the `api_key` initialization parameter, where the key is resolved using [Secret API](../../concepts/secret-management.mdx).
+2. By setting it in the `OPENAI_API_KEY` environment variable, which the system will use to access the key.
+
+```python
+from haystack.components.audio import RemoteWhisperTranscriber
+
+transcriber = RemoteWhisperTranscriber()
+```
+
+Additionally, the component requires the following parameters to work:
+
+- `model` specifies the Whisper model.
+- `api_base_url` specifies the OpenAI base URL and defaults to `"https://api.openai.com/v1"`. If you are using Whisper provider other than OpenAI set this parameter according to provider's documentation.
+
+See other optional parameters in our [API documentation](/reference/audio-api).
+
+See the [Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper [GitHub repo](https://github.com/openai/whisper) for the supported audio formats and languages.
+
+## Usage
+
+### On its own
+
+Here’s an example of how to use `RemoteWhisperTranscriber` to transcribe a local file:
+
+```python
+import requests
+from haystack.components.audio import RemoteWhisperTranscriber
+
+response = requests.get(
+ "https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3",
+)
+with open("kennedy_speech.mp3", "wb") as file:
+ file.write(response.content)
+
+transcriber = RemoteWhisperTranscriber()
+transcription = transcriber.run(sources=["./kennedy_speech.mp3"])
+
+print(transcription["documents"][0].content)
+```
+
+### In a pipeline
+
+The pipeline below fetches an audio file from a specified URL and transcribes it. It first retrieves the audio file using `LinkContentFetcher`, then transcribes the audio into text with `RemoteWhisperTranscriber`, and finally outputs the transcription text.
+
+```python
+from haystack.components.audio import RemoteWhisperTranscriber
+from haystack.components.fetchers import LinkContentFetcher
+from haystack import Pipeline
+
+pipe = Pipeline()
+pipe.add_component("fetcher", LinkContentFetcher())
+pipe.add_component("transcriber", RemoteWhisperTranscriber())
+
+pipe.connect("fetcher", "transcriber")
+result = pipe.run(
+ data={
+ "fetcher": {
+ "urls": [
+ "https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3",
+ ],
+ },
+ },
+)
+print(result["transcriber"]["documents"][0].content)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Multilingual RAG from a podcast with Whisper, Qdrant and Mistral](https://haystack.deepset.ai/cookbook/multilingual_rag_podcast)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders.mdx
new file mode 100644
index 0000000000..49b72d883c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders.mdx
@@ -0,0 +1,13 @@
+---
+title: "Builders"
+id: builders
+slug: "/builders"
+---
+
+# Builders
+
+| Component | Description |
+| --- | --- |
+| [AnswerBuilder](builders/answerbuilder.mdx) | Creates `GeneratedAnswer` objects from the query and the answer. |
+| [PromptBuilder](builders/promptbuilder.mdx) | Renders prompt templates with given parameters. |
+| [ChatPromptBuilder](builders/chatpromptbuilder.mdx) | PromptBuilder for chat messages. |
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders/answerbuilder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders/answerbuilder.mdx
new file mode 100644
index 0000000000..6b4d38ae89
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders/answerbuilder.mdx
@@ -0,0 +1,114 @@
+---
+title: "AnswerBuilder"
+id: answerbuilder
+slug: "/answerbuilder"
+description: "Use this component in pipelines that contain a Generator to parse its replies."
+---
+
+# AnswerBuilder
+
+Use this component in pipelines that contain a Generator to parse its replies.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Use in pipelines (such as a RAG pipeline) after a [Generator](../generators.mdx) component to create [`GeneratedAnswer`](../../concepts/data-classes.mdx#generatedanswer) objects from its replies. |
+| **Mandatory run variables** | `query`: A query string
`replies`: A list of strings, or a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects that are replies from a Generator | +| **Output variables** | `answers`: A list of `GeneratedAnswer` objects | +| **API reference** | [Builders](/reference/builders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/builders/answer_builder.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`AnswerBuilder` takes a query and the replies a Generator returns as input and parses them into `GeneratedAnswer` objects. Optionally, it also takes documents and metadata from the Generator as inputs to enrich the `GeneratedAnswer` objects.
+
+The `AnswerBuilder` works with both Chat and non-Chat Generators.
+
+The optional `pattern` parameter defines how to extract answer texts from replies. It needs to be a regular expression with a maximum of one capture group. If a capture group is present, the text matched by the capture group is used as the answer. If no capture group is present, the whole match is used as the answer. If no `pattern` is set, the whole reply is used as the answer text.
+
+The optional `reference_pattern` parameter can be set to a regular expression that parses referenced documents from the replies so that only those referenced documents are listed in the `GeneratedAnswer` objects. Haystack assumes that documents are referenced by their index in the list of input documents and that indices start at 1. For example, if you set the `reference_pattern` to _`\\[(\\d+)\\]`,_ it finds “1” in a string "This is an answer[1]". If `reference_pattern` is not set, all input documents are listed in the `GeneratedAnswer` objects.
+
+## Usage
+
+### On its own
+
+Below is an example where we’re using the `AnswerBuilder` to parse a string that could be the reply received from a Generator using a custom regular expression. Any text other than the answer will not be included in the `GeneratedAnswer` object constructed by the builder.
+
+```python
+from haystack.components.builders import AnswerBuilder
+
+builder = AnswerBuilder(pattern="Answer: (.*)")
+builder.run(
+ query="What's the answer?",
+ replies=["This is an argument. Answer: This is the answer."],
+)
+```
+
+### In a pipeline
+
+Below is an example of a RAG pipeline where we use an `AnswerBuilder` to create `GeneratedAnswer` objects from the replies returned by a Generator. In addition to the text of the reply, these objects also hold the query, the referenced docs, and metadata returned by the Generator.
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.utils import Secret
+from haystack.dataclasses import ChatMessage
+from haystack.dataclasses import Document
+
+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:",
+ ),
+]
+
+docs = [
+ Document(content="The capital of France is Paris"),
+ Document(content="The capital of England is London"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+p = Pipeline()
+p.add_component(
+ instance=InMemoryBM25Retriever(document_store=document_store),
+ name="retriever",
+)
+p.add_component(
+ instance=ChatPromptBuilder(
+ template=prompt_template,
+ required_variables={"query", "documents"},
+ ),
+ name="prompt_builder",
+)
+p.add_component(
+ instance=OpenAIChatGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")),
+ name="llm",
+)
+p.add_component(instance=AnswerBuilder(), name="answer_builder")
+p.connect("retriever", "prompt_builder.documents")
+p.connect("prompt_builder", "llm.messages")
+p.connect("llm.replies", "answer_builder.replies")
+p.connect("retriever", "answer_builder.documents")
+
+query = "What is the capital of France?"
+result = p.run(
+ {
+ "retriever": {"query": query},
+ "prompt_builder": {"query": query},
+ "answer_builder": {"query": query},
+ },
+)
+
+print(result)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders/chatpromptbuilder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders/chatpromptbuilder.mdx
new file mode 100644
index 0000000000..7a4f09bd94
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders/chatpromptbuilder.mdx
@@ -0,0 +1,451 @@
+---
+title: "ChatPromptBuilder"
+id: chatpromptbuilder
+slug: "/chatpromptbuilder"
+description: "This component constructs prompts dynamically by processing chat messages."
+---
+
+# ChatPromptBuilder
+
+This component constructs prompts dynamically by processing chat messages.
+
+`replies`: A list of strings, or a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects that are replies from a Generator | +| **Output variables** | `answers`: A list of `GeneratedAnswer` objects | +| **API reference** | [Builders](/reference/builders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/builders/answer_builder.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [Generator](../generators.mdx) |
+| **Mandatory init variables** | `template`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects or a special string template. Needs to be provided either during init or run. |
+| **Mandatory run variables** | `**kwargs`: Any strings that should be used to render the prompt template. See [Variables](#variables) section for more details. |
+| **Output variables** | `prompt`: A dynamically constructed prompt |
+| **API reference** | [Builders](/reference/builders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/builders/chat_prompt_builder.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `ChatPromptBuilder` component creates prompts using static or dynamic templates written in [Jinja2](https://palletsprojects.com/p/jinja/) syntax, by processing a list of chat messages or a special string template. The templates contain placeholders like `{{ variable }}` that are filled with values provided during runtime. You can use it for static prompts set at initialization or change the templates and variables dynamically while running.
+
+To use it, start by providing a list of `ChatMessage` objects or a special string as the template.
+
+[`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) is a data class that includes message content, a role (who generated the message, such as `user`, `assistant`, `system`, `tool`), and optional metadata.
+
+The builder looks for placeholders in the template and identifies the required variables. You can also list these variables manually. During runtime, the `run` method takes the template and the variables, fills in the placeholders, and returns the completed prompt. If required variables are missing. If the template is invalid, the builder raises an error.
+
+For example, you can create a simple translation prompt:
+
+```python
+template = [ChatMessage.from_user("Translate to {{ target_language }}: {{ text }}")]
+builder = ChatPromptBuilder(template=template)
+result = builder.run(target_language="French", text="Hello, how are you?")
+```
+
+Or you can also replace the template at runtime with a new one:
+
+```python
+new_template = [
+ ChatMessage.from_user("Summarize in {{ target_language }}: {{ content }}"),
+]
+result = builder.run(
+ template=new_template,
+ target_language="English",
+ content="A detailed paragraph.",
+)
+```
+
+### Variables
+
+The template variables found in the init template are used as input types for the component. If there are no `required_vairables` set, all variables are considered optional by default. In this case, any missing variables are replaced with empty strings, which can lead to unintended behavior, especially in complex pipelines.
+
+Use `required_variables` and `variables` to specify the input types and required variables:
+
+- `required_variables`
+ - Defines which template variables must be provided when the component runs.
+ - If any required variable is missing, the component raises an error and halts execution.
+ - You can:
+ - Pass a list of required variable names (such as `["name"]`), or
+ - Use `"*"` to mark all variables in the template as required.
+
+- `variables`
+ - Lists all variables that can appear in the template, whether required or optional.
+ - Optional variables that aren't provided are replaced with an empty string in the rendered prompt.
+ - This allows partial prompts to be constructed without errors, unless a variable is marked as required.
+
+In the example below, only _name_ is required to run the component, while _topic_ is only an optional variable:
+
+```python
+template = [
+ ChatMessage.from_user("Hello, {{ name }}. How can I assist you with {{ topic }}?"),
+]
+
+builder = ChatPromptBuilder(
+ template=template,
+ required_variables=["name"],
+ variables=["name", "topic"],
+)
+
+result = builder.run(name="Alice")
+## Output: "Hello, Alice. How can I assist you with ?"
+```
+
+The component only waits for the required inputs before running.
+
+### Roles
+
+A [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) represents a single message in the conversation and can have one of three class methods that build the chat messages: `from_user`, `from_system`, or `from_assistant`. `from_user` messages are inputs provided by the user, such as a query or request. `from_system` messages provide context or instructions to guide the LLM’s behavior, such as setting a tone or purpose for the conversation. `from_assistant` defines the expected or actual response from the LLM.
+
+Here’s how the roles work together in a `ChatPromptBuilder`:
+
+```python
+system_message = ChatMessage.from_system(
+ "You are an assistant helping tourists in {{ language }}.",
+)
+
+user_message = ChatMessage.from_user("What are the best places to visit in {{ city }}?")
+
+assistant_message = ChatMessage.from_assistant(
+ "The best places to visit in {{ city }} include the Eiffel Tower, Louvre Museum, and Montmartre.",
+)
+```
+
+### String Templates
+
+Instead of a list of `ChatMessage` objects, you can also express the template as a special string.
+
+This template format allows you to define `ChatMessage` sequences using Jinja2 syntax. Each `{% message %}` block defines a single message with a specific role, and you can insert dynamic content using `{{ variables }}`.
+
+Compared to using a list of `ChatMessage`s, this format is more flexible and allows including structured parts like images in the templatized `ChatMessage`; to better understand this use case, check out the [multimodal example](#multimodal) in the Usage section below.
+
+### Jinja2 Time Extension
+
+`PromptBuilder` supports the Jinja2 TimeExtension, which allows you to work with datetime formats.
+
+The Time Extension provides two main features:
+
+1. A `now` tag that gives you access to the current time,
+2. Date/time formatting capabilities through Python's datetime module.
+
+To use the Jinja2 TimeExtension, you need to install a dependency with:
+
+```shell
+pip install arrow>=1.3.0
+```
+
+#### The `now` Tag
+
+The `now` tag creates a datetime object representing the current time, which you can then store in a variable:
+
+```jinja2
+{% now 'utc' as current_time %}
+The current UTC time is: {{ current_time }}
+```
+
+You can specify different timezones:
+
+```jinja2
+{% now 'America/New_York' as ny_time %}
+The time in New York is: {{ ny_time }}
+```
+
+If you don't specify a timezone, your system's local timezone will be used:
+
+```jinja2
+{% now as local_time %}
+Local time: {{ local_time }}
+```
+
+#### Date Formatting
+
+You can format the datetime objects using Python's `strftime` syntax:
+
+```jinja2
+{% now as current_time %}
+Formatted date: {{ current_time.strftime('%Y-%m-%d %H:%M:%S') }}
+```
+
+The common format codes are:
+
+- `%Y`: 4-digit year (for example, 2025)
+- `%m`: Month as a zero-padded number (01-12)
+- `%d`: Day as a zero-padded number (01-31)
+- `%H`: Hour (24-hour clock) as a zero-padded number (00-23)
+- `%M`: Minute as a zero-padded number (00-59)
+- `%S`: Second as a zero-padded number (00-59)
+
+#### Example
+
+```python
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = [
+ ChatMessage.from_user("Current date is: {% now 'UTC' %}"),
+ ChatMessage.from_assistant("Thank you for providing the date"),
+ ChatMessage.from_user("Yesterday was: {% now 'UTC' - 'days=1' %}"),
+]
+builder = ChatPromptBuilder(template=template)
+
+result = builder.run()["prompt"]
+```
+
+## Usage
+
+### On its own
+
+#### With static template
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = [
+ ChatMessage.from_user(
+ "Translate to {{ target_language }}. Context: {{ snippet }}; Translation:",
+ ),
+]
+builder = ChatPromptBuilder(template=template)
+builder.run(target_language="spanish", snippet="I can't speak spanish.")
+```
+
+#### With special string template
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = """
+{% message role="user" %}
+Hello, my name is {{name}}!
+{% endmessage %}
+"""
+
+builder = ChatPromptBuilder(template=template)
+result = builder.run(name="John")
+
+assert result["prompt"] == [ChatMessage.from_user("Hello, my name is John!")]
+```
+
+#### Specifying name and meta in a ChatMessage
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = """
+{% message role="user" name="John" meta={"key": "value"} %}
+Hello from {{country}}!
+{% endmessage %}
+"""
+
+builder = ChatPromptBuilder(template=template)
+result = builder.run(country="Italy")
+assert result["prompt"] == [
+ ChatMessage.from_user("Hello from Italy!", name="John", meta={"key": "value"}),
+]
+```
+
+#### Multiple ChatMessages with different roles
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = """
+{% message role="system" %}
+You are a {{adjective}} assistant.
+{% endmessage %}
+
+{% message role="user" %}
+Hello, my name is {{name}}!
+{% endmessage %}
+
+{% message role="assistant" %}
+Hello, {{name}}! How can I help you today?
+{% endmessage %}
+"""
+
+builder = ChatPromptBuilder(template=template)
+result = builder.run(name="John", adjective="helpful")
+assert result["prompt"] == [
+ ChatMessage.from_system("You are a helpful assistant."),
+ ChatMessage.from_user("Hello, my name is John!"),
+ ChatMessage.from_assistant("Hello, John! How can I help you today?"),
+]
+```
+
+#### Overriding static template at runtime
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = [
+ ChatMessage.from_user(
+ "Translate to {{ target_language }}. Context: {{ snippet }}; Translation:",
+ ),
+]
+builder = ChatPromptBuilder(template=template)
+builder.run(target_language="spanish", snippet="I can't speak spanish.")
+
+summary_template = [
+ ChatMessage.from_user(
+ "Translate to {{ target_language }} and summarize. Context: {{ snippet }}; Summary:",
+ ),
+]
+builder.run(
+ target_language="spanish",
+ snippet="I can't speak spanish.",
+ template=summary_template,
+)
+```
+
+#### Multimodal
+
+The `| templatize_part` filter in the example below tells the template engine to insert structured (non-text) objects, such as images, into the message content. These are treated differently from plain text and are rendered as special content parts in the final `ChatMessage`.
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage, ImageContent
+
+template = """
+{% message role="user" meta={"key": "value"}%}
+Hello! I am {{user_name}}. What's the difference between the following images?
+{% for image in images %}
+{{ image | templatize_part }}
+{% endfor %}
+{% endmessage %}
+"""
+builder = ChatPromptBuilder(template=template)
+images = [
+ ImageContent.from_file_path("apple.jpg"),
+ ImageContent.from_file_path("kiwi.jpg"),
+]
+result = builder.run(user_name="John", images=images)
+
+assert result["prompt"] == [
+ ChatMessage.from_user(
+ content_parts=[
+ "Hello! I am John. What's the difference between the following images?",
+ *images,
+ ],
+ meta={"key": "value"},
+ ),
+]
+```
+
+### In a pipeline
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+from haystack.utils import Secret
+
+## no parameter init, we don't use any runtime template variables
+prompt_builder = ChatPromptBuilder()
+llm = OpenAIChatGenerator()
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+location = "Berlin"
+language = "English"
+system_message = ChatMessage.from_system(
+ "You are an assistant giving information to tourists in {{language}}",
+)
+messages = [system_message, ChatMessage.from_user("Tell me about {{location}}")]
+
+res = pipe.run(
+ data={
+ "prompt_builder": {
+ "template_variables": {"location": location, "language": language},
+ "template": messages,
+ },
+ },
+)
+print(res)
+```
+
+Then, you could ask about the weather forecast for the said location. The `ChatPromptBuilder` fills in the template with the new `day_count` variable and passes it to an LLM once again:
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+from haystack.utils import Secret
+
+## no parameter init, we don't use any runtime template variables
+prompt_builder = ChatPromptBuilder()
+llm = OpenAIChatGenerator()
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+location = "Berlin"
+
+messages = [
+ system_message,
+ ChatMessage.from_user(
+ "What's the weather forecast for {{location}} in the next {{day_count}} days?",
+ ),
+]
+res = pipe.run(
+ data={
+ "prompt_builder": {
+ "template_variables": {"location": location, "day_count": "5"},
+ "template": messages,
+ },
+ },
+)
+
+print(res)
+```
+
+### In YAML
+
+This is the YAML representation of the pipeline shown above. It dynamically constructs a prompt and generates an answer using a chat model.
+
+```yaml
+components:
+ llm:
+ init_parameters:
+ api_base_url: null
+ api_key:
+ env_vars:
+ - OPENAI_API_KEY
+ strict: true
+ type: env_var
+ generation_kwargs: {}
+ http_client_kwargs: null
+ max_retries: null
+ model: gpt-4o-mini
+ organization: null
+ streaming_callback: null
+ timeout: null
+ tools: null
+ tools_strict: false
+ type: haystack.components.generators.chat.openai.OpenAIChatGenerator
+ prompt_builder:
+ init_parameters:
+ required_variables: null
+ template: null
+ variables: null
+ type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
+connection_type_validation: true
+connections:
+- receiver: llm.messages
+ sender: prompt_builder.prompt
+max_runs_per_component: 100
+metadata: {}
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Advanced Prompt Customization for Anthropic](https://haystack.deepset.ai/cookbook/prompt_customization_for_anthropic)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders/promptbuilder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders/promptbuilder.mdx
new file mode 100644
index 0000000000..a553017109
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/builders/promptbuilder.mdx
@@ -0,0 +1,305 @@
+---
+title: "PromptBuilder"
+id: promptbuilder
+slug: "/promptbuilder"
+description: "Use this component in pipelines before a Generator to render a prompt template and fill in variable values."
+---
+
+# PromptBuilder
+
+Use this component in pipelines before a Generator to render a prompt template and fill in variable values.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a querying pipeline, before a [Generator](../generators.mdx) |
+| **Mandatory init variables** | `template`: A prompt template string that uses Jinja2 syntax |
+| **Mandatory run variables** | `**kwargs`: Any strings that should be used to render the prompt template. See [Variables](#variables) section for more details. |
+| **Output variables** | `prompt`: A string that represents the rendered prompt template |
+| **API reference** | [Builders](/reference/builders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/builders/prompt_builder.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`PromptBuilder` is initialized with a prompt template and renders it by filling in parameters passed through keyword arguments, `kwargs`. With `kwargs`, you can pass a variable number of keyword arguments so that any variable used in the prompt template can be specified with the desired value. Values for all variables appearing in the prompt template need to be provided through the `kwargs`.
+
+The template that is provided to the `PromptBuilder` during initialization needs to conform to the [Jinja2](https://palletsprojects.com/p/jinja/) template language.
+
+### Variables
+
+The template variables found in the init template are used as input types for the component. If there are no `required_variables` set, all variables are considered optional by default. In this case, any missing variables are replaced with empty strings, which can lead to unintended behavior, especially in complex pipelines.
+
+Use `required_variables` and `variables` to specify the input types and required variables:
+
+- `required_variables`
+ - Defines which template variables must be provided when the component runs.
+ - If any required variable is missing, the component raises an error and halts execution.
+ - You can:
+ - Pass a list of required variable names (such as `["query"]`), or
+ - Use `"*"` to mark all variables in the template as required.
+
+- `variables`
+ - Lists all variables that can appear in the template, whether required or optional.
+ - Optional variables that aren't provided are replaced with an empty string in the rendered prompt.
+ - This allows partial prompts to be constructed without errors, unless a variable is marked as required.
+
+```python
+from haystack.components.builders import PromptBuilder
+
+## All variables optional (default to empty string)
+builder = PromptBuilder(
+ template="Hello {{name}}! {{greeting}}",
+ required_variables=[], # or omit this parameter entirely
+)
+
+## Some variables required
+builder = PromptBuilder(
+ template="Hello {{name}}! {{greeting}}",
+ required_variables=["name"], # 'greeting' remains optional
+)
+```
+
+The component only waits for the required inputs before running.
+
+### Jinja2 Time Extension
+
+`PromptBuilder` supports the Jinja2 TimeExtension, which allows you to work with datetime formats.
+
+The Time Extension provides two main features:
+
+1. A `now` tag that gives you access to the current time,
+2. Date/time formatting capabilities through Python's datetime module.
+
+To use the Jinja2 TimeExtension, you need to install a dependency with:
+
+```shell
+pip install arrow>=1.3.0
+```
+
+#### The `now` Tag
+
+The `now` tag creates a datetime object representing the current time, which you can then store in a variable:
+
+```jinja2
+{% now 'utc' as current_time %}
+The current UTC time is: {{ current_time }}
+```
+
+You can specify different timezones:
+
+```jinja2
+{% now 'America/New_York' as ny_time %}
+The time in New York is: {{ ny_time }}
+```
+
+If you don't specify a timezone, your system's local timezone will be used:
+
+```jinja2
+{% now as local_time %}
+Local time: {{ local_time }}
+```
+
+#### Date Formatting
+
+You can format the datetime objects using Python's `strftime` syntax:
+
+```jinja2
+{% now as current_time %}
+Formatted date: {{ current_time.strftime('%Y-%m-%d %H:%M:%S') }}
+```
+
+The common format codes are:
+
+- `%Y`: 4-digit year (for example, 2025)
+- `%m`: Month as a zero-padded number (01-12)
+- `%d`: Day as a zero-padded number (01-31)
+- `%H`: Hour (24-hour clock) as a zero-padded number (00-23)
+- `%M`: Minute as a zero-padded number (00-59)
+- `%S`: Second as a zero-padded number (00-59)
+
+#### Example
+
+```python
+from haystack.components.builders import PromptBuilder
+
+## Define template using Jinja-style formatting
+template = """
+Current date is: {% now 'UTC' %}
+Thank you for providing the date
+Yesterday was: {% now 'UTC' - 'days=1' %}
+"""
+
+builder = PromptBuilder(template=template)
+
+result = builder.run()["prompt"]
+```
+
+## Usage
+
+### On its own
+
+Below is an example of using the `PromptBuilder` to render a prompt template and fill it with `target_language` and `snippet`. The PromptBuilder returns a prompt with the string `Translate the following context to spanish. Context: I can't speak spanish.; Translation:`.
+
+```python
+from haystack.components.builders import PromptBuilder
+
+template = "Translate the following context to {{ target_language }}. Context: {{ snippet }}; Translation:"
+builder = PromptBuilder(template=template)
+builder.run(target_language="spanish", snippet="I can't speak spanish.")
+```
+
+### In a pipeline
+
+Below is an example of a RAG pipeline where we use a `PromptBuilder` to render a custom prompt template and fill it with the contents of retrieved documents and a query. The rendered prompt is then sent to a Generator.
+
+```python
+from haystack import Pipeline, Document
+from haystack.utils import Secret
+from haystack.components.generators import OpenAIGenerator
+from haystack.components.builders.prompt_builder import PromptBuilder
+
+## in a real world use case documents could come from a retriever, web, or any other source
+documents = [
+ Document(content="Joe lives in Berlin"),
+ Document(content="Joe is a software engineer"),
+]
+prompt_template = """
+ Given these documents, answer the question.\nDocuments:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ \nQuestion: {{query}}
+ \nAnswer:
+ """
+p = Pipeline()
+p.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+p.add_component(
+ instance=OpenAIGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")),
+ name="llm",
+)
+p.connect("prompt_builder", "llm")
+
+question = "Where does Joe live?"
+result = p.run({"prompt_builder": {"documents": documents, "query": question}})
+print(result)
+```
+
+#### Changing the template at runtime (Prompt Engineering)
+
+`PromptBuilder` allows you to switch the prompt template of an existing pipeline. The example below builds on top of the existing pipeline in the previous section. We are invoking the existing pipeline with a new prompt template:
+
+```python
+documents = [
+ Document(content="Joe lives in Berlin", meta={"name": "doc1"}),
+ Document(content="Joe is a software engineer", meta={"name": "doc1"}),
+]
+new_template = """
+ You are a helpful assistant.
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ Document {{ loop.index }}:
+ Document name: {{ doc.meta['name'] }}
+ {{ doc.content }}
+ {% endfor %}
+
+ Question: {{ query }}
+ Answer:
+ """
+p.run(
+ {
+ "prompt_builder": {
+ "documents": documents,
+ "query": question,
+ "template": new_template,
+ },
+ },
+)
+```
+
+If you want to use different variables during prompt engineering than in the default template, you can do so by setting `PromptBuilder`'s variables init parameter accordingly.
+
+#### Overwriting variables at runtime
+
+In case you want to overwrite the values of variables, you can use `template_variables` during runtime, as shown below:
+
+```python
+language_template = """
+ You are a helpful assistant.
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ Document {{ loop.index }}:
+ Document name: {{ doc.meta['name'] }}
+ {{ doc.content }}
+ {% endfor %}
+
+ Question: {{ query }}
+ Please provide your answer in {{ answer_language | default('English') }}
+ Answer:
+ """
+p.run(
+ {
+ "prompt_builder": {
+ "documents": documents,
+ "query": question,
+ "template": language_template,
+ "template_variables": {"answer_language": "German"},
+ },
+ },
+)
+```
+
+Note that `language_template` introduces `answer_language` variable which is not bound to any pipeline variable. If not set otherwise, it would use its default value, "English". In this example, we overwrite its value to "German".
+The `template_variables` allows you to overwrite pipeline variables (such as documents) as well.
+
+### In YAML
+
+This is the YAML representation of the RAG pipeline shown above. It renders a custom prompt template by filling it with the contents of retrieved documents and a query, then sends the rendered prompt to a generator.
+
+```yaml
+components:
+ llm:
+ init_parameters:
+ api_base_url: null
+ api_key:
+ env_vars:
+ - OPENAI_API_KEY
+ strict: true
+ type: env_var
+ generation_kwargs: {}
+ http_client_kwargs: null
+ max_retries: null
+ model: gpt-5-mini
+ organization: null
+ streaming_callback: null
+ system_prompt: null
+ timeout: null
+ type: haystack.components.generators.openai.OpenAIGenerator
+ prompt_builder:
+ init_parameters:
+ required_variables: null
+ template: "\n Given these documents, answer the question.\\nDocuments:\n\
+ \ {% for doc in documents %}\n {{ doc.content }}\n {% endfor\
+ \ %}\n\n \\nQuestion: {{query}}\n \\nAnswer:\n "
+ variables: null
+ type: haystack.components.builders.prompt_builder.PromptBuilder
+connection_type_validation: true
+connections:
+- receiver: llm.prompt
+ sender: prompt_builder.prompt
+max_runs_per_component: 100
+metadata: {}
+```
+
+## Additional References
+
+🧑🍳 Cookbooks:
+
+- [Advanced Prompt Customization for Anthropic](https://haystack.deepset.ai/cookbook/prompt_customization_for_anthropic)
+- [Prompt Optimization with DSPy](https://haystack.deepset.ai/cookbook/prompt_optimization_with_dspy)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/caching/cachechecker.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/caching/cachechecker.mdx
new file mode 100644
index 0000000000..c81b38ac80
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/caching/cachechecker.mdx
@@ -0,0 +1,106 @@
+---
+title: "CacheChecker"
+id: cachechecker
+slug: "/cachechecker"
+description: "This component checks for the presence of documents in a Document Store based on a specified cache field."
+---
+
+# CacheChecker
+
+This component checks for the presence of documents in a Document Store based on a specified cache field.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory init variables** | `document_store`: A Document Store instance
`cache_field`: Name of the document's metadata field | +| **Mandatory run variables** | `items`: A list of values associated with the `cache_field` in documents | +| **Output variables** | `hits`: A list of documents that were found with the specified value in cache
`misses`: A list of values that could not be found | +| **API reference** | [Caching](/reference/caching-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/caching/cache_checker.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`CacheChecker` checks if a Document Store contains any document with a value in the `cache_field` that matches any of the values provided in the `items` input variable. It returns a dictionary with two keys: `"hits"` and `"misses"`. The values are lists of documents that were found in the cache and items that were not, respectively.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.caching import CacheChecker
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+my_doc_store = InMemoryDocumentStore()
+
+## For URL-based caching
+cache_checker = CacheChecker(document_store=my_doc_store, cache_field="url")
+cache_check_results = cache_checker.run(
+ items=[
+ "https://example.com/resource",
+ "https://another_example.com/other_resources",
+ ],
+)
+print(
+ cache_check_results["hits"],
+) # List of Documents that were found in the cache: all of these have 'url': `cache_field`: Name of the document's metadata field | +| **Mandatory run variables** | `items`: A list of values associated with the `cache_field` in documents | +| **Output variables** | `hits`: A list of documents that were found with the specified value in cache
`misses`: A list of values that could not be found | +| **API reference** | [Caching](/reference/caching-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/caching/cache_checker.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [`MetadataRouter`](../routers/metadatarouter.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Classifiers](/reference/classifiers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/classifiers/document_language_classifier.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`DocumentLanguageClassifier` classifies the language of documents and adds the detected language to their metadata. If a document's text does not match any of the languages specified at initialization, it is classified as "unmatched". By default, the classifier classifies for English (”en”) documents, with the rest being classified as “unmatched”.
+
+The set of supported languages can be specified in the init method with the `languages` variable, using ISO codes.
+
+To route your documents to various branches of the pipeline based on the language, use `MetadataRouter` component right after `DocumentLanguageClassifier`.
+
+For classifying and then routing plain text using the same logic, use the `TextLanguageRouter` component instead.
+
+## Usage
+
+Install the `langdetect`package to use the `DocumentLanguageClassifier`component:
+
+```shell shell
+pip install langdetect
+```
+
+### On its own
+
+Below, we are using the `DocumentLanguageClassifier` to classify English and German documents:
+
+```python
+from haystack.components.classifiers import DocumentLanguageClassifier
+from haystack import Document
+
+documents = [
+ Document(content="Mein Name ist Jean und ich wohne in Paris."),
+ Document(content="Mein Name ist Mark und ich wohne in Berlin."),
+ Document(content="Mein Name ist Giorgio und ich wohne in Rome."),
+ Document(content="My name is Pierre and I live in Paris"),
+ Document(content="My name is Paul and I live in Berlin."),
+ Document(content="My name is Alessia and I live in Rome."),
+]
+
+document_classifier = DocumentLanguageClassifier(languages=["en", "de"])
+document_classifier.run(documents=documents)
+```
+
+### In a pipeline
+
+Below, we are using the `DocumentLanguageClassifier` in an indexing pipeline that indexes English and German documents into two difference indexes in an `InMemoryDocumentStore`, using embedding models for each language.
+
+```python
+from haystack import Pipeline
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.classifiers import DocumentLanguageClassifier
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+from haystack.components.writers import DocumentWriter
+from haystack.components.routers import MetadataRouter
+
+document_store_en = InMemoryDocumentStore()
+document_store_de = InMemoryDocumentStore()
+
+document_classifier = DocumentLanguageClassifier(languages=["en", "de"])
+metadata_router = MetadataRouter(
+ rules={"en": {"language": {"$eq": "en"}}, "de": {"language": {"$eq": "de"}}},
+)
+english_embedder = SentenceTransformersDocumentEmbedder()
+german_embedder = SentenceTransformersDocumentEmbedder(
+ model="PM-AI/bi-encoder_msmarco_bert-base_german",
+)
+en_writer = DocumentWriter(document_store=document_store_en)
+de_writer = DocumentWriter(document_store=document_store_de)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(document_classifier, name="document_classifier")
+indexing_pipeline.add_component(metadata_router, name="metadata_router")
+indexing_pipeline.add_component(english_embedder, name="english_embedder")
+indexing_pipeline.add_component(german_embedder, name="german_embedder")
+indexing_pipeline.add_component(en_writer, name="en_writer")
+indexing_pipeline.add_component(de_writer, name="de_writer")
+
+indexing_pipeline.connect("document_classifier.documents", "metadata_router.documents")
+indexing_pipeline.connect("metadata_router.en", "english_embedder.documents")
+indexing_pipeline.connect("metadata_router.de", "german_embedder.documents")
+indexing_pipeline.connect("english_embedder", "en_writer")
+indexing_pipeline.connect("german_embedder", "de_writer")
+
+indexing_pipeline.run(
+ {
+ "document_classifier": {
+ "documents": [
+ Document(content="This is an English sentence."),
+ Document(content="Dies ist ein deutscher Satz."),
+ ],
+ },
+ },
+)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx
new file mode 100644
index 0000000000..aa7b6463ad
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx
@@ -0,0 +1,105 @@
+---
+title: "TransformersZeroShotDocumentClassifier"
+id: transformerszeroshotdocumentclassifier
+slug: "/transformerszeroshotdocumentclassifier"
+description: "Classifies the documents based on the provided labels and adds them to their metadata."
+---
+
+# TransformersZeroShotDocumentClassifier
+
+Classifies the documents based on the provided labels and adds them to their metadata.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [MetadataRouter](../routers/metadatarouter.mdx) |
+| **Mandatory init variables** | `model`: The name or path of a Hugging Face model for zero shot document classification
`labels`: The set of possible class labels to classify each document into, for example, [`positive`, `negative`]. The labels depend on the selected model. | +| **Mandatory run variables** | `documents`: A list of documents to classify | +| **Output variables** | `documents`: A list of processed documents with an added `classification` metadata field | +| **API reference** | [Classifiers](/reference/classifiers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/classifiers/zero_shot_document_classifier.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+The `TransformersZeroShotDocumentClassifier` component performs zero-shot classification of documents based on the labels that you set and adds the predicted label to their metadata.
+
+The component uses a Hugging Face pipeline for zero-shot classification.
+To initialize the component, provide the model and the set of labels to be used for categorization.
+You can additionally configure the component to allow multiple labels to be true with the `multi_label` boolean set to True.
+
+Classification is run on the document's content field by default. If you want it to run on another field, set the`classification_field` to one of the document's metadata fields.
+
+The classification results are stored in the `classification` dictionary within each document's metadata. If `multi_label` is set to `True`, you will find the scores for each label under the `details` key within the `classification` dictionary.
+
+Available models for the task of zero-shot-classification are:
+ - `valhalla/distilbart-mnli-12-3`
+ - `cross-encoder/nli-distilroberta-base`
+ - `cross-encoder/nli-deberta-v3-xsmall`
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.classifiers import TransformersZeroShotDocumentClassifier
+
+documents = [
+ Document(id="0", content="Cats don't get teeth cavities."),
+ Document(id="1", content="Cucumbers can be grown in water."),
+]
+
+document_classifier = TransformersZeroShotDocumentClassifier(
+ model="cross-encoder/nli-deberta-v3-xsmall",
+ labels=["animals", "food"],
+)
+
+document_classifier.run(documents=documents)
+```
+
+### In a pipeline
+
+The following is a pipeline that classifies documents based on predefined classification labels
+retrieved from a search pipeline:
+
+```python
+from haystack import Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.core.pipeline import Pipeline
+from haystack.components.classifiers import TransformersZeroShotDocumentClassifier
+
+documents = [
+ Document(id="0", content="Today was a nice day!"),
+ Document(id="1", content="Yesterday was a bad day!"),
+]
+
+document_store = InMemoryDocumentStore()
+retriever = InMemoryBM25Retriever(document_store=document_store)
+document_classifier = TransformersZeroShotDocumentClassifier(
+ model="cross-encoder/nli-deberta-v3-xsmall",
+ labels=["positive", "negative"],
+)
+
+document_store.write_documents(documents)
+
+pipeline = Pipeline()
+pipeline.add_component(retriever, name="retriever")
+pipeline.add_component(document_classifier, name="document_classifier")
+pipeline.connect("retriever", "document_classifier")
+
+queries = ["How was your day today?", "How was your day yesterday?"]
+expected_predictions = ["positive", "negative"]
+
+for idx, query in enumerate(queries):
+ result = pipeline.run({"retriever": {"query": query, "top_k": 1}})
+ classified_docs = result["document_classifier"]["documents"]
+ assert classified_docs[0].id == str(idx)
+ assert (
+ classified_docs[0].meta["classification"]["label"] == expected_predictions[idx]
+ )
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors.mdx
new file mode 100644
index 0000000000..faf8975d15
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors.mdx
@@ -0,0 +1,24 @@
+---
+title: "Connectors"
+id: connectors
+slug: "/connectors"
+description: "These are Haystack integrations that connect your pipelines to services by external providers."
+---
+
+# Connectors
+
+These are Haystack integrations that connect your pipelines to services by external providers.
+
+| Component | Description |
+| --- | --- |
+| [GitHubFileEditor](connectors/githubfileeditor.mdx) | Enables editing files in GitHub repositories through the GitHub API. |
+| [GitHubIssueCommenter](connectors/githubissuecommenter.mdx) | Enables posting comments to GitHub issues using the GitHub API. |
+| [GitHubIssueViewer](connectors/githubissueviewer.mdx) | Enables fetching and parsing GitHub issues into Haystack documents. |
+| [GitHubPRCreator](connectors/githubprcreator.mdx) | Enables creating pull requests from a fork back to the original repository through the GitHub API. |
+| [GitHubRepoForker](connectors/githubrepoforker.mdx) | Enables forking a GitHub repository from an issue URL through the GitHub API. |
+| [GitHubRepoViewer](connectors/githubrepoviewer.mdx) | Enables navigating and fetching content from GitHub repositories through the GitHub API. |
+| [JinaReaderConnector](connectors/jinareaderconnector.mdx) | Use Jina AI’s Reader API with Haystack. |
+| [LangfuseConnector](connectors/langfuseconnector.mdx) | Enables tracing in Haystack pipelines using Langfuse. |
+| [OpenAPIConnector](connectors/openapiconnector.mdx) | Acts as an interface between the Haystack ecosystem and OpenAPI services, using explicit input arguments. |
+| [OpenAPIServiceConnector](connectors/openapiserviceconnector.mdx) | Acts as an interface between the Haystack ecosystem and OpenAPI services. |
+| [WeaveConnector](connectors/weaveconnector.mdx) | Connects you to Weights & Biases Weave framework for tracing and monitoring your pipeline components. |
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/external-integrations-connectors.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/external-integrations-connectors.mdx
new file mode 100644
index 0000000000..cb22c9473e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/external-integrations-connectors.mdx
@@ -0,0 +1,18 @@
+---
+title: "External Integrations"
+id: external-integrations-connectors
+slug: "/external-integrations-connectors"
+description: "External integrations that connect your pipelines to services by external providers."
+---
+
+# External Integrations
+
+External integrations that connect your pipelines to services by external providers.
+
+| Name | Description |
+| --- | --- |
+| [Arize AI](https://haystack.deepset.ai/integrations/arize) | Trace and evaluate your Haystack pipelines with Arize AI. |
+| [Arize Phoenix](https://haystack.deepset.ai/integrations/arize-phoenix) | Trace and evaluate your Haystack pipelines with Arize Phoenix. |
+| [Context AI](https://haystack.deepset.ai/integrations/context-ai) | Log conversations for analytics by Context.ai |
+| [Opik](https://haystack.deepset.ai/integrations/opik) | Trace and evaluate your Haystack pipelines with Opik platform. |
+| [Traceloop](https://haystack.deepset.ai/integrations/traceloop) | Evaluate and monitor the quality of your LLM apps and agents |
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubfileeditor.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubfileeditor.mdx
new file mode 100644
index 0000000000..fc80a5c243
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubfileeditor.mdx
@@ -0,0 +1,105 @@
+---
+title: "GitHubFileEditor"
+id: githubfileeditor
+slug: "/githubfileeditor"
+description: "This is a component for editing files in GitHub repositories through the GitHub API."
+---
+
+# GitHubFileEditor
+
+This is a component for editing files in GitHub repositories through the GitHub API.
+
+`labels`: The set of possible class labels to classify each document into, for example, [`positive`, `negative`]. The labels depend on the selected model. | +| **Mandatory run variables** | `documents`: A list of documents to classify | +| **Output variables** | `documents`: A list of processed documents with an added `classification` metadata field | +| **API reference** | [Classifiers](/reference/classifiers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/classifiers/zero_shot_document_classifier.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a Chat Generator, or right at the beginning of a pipeline |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var. |
+| **Mandatory run variables** | `command`: Operation type (edit, create, delete, undo)
`payload`: Command-specific parameters | +| **Output variables** | `result`: String that indicates the operation result | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | +| **Package name** | `github-haystack` | + +
+
+## Overview
+
+`GitHubFileEditor` supports multiple file operations, including editing existing files, creating new files, deleting files, and undoing recent changes.
+
+There are four main commands:
+
+- **EDIT**: Edit an existing file by replacing specific content
+- **CREATE**: Create a new file with specified content
+- **DELETE**: Delete an existing file
+- **UNDO**: Revert the last commit if made by the same user
+
+### Authorization
+
+This component requires GitHub authentication with a personal access token. You can set the token using the `GITHUB_TOKEN` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens). Make sure to grant the appropriate permissions for repository access and content management.
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Editing an existing file:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubFileEditor, Command
+
+editor = GitHubFileEditor(repo="owner/repo", branch="main")
+
+result = editor.run(
+ command=Command.EDIT,
+ payload={
+ "path": "src/example.py",
+ "original": "def old_function():",
+ "replacement": "def new_function():",
+ "message": "Renamed function for clarity",
+ },
+)
+
+print(result)
+```
+
+```bash
+{'result': 'Edit successful'}
+```
+
+Creating a new file:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubFileEditor, Command
+
+editor = GitHubFileEditor(repo="owner/repo")
+
+result = editor.run(
+ command=Command.CREATE,
+ payload={
+ "path": "docs/new_file.md",
+ "content": "# New Documentation\n\nThis is a new file.",
+ "message": "Add new documentation file",
+ },
+)
+
+print(result)
+```
+
+```bash
+{'result': 'File created successfully'}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubissuecommenter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubissuecommenter.mdx
new file mode 100644
index 0000000000..f23acda143
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubissuecommenter.mdx
@@ -0,0 +1,129 @@
+---
+title: "GitHubIssueCommenter"
+id: githubissuecommenter
+slug: "/githubissuecommenter"
+description: "This component posts comments to GitHub issues using the GitHub API."
+---
+
+# GitHubIssueCommenter
+
+This component posts comments to GitHub issues using the GitHub API.
+
+`payload`: Command-specific parameters | +| **Output variables** | `result`: String that indicates the operation result | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | +| **Package name** | `github-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a Chat Generator that provides the comment text to post or right at the beginning of a pipeline |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var. |
+| **Mandatory run variables** | `url`: A GitHub issue URL
`comment`: Comment text to post | +| **Output variables** | `success`: Boolean indicating whether the comment was posted successfully | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | +| **Package name** | `github-haystack` | + +
+
+## Overview
+
+`GitHubIssueCommenter` takes a GitHub issue URL and comment text, then posts the comment to the specified issue.
+
+The component requires authentication with a GitHub personal access token since posting comments is an authenticated operation.
+
+### Authorization
+
+This component requires GitHub authentication with a personal access token. You can set the token using the `GITHUB_TOKEN` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens). Make sure to grant the appropriate permissions for repository access and issue management.
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Basic usage with environment variable authentication:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubIssueCommenter
+
+commenter = GitHubIssueCommenter()
+result = commenter.run(
+ url="https://github.com/owner/repo/issues/123",
+ comment="Thanks for reporting this issue! We'll look into it.",
+)
+
+print(result)
+```
+
+```bash
+{'success': True}
+```
+
+### In a pipeline
+
+The following pipeline analyzes a GitHub issue and automatically posts a response:
+
+```python
+from haystack import Pipeline
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.connectors.github import (
+ GitHubIssueViewer,
+ GitHubIssueCommenter,
+)
+
+issue_viewer = GitHubIssueViewer()
+issue_commenter = GitHubIssueCommenter()
+
+prompt_template = [
+ ChatMessage.from_system(
+ "You are a helpful assistant that analyzes GitHub issues and creates appropriate responses.",
+ ),
+ ChatMessage.from_user(
+ "Based on the following GitHub issue:\n"
+ "{% for document in documents %}"
+ "{% if document.meta.type == 'issue' %}"
+ "**Issue Title:** {{ document.meta.title }}\n"
+ "**Issue Description:** {{ document.content }}\n"
+ "{% endif %}"
+ "{% endfor %}\n"
+ "Generate a helpful response comment for this issue. Keep it professional and concise.",
+ ),
+]
+
+prompt_builder = ChatPromptBuilder(template=prompt_template, required_variables="*")
+llm = OpenAIChatGenerator(model="gpt-4o-mini")
+
+pipeline = Pipeline()
+pipeline.add_component("issue_viewer", issue_viewer)
+pipeline.add_component("prompt_builder", prompt_builder)
+pipeline.add_component("llm", llm)
+pipeline.add_component("issue_commenter", issue_commenter)
+
+pipeline.connect("issue_viewer.documents", "prompt_builder.documents")
+pipeline.connect("prompt_builder.prompt", "llm.messages")
+pipeline.connect("llm.replies", "issue_commenter.comment")
+
+issue_url = "https://github.com/owner/repo/issues/123"
+result = pipeline.run(
+ data={"issue_viewer": {"url": issue_url}, "issue_commenter": {"url": issue_url}},
+)
+
+print(f"Comment posted successfully: {result['issue_commenter']['success']}")
+```
+
+```
+Comment posted successfully: True
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubissueviewer.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubissueviewer.mdx
new file mode 100644
index 0000000000..6bd9ab931b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubissueviewer.mdx
@@ -0,0 +1,127 @@
+---
+title: "GitHubIssueViewer"
+id: githubissueviewer
+slug: "/githubissueviewer"
+description: "This component fetches and parses GitHub issues into Haystack documents."
+---
+
+# GitHubIssueViewer
+
+This component fetches and parses GitHub issues into Haystack documents.
+
+`comment`: Comment text to post | +| **Output variables** | `success`: Boolean indicating whether the comment was posted successfully | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | +| **Package name** | `github-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Right at the beginning of a pipeline and before a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) that expects the content of a GitHub issue as input |
+| **Mandatory run variables** | `url`: A GitHub issue URL |
+| **Output variables** | `documents`: A list of documents containing the main issue and its comments |
+| **API reference** | [GitHub](/reference/integrations-github) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github |
+| **Package name** | `github-haystack` |
+
+
+
+## Overview
+
+`GitHubIssueViewer` takes a GitHub issue URL and returns a list of documents where:
+
+- The first document contains the main issue content
+- Subsequent documents contain the issue comments (if any)
+
+Each document includes rich metadata such as the issue title, number, state, creation date, author, and more.
+
+### Authorization
+
+The component can work without authentication for public repositories, but for private repositories or to avoid rate limiting, you can provide a GitHub personal access token.
+
+You can set the token using the `GITHUB_API_KEY` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens).
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Basic usage without authentication:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubIssueViewer
+
+viewer = GitHubIssueViewer()
+result = viewer.run(url="https://github.com/deepset-ai/haystack/issues/123")
+
+print(result)
+```
+
+```bash
+{'documents': [Document(id=3989459bbd8c2a8420a9ba7f3cd3cf79bb41d78bd0738882e57d509e1293c67a, content: 'sentence-transformers = 0.2.6.1
+haystack = latest
+farm = 0.4.3 latest branch
+
+In the call to Emb...', meta: {'type': 'issue', 'title': 'SentenceTransformer no longer accepts \'gpu" as argument', 'number': 123, 'state': 'closed', 'created_at': '2020-05-28T04:49:31Z', 'updated_at': '2020-05-28T07:11:43Z', 'author': 'predoctech', 'url': 'https://github.com/deepset-ai/haystack/issues/123'}), Document(id=a8a56b9ad119244678804d5873b13da0784587773d8f839e07f644c4d02c167a, content: 'Thanks for reporting!
+Fixed with #124 ', meta: {'type': 'comment', 'issue_number': 123, 'created_at': '2020-05-28T07:11:42Z', 'updated_at': '2020-05-28T07:11:42Z', 'author': 'tholor', 'url': 'https://github.com/deepset-ai/haystack/issues/123#issuecomment-635153940'})]}
+```
+
+### In a pipeline
+
+The following pipeline fetches a GitHub issue, extracts relevant information, and generates a summary:
+
+```python
+from haystack import Pipeline
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.connectors.github import GitHubIssueViewer
+
+## Initialize components
+issue_viewer = GitHubIssueViewer()
+
+prompt_template = [
+ ChatMessage.from_system("You are a helpful assistant that analyzes GitHub issues."),
+ ChatMessage.from_user(
+ "Based on the following GitHub issue and comments:\n"
+ "{% for document in documents %}"
+ "{% if document.meta.type == 'issue' %}"
+ "**Issue Title:** {{ document.meta.title }}\n"
+ "**Issue Description:** {{ document.content }}\n"
+ "{% else %}"
+ "**Comment by {{ document.meta.author }}:** {{ document.content }}\n"
+ "{% endif %}"
+ "{% endfor %}\n"
+ "Please provide a summary of the issue and suggest potential solutions.",
+ ),
+]
+
+prompt_builder = ChatPromptBuilder(template=prompt_template, required_variables="*")
+llm = OpenAIChatGenerator(model="gpt-4o-mini")
+
+## Create pipeline
+pipeline = Pipeline()
+pipeline.add_component("issue_viewer", issue_viewer)
+pipeline.add_component("prompt_builder", prompt_builder)
+pipeline.add_component("llm", llm)
+
+## Connect components
+pipeline.connect("issue_viewer.documents", "prompt_builder.documents")
+pipeline.connect("prompt_builder.prompt", "llm.messages")
+
+## Run pipeline
+issue_url = "https://github.com/deepset-ai/haystack/issues/123"
+result = pipeline.run(data={"issue_viewer": {"url": issue_url}})
+
+print(result["llm"]["replies"][0])
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubprcreator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubprcreator.mdx
new file mode 100644
index 0000000000..e80841cc12
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubprcreator.mdx
@@ -0,0 +1,79 @@
+---
+title: "GitHubPRCreator"
+id: githubprcreator
+slug: "/githubprcreator"
+description: "This component creates pull requests from a fork back to the original repository through the GitHub API."
+---
+
+# GitHubPRCreator
+
+This component creates pull requests from a fork back to the original repository through the GitHub API.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | At the end of a pipeline, after [GitHubRepoForker](githubrepoforker.mdx), [GitHubFileEditor](githubfileeditor.mdx) and other components that prepare changes for submission |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var. |
+| **Mandatory run variables** | `issue_url`: GitHub issue URL
`title`: PR title
`branch`: Source branch
`base`: Target branch | +| **Output variables** | `result`: String indicating the pull request creation result | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | +| **Package name** | `github-haystack` | + +
+
+## Overview
+
+`GitHubPRCreator` takes a GitHub issue URL and creates a pull request from your fork to the original repository, automatically linking it to the specified issue. It's designed to work with existing forks and assumes you have already made changes in a branch.
+
+Key features:
+
+- **Cross-repository PRs**: Creates pull requests from your fork to the original repository
+- **Issue linking**: Automatically links the PR to the specified GitHub issue
+- **Draft support**: Option to create draft pull requests
+- **Fork validation**: Checks that the required fork exists before creating the PR
+
+As optional parameters, you can set `body` to provide a pull request description and the boolean parameter `draft` to open a draft pull request.
+
+### Authorization
+
+This component requires GitHub authentication with a personal access token from the fork owner. You can set the token using the `GITHUB_TOKEN` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens). Make sure to grant the appropriate permissions for repository access and pull request creation.
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+```python
+from haystack_integrations.components.connectors.github import GitHubPRCreator
+
+pr_creator = GitHubPRCreator()
+result = pr_creator.run(
+ issue_url="https://github.com/owner/repo/issues/123",
+ title="Fix issue #123",
+ body="This PR addresses issue #123 by implementing the requested changes.",
+ branch="fix-123", # Branch in your fork with the changes
+ base="main", # Branch in original repo to merge into
+)
+
+print(result)
+```
+
+```bash
+{'result': 'Pull request #456 created successfully and linked to issue #123'}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubrepoforker.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubrepoforker.mdx
new file mode 100644
index 0000000000..6f8f9d2634
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubrepoforker.mdx
@@ -0,0 +1,71 @@
+---
+title: "GitHubRepoForker"
+id: githubrepoforker
+slug: "/githubrepoforker"
+description: "This component forks a GitHub repository from an issue URL through the GitHub API."
+---
+
+# GitHubRepoForker
+
+This component forks a GitHub repository from an issue URL through the GitHub API.
+
+`title`: PR title
`branch`: Source branch
`base`: Target branch | +| **Output variables** | `result`: String indicating the pull request creation result | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | +| **Package name** | `github-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Right at the beginning of a pipeline and before an [Agent](../agents-1/agent.mdx) component that expects the name of a GitHub branch as input |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var. |
+| **Mandatory run variables** | `url`: The URL of a GitHub issue in the repository that should be forked |
+| **Output variables** | `repo`: Fork repository path
`issue_branch`: Issue-specific branch name (if created) | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | +| **Package name** | `github-haystack` | + +
+
+## Overview
+
+`GitHubRepoForker` takes a GitHub issue URL, extracts the repository information, creates or syncs a fork of that repository, and optionally creates an issue-specific branch. It's particularly useful for automated workflows that need to create pull requests or work with repository forks.
+
+Key features:
+
+- **Auto-sync**: Automatically syncs existing forks with the upstream repository
+- **Branch creation**: Creates issue-specific branches (e.g., "fix-123" for issue #123)
+- **Completion waiting**: Optionally waits for fork creation to complete
+- **Fork management**: Handles existing forks intelligently
+
+### Authorization
+
+This component requires GitHub authentication with a personal access token. You can set the token using the `GITHUB_TOKEN` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens). Make sure to grant the appropriate permissions for repository forking and management.
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+```python
+from haystack_integrations.components.connectors.github import GitHubRepoForker
+
+forker = GitHubRepoForker()
+result = forker.run(url="https://github.com/owner/repo/issues/123")
+
+print(result)
+```
+
+```bash
+{'repo': 'owner/repo', 'issue_branch': 'fix-123'}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubrepoviewer.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubrepoviewer.mdx
new file mode 100644
index 0000000000..947364c8b2
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/githubrepoviewer.mdx
@@ -0,0 +1,92 @@
+---
+title: "GitHubRepoViewer"
+id: githubrepoviewer
+slug: "/githubrepoviewer"
+description: "This component navigates and fetches content from GitHub repositories through the GitHub API."
+---
+
+# GitHubRepoViewer
+
+This component navigates and fetches content from GitHub repositories through the GitHub API.
+
+`issue_branch`: Issue-specific branch name (if created) | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | +| **Package name** | `github-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Right at the beginning of a pipeline and before a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) that expects the content of GitHub files as input |
+| **Mandatory run variables** | `path`: Repository path to view
`repo`: Repository in owner/repo format | +| **Output variables** | `documents`: A list of documents containing repository contents | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | +| **Package name** | `github-haystack` | + +
+
+## Overview
+
+`GitHubRepoViewer` provides different behavior based on the path type:
+
+- **For directories**: Returns a list of documents, one for each item (files and subdirectories),
+- **For files**: Returns a single document containing the file content.
+
+Each document includes rich metadata such as the path, type, size, and URL.
+
+### Authorization
+
+The component can work without authentication for public repositories, but for private repositories or to avoid rate limiting, you can provide a GitHub personal access token.
+
+You can set the token using the `GITHUB_TOKEN` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens).
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Viewing a directory listing:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubRepoViewer
+
+viewer = GitHubRepoViewer()
+result = viewer.run(
+ repo="deepset-ai/haystack",
+ path="haystack/components",
+ branch="main",
+)
+
+print(result)
+```
+
+```bash
+{'documents': [Document(id=..., content: 'agents', meta: {'path': 'haystack/components/agents', 'type': 'dir', 'size': 0, 'url': 'https://github.com/deepset-ai/haystack/tree/main/haystack/components/agents'}), ...]}
+```
+
+Viewing a specific file:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubRepoViewer
+
+viewer = GitHubRepoViewer(repo="deepset-ai/haystack", branch="main")
+result = viewer.run(path="README.md")
+
+print(result)
+```
+
+```bash
+{'documents': [Document(id=..., content: '
+
+## Overview
+
+`JinaReaderConnector` interacts with Jina AI’s Reader API to process queries and output documents.
+
+You need to select one of the following modes of operations when initializing the component:
+
+- `read`: Processes a URL and extracts the textual content.
+- `search`: Searches the web and returns textual content from the most relevant pages.
+- `ground`: Performs fact-checking using a grounding engine.
+
+You can find more information on these modes in the [Jina Reader documentation](https://jina.ai/reader/).
+
+You can additionally control the response format from the Jina Reader API using the component’s `json_response` parameter:
+
+- `True` (default) requests a JSON response for documents enriched with structured metadata.
+- `False` requests a raw response, resulting in one document with minimal metadata.
+
+### 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("`repo`: Repository in owner/repo format | +| **Output variables** | `documents`: A list of documents containing repository contents | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | +| **Package name** | `github-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Anywhere, as it’s not connected to other components |
+| **Mandatory init variables** | `name`: The name of the pipeline or component to identify the tracing run |
+| **Output variables** | `name`: The name of the tracing component
`trace_url`: A link to the tracing data | +| **API reference** | [langfuse](/reference/integrations-langfuse) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/langfuse | +| **Package name** | `langfuse-haystack` | + +
+
+## Overview
+
+`LangfuseConnector` integrates tracing capabilities into Haystack pipelines using [Langfuse](https://langfuse.com/). It captures detailed information about pipeline runs, like API calls, context data, prompts, and more. Use this component to:
+
+- Monitor model performance, such as token usage and cost.
+- Find areas for pipeline improvement by identifying low-quality outputs and collecting user feedback.
+- Create datasets for fine-tuning and testing from your pipeline executions.
+
+To work with the integration, add the `LangfuseConnector` to your pipeline, run the pipeline, and then view the tracing data on the Langfuse website. Don’t connect this component to any other – `LangfuseConnector` will simply run in your pipeline’s background.
+
+You can optionally define two more parameters when working with this component:
+
+- `httpx_client`: An optional custom `httpx.Client` instance for Langfuse API calls. Note that custom clients are discarded when deserializing a pipeline from YAML, as HTTPX clients cannot be serialized. In such cases, Langfuse creates a default client.
+- `span_handler`: An optional custom handler for processing spans. If not provided, the `DefaultSpanHandler` is used. The span handler defines how spans are created and processed, enabling customization of span types based on component types and post-processing of spans. See more details in the [Advanced Usage section](#advanced-usage) below.
+
+### Prerequisites
+
+These are the things that you need before working with LangfuseConnector:
+
+1. Make sure you have an active Langfuse [account](https://cloud.langfuse.com/).
+2. Set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true` – this will enable tracing in your pipelines.
+3. Set the `LANGFUSE_SECRET_KEY` and `LANGFUSE_PUBLIC_KEY` environment variables with your Langfuse secret and public keys found in your account profile.
+
+### Installation
+
+First, install `langfuse-haystack` package to use the `LangfuseConnector`:
+
+```shell
+pip install langfuse-haystack
+```
+
+`trace_url`: A link to the tracing data | +| **API reference** | [langfuse](/reference/integrations-langfuse) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/langfuse | +| **Package name** | `langfuse-haystack` | + +
+ +:::info[Usage Notice] + +To ensure proper tracing, always set environment variables before importing any Haystack components. This is crucial because Haystack initializes its internal tracing components during import. In the example below, we first set the environmental variables and then import the relevant Haystack components. + +Alternatively, an even better practice is to set these environment variables in your shell before running the script. This approach keeps configuration separate from code and allows for easier management of different environments. +::: + +## Usage + +In the example below, we are adding `LangfuseConnector` to the pipeline as a _tracer_. Each pipeline run will produce one trace that includes the entire execution context, including prompts, completions, and metadata. + +You can then view the trace by following a URL link printed in the output. + +```python +import os + +os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" +os.environ["TOKENIZERS_PARALLELISM"] = "false" +os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true" + +from haystack.components.builders import ChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack import Pipeline + +from haystack_integrations.components.connectors.langfuse import LangfuseConnector + +if __name__ == "__main__": + pipe = Pipeline() + pipe.add_component("tracer", LangfuseConnector("Chat example")) + pipe.add_component("prompt_builder", ChatPromptBuilder()) + pipe.add_component("llm", OpenAIChatGenerator()) + + pipe.connect("prompt_builder.prompt", "llm.messages") + + messages = [ + ChatMessage.from_system( + "Always respond in German even if some input data is in other languages.", + ), + ChatMessage.from_user("Tell me about {{location}}"), + ] + + response = pipe.run( + data={ + "prompt_builder": { + "template_variables": {"location": "Berlin"}, + "template": messages, + }, + }, + ) + print(response["llm"]["replies"][0]) + print(response["tracer"]["trace_url"]) +``` + +### With an Agent + +```python +import os + +os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" +os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true" + +from typing import Annotated + +from haystack.components.agents import Agent +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack.tools import tool +from haystack import Pipeline + +from haystack_integrations.components.connectors.langfuse import LangfuseConnector + + +@tool +def get_weather(city: Annotated[str, "The city to get weather for"]) -> str: + """Get current weather information for a city.""" + weather_data = { + "Berlin": "18°C, partly cloudy", + "New York": "22°C, sunny", + "Tokyo": "25°C, clear skies", + } + return weather_data.get(city, f"Weather information for {city} not available") + + +@tool +def calculate( + operation: Annotated[ + str, + "Mathematical operation: add, subtract, multiply, divide", + ], + a: Annotated[float, "First number"], + b: Annotated[float, "Second number"], +) -> str: + """Perform basic mathematical calculations.""" + if operation == "add": + result = a + b + elif operation == "subtract": + result = a - b + elif operation == "multiply": + result = a * b + elif operation == "divide": + if b == 0: + return "Error: Division by zero" + else: + result = a / b + else: + return f"Error: Unknown operation '{operation}'" + + return f"The result of {a} {operation} {b} is {result}" + + +if __name__ == "__main__": + ## Create components + chat_generator = OpenAIChatGenerator() + + agent = Agent( + chat_generator=chat_generator, + tools=[get_weather, calculate], + system_prompt="You are a helpful assistant with access to weather and calculator tools. Use them when needed.", + exit_conditions=["text"], + ) + + langfuse_connector = LangfuseConnector("Agent Example") + + ## Create and run pipeline + pipe = Pipeline() + pipe.add_component("tracer", langfuse_connector) + pipe.add_component("agent", agent) + + response = pipe.run( + data={ + "agent": { + "messages": [ + ChatMessage.from_user( + "What's the weather in Berlin and calculate 15 + 27?", + ), + ], + }, + "tracer": {"invocation_context": {"test": "agent_with_tools"}}, + }, + ) + + print(response["agent"]["last_message"].text) + print(response["tracer"]["trace_url"]) +``` + +## Advanced Usage + +### Customizing Langfuse Traces with SpanHandler + +The `SpanHandler` interface in Haystack allows you to customize how spans are created and processed for Langfuse trace creation. This enables you to log custom metrics, add tags, or integrate metadata. + +By extending `SpanHandler` or its default implementation, `DefaultSpanHandler`, you can define custom logic for span processing, providing precise control over what data is logged to Langfuse for tracking and analyzing pipeline executions. + +Here's an example: + +```python +from haystack_integrations.tracing.langfuse import ( + LangfuseConnector, + DefaultSpanHandler, + LangfuseSpan, +) +from typing import Optional + + +class CustomSpanHandler(DefaultSpanHandler): + def handle(self, span: LangfuseSpan, component_type: Optional[str]) -> None: + # Custom logic to add metadata or modify span + if component_type == "OpenAIChatGenerator": + output = span._data.get("haystack.component.output", {}) + if len(output.get("text", "")) < 10: + span._span.update(level="WARNING", status_message="Response too short") + + +## Add the custom handler to the LangfuseConnector +connector = LangfuseConnector(span_handler=CustomSpanHandler()) +``` diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/openapiconnector.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/openapiconnector.mdx new file mode 100644 index 0000000000..5b7198f997 --- /dev/null +++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/openapiconnector.mdx @@ -0,0 +1,107 @@ +--- +title: "OpenAPIConnector" +id: openapiconnector +slug: "/openapiconnector" +description: "`OpenAPIConnector` is a component that acts as an interface between the Haystack ecosystem and OpenAPI services." +--- + +# OpenAPIConnector + +`OpenAPIConnector` is a component that acts as an interface between the Haystack ecosystem and OpenAPI services. + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Anywhere, after components providing input for its run parameters |
+| **Mandatory init variables** | `openapi_spec`: The OpenAPI specification for the service. Can be a URL, file path, or raw string. |
+| **Mandatory run variables** | `operation_id`: The operationId from the OpenAPI spec to invoke. |
+| **Output variables** | `response`: A REST service response |
+| **API reference** | [Connectors](/reference/connectors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/connectors/openapi.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `OpenAPIConnector` is a component within the Haystack ecosystem that allows direct invocation of REST endpoints defined in an OpenAPI (formerly Swagger) specification. It acts as a bridge between Haystack pipelines and any REST API that follows the OpenAPI standard, enabling dynamic method calls, authentication, and parameter handling.
+
+To use the `OpenAPIConnector`, ensure that you have the `openapi-llm` dependency installed:
+
+```shell
+pip install openapi-llm
+```
+
+Unlike [OpenAPIServiceConnector](openapiserviceconnector.mdx), which works with LLMs, `OpenAPIConnector` directly calls REST endpoints using explicit input arguments.
+
+## Usage
+
+### On its own
+
+You can initialize and use the `OpenAPIConnector` on its own by passing an OpenAPI specification and other parameters:
+
+```python
+from haystack.utils import Secret
+from haystack.components.connectors.openapi import OpenAPIConnector
+
+connector = OpenAPIConnector(
+ openapi_spec="https://bit.ly/serperdev_openapi",
+ credentials=Secret.from_env_var("SERPERDEV_API_KEY"),
+ service_kwargs={"config_factory": my_custom_config_factory},
+)
+
+response = connector.run(
+ operation_id="search",
+ arguments={"q": "Who was Nikola Tesla?"},
+)
+```
+
+#### Output
+
+The `OpenAPIConnector` returns a dictionary containing the service response:
+
+```json
+{
+ "response": { // here goes REST endpoint response JSON
+ }
+}
+```
+
+### In a pipeline
+
+The `OpenAPIConnector` can be integrated into a Haystack pipeline to interact with OpenAPI services. For example, here’s how you can link the `OpenAPIConnector` to a pipeline:
+
+```python
+from haystack import Pipeline
+from haystack.components.connectors.openapi import OpenAPIConnector
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack.utils import Secret
+
+## Initialize the OpenAPIConnector
+connector = OpenAPIConnector(
+ openapi_spec="https://bit.ly/serperdev_openapi",
+ credentials=Secret.from_env_var("SERPERDEV_API_KEY"),
+)
+
+## Create a ChatMessage from the user
+user_message = ChatMessage.from_user(text="Who was Nikola Tesla?")
+
+## Define the pipeline
+pipeline = Pipeline()
+pipeline.add_component("openapi_connector", connector)
+
+## Run the pipeline
+response = pipeline.run(
+ data={
+ "openapi_connector": {
+ "operation_id": "search",
+ "arguments": {"q": user_message.text},
+ },
+ },
+)
+
+## Extract the answer from the response
+answer = response.get("openapi_connector", {}).get("response", {})
+print(answer)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/openapiserviceconnector.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/openapiserviceconnector.mdx
new file mode 100644
index 0000000000..17186331c0
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/openapiserviceconnector.mdx
@@ -0,0 +1,141 @@
+---
+title: "OpenAPIServiceConnector"
+id: openapiserviceconnector
+slug: "/openapiserviceconnector"
+description: "`OpenAPIServiceConnector` is a component that acts as an interface between the Haystack ecosystem and OpenAPI services."
+---
+
+# OpenAPIServiceConnector
+
+`OpenAPIServiceConnector` is a component that acts as an interface between the Haystack ecosystem and OpenAPI services.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects where the last message must be from the assistant and contain tool calls.
`service_openapi_spec`: OpenAPI specification of the service being invoked. It can be YAML/JSON, and all ref values must be resolved.
`service_credentials`: Authentication credentials for the service. We currently support two OpenAPI spec v3 security schemes:
1. http – for Basic, Bearer, and other HTTP authentication schemes;
2. apiKey – for API keys and cookie authentication. | +| **Output variables** | `service_response`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects where each message corresponds to a tool call invocation.
If a message contains multiple tool calls, there will be multiple responses. | +| **API reference** | [Connectors](/reference/connectors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/connectors/openapi_service.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`OpenAPIServiceConnector` acts as a bridge between Haystack ecosystem and OpenAPI services. This component works by using information from a `ChatMessage` to dynamically invoke service methods. It handles parameter payload parsing from `ChatMessage`, service authentication, method invocation, and response formatting, making it easier to integrate OpenAPI services.
+
+To use `OpenAPIServiceConnector`, you need to install the optional `openapi3` dependency with:
+
+```shell
+pip install openapi3
+```
+
+`OpenAPIServiceConnector` component doesn’t have any init parameters.
+
+## Usage
+
+### On its own
+
+This component is primarily meant to be used in pipelines, as [`OpenAPIServiceToFunctions`](../converters/openapiservicetofunctions.mdx), in tandem with an LLM with tool calling capabilities, resolves the actual tool call parameters that are injected as invocation parameters for `OpenAPIServiceConnector`.
+
+### In a pipeline
+
+Let's say we're linking the Serper search engine to a pipeline. Here, `OpenAPIServiceConnector` uses the abilities of `OpenAPIServiceToFunctions`. `OpenAPIServiceToFunctions` first fetches and changes the [Serper's OpenAPI specification](https://bit.ly/serper_dev_spec) into function definitions that an LLM with tool calling capabilities can understand. Then, `OpenAPIServiceConnector` activates the Serper service using this specification.
+
+More precisely, `OpenAPIServiceConnector` dynamically calls methods defined in the Serper OpenAPI specification. This involves reading chat messages to extract tool call parameters, handling authentication with the Serper service, and making the right API calls. The connector makes sure that the method call follows the Serper API requirements, such as correct formatting requests and handling responses.
+
+Note that we used Serper just as an example here. This could be any OpenAPI-compliant service.
+
+:::info
+To run the following code snippet, note that you have to have your own Serper and OpenAI API keys.
+:::
+
+```python
+import json
+import requests
+
+from typing import Any
+
+from haystack import Pipeline
+from haystack.components.connectors import OpenAPIServiceConnector
+from haystack.components.converters import OpenAPIServiceToFunctions, OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.dataclasses.byte_stream import ByteStream
+
+
+def prepare_fc_params(openai_functions_schema: dict[str, Any]) -> dict[str, Any]:
+ return {
+ "tools": [{"type": "function", "function": openai_functions_schema}],
+ "tool_choice": {
+ "type": "function",
+ "function": {"name": openai_functions_schema["name"]},
+ },
+ }
+
+
+serperdev_spec = requests.get("https://bit.ly/serper_dev_spec").json()
+system_prompt = requests.get("https://bit.ly/serper_dev_system").text
+user_prompt = "Why was Sam Altman ousted from OpenAI?"
+
+pipe = Pipeline()
+pipe.add_component("spec_to_functions", OpenAPIServiceToFunctions())
+pipe.add_component(
+ "prepare_fc_adapter",
+ OutputAdapter(
+ "{{functions[0] | prepare_fc}}",
+ dict[str, Any],
+ {"prepare_fc": prepare_fc_params},
+ ),
+)
+pipe.add_component("functions_llm", OpenAIChatGenerator())
+pipe.add_component("openapi_connector", OpenAPIServiceConnector())
+pipe.add_component(
+ "message_adapter",
+ OutputAdapter(
+ "{{system_message + service_response}}",
+ list[ChatMessage],
+ unsafe=True,
+ ),
+)
+pipe.add_component("llm", OpenAIChatGenerator())
+
+pipe.connect("spec_to_functions.functions", "prepare_fc_adapter.functions")
+pipe.connect(
+ "spec_to_functions.openapi_specs",
+ "openapi_connector.service_openapi_spec",
+)
+pipe.connect("prepare_fc_adapter", "functions_llm.generation_kwargs")
+pipe.connect("functions_llm.replies", "openapi_connector.messages")
+pipe.connect("openapi_connector.service_response", "message_adapter.service_response")
+pipe.connect("message_adapter", "llm.messages")
+
+result = pipe.run(
+ data={
+ "functions_llm": {
+ "messages": [
+ ChatMessage.from_system("Only do tool/function calling"),
+ ChatMessage.from_user(user_prompt),
+ ],
+ },
+ "openapi_connector": {
+ "service_credentials": serper_dev_key,
+ },
+ "spec_to_functions": {
+ "sources": [ByteStream.from_string(json.dumps(serperdev_spec))],
+ },
+ "message_adapter": {
+ "system_message": [ChatMessage.from_system(system_prompt)],
+ },
+ },
+)
+
+print(result["llm"]["replies"][0].text)
+
+# Sam Altman was ousted from OpenAI on November 17, 2023, following
+# a "deliberative review process" by the board of directors. The board concluded
+# that he was not "consistently candid in his communications". However, he
+# returned as CEO just days after his ouster.
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/weaveconnector.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/weaveconnector.mdx
new file mode 100644
index 0000000000..5e64e130d5
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/connectors/weaveconnector.mdx
@@ -0,0 +1,184 @@
+---
+title: "WeaveConnector"
+id: weaveconnector
+slug: "/weaveconnector"
+description: "Learn how to use Weights & Biases Weave framework for tracing and monitoring your pipeline components."
+---
+
+# WeaveConnector
+
+Learn how to use Weights & Biases Weave framework for tracing and monitoring your pipeline components.
+
+`service_openapi_spec`: OpenAPI specification of the service being invoked. It can be YAML/JSON, and all ref values must be resolved.
`service_credentials`: Authentication credentials for the service. We currently support two OpenAPI spec v3 security schemes:
1. http – for Basic, Bearer, and other HTTP authentication schemes;
2. apiKey – for API keys and cookie authentication. | +| **Output variables** | `service_response`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects where each message corresponds to a tool call invocation.
If a message contains multiple tool calls, there will be multiple responses. | +| **API reference** | [Connectors](/reference/connectors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/connectors/openapi_service.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Anywhere, as it’s not connected to other components |
+| **Mandatory init variables** | `pipeline_name`: The name of your pipeline, which will also show up in Weaver dashboard. |
+| **Output variables** | `pipeline_name`: The name of the pipeline that just run |
+| **API reference** | [Weave](/reference/integrations-weave) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/weave |
+| **Package name** | `weave-haystack` |
+
+
+
+## Overview
+
+This integration allows you to trace and visualize your pipeline execution in [Weights & Biases](https://wandb.ai/site/).
+
+Information captured by the Haystack tracing tool, such as API calls, context data, and prompts, is sent to Weights & Biases, where you can see the complete trace of your pipeline execution.
+
+### Prerequisites
+
+You need a Weave account to use this feature. You can sign up for free at [Weights & Biases website](https://wandb.ai/site).
+
+You will then need to set the `WANDB_API_KEY` environment variable with your Weights & Biases API key. Once logged in, you can find your API key on [your home page](https://wandb.ai/home).
+
+Then go to `https://wandb.ai/
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx), or right at the beginning of an indexing pipeline |
+| **Mandatory init variables** | `endpoint`: The endpoint URL of your Azure Document Intelligence resource
`api_key`: The API key for Azure authentication. Can be set with `AZURE_DI_API_KEY` environment variable. | +| **Mandatory run variables** | `sources`: A list of file paths or ByteStream objects | +| **Output variables** | `documents`: A list of documents
`raw_azure_response`: A list of raw responses from Azure | +| **API reference** | [Azure Document Intelligence](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_doc_intelligence) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_doc_intelligence | +| **Package name** | `azure-doc-intelligence-haystack` | + +
+
+## Overview
+
+`AzureDocumentIntelligenceConverter` takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and uses Azure's Document Intelligence service to convert the files to a list of documents. Optionally, metadata can be attached to the documents through the `meta` input parameter. You need an active Azure account and a Document Intelligence or Cognitive Services resource to use this integration. Follow the steps described in the Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/quickstarts/get-started-sdks-rest-api) to set up your resource.
+
+The component uses an `AZURE_DI_API_KEY` environment variable by default. Otherwise, you can pass an `api_key` at initialization — see code examples below.
+
+This component uses the `azure-ai-documentintelligence` package (v1.0.0+) and outputs GitHub Flavored Markdown, preserving document structure such as headings, tables, and lists. Tables are rendered as inline markdown tables rather than being extracted as separate documents.
+
+When you initialize the component, you can optionally set the `model_id`, which refers to the model you want to use. Available options include:
+- `"prebuilt-document"`: General document analysis (default)
+- `"prebuilt-read"`: Fast OCR for text extraction
+- `"prebuilt-layout"`: Enhanced layout analysis with better table and structure detection
+- Custom model IDs from your Azure resource
+
+Refer to the [Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/choose-model-feature) for a full list of available models.
+
+:::info
+This component replaces the legacy [`AzureOCRDocumentConverter`](azureocrdocumentconverter.mdx), which uses the older `azure-ai-formrecognizer` package. The `AzureDocumentIntelligenceConverter` uses the newer `azure-ai-documentintelligence` SDK and produces Markdown output instead of plain text, making it better suited for LLM and RAG applications.
+:::
+
+:::note
+This component returns Markdown content. Avoid piping it through `DocumentCleaner()` with its default settings because `remove_extra_whitespaces=True` and `remove_empty_lines=True` can collapse line breaks and flatten headings, tables, and lists. Connect the converter directly to your next component, or disable those options if you need custom cleanup.
+:::
+
+## Usage
+
+You need to install the `azure-doc-intelligence-haystack` integration to use the `AzureDocumentIntelligenceConverter`:
+
+```shell
+pip install azure-doc-intelligence-haystack
+```
+
+### On its own
+
+```python
+from pathlib import Path
+
+from haystack_integrations.components.converters.azure_doc_intelligence import (
+ AzureDocumentIntelligenceConverter,
+)
+from haystack.utils import Secret
+
+converter = AzureDocumentIntelligenceConverter(
+ endpoint="https://YOUR_RESOURCE.cognitiveservices.azure.com/",
+ api_key=Secret.from_env_var("AZURE_DI_API_KEY"),
+)
+
+result = converter.run(sources=[Path("my_file.pdf")])
+documents = result["documents"]
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+from haystack.utils import Secret
+from haystack_integrations.components.converters.azure_doc_intelligence import (
+ AzureDocumentIntelligenceConverter,
+)
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component(
+ "converter",
+ AzureDocumentIntelligenceConverter(
+ endpoint="https://YOUR_RESOURCE.cognitiveservices.azure.com/",
+ api_key=Secret.from_env_var("AZURE_DI_API_KEY"),
+ ),
+)
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "splitter")
+pipeline.connect("splitter", "writer")
+
+file_names = ["my_file.pdf"]
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/azureocrdocumentconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/azureocrdocumentconverter.mdx
new file mode 100644
index 0000000000..1d8239f2c8
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/azureocrdocumentconverter.mdx
@@ -0,0 +1,93 @@
+---
+title: "AzureOCRDocumentConverter"
+id: azureocrdocumentconverter
+slug: "/azureocrdocumentconverter"
+description: "`AzureOCRDocumentConverter` converts files to documents using Azure's Document Intelligence service. It supports the following file formats: PDF (both searchable and image-only), JPEG, PNG, BMP, TIFF, DOCX, XLSX, PPTX, and HTML."
+---
+
+# AzureOCRDocumentConverter
+
+`AzureOCRDocumentConverter` converts files to documents using Azure's Document Intelligence service. It supports the following file formats: PDF (both searchable and image-only), JPEG, PNG, BMP, TIFF, DOCX, XLSX, PPTX, and HTML.
+
+`api_key`: The API key for Azure authentication. Can be set with `AZURE_DI_API_KEY` environment variable. | +| **Mandatory run variables** | `sources`: A list of file paths or ByteStream objects | +| **Output variables** | `documents`: A list of documents
`raw_azure_response`: A list of raw responses from Azure | +| **API reference** | [Azure Document Intelligence](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_doc_intelligence) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_doc_intelligence | +| **Package name** | `azure-doc-intelligence-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory init variables** | `endpoint`: The endpoint of your Azure resource
`api_key`: The API key of your Azure resource. Can be set with `AZURE_AI_API_KEY` environment variable. | +| **Mandatory run variables** | `sources`: A list of file paths | +| **Output variables** | `documents`: A list of documents
`raw_azure_response`: A list of raw responses from Azure | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/azure.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`AzureOCRDocumentConverter` takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and uses Azure services to convert the files to a list of documents. Optionally, metadata can be attached to the documents through the `meta` input parameter. You need an active Azure account and a Document Intelligence or Cognitive Services resource to use this integration. Follow the steps described in the Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/quickstarts/get-started-sdks-rest-api) to set up your resource.
+
+The component uses an `AZURE_AI_API_KEY` environment variable by default. Otherwise, you can pass an `api_key` at initialization – see code examples below.
+
+When you initialize the component, you can optionally set the `model_id`, which refers to the model you want to use. Please refer to [Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/choose-model-feature) for a list of available models. The default model is `"prebuilt-read"`.
+
+The `AzureOCRDocumentConverter` doesn’t extract the tables from a file as plain text but generates separate `Document` objects of type `table` that maintain the two-dimensional structure of the tables.
+
+## Usage
+
+You need to install `azure-ai-formrecognizer` package to use the `AzureOCRDocumentConverter`:
+
+```shell
+pip install "azure-ai-formrecognizer>=3.2.0b2"
+```
+
+### On its own
+
+```python
+from pathlib import Path
+
+from haystack.components.converters import AzureOCRDocumentConverter
+from haystack.utils import Secret
+
+converter = AzureOCRDocumentConverter(
+ endpoint="azure_resource_url",
+ api_key=Secret.from_token("`api_key`: The API key of your Azure resource. Can be set with `AZURE_AI_API_KEY` environment variable. | +| **Mandatory run variables** | `sources`: A list of file paths | +| **Output variables** | `documents`: A list of documents
`raw_azure_response`: A list of raw responses from Azure | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/azure.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/csv.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`CSVToDocument` converts one or more CSV files into a text document.
+
+The component uses UTF-8 encoding by default, but you may specify a different encoding if needed during initialization.
+You can optionally attach metadata to each document with a `meta` parameter when running the component.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.converters.csv import CSVToDocument
+
+converter = CSVToDocument()
+results = converter.run(
+ sources=["sample.csv"],
+ meta={"date_added": datetime.now().isoformat()},
+)
+documents = results["documents"]
+
+print(documents[0].content)
+## 'col1,col2\now1,row1\nrow2row2\n'
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import CSVToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", CSVToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/doclingconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/doclingconverter.mdx
new file mode 100644
index 0000000000..823e73ac10
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/doclingconverter.mdx
@@ -0,0 +1,138 @@
+---
+title: "DoclingConverter"
+id: doclingconverter
+slug: "/doclingconverter"
+description: "`DoclingConverter` converts PDF, DOCX, HTML, and other document formats to Haystack Documents using Docling, with support for layout-aware chunking, Markdown, and JSON export."
+---
+
+# DoclingConverter
+
+`DoclingConverter` converts PDF, DOCX, HTML, and other document formats to Haystack Documents using [Docling](https://ds4sd.github.io/docling/), a document parsing library that understands document structure including layout, tables, and headings.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx), or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of file paths, URLs, or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Docling](/reference/integrations-docling) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/docling |
+| **Package name** | `docling-haystack` |
+
+
+
+## Overview
+
+The `DoclingConverter` takes a list of file paths, URLs, or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects and uses Docling to parse them into a rich document representation that captures layout, tables, headings, and other structural elements.
+
+The component supports three export modes, controlled by the `export_type` parameter:
+
+- **`ExportType.DOC_CHUNKS`** (default): Chunks each document using Docling's `HybridChunker` and returns one [`Document`](../../concepts/data-classes.mdx#document) per chunk. Chunk metadata includes structural context from Docling. Use this mode for indexing pipelines where downstream retrieval benefits from semantically coherent chunks.
+- **`ExportType.MARKDOWN`**: Exports each input document as a single Markdown string in one [`Document`](../../concepts/data-classes.mdx#document). Use this mode when you want to preserve the full document content as formatted text.
+- **`ExportType.JSON`**: Serializes the full Docling document to a JSON string in one [`Document`](../../concepts/data-classes.mdx#document). Use this mode when you need access to the complete structured representation.
+
+You can customize parsing behavior by passing a pre-configured `DocumentConverter` instance via the `converter` parameter, and pass additional keyword arguments to Docling's conversion step via `convert_kwargs`. For `ExportType.MARKDOWN`, use `md_export_kwargs` to control Markdown rendering options (for example, image placeholder text). For `ExportType.DOC_CHUNKS`, provide a custom `BaseChunker` instance via the `chunker` parameter.
+
+Document metadata is populated by a `MetaExtractor` instance. The default `MetaExtractor` adds Docling-specific metadata (chunk structure or document origin) under the `dl_meta` key. You can supply a custom `BaseMetaExtractor` implementation via the `meta_extractor` parameter. Additional metadata can be attached to all output Documents by passing a dictionary to the `meta` run parameter, or per source by passing a list of dictionaries.
+
+## Usage
+
+Install the Docling integration:
+
+```shell
+pip install docling-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.converters.docling import (
+ DoclingConverter,
+ ExportType,
+)
+
+# Default: chunk-based output
+converter = DoclingConverter()
+result = converter.run(sources=["report.pdf", "notes.docx"])
+documents = result["documents"]
+
+# Full document as Markdown
+converter = DoclingConverter(export_type=ExportType.MARKDOWN)
+result = converter.run(sources=["report.pdf"])
+documents = result["documents"]
+print(documents[0].content)
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.converters.docling import DoclingConverter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", DoclingConverter())
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "writer")
+
+pipeline.run({"converter": {"sources": ["report.pdf", "manual.docx"]}})
+```
+
+Because `DoclingConverter` with `ExportType.DOC_CHUNKS` already chunks the documents, you typically don't need a separate `DocumentSplitter` in the pipeline.
+
+## Additional Features
+
+### Custom chunking
+
+Provide a custom Docling chunker to control how documents are split:
+
+```python
+from docling.chunking import HybridChunker
+from haystack_integrations.components.converters.docling import DoclingConverter
+
+chunker = HybridChunker(tokenizer="BAAI/bge-small-en-v1.5", max_tokens=256)
+converter = DoclingConverter(chunker=chunker)
+result = converter.run(sources=["report.pdf"])
+```
+
+### Attaching metadata
+
+Pass a single dictionary to apply metadata to all output Documents, or a list to set metadata per source:
+
+```python
+from haystack_integrations.components.converters.docling import DoclingConverter
+
+converter = DoclingConverter()
+
+# Same metadata for all sources
+result = converter.run(
+ sources=["a.pdf", "b.pdf"],
+ meta={"project": "research"},
+)
+
+# Per-source metadata
+result = converter.run(
+ sources=["a.pdf", "b.pdf"],
+ meta=[{"title": "Report A"}, {"title": "Report B"}],
+)
+```
+
+### Processing in-memory files
+
+Pass [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects to convert files loaded into memory. Set `file_path` in the ByteStream metadata so Docling can detect the file format:
+
+```python
+from haystack.dataclasses import ByteStream
+from haystack_integrations.components.converters.docling import DoclingConverter
+
+with open("report.pdf", "rb") as f:
+ data = f.read()
+
+source = ByteStream(data=data, meta={"file_path": "report.pdf"})
+converter = DoclingConverter()
+result = converter.run(sources=[source])
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/doclingserveconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/doclingserveconverter.mdx
new file mode 100644
index 0000000000..c042198a94
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/doclingserveconverter.mdx
@@ -0,0 +1,161 @@
+---
+title: "DoclingServeConverter"
+id: doclingserveconverter
+slug: "/doclingserveconverter"
+description: "`DoclingServeConverter` converts PDF, DOCX, HTML, and other document formats to Haystack Documents by calling a remote DoclingServe HTTP server, with no local ML dependencies."
+---
+
+# DoclingServeConverter
+
+`DoclingServeConverter` converts PDF, DOCX, HTML, and other document formats to Haystack Documents by calling a [DoclingServe](https://github.com/docling-project/docling-serve) HTTP server. Unlike the local [`DoclingConverter`](doclingconverter.mdx), this component has no heavy ML dependencies — all document parsing happens on the remote server.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx), or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of file paths, URLs, or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Docling Serve](/reference/integrations-docling_serve) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/docling_serve |
+| **Package name** | `docling-serve-haystack` |
+
+
+
+## Overview
+
+The `DoclingServeConverter` takes a list of file paths, URLs, or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects and sends them to a running DoclingServe instance for parsing. Local files and `ByteStream` objects are uploaded to the `/v1/convert/file` endpoint; URL strings are sent to `/v1/convert/source`.
+
+The component supports three export modes, controlled by the `export_type` parameter:
+
+- **`ExportType.MARKDOWN`** (default): Returns the document content as a Markdown string. Use this mode when you want well-structured text output with formatting preserved.
+- **`ExportType.TEXT`**: Returns plain text extracted from the document. Use this mode when you need clean, unformatted text.
+- **`ExportType.JSON`**: Returns the full Docling document representation as a JSON string. Use this mode when you need access to the complete structured representation.
+
+Each source produces one [`Document`](../../concepts/data-classes.mdx#document) in the output. Sources that fail to convert are skipped with a warning logged.
+
+You can pass additional conversion options to the DoclingServe API via the `convert_options` parameter (for example, `{"do_ocr": True, "ocr_engine": "tesseract"}`). If the DoclingServe instance requires authentication, pass the API key via the `api_key` parameter or set the `DOCLING_SERVE_API_KEY` environment variable.
+
+The component supports both synchronous (`run`) and asynchronous (`run_async`) execution.
+
+## Usage
+
+Install the Docling Serve integration:
+
+```shell
+pip install docling-serve-haystack
+```
+
+Start a DoclingServe instance locally (requires Docker):
+
+```shell
+docker run -p 5001:5001 ghcr.io/docling-project/docling-serve-cpu:latest
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.converters.docling_serve import (
+ DoclingServeConverter,
+)
+
+# Default: Markdown output
+converter = DoclingServeConverter(base_url="http://localhost:5001")
+result = converter.run(sources=["report.pdf", "notes.docx"])
+documents = result["documents"]
+print(documents[0].content[:200])
+
+# Plain text output
+from haystack_integrations.components.converters.docling_serve import ExportType
+
+converter = DoclingServeConverter(
+ base_url="http://localhost:5001",
+ export_type=ExportType.TEXT,
+)
+result = converter.run(sources=["report.pdf"])
+print(result["documents"][0].content)
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.converters.docling_serve import (
+ DoclingServeConverter,
+)
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component(
+ "converter",
+ DoclingServeConverter(base_url="http://localhost:5001"),
+)
+pipeline.add_component("splitter", DocumentSplitter())
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": ["report.pdf", "manual.docx"]}})
+```
+
+## Additional Features
+
+### Converting URLs directly
+
+Pass URL strings to convert remote documents without downloading them first:
+
+```python
+from haystack_integrations.components.converters.docling_serve import (
+ DoclingServeConverter,
+)
+
+converter = DoclingServeConverter(base_url="http://localhost:5001")
+result = converter.run(sources=["https://arxiv.org/pdf/2602.17316"])
+print(result["documents"][0].content[:200])
+```
+
+### Attaching metadata
+
+Pass a single dictionary to apply metadata to all output Documents, or a list to set metadata per source:
+
+```python
+from haystack_integrations.components.converters.docling_serve import (
+ DoclingServeConverter,
+)
+
+converter = DoclingServeConverter(base_url="http://localhost:5001")
+
+# Same metadata for all sources
+result = converter.run(
+ sources=["a.pdf", "b.pdf"],
+ meta={"project": "research"},
+)
+
+# Per-source metadata
+result = converter.run(
+ sources=["a.pdf", "b.pdf"],
+ meta=[{"title": "Report A"}, {"title": "Report B"}],
+)
+```
+
+### Processing in-memory files
+
+Pass [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects to convert files loaded into memory. Set `file_path` in the ByteStream metadata so DoclingServe can detect the file format:
+
+```python
+from haystack.dataclasses import ByteStream
+from haystack_integrations.components.converters.docling_serve import (
+ DoclingServeConverter,
+)
+
+with open("report.pdf", "rb") as f:
+ data = f.read()
+
+source = ByteStream(data=data, meta={"file_path": "report.pdf"})
+converter = DoclingServeConverter(base_url="http://localhost:5001")
+result = converter.run(sources=[source])
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/documenttoimagecontent.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/documenttoimagecontent.mdx
new file mode 100644
index 0000000000..1c27a0fd2c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/documenttoimagecontent.mdx
@@ -0,0 +1,154 @@
+---
+title: "DocumentToImageContent"
+id: documenttoimagecontent
+slug: "/documenttoimagecontent"
+description: "`DocumentToImageContent` extracts visual data from image or PDF file-based documents and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image question-answering and captioning."
+---
+
+# DocumentToImageContent
+
+`DocumentToImageContent` extracts visual data from image or PDF file-based documents and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image question-answering and captioning.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a `ChatPromptBuilder` in a query pipeline |
+| **Mandatory run variables** | `documents`: A list of documents to process. Each document should have metadata containing at minimum a 'file_path_meta_field' key. PDF documents additionally require a 'page_number' key to specify which page to convert. |
+| **Output variables** | `image_contents`: A list of `ImageContent` objects |
+| **API reference** | [Image Converters](/reference/image-converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/image/document_to_image.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`DocumentToImageContent` processes a list of documents containing image or PDF file paths and converts them into `ImageContent` objects.
+
+- For images, it reads and encodes the file directly.
+- For PDFs, it extracts the specified page (through `page_number` in metadata) and converts it to an image.
+
+By default, it looks for the file path in the `file_path` metadata field. You can customize this with the `file_path_meta_field` parameter. The `root_path` lets you specify a common base directory for file resolution.
+
+This component is typically used in query pipelines right before a `ChatPromptBuilder` when you would like to add Images to your user prompt.
+
+If `size` is provided, the images will be resized while maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial when working with models that have resolution constraints or when transmitting images to remote services.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.converters.image.document_to_image import (
+ DocumentToImageContent,
+)
+
+converter = DocumentToImageContent(
+ file_path_meta_field="file_path",
+ root_path="/data/documents",
+ detail="high",
+ size=(800, 600),
+)
+
+documents = [
+ Document(content="Photo of a mountain", meta={"file_path": "mountain.jpg"}),
+ Document(
+ content="First page of a report",
+ meta={"file_path": "report.pdf", "page_number": 1},
+ ),
+]
+
+result = converter.run(documents)
+image_contents = result["image_contents"]
+print(image_contents)
+
+## [
+## ImageContent(
+## base64_image="/9j/4A...", mime_type="image/jpeg", detail="high",
+## meta={"file_path": "mountain.jpg"}
+## ),
+## ImageContent(
+## base64_image="/9j/4A...", mime_type="image/jpeg", detail="high",
+## meta={"file_path": "report.pdf", "page_number": 1}
+## )
+## ]
+```
+
+### In a pipeline
+
+You can use `DocumentToImageContent` in multimodal indexing pipelines before passing to an Embedder or captioning model.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.converters.image.document_to_image import (
+ DocumentToImageContent,
+)
+
+## Query pipeline
+pipeline = Pipeline()
+pipeline.add_component("image_converter", DocumentToImageContent(detail="auto"))
+pipeline.add_component(
+ "chat_prompt_builder",
+ ChatPromptBuilder(
+ required_variables=["question"],
+ template="""{% message role="system" %}
+You are a friendly assistant that answers questions based on provided images.
+{% endmessage %}
+
+{%- message role="user" -%}
+Only provide an answer to the question using the images provided.
+
+Question: {{ question }}
+Answer:
+
+{%- for img in image_contents -%}
+ {{ img | templatize_part }}
+{%- endfor -%}
+{%- endmessage -%}
+""",
+ ),
+)
+pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+
+pipeline.connect("image_converter", "chat_prompt_builder.image_contents")
+pipeline.connect("chat_prompt_builder", "llm")
+
+documents = [
+ Document(content="Cat image", meta={"file_path": "cat.jpg"}),
+ Document(content="Doc intro", meta={"file_path": "paper.pdf", "page_number": 1}),
+]
+
+result = pipeline.run(
+ data={
+ "image_converter": {"documents": documents},
+ "chat_prompt_builder": {"question": "What color is the cat?"},
+ },
+)
+print(result)
+
+## {
+## "llm": {
+## "replies": [
+## ChatMessage(
+## _role=
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: DOCX file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/docx.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `DOCXToDocument` component converts DOCX files into documents. It takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. By defining the table format (CSV or Markdown), you can use this component to extract tables in your DOCX files. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+## Usage
+
+First, install the`python-docx` package to start using this converter:
+
+```shell
+pip install python-docx
+```
+
+### On its own
+
+```python
+from haystack.components.converters.docx import DOCXToDocument, DOCXTableFormat
+
+converter = DOCXToDocument()
+## or define the table format
+converter = DOCXToDocument(table_format=DOCXTableFormat.CSV)
+
+results = converter.run(
+ sources=["sample.docx"],
+ meta={"date_added": datetime.now().isoformat()},
+)
+documents = results["documents"]
+
+print(documents[0].content)
+
+## 'This is the text from the DOCX file.'
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import DOCXToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", DOCXToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/filetofilecontent.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/filetofilecontent.mdx
new file mode 100644
index 0000000000..642817a081
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/filetofilecontent.mdx
@@ -0,0 +1,106 @@
+---
+title: "FileToFileContent"
+id: filetofilecontent
+slug: "/filetofilecontent"
+description: "`FileToFileContent` reads local files and converts them into `FileContent` objects"
+---
+
+# FileToFileContent
+
+`FileToFileContent` reads local files and converts them into `FileContent` objects. These are ready for multimodal AI pipelines that need to pass PDFs and other file types to an LLM.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a `ChatPromptBuilder` in a query pipeline |
+| **Mandatory run variables** | `sources`: A list of file paths or ByteStreams |
+| **Output variables** | `file_contents`: A list of `FileContent` objects |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/file_to_file_content.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`FileToFileContent` processes a list of file sources and converts them into `FileContent` objects that can be embedded
+into a `ChatMessage` and passed to a Language Model.
+
+Each source can be:
+
+- A file path (string or `Path`), or
+- A `ByteStream` object.
+
+Optionally, you can provide extra provider-specific information using the `extra` parameter. This can be a single dictionary (applied to all files) or a list matching the length of `sources`.
+
+Support for passing files to LLMs varies by provider. Some providers do not support file inputs, some restrict support
+to PDF files, and others accept a wider range of file types.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.converters import FileToFileContent
+
+converter = FileToFileContent()
+
+sources = ["document.pdf", "recording.mp3"]
+
+result = converter.run(sources=sources)
+file_contents = result["file_contents"]
+print(file_contents)
+
+## [
+## FileContent(
+## base64_data='JVBERi0x...', mime_type='application/pdf',
+## filename='document.pdf', extra={}
+## ),
+## FileContent(
+## base64_data='SUQzBA...', mime_type='audio/mpeg',
+## filename='recording.mp3', extra={}
+## )
+## ]
+```
+
+### In a pipeline
+
+Use `FileToFileContent` together with a `LinkContentFetcher` and a `ChatPromptBuilder` to build a pipeline that fetches a remote file, converts it, and passes it to an LLM.
+
+```python
+from haystack.components.converters import FileToFileContent
+from haystack.components.fetchers import LinkContentFetcher
+from haystack.components.generators.chat.openai import OpenAIChatGenerator
+from haystack.components.builders import ChatPromptBuilder
+
+from haystack import Pipeline
+
+template = """
+{% message role="user"%}
+{% for file in files %}
+{{ file | templatize_part }}
+{% endfor %}
+What's the main takeaway of the following document? Just one sentence.
+{% endmessage %}
+"""
+
+pipeline = Pipeline()
+pipeline.add_component("fetcher", LinkContentFetcher())
+pipeline.add_component("converter", FileToFileContent())
+pipeline.add_component("prompt_builder", ChatPromptBuilder(template=template))
+pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4.1-mini"))
+
+pipeline.connect("fetcher", "converter")
+pipeline.connect("converter", "prompt_builder")
+pipeline.connect("prompt_builder", "llm")
+
+results = pipeline.run({"fetcher": {"urls": ["https://arxiv.org/pdf/2309.08632"]}})
+
+print(results["llm"]["replies"][0].text)
+
+# The document is a satirical paper humorously claiming that pretraining a
+# small language model exclusively on evaluation benchmark test sets can achieve
+# perfect performance, highlighting issues of data contamination in model
+# evaluation.
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/htmltodocument.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/htmltodocument.mdx
new file mode 100644
index 0000000000..fa8e1676b7
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/htmltodocument.mdx
@@ -0,0 +1,71 @@
+---
+title: "HTMLToDocument"
+id: htmltodocument
+slug: "/htmltodocument"
+description: "A component that converts HTML files to documents."
+---
+
+# HTMLToDocument
+
+A component that converts HTML files to documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of HTML file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/html.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `HTMLToDocument` component converts HTML files into documents. It can be used in an indexing pipeline to index the contents of an HTML file into a Document Store or even in a querying pipeline after the [`LinkContentFetcher`](../fetchers/linkcontentfetcher.mdx). The `HTMLToDocument` component takes a list of HTML file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and converts the files to a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+When you initialize the component, you can optionally set `extraction_kwargs`, a dictionary containing keyword arguments to customize the extraction process. These are passed to the underlying Trafilatura `extract` function. For the full list of available arguments, see the [Trafilatura documentation](https://trafilatura.readthedocs.io/en/latest/corefunctions.html#extract).
+
+## Usage
+
+### On its own
+
+```python
+from pathlib import Path
+from haystack.components.converters import HTMLToDocument
+
+converter = HTMLToDocument()
+
+docs = converter.run(sources=[Path("saved_page.html")])
+```
+
+### In a pipeline
+
+Here's an example of an indexing pipeline that writes the contents of an HTML file into an `InMemoryDocumentStore`:
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import HTMLToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", HTMLToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/imagefiletodocument.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/imagefiletodocument.mdx
new file mode 100644
index 0000000000..8f63fabbde
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/imagefiletodocument.mdx
@@ -0,0 +1,105 @@
+---
+title: "ImageFileToDocument"
+id: imagefiletodocument
+slug: "/imagefiletodocument"
+description: "Converts image file references into empty `Document` objects with associated metadata."
+---
+
+# ImageFileToDocument
+
+Converts image file references into empty `Document` objects with associated metadata.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a component that processes images, like `SentenceTransformersImageDocumentEmbedder` or `LLMDocumentContentExtractor` |
+| **Mandatory run variables** | `sources`: A list of image file paths or ByteStreams |
+| **Output variables** | `documents`: A list of empty Document objects with associated metadata |
+| **API reference** | [Image Converters](/reference/image-converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/image/file_to_document.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`ImageFileToDocument` converts image file sources into empty `Document` objects with associated metadata.
+
+This component is useful in pipelines where image file paths need to be wrapped in `Document` objects to be processed by downstream components such as `SentenceTransformersImageDocumentEmbedder` or `LLMDocumentContentExtractor`.
+
+It _does not_ extract any content from the image files, but instead creates `Document` objects with `None` as their content and attaches metadata such as file path and any user-provided values.
+
+Each source can be:
+
+- A file path (string or `Path`), or
+- A `ByteStream` object.
+
+Optionally, you can provide metadata using the `meta` parameter. This can be a single dictionary (applied to all documents) or a list matching the length of `sources`.
+
+## Usage
+
+### On its own
+
+This component is primarily meant to be used in pipelines.
+
+```python
+
+from haystack.components.converters.image import ImageFileToDocument
+
+converter = ImageFileToDocument()
+
+sources = ["image.jpg", "another_image.png"]
+
+result = converter.run(sources=sources)
+documents = result["documents"]
+
+print(documents)
+
+## [Document(id=..., content=None, meta={'file_path': 'image.jpg'}),
+## Document(id=..., content=None, meta={'file_path': 'another_image.png'})]
+```
+
+### In a pipeline
+
+In the following Pipeline, image documents are created using the `ImageFileToDocument` component, then they are enriched with image embeddings and saved in the Document Store.
+
+```python
+from haystack import Pipeline
+from haystack.components.converters.image import ImageFileToDocument
+from haystack.components.embedders.image import (
+ SentenceTransformersDocumentImageEmbedder,
+)
+from haystack.components.writers.document_writer import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+## Create our document store
+doc_store = InMemoryDocumentStore()
+
+## Define pipeline with components
+indexing_pipe = Pipeline()
+indexing_pipe.add_component(
+ "image_converter",
+ ImageFileToDocument(store_full_path=True),
+)
+indexing_pipe.add_component(
+ "image_doc_embedder",
+ SentenceTransformersDocumentImageEmbedder(),
+)
+indexing_pipe.add_component("document_writer", DocumentWriter(doc_store))
+
+indexing_pipe.connect("image_converter.documents", "image_doc_embedder.documents")
+indexing_pipe.connect("image_doc_embedder.documents", "document_writer.documents")
+
+indexing_result = indexing_pipe.run(
+ data={"image_converter": {"sources": ["apple.jpg", "kiwi.png"]}},
+)
+
+indexed_documents = doc_store.filter_documents()
+print(f"Indexed {len(indexed_documents)} documents")
+## Indexed 2 documents
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Introduction to Multimodality](https://haystack.deepset.ai/cookbook/multimodal_intro)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/imagefiletoimagecontent.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/imagefiletoimagecontent.mdx
new file mode 100644
index 0000000000..61d7456c16
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/imagefiletoimagecontent.mdx
@@ -0,0 +1,129 @@
+---
+title: "ImageFileToImageContent"
+id: imagefiletoimagecontent
+slug: "/imagefiletoimagecontent"
+description: "`ImageFileToImageContent` reads local image files and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image captioning, visual QA, or prompt-based generation."
+---
+
+# ImageFileToImageContent
+
+`ImageFileToImageContent` reads local image files and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image captioning, visual QA, or prompt-based generation.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a `ChatPromptBuilder` in a query pipeline |
+| **Mandatory run variables** | `sources`: A list of image file paths or ByteStreams |
+| **Output variables** | `image_contents`: A list of ImageContent objects |
+| **API reference** | [Image Converters](/reference/image-converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/image/file_to_image.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`ImageFileToImageContent` processes a list of image sources and converts them into `ImageContent` objects. These can be used in multimodal pipelines that require base64-encoded image input.
+
+Each source can be:
+
+- A file path (string or `Path`), or
+- A `ByteStream` object.
+
+Optionally, you can provide metadata using the `meta` parameter. This can be a single dictionary (applied to all images) or a list matching the length of `sources`.
+
+Use the `size` parameter to resize images while preserving aspect ratio. This reduces memory usage and transmission size, which is helpful when working with remote models or limited-resource environments.
+
+This component is often used in query pipelines just before a `ChatPromptBuilder`.
+
+## Usage
+
+### On its own
+
+```python
+
+from haystack.components.converters.image import ImageFileToImageContent
+
+converter = ImageFileToImageContent(detail="high", size=(800, 600))
+
+sources = ["cat.jpg", "scenery.png"]
+
+result = converter.run(sources=sources)
+image_contents = result["image_contents"]
+print(image_contents)
+
+## [
+## ImageContent(
+## base64_image="/9j/4A...", mime_type="image/jpeg", detail="high",
+## meta={"file_path": "cat.jpg"}
+## ),
+## ImageContent(
+## base64_image="/9j/4A...", mime_type="image/png", detail="high",
+## meta={"file_path": "scenery.png"}
+## )
+## ]
+```
+
+### In a pipeline
+
+Use `ImageFileToImageContent` to supply image data to a `ChatPromptBuilder` for multimodal QA or captioning with an LLM.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.converters.image import ImageFileToImageContent
+
+## Query pipeline
+pipeline = Pipeline()
+pipeline.add_component("image_converter", ImageFileToImageContent(detail="auto"))
+pipeline.add_component(
+ "chat_prompt_builder",
+ ChatPromptBuilder(
+ required_variables=["question"],
+ template="""{% message role="system" %}
+You are a helpful assistant that answers questions using the provided images.
+{% endmessage %}
+
+{% message role="user" %}
+Question: {{ question }}
+
+{% for img in image_contents %}
+{{ img | templatize_part }}
+{% endfor %}
+{% endmessage %}
+""",
+ ),
+)
+pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+
+pipeline.connect("image_converter", "chat_prompt_builder.image_contents")
+pipeline.connect("chat_prompt_builder", "llm")
+
+sources = ["apple.jpg", "haystack-logo.png"]
+
+result = pipeline.run(
+ data={
+ "image_converter": {"sources": sources},
+ "chat_prompt_builder": {"question": "Describe the Haystack logo."},
+ },
+)
+print(result)
+
+## {
+## "llm": {
+## "replies": [
+## ChatMessage(
+## _role=
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory init variables** | ONE OF, OR BOTH:
`jq_schema`: A jq filter string to extract content
`content_key`: A key string to extract document content | +| **Mandatory run variables** | `sources`: A list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/json.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`JSONConverter` converts one or more JSON files into a text document.
+
+### Parameters Overview
+
+To initialize `JSONConverter`, you must provide either `jq_schema`, or `content_key` parameter, or both.
+
+`jq_schema` parameter filter extracts nested data from JSON files. Refer to the [jq documentation](https://jqlang.github.io/jq/) for filter syntax. If not set, the entire JSON file is used.
+
+The `content_key` parameter lets you specify which key in the extracted data will be the document's content.
+
+- If both `jq_schema` and `content_key` are set, the `content_key` is searched in the data extracted by `jq_schema`. Non-object data will be skipped.
+- If only `jq_schema` is set, the extracted value must be scalar; objects or arrays will be skipped.
+- If only `content_key` is set, the source must be a JSON object, or it will be skipped.
+
+Check out the [API reference](../converters.mdx) for the full list of parameters.
+
+## Usage
+
+You need to install the `jq` package to use this Converter:
+
+```shell
+pip install jq
+```
+
+### Example
+
+Here is an example of simple component usage:
+
+```python
+import json
+
+from haystack.components.converters import JSONConverter
+from haystack.dataclasses import ByteStream
+
+source = ByteStream.from_string(
+ json.dumps({"text": "This is the content of my document"}),
+)
+
+converter = JSONConverter(content_key="text")
+results = converter.run(sources=[source])
+documents = results["documents"]
+print(documents[0].content)
+## 'This is the content of my document'
+```
+
+In the following more complex example, we provide a `jq_schema` string to filter the JSON source files and `extra_meta_fields` to extract from the filtered data:
+
+```python
+import json
+
+from haystack.components.converters import JSONConverter
+from haystack.dataclasses import ByteStream
+
+data = {
+ "laureates": [
+ {
+ "firstname": "Enrico",
+ "surname": "Fermi",
+ "motivation": "for his demonstrations of the existence of new radioactive elements produced "
+ "by neutron irradiation, and for his related discovery of nuclear reactions brought about by"
+ " slow neutrons",
+ },
+ {
+ "firstname": "Rita",
+ "surname": "Levi-Montalcini",
+ "motivation": "for their discoveries of growth factors",
+ },
+ ],
+}
+source = ByteStream.from_string(json.dumps(data))
+converter = JSONConverter(
+ jq_schema=".laureates[]",
+ content_key="motivation",
+ extra_meta_fields={"firstname", "surname"},
+)
+
+results = converter.run(sources=[source])
+documents = results["documents"]
+print(documents[0].content)
+## 'for his demonstrations of the existence of new radioactive elements produced by
+## neutron irradiation, and for his related discovery of nuclear reactions brought
+## about by slow neutrons'
+
+print(documents[0].meta)
+## {'firstname': 'Enrico', 'surname': 'Fermi'}
+
+print(documents[1].content)
+## 'for their discoveries of growth factors'
+
+print(documents[1].meta)
+## {'firstname': 'Rita', 'surname': 'Levi-Montalcini'}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/kreuzbergconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/kreuzbergconverter.mdx
new file mode 100644
index 0000000000..c3c1b19fae
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/kreuzbergconverter.mdx
@@ -0,0 +1,148 @@
+---
+title: "KreuzbergConverter"
+id: kreuzbergconverter
+slug: "/kreuzbergconverter"
+description: "`KreuzbergConverter` converts files to Haystack Documents using Kreuzberg, a document intelligence framework with a Rust core that extracts text from 91+ file formats entirely locally with no external API calls."
+---
+
+# KreuzbergConverter
+
+`KreuzbergConverter` converts files to Haystack Documents using [Kreuzberg](https://docs.kreuzberg.dev/), a document intelligence framework with a Rust core that extracts text from 91+ file formats entirely locally with no external API calls.
+
+`jq_schema`: A jq filter string to extract content
`content_key`: A key string to extract document content | +| **Mandatory run variables** | `sources`: A list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/json.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx), or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of file paths, directory paths, or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Kreuzberg](/reference/integrations-kreuzberg) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/kreuzberg |
+| **Package name** | `kreuzberg-haystack` |
+
+
+
+## Overview
+
+The `KreuzbergConverter` takes a list of file paths, directory paths, or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects and uses Kreuzberg to extract text and metadata. All processing is performed locally with no external API calls.
+
+**Supported format categories:**
+- **Documents**: PDF, DOCX, DOC, PPTX, PPT, XLSX, XLS, ODT, ODS, ODP, RTF, Pages, Keynote, Numbers, and more
+- **Images (via OCR)**: PNG, JPEG, TIFF, GIF, BMP, WebP, JPEG 2000, SVG
+- **Text/Markup**: Markdown, HTML, XML, LaTeX, Typst, JSON, YAML, reStructuredText, Jupyter notebooks
+- **Email**: EML, MSG (with attachment extraction)
+- **Archives**: ZIP, TAR, GZIP, 7Z (extracts and processes contents recursively)
+- **eBooks & Academic**: EPUB, BibTeX, DocBook, JATS
+
+The component returns one Haystack [`Document`](../../concepts/data-classes.mdx#document) per source by default. When per-page extraction or chunking is enabled, it returns one Document per page or chunk instead. Documents include rich metadata such as quality scores, detected languages, extracted keywords, table data, and PDF annotations.
+
+By default, batch processing is enabled, leveraging Rust's rayon thread pool for parallel extraction. Set `batch=False` for sequential processing.
+
+You can customize extraction behavior with Kreuzberg's `ExtractionConfig`, either passed directly or loaded from a TOML, YAML, or JSON configuration file via `config_path`. See the [Kreuzberg documentation](https://docs.kreuzberg.dev/) for the full configuration reference.
+
+## Usage
+
+Install the Kreuzberg integration:
+
+```shell
+pip install kreuzberg-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter
+
+converter = KreuzbergConverter()
+result = converter.run(sources=["report.pdf", "notes.docx"])
+documents = result["documents"]
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", KreuzbergConverter())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+
+pipeline.connect("converter", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": ["report.pdf", "presentation.pptx"]}})
+```
+
+## Additional Features
+
+### Markdown Output with OCR
+
+Use `ExtractionConfig` to customize the output format and OCR settings:
+
+```python
+from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter
+from kreuzberg import ExtractionConfig, OcrConfig
+
+converter = KreuzbergConverter(
+ config=ExtractionConfig(
+ output_format="markdown",
+ ocr=OcrConfig(backend="tesseract", language="eng"),
+ ),
+)
+result = converter.run(sources=["scanned_document.pdf"])
+documents = result["documents"]
+```
+
+### Per-Page Extraction
+
+Create one Document per page using `PageConfig`:
+
+```python
+from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter
+from kreuzberg import ExtractionConfig, PageConfig
+
+converter = KreuzbergConverter(
+ config=ExtractionConfig(
+ page=PageConfig(extract_pages=True),
+ ),
+)
+result = converter.run(sources=["multipage.pdf"])
+# One Document per page, each with page_number in metadata
+```
+
+### Token Reduction
+
+Reduce output size for LLM consumption with `TokenReductionConfig`. Token reduction uses TF-IDF-based extractive summarization to identify and preserve the most important terms and phrases, progressively removing less critical content such as extra whitespace, filler words, and redundant phrases. Five levels are available: `"off"` (no reduction), `"light"` (~15%), `"moderate"` (~30%), `"aggressive"` (~50%), and `"maximum"` (>50% reduction):
+
+```python
+from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter
+from kreuzberg import ExtractionConfig, TokenReductionConfig
+
+converter = KreuzbergConverter(
+ config=ExtractionConfig(
+ token_reduction=TokenReductionConfig(mode="moderate"),
+ ),
+)
+```
+
+### Config from File
+
+Load extraction settings from a TOML, YAML, or JSON file:
+
+```python
+from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter
+
+converter = KreuzbergConverter(config_path="extraction_config.toml")
+```
+
+For the full configuration reference and format support matrix, see the [Kreuzberg documentation](https://docs.kreuzberg.dev/).
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/libreofficefileconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/libreofficefileconverter.mdx
new file mode 100644
index 0000000000..aaea2dd84b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/libreofficefileconverter.mdx
@@ -0,0 +1,96 @@
+---
+title: "LibreOfficeFileConverter"
+id: libreofficefileconverter
+slug: "/libreofficefileconverter"
+description: "A component that converts office files (documents, spreadsheets, presentations) between formats using LibreOffice's command line interface."
+---
+
+# LibreOfficeFileConverter
+
+A component that converts office files between formats using LibreOffice's command line interface (`soffice`).
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a document converter (e.g. [`DOCXToDocument`](./docxtodocument.mdx)) when the source files need to be converted to a format that the converter supports |
+| **Mandatory run variables** | `sources`: File paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects; `output_file_type`: The target file format |
+| **Output variables** | `output`: A list of [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **API reference** | [LibreOffice](/reference/integrations-libreoffice) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/libreoffice |
+| **Package name** | `libreoffice-haystack` |
+
+
+
+## Overview
+
+`LibreOfficeFileConverter` converts office files from one format to another using LibreOffice's `soffice` command line utility. It supports a wide range of document, spreadsheet, and presentation formats and is useful when your pipeline receives files in a format that downstream converters don't support.
+
+Unlike most converters, `LibreOfficeFileConverter` outputs [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects rather than Haystack Documents. This means it's typically chained with a document converter (such as [`DOCXToDocument`](./docxtodocument.mdx) or [`PyPDFToDocument`](./pypdftodocument.mdx)) to produce the final Documents.
+
+**Requires LibreOffice to be installed** and available in `PATH` as `soffice`. See the [LibreOffice installation guide](https://www.libreoffice.org/get-help/install-howto/) for details.
+
+### Supported conversions
+
+| Category | Input formats | Possible output formats |
+| --- | --- | --- |
+| Documents | `doc`, `docx`, `odt`, `rtf`, `txt`, `html` | `pdf`, `docx`, `doc`, `odt`, `rtf`, `txt`, `html`, `epub` |
+| Spreadsheets | `xlsx`, `xls`, `ods`, `csv` | `pdf`, `xlsx`, `xls`, `ods`, `csv`, `html` |
+| Presentations | `pptx`, `ppt`, `odp` | `pdf`, `pptx`, `ppt`, `odp`, `html`, `png`, `jpg` |
+
+This is a non-exhaustive list. See the [LibreOffice filter documentation](https://help.libreoffice.org/latest/en-GB/text/shared/guide/convertfilters.html) for all supported conversions.
+
+## Usage
+
+Install the LibreOffice integration:
+
+```shell
+pip install libreoffice-haystack
+```
+
+### On its own
+
+```python
+from pathlib import Path
+from haystack_integrations.components.converters.libreoffice import (
+ LibreOfficeFileConverter,
+)
+
+converter = LibreOfficeFileConverter()
+result = converter.run(sources=[Path("sample.doc")], output_file_type="docx")
+bytestreams = result["output"]
+```
+
+You can also set `output_file_type` at initialization to avoid passing it on every `run()` call:
+
+```python
+converter = LibreOfficeFileConverter(output_file_type="pdf")
+result = converter.run(sources=[Path("report.pptx")])
+```
+
+### In a pipeline
+
+A common pattern is to chain `LibreOfficeFileConverter` with a document converter. The example below converts a legacy `.doc` file to `.docx` and then extracts it as a Haystack Document:
+
+```python
+from pathlib import Path
+from haystack import Pipeline
+from haystack.components.converters import DOCXToDocument
+from haystack_integrations.components.converters.libreoffice import (
+ LibreOfficeFileConverter,
+)
+
+pipeline = Pipeline()
+pipeline.add_component(
+ "libreoffice_converter",
+ LibreOfficeFileConverter(output_file_type="docx"),
+)
+pipeline.add_component("docx_converter", DOCXToDocument())
+
+pipeline.connect("libreoffice_converter.output", "docx_converter.sources")
+
+result = pipeline.run(
+ {"libreoffice_converter": {"sources": [Path("legacy_report.doc")]}},
+)
+documents = result["docx_converter"]["documents"]
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/markdowntodocument.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/markdowntodocument.mdx
new file mode 100644
index 0000000000..c911328c0a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/markdowntodocument.mdx
@@ -0,0 +1,78 @@
+---
+title: "MarkdownToDocument"
+id: markdowntodocument
+slug: "/markdowntodocument"
+description: "A component that converts Markdown files to documents."
+---
+
+# MarkdownToDocument
+
+A component that converts Markdown files to documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: Markdown file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/markdown.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `MarkdownToDocument` component converts Markdown files into documents. You can use it in an indexing pipeline to index the contents of a Markdown file into a Document Store. It takes a list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+When you initialize the component, you can optionally turn off progress bars by setting `progress_bar` to `False`. If you want to convert the contents of tables into a single line, you can enable that through the `table_to_single_line` parameter.
+
+## Usage
+
+You need to install `markdown-it-py` and `mdit_plain packages` to use the `MarkdownToDocument` component:
+
+```shell
+pip install markdown-it-py mdit_plain
+```
+
+### On its own
+
+```python
+from haystack.components.converters import MarkdownToDocument
+
+converter = MarkdownToDocument()
+
+docs = converter.run(sources=Path("my_file.md"))
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import MarkdownToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", MarkdownToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
+
+## Additional References
+
+:notebook: Tutorial: [Preprocessing Different File Types](https://haystack.deepset.ai/tutorials/30_file_type_preprocessing_index_pipeline)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/markitdownconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/markitdownconverter.mdx
new file mode 100644
index 0000000000..3680d46036
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/markitdownconverter.mdx
@@ -0,0 +1,75 @@
+---
+title: "MarkItDownConverter"
+id: markitdownconverter
+slug: "/markitdownconverter"
+description: "A component that converts files (PDF, Word, PowerPoint, Excel, HTML, images, and more) to Documents using Microsoft's MarkItDown library."
+---
+
+# MarkItDownConverter
+
+A component that converts files to Documents using Microsoft's MarkItDown library.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: File paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [MarkItDown](/reference/integrations-markitdown) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/markitdown |
+| **Package name** | `markitdown-haystack` |
+
+
+
+## Overview
+
+`MarkItDownConverter` converts files into Haystack Documents using Microsoft's [MarkItDown](https://github.com/microsoft/markitdown) library. MarkItDown converts many file formats to Markdown, including PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), HTML, and more. All processing is performed locally without relying on external APIs.
+
+The converter accepts file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of Documents. You can attach metadata to the Documents through the `meta` input parameter.
+
+:::note
+This component returns Markdown content. Avoid piping it through `DocumentCleaner()` with its default settings because `remove_extra_whitespaces=True` and `remove_empty_lines=True` can collapse line breaks and flatten headings, tables, lists, and image tags. Connect the converter directly to your next component, or disable those options if you need custom cleanup.
+:::
+
+## Usage
+
+Install the MarkItDown integration:
+
+```shell
+pip install markitdown-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.converters.markitdown import MarkItDownConverter
+
+converter = MarkItDownConverter()
+result = converter.run(sources=["document.pdf", "report.docx"])
+documents = result["documents"]
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.converters.markitdown import MarkItDownConverter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", MarkItDownConverter())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": ["document.pdf", "report.docx"]}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/mistralocrdocumentconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/mistralocrdocumentconverter.mdx
new file mode 100644
index 0000000000..84b3a98823
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/mistralocrdocumentconverter.mdx
@@ -0,0 +1,192 @@
+---
+title: "MistralOCRDocumentConverter"
+id: mistralocrdocumentconverter
+slug: "/mistralocrdocumentconverter"
+description: "`MistralOCRDocumentConverter` extracts text from documents using Mistral's OCR API, with optional structured annotations for both individual image regions and full documents. It supports various input formats including local files, URLs, and Mistral file IDs."
+---
+
+# MistralOCRDocumentConverter
+
+`MistralOCRDocumentConverter` extracts text from documents using Mistral's OCR API, with optional structured annotations for both individual image regions and full documents. It supports various input formats including local files, URLs, and Mistral file IDs.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx), or right at the beginning of an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Mistral API key. Can be set with `MISTRAL_API_KEY` environment variable. |
+| **Mandatory run variables** | `sources`: A list of document sources (file paths, ByteStreams, URLs, or Mistral chunks) |
+| **Output variables** | `documents`: A list of documents
`raw_mistral_response`: A list of raw OCR responses from Mistral API | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | +| **Package name** | `mistral-haystack` | + +
+
+## Overview
+
+The `MistralOCRDocumentConverter` takes a list of document sources and uses Mistral's OCR API to extract text from images and PDFs. It supports multiple input formats:
+
+- **Local files**: File paths (str or Path) or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects
+- **Remote resources**: Document URLs, image URLs using Mistral's `DocumentURLChunk` and `ImageURLChunk`
+- **Mistral storage**: File IDs using Mistral's `FileChunk` for files previously uploaded to Mistral
+
+The component returns one Haystack [`Document`](../../concepts/data-classes.mdx#document) per source, with all pages concatenated using form feed characters (`\f`) as separators. This format ensures compatibility with Haystack's [`DocumentSplitter`](../preprocessors/documentsplitter.mdx) for accurate page-wise splitting and overlap handling. The content is returned in markdown format, with images represented as `` tags.
+
+By default, the component uses the `MISTRAL_API_KEY` environment variable for authentication. You can also pass an `api_key` at initialization. Local files are automatically uploaded to Mistral's storage for processing and deleted afterward (configurable with `cleanup_uploaded_files`).
+
+When you initialize the component, you can optionally specify which pages to process, set limits on image extraction, configure minimum image sizes, or include base64-encoded images in the response. The default model is `"mistral-ocr-2505"`. See the [Mistral models documentation](https://docs.mistral.ai/getting-started/models/models_overview/) for available models.
+
+### Structured Annotations
+
+A unique feature of `MistralOCRDocumentConverter` is its support for structured annotations using Pydantic schemas:
+
+- **Bounding box annotations** (`bbox_annotation_schema`): Annotate individual image regions with structured data (for example, image type, description, summary). These annotations are inserted inline after the corresponding image tags in the markdown content.
+- **Document annotations** (`document_annotation_schema`): Annotate the full document with structured data (for example, language, chapter titles, URLs). These annotations are unpacked into the document's metadata with a `source_` prefix (for example, `source_language`, `source_chapter_titles`).
+
+When annotation schemas are provided, the OCR model first extracts text and structure, then a Vision LLM analyzes the content and generates structured annotations according to your defined Pydantic schemas. Note that document annotation is limited to a maximum of 8 pages. For more details, see the [Mistral documentation on annotations](https://docs.mistral.ai/capabilities/document_ai/annotations/).
+
+:::note
+This component returns Markdown content. Avoid piping it through `DocumentCleaner()` with its default settings because `remove_extra_whitespaces=True` and `remove_empty_lines=True` can collapse line breaks and flatten headings, tables, and image tags. For page-aware chunking, connect the converter directly to `DocumentSplitter`, or disable those options if you need custom cleanup.
+:::
+
+## Usage
+
+You need to install the `mistral-haystack` integration to use `MistralOCRDocumentConverter`:
+
+```shell
+pip install mistral-haystack
+```
+
+### On its own
+
+Basic usage with a local file:
+
+```python
+from pathlib import Path
+from haystack.utils import Secret
+from haystack_integrations.components.converters.mistral import (
+ MistralOCRDocumentConverter,
+)
+
+converter = MistralOCRDocumentConverter(
+ api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+ model="mistral-ocr-2505",
+)
+
+result = converter.run(sources=[Path("my_document.pdf")])
+documents = result["documents"]
+```
+
+Processing multiple sources with different types:
+
+```python
+from pathlib import Path
+from haystack.utils import Secret
+from haystack_integrations.components.converters.mistral import (
+ MistralOCRDocumentConverter,
+)
+from mistralai.models import DocumentURLChunk, ImageURLChunk
+
+converter = MistralOCRDocumentConverter(
+ api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+ model="mistral-ocr-2505",
+)
+
+sources = [
+ Path("local_document.pdf"),
+ DocumentURLChunk(document_url="https://example.com/document.pdf"),
+ ImageURLChunk(image_url="https://example.com/receipt.jpg"),
+]
+
+result = converter.run(sources=sources)
+documents = result["documents"] # List of 3 Documents
+raw_responses = result["raw_mistral_response"] # List of 3 raw responses
+```
+
+Using structured annotations:
+
+```python
+from pathlib import Path
+from typing import List
+from pydantic import BaseModel, Field
+from haystack.utils import Secret
+from haystack_integrations.components.converters.mistral import (
+ MistralOCRDocumentConverter,
+)
+from mistralai.models import DocumentURLChunk
+
+
+# Define schema for image region annotations
+class ImageAnnotation(BaseModel):
+ image_type: str = Field(..., description="The type of image content")
+ short_description: str = Field(
+ ...,
+ description="Short natural-language description",
+ )
+ summary: str = Field(..., description="Detailed summary of the image content")
+
+
+# Define schema for document-level annotations
+class DocumentAnnotation(BaseModel):
+ language: str = Field(..., description="Primary language of the document")
+ chapter_titles: List[str] = Field(
+ ...,
+ description="Detected chapter or section titles",
+ )
+ urls: List[str] = Field(..., description="URLs found in the text")
+
+
+converter = MistralOCRDocumentConverter(
+ api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+ model="mistral-ocr-2505",
+)
+
+sources = [DocumentURLChunk(document_url="https://example.com/report.pdf")]
+result = converter.run(
+ sources=sources,
+ bbox_annotation_schema=ImageAnnotation,
+ document_annotation_schema=DocumentAnnotation,
+)
+
+documents = result["documents"]
+# Document metadata will include:
+# - source_language: extracted from DocumentAnnotation
+# - source_chapter_titles: extracted from DocumentAnnotation
+# - source_urls: extracted from DocumentAnnotation
+# Document content will include inline image annotations
+```
+
+### In a pipeline
+
+Here's an example of an indexing pipeline that processes PDFs with OCR and writes them to a Document Store:
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+from haystack.utils import Secret
+from haystack_integrations.components.converters.mistral import (
+ MistralOCRDocumentConverter,
+)
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component(
+ "converter",
+ MistralOCRDocumentConverter(
+ api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+ model="mistral-ocr-2505",
+ ),
+)
+pipeline.add_component("splitter", DocumentSplitter(split_by="page", split_length=1))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+
+pipeline.connect("converter", "splitter")
+pipeline.connect("splitter", "writer")
+
+file_paths = ["invoice.pdf", "receipt.jpg", "contract.pdf"]
+pipeline.run({"converter": {"sources": file_paths}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/msgtodocument.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/msgtodocument.mdx
new file mode 100644
index 0000000000..7c38ca4c1d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/msgtodocument.mdx
@@ -0,0 +1,78 @@
+---
+title: "MSGToDocument"
+id: msgtodocument
+slug: "/msgtodocument"
+description: "Converts Microsoft Outlook .msg files to documents."
+---
+
+# MSGToDocument
+
+Converts Microsoft Outlook .msg files to documents.
+
+`raw_mistral_response`: A list of raw OCR responses from Mistral API | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | +| **Package name** | `mistral-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of .msg file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents
`attachments`: A list of ByteStream objects representing file attachments | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/msg.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+The `MSGToDocument` component converts Microsoft Outlook `.msg` files into documents. This component extracts the email metadata (such as sender, recipients, CC, BCC, subject) and body content. Additionally, any file attachments within the `.msg` file are extracted as `ByteStream` objects.
+
+## Usage
+
+First, install the `python-oxmsg` package to start using this converter:
+
+```
+pip install python-oxmsg
+```
+
+### On its own
+
+```python
+from haystack.components.converters.msg import MSGToDocument
+from datetime import datetime
+
+converter = MSGToDocument()
+results = converter.run(
+ sources=["sample.msg"],
+ meta={"date_added": datetime.now().isoformat()},
+)
+documents = results["documents"]
+attachments = results["attachments"]
+
+print(documents[0].content)
+```
+
+### In a pipeline
+
+The following setup enables efficient extraction, preprocessing, and indexing of `.msg` email files within a Haystack pipeline:
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.routers import FileTypeRouter
+from haystack.components.converters import MSGToDocument
+from haystack.components.writers import DocumentWriter
+
+router = FileTypeRouter(mime_types=["application/vnd.ms-outlook"])
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("router", router)
+pipeline.add_component("converter", MSGToDocument())
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+
+pipeline.connect("router.application/vnd.ms-outlook", "converter.sources")
+pipeline.connect("converter.documents", "writer.documents")
+
+file_names = ["email1.msg", "email2.msg"]
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/multifileconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/multifileconverter.mdx
new file mode 100644
index 0000000000..b3ec864cf6
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/multifileconverter.mdx
@@ -0,0 +1,80 @@
+---
+title: "MultiFileConverter"
+id: multifileconverter
+slug: "/multifileconverter"
+description: "Converts CSV, DOCX, HTML, JSON, MD, PPTX, PDF, TXT, and XSLX files to documents."
+---
+
+# MultiFileConverter
+
+Converts CSV, DOCX, HTML, JSON, MD, PPTX, PDF, TXT, and XSLX files to documents.
+
+`attachments`: A list of ByteStream objects representing file attachments | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/msg.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before PreProcessors , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of file paths or ByteStream objects |
+| **Output variables** | `documents`: A list of converted documents
`unclassified`: A list of uncategorized file paths or byte streams | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/multi_file_converter.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`MultiFileConverter` converts input files of various file types into documents.
+
+It is a SuperComponent that combines a [`FileTypeRouter`](../routers/filetyperouter.mdx), nine converters and a [`DocumentJoiner`](../joiners/documentjoiner.mdx) into a single component.
+
+### Parameters
+
+To initialize `MultiFileConverter`, there are no mandatory parameters. Optionally, you can provide `encoding` and `json_content_key` parameters.
+
+The `json_content_key` parameter lets you specify for the JSON files which key in the extracted data will be the document's content. The parameter is passed on to the underlying [`JSONConverter`](jsonconverter.mdx) component.
+
+The `encoding` parameter lets you specify the default encoding of the TXT, CSV, and MD files. If you don't provide any value, the component uses `utf-8` by default. Note that if the encoding is specified in the metadata of an input ByteStream, it will override this parameter's setting. The parameter is passed on to the underlying [`TextFileToDocument`](textfiletodocument.mdx) and [`CSVToDocument`](csvtodocument.mdx) components.
+
+## Usage
+
+Install dependencies for all supported file types to use the `MultiFileConverter`:
+
+```shell
+pip install pypdf markdown-it-py mdit_plain trafilatura python-pptx python-docx jq openpyxl tabulate pandas
+```
+
+### On its own
+
+```python
+from haystack.components.converters import MultiFileConverter
+
+converter = MultiFileConverter()
+converter.run(sources=["test.txt", "test.pdf"], meta={})
+```
+
+### In a pipeline
+
+You can also use `MultiFileConverter` in your indexing pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.converters import MultiFileConverter
+from haystack.components.preprocessors import DocumentPreprocessor
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", MultiFileConverter())
+pipeline.add_component("preprocessor", DocumentPreprocessor())
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "preprocessor")
+pipeline.connect("preprocessor", "writer")
+
+result = pipeline.run(data={"sources": ["test.txt", "test.pdf"]})
+
+print(result)
+## {'writer': {'documents_written': 3}}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/openapiservicetofunctions.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/openapiservicetofunctions.mdx
new file mode 100644
index 0000000000..c75fb0e0bb
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/openapiservicetofunctions.mdx
@@ -0,0 +1,139 @@
+---
+title: "OpenAPIServiceToFunctions"
+id: openapiservicetofunctions
+slug: "/openapiservicetofunctions"
+description: "`OpenAPIServiceToFunctions` is a component that transforms OpenAPI service specifications into a format compatible with LLM tool calling."
+---
+
+# OpenAPIServiceToFunctions
+
+`OpenAPIServiceToFunctions` is a component that transforms OpenAPI service specifications into a format compatible with LLM tool calling.
+
+`unclassified`: A list of uncategorized file paths or byte streams | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/multi_file_converter.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory run variables** | `sources`: A list of OpenAPI specification sources, which can be file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `functions`: A list of JSON function definitions objects. For each path definition in OpenAPI specification, a corresponding function definition is generated.
`openapi_specs`: A list of JSON/YAML objects with references resolved. Such OpenAPI spec (with references resolved) can, in turn, be used as input to OpenAPIServiceConnector. | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/openapi_functions.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`OpenAPIServiceToFunctions` transforms OpenAPI service specifications into a function calling format suitable for LLM tool calling. It takes an OpenAPI specification, processes it to extract function definitions, and formats these definitions to be compatible with LLM tool calling.
+
+`OpenAPIServiceToFunctions` is valuable when used together with [`OpenAPIServiceConnector`](../connectors/openapiserviceconnector.mdx) component. It converts OpenAPI specifications into function definitions, allowing `OpenAPIServiceConnector` to handle input parameters for the OpenAPI specification and facilitate their use in REST API calls through `OpenAPIServiceConnector`.
+
+To use `OpenAPIServiceToFunctions`, you need to install an optional `jsonref` dependency with:
+
+```shell
+pip install jsonref
+```
+
+`OpenAPIServiceToFunctions` component doesn’t have any init parameters.
+
+## Usage
+
+### On its own
+
+This component is primarily meant to be used in pipelines. Using this component alone is useful when you want to convert OpenAPI specification into function definitions and then perhaps save them in a file and subsequently use them for tool calling.
+
+### In a pipeline
+
+In a pipeline context, `OpenAPIServiceToFunctions` is most valuable when used alongside `OpenAPIServiceConnector`. For instance, let’s consider integrating [serper.dev](http://serper.dev/) search engine bridge into a pipeline. `OpenAPIServiceToFunctions` retrieves the OpenAPI specification of Serper from https://bit.ly/serper_dev_spec, converts this specification into function definitions that an LLM with tool calling capabilities can understand, and then seamlessly passes these definitions as `generation_kwargs` to the Chat Generator component.
+
+:::info
+To run the following code snippet, note that you have to have your own Serper and OpenAI API keys.
+:::
+
+```python
+import json
+import requests
+
+from typing import Any
+
+from haystack import Pipeline
+from haystack.components.connectors import OpenAPIServiceConnector
+from haystack.components.converters import OpenAPIServiceToFunctions, OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.dataclasses.byte_stream import ByteStream
+
+
+def prepare_fc_params(openai_functions_schema: dict[str, Any]) -> dict[str, Any]:
+ return {
+ "tools": [{"type": "function", "function": openai_functions_schema}],
+ "tool_choice": {
+ "type": "function",
+ "function": {"name": openai_functions_schema["name"]},
+ },
+ }
+
+
+serperdev_spec = requests.get("https://bit.ly/serper_dev_spec").json()
+system_prompt = requests.get("https://bit.ly/serper_dev_system").text
+user_prompt = "Why was Sam Altman ousted from OpenAI?"
+
+pipe = Pipeline()
+pipe.add_component("spec_to_functions", OpenAPIServiceToFunctions())
+pipe.add_component(
+ "prepare_fc_adapter",
+ OutputAdapter(
+ "{{functions[0] | prepare_fc}}",
+ dict[str, Any],
+ {"prepare_fc": prepare_fc_params},
+ ),
+)
+pipe.add_component("functions_llm", OpenAIChatGenerator())
+pipe.add_component("openapi_connector", OpenAPIServiceConnector())
+pipe.add_component(
+ "message_adapter",
+ OutputAdapter(
+ "{{system_message + service_response}}",
+ list[ChatMessage],
+ unsafe=True,
+ ),
+)
+pipe.add_component("llm", OpenAIChatGenerator())
+
+pipe.connect("spec_to_functions.functions", "prepare_fc_adapter.functions")
+pipe.connect(
+ "spec_to_functions.openapi_specs",
+ "openapi_connector.service_openapi_spec",
+)
+pipe.connect("prepare_fc_adapter", "functions_llm.generation_kwargs")
+pipe.connect("functions_llm.replies", "openapi_connector.messages")
+pipe.connect("openapi_connector.service_response", "message_adapter.service_response")
+pipe.connect("message_adapter", "llm.messages")
+
+result = pipe.run(
+ data={
+ "functions_llm": {
+ "messages": [
+ ChatMessage.from_system("Only do tool/function calling"),
+ ChatMessage.from_user(user_prompt),
+ ],
+ },
+ "openapi_connector": {
+ "service_credentials": serper_dev_key,
+ },
+ "spec_to_functions": {
+ "sources": [ByteStream.from_string(json.dumps(serperdev_spec))],
+ },
+ "message_adapter": {
+ "system_message": [ChatMessage.from_system(system_prompt)],
+ },
+ },
+)
+
+print(result["llm"]["replies"][0].text)
+
+# Sam Altman was ousted from OpenAI on November 17, 2023, following
+# a "deliberative review process" by the board of directors. The board concluded
+# that he was not "consistently candid in his communications". However, he
+# returned as CEO just days after his ouster.
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/outputadapter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/outputadapter.mdx
new file mode 100644
index 0000000000..729f0ee82b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/outputadapter.mdx
@@ -0,0 +1,135 @@
+---
+title: "OutputAdapter"
+id: outputadapter
+slug: "/outputadapter"
+description: "This component helps the output of one component fit smoothly into the input of another. It uses Jinja expressions to define how this adaptation occurs."
+---
+
+# OutputAdapter
+
+This component helps the output of one component fit smoothly into the input of another. It uses Jinja expressions to define how this adaptation occurs.
+
+`openapi_specs`: A list of JSON/YAML objects with references resolved. Such OpenAPI spec (with references resolved) can, in turn, be used as input to OpenAPIServiceConnector. | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/openapi_functions.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory init variables** | `template`: A Jinja template string that defines how to adapt the data
`output_type`: Type alias that this instance will return | +| **Mandatory run variables** | `**kwargs`: Input variables to be used in Jinja expression. See [Variables](#variables) section for more details. | +| **Output variables** | The output is specified under the `output` key dictionary | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/output_adapter.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+To use `OutputAdapter`, you need to specify the adaptation rule that includes:
+
+- `template`: A Jinja template string that defines how to adapt the input data.
+- `output_type`: The type of the output data (such as `str`, `List[int]`..). This doesn't change the actual output type and is only needed to validate connection with other components.
+- `custom_filters`: An optional dictionary of custom Jinja filters to be used in the template.
+
+### Variables
+
+The `OutputAdapter` requires all template variables to be present before running and raises an error if any template variable is missing at pipeline connect time.
+
+```python
+from haystack.components.converters import OutputAdapter
+
+adapter = OutputAdapter(template="Hello {{name}}!", output_type=str)
+```
+
+### Unsafe behavior
+
+The `OutputAdapter` internally renders the `template` using Jinja, and by default, this is safe behavior. However, it limits the output types to strings, bytes, numbers, tuples, lists, dicts, sets, booleans, `None`, and `Ellipsis` (`...`), as well as any combination of these structures.
+
+If you want to use other types such as `ChatMessage`, `Document`, or `Answer`, you must enable unsafe template rendering by setting the `unsafe` init argument to `True`.
+
+Be cautious, as enabling this can be unsafe and may lead to remote code execution if the `template` is a string customizable by the end user.
+
+## Usage
+
+### On its own
+
+This component is primarily meant to be used in pipelines.
+
+In this example, `OutputAdapter` simply outputs the content field of the first document in the arrays of documents:
+
+```python
+from haystack import Document
+from haystack.components.converters import OutputAdapter
+
+adapter = OutputAdapter(template="{{ documents[0].content }}", output_type=str)
+input_data = {"documents": [Document(content="Test content")]}
+expected_output = {"output": "Test content"}
+assert adapter.run(**input_data) == expected_output
+```
+
+### In a pipeline
+
+The example below demonstrates a straightforward pipeline that uses the `OutputAdapter` to capitalize the first document in the list. If needed, you can also utilize the predefined Jinja [filters](https://jinja.palletsprojects.com/en/3.1.x/templates/#builtin-filters).
+
+```python
+from haystack import Pipeline, component, Document
+from haystack.components.converters import OutputAdapter
+
+
+@component
+class DocumentProducer:
+ @component.output_types(documents=dict)
+ def run(self):
+ return {"documents": [Document(content="haystack")]}
+
+
+pipe = Pipeline()
+pipe.add_component(
+ name="output_adapter",
+ instance=OutputAdapter(
+ template="{{ documents[0].content | capitalize}}",
+ output_type=str,
+ ),
+)
+pipe.add_component(name="document_producer", instance=DocumentProducer())
+pipe.connect("document_producer", "output_adapter")
+result = pipe.run(data={})
+
+assert result["output_adapter"]["output"] == "Haystack"
+```
+
+You can also define your own custom filters, which can then be added to an `OutputAdapter` instance through its init method and used in templates. Here’s an example of this approach:
+
+```python
+
+from haystack import Pipeline, component, Document
+from haystack.components.converters import OutputAdapter
+
+
+def reverse_string(s):
+ return s[::-1]
+
+
+@component
+class DocumentProducer:
+ @component.output_types(documents=dict)
+ def run(self):
+ return {"documents": [Document(content="haystack")]}
+
+
+pipe = Pipeline()
+pipe.add_component(
+ name="output_adapter",
+ instance=OutputAdapter(
+ template="{{ documents[0].content | reverse_string}}",
+ output_type=str,
+ custom_filters={"reverse_string": reverse_string},
+ ),
+)
+
+pipe.add_component(name="document_producer", instance=DocumentProducer())
+pipe.connect("document_producer", "output_adapter")
+result = pipe.run(data={})
+
+assert result["output_adapter"]["output"] == "kcatsyah"
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/paddleocrvldocumentconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/paddleocrvldocumentconverter.mdx
new file mode 100644
index 0000000000..4a58753854
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/paddleocrvldocumentconverter.mdx
@@ -0,0 +1,157 @@
+---
+title: "PaddleOCRVLDocumentConverter"
+id: paddleocrvldocumentconverter
+slug: "/paddleocrvldocumentconverter"
+description: "`PaddleOCRVLDocumentConverter` extracts text from documents using PaddleOCR's large model document parsing API."
+---
+
+# PaddleOCRVLDocumentConverter
+
+`PaddleOCRVLDocumentConverter` extracts text from documents using PaddleOCR's large model document parsing API. PaddleOCR-VL is used behind the scenes. For more information, please refer to the [PaddleOCR-VL documentation](https://www.paddleocr.ai/latest/en/version3.x/algorithm/PaddleOCR-VL/PaddleOCR-VL.html).
+
+`output_type`: Type alias that this instance will return | +| **Mandatory run variables** | `**kwargs`: Input variables to be used in Jinja expression. See [Variables](#variables) section for more details. | +| **Output variables** | The output is specified under the `output` key dictionary | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/output_adapter.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx), or right at the beginning of an indexing pipeline |
+| **Mandatory init variables** | `api_url`: The URL of the PaddleOCR-VL API.
`access_token`: The AI Studio access token. Can be set with `AISTUDIO_ACCESS_TOKEN` environment variable. | +| **Mandatory run variables** | `sources`: A list of image or PDF file paths or ByteStream objects. | +| **Output variables** | `documents`: A list of documents.
`raw_paddleocr_responses`: A list of raw OCR responses from PaddleOCR API. | +| **API reference** | [PaddleOCR](/reference/integrations-paddleocr) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/paddleocr | +| **Package name** | `paddleocr-haystack` | + +
+
+## Overview
+
+The `PaddleOCRVLDocumentConverter` takes a list of document sources and uses PaddleOCR's large model document parsing API to extract text from images and PDFs. It supports both images and PDF files.
+
+The component returns one Haystack [`Document`](../../concepts/data-classes.mdx#document) per source, with all pages concatenated using form feed characters (`\f`) as separators. This format ensures compatibility with Haystack's [`DocumentSplitter`](../preprocessors/documentsplitter.mdx) for accurate page-wise splitting and overlap handling. The content is returned in markdown format, with images represented as `` tags.
+
+The component takes `api_url` as a required parameter. To obtain the API URL, visit the [PaddleOCR official website](https://aistudio.baidu.com/paddleocr), click the **API** button, choose the example code for PaddleOCR-VL, and copy the `API_URL`.
+
+By default, the component uses the `AISTUDIO_ACCESS_TOKEN` environment variable for authentication. You can also pass an `access_token` at initialization. The AI Studio access token can be obtained from [this page](https://aistudio.baidu.com/account/accessToken).
+
+`raw_paddleocr_responses` can be useful while tuning layout thresholds, prompt settings, or Markdown post-processing options because it gives you access to the original API output alongside the converted Haystack documents.
+
+:::note
+This component returns Markdown content. Avoid piping it through `DocumentCleaner()` with its default settings because `remove_extra_whitespaces=True` and `remove_empty_lines=True` can collapse line breaks and flatten headings, tables, and image tags. For page-aware chunking, connect the converter directly to `DocumentSplitter`, or disable those options if you need custom cleanup.
+:::
+
+## When to use it
+
+`PaddleOCRVLDocumentConverter` is a strong fit when you need more than plain OCR text:
+
+- **Scanned PDFs and camera-captured documents** where page orientation and warped text can reduce extraction quality.
+- **Layout-sensitive documents** such as invoices, reports, forms, and multi-column PDFs where preserving structure matters for downstream chunking and retrieval.
+- **Tables, formulas, charts, or seals** where you want more targeted extraction behavior than plain text OCR.
+- **RAG ingestion pipelines** where Markdown output is useful because headings, lists, tables, and page breaks can be preserved for later splitting.
+
+## Useful configuration areas
+
+The full parameter list is available in the [API reference](/reference/integrations-paddleocr). In practice, the most useful options tend to fall into these groups:
+
+- **Input handling and image cleanup**: `file_type`, `use_doc_orientation_classify`, and `use_doc_unwarping` help when you mix PDFs and images or work with skewed scans and mobile photos.
+- **Layout-aware extraction**: `use_layout_detection`, `layout_threshold`, `layout_nms`, `layout_unclip_ratio`, `layout_merge_bboxes_mode`, `layout_shape_mode`, and `merge_layout_blocks` help you tune how regions are detected and merged before Markdown is generated.
+- **Content focus**: `prompt_label`, `use_ocr_for_image_block`, `use_chart_recognition`, and `use_seal_recognition` let you bias extraction toward a particular type of content, such as plain OCR, formulas, tables, charts, or seals.
+- **Markdown output shaping**: `format_block_content`, `markdown_ignore_labels`, `prettify_markdown`, `show_formula_number`, `restructure_pages`, `merge_tables`, and `relevel_titles` help you control how much cleanup and restructuring happens before the result becomes a Haystack document.
+- **VLM generation controls**: `repetition_penalty`, `temperature`, `top_p`, `min_pixels`, `max_pixels`, `max_new_tokens`, `vlm_extra_args`, and `additional_params` are useful when you need to trade off output quality, determinism, and cost.
+- **Debugging and inspection**: `visualize=True` and the returned `raw_paddleocr_responses` are helpful when you are tuning extraction quality for a new document type.
+
+## Typical scenarios
+
+These settings are especially useful in a few common workflows:
+
+- **Scanned contracts or receipts from phones**: start with `use_doc_orientation_classify=True` and `use_doc_unwarping=True`.
+- **Table-heavy financial or operations PDFs**: consider `use_layout_detection=True`, `merge_tables=True`, and `restructure_pages=True`.
+- **Formula-heavy documents**: use `prompt_label="formula"` together with `show_formula_number=True` if formula numbering matters in the final Markdown.
+- **Mixed business documents with figures or seals**: enable `use_chart_recognition=True`, `use_seal_recognition=True`, or `use_ocr_for_image_block=True` depending on the content you want to preserve.
+
+## Usage
+
+You need to install the `paddleocr-haystack` integration to use `PaddleOCRVLDocumentConverter`:
+
+```shell
+pip install paddleocr-haystack
+```
+
+### On its own
+
+Basic usage with a local file:
+
+```python
+from pathlib import Path
+from haystack.utils import Secret
+from haystack_integrations.components.converters.paddleocr import (
+ PaddleOCRVLDocumentConverter,
+)
+
+converter = PaddleOCRVLDocumentConverter(
+ api_url="`access_token`: The AI Studio access token. Can be set with `AISTUDIO_ACCESS_TOKEN` environment variable. | +| **Mandatory run variables** | `sources`: A list of image or PDF file paths or ByteStream objects. | +| **Output variables** | `documents`: A list of documents.
`raw_paddleocr_responses`: A list of raw OCR responses from PaddleOCR API. | +| **API reference** | [PaddleOCR](/reference/integrations-paddleocr) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/paddleocr | +| **Package name** | `paddleocr-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: PDF file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/pdfminer.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `PDFMinerToDocument` component converts PDF files into documents using [PDFMiner](https://pdfminersix.readthedocs.io/en/latest/) extraction tool arguments.
+
+You can use it in an indexing pipeline to index the contents of a PDF file in a Document Store. It takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream)objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+When initializing the component, you can adjust several parameters to fit your PDF. See the full parameter list and descriptions in our [API reference](/reference/converters-api#pdfminertodocument).
+
+## Usage
+
+First, install `pdfminer` package to start using this converter:
+
+```shell
+pip install pdfminer.six
+```
+
+### On its own
+
+```python
+from haystack.components.converters import PDFMinerToDocument
+
+converter = PDFMinerToDocument()
+results = converter.run(
+ sources=["sample.pdf"],
+ meta={"date_added": datetime.now().isoformat()},
+)
+documents = results["documents"]
+
+print(documents[0].content)
+
+## 'This is a text from the PDF file.'
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import PDFMinerToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", PDFMinerToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/pdftoimagecontent.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/pdftoimagecontent.mdx
new file mode 100644
index 0000000000..8f4a7da117
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/pdftoimagecontent.mdx
@@ -0,0 +1,117 @@
+---
+title: "PDFToImageContent"
+id: pdftoimagecontent
+slug: "/pdftoimagecontent"
+description: "`PDFToImageContent` reads local PDF files and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image captioning, visual QA, or prompt-based generation."
+---
+
+# PDFToImageContent
+
+`PDFToImageContent` reads local PDF files and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image captioning, visual QA, or prompt-based generation.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a `ChatPromptBuilder` in a query pipeline |
+| **Mandatory run variables** | `sources`: A list of PDF file paths or ByteStreams |
+| **Output variables** | `image_contents`: A list of ImageContent objects |
+| **API reference** | [Image Converters](/reference/image-converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/image/pdf_to_image.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`PDFToImageContent` processes a list of PDF sources and converts them into `ImageContent` objects, one for each page of the PDF. These can be used in multimodal pipelines that require base64-encoded image input.
+
+Each source can be:
+
+- A file path (string or `Path`), or
+- A `ByteStream` object.
+
+Optionally, you can provide metadata using the `meta` parameter. This can be a single dictionary (applied to all images) or a list matching the length of `sources`.
+
+Use the `size` parameter to resize images while preserving aspect ratio. This reduces memory usage and transmission size, which is helpful when working with remote models or limited-resource environments.
+
+This component is often used in query pipelines just before a `ChatPromptBuilder`.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.converters.image import PDFToImageContent
+
+converter = PDFToImageContent()
+
+sources = ["file.pdf", "another_file.pdf"]
+
+image_contents = converter.run(sources=sources)["image_contents"]
+print(image_contents)
+
+## [ImageContent(base64_image='...',
+## mime_type='application/pdf',
+## detail=None,
+## meta={'file_path': 'file.pdf', 'page_number': 1}),
+## ...]
+```
+
+### In a pipeline
+
+Use `ImageFileToImageContent` to supply image data to a `ChatPromptBuilder` for multimodal QA or captioning with an LLM.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.converters.image import PDFToImageContent
+
+## Query pipeline
+pipeline = Pipeline()
+pipeline.add_component("image_converter", PDFToImageContent(detail="auto"))
+pipeline.add_component(
+ "chat_prompt_builder",
+ ChatPromptBuilder(
+ required_variables=["question"],
+ template="""{% message role="system" %}
+You are a helpful assistant that answers questions using the provided images.
+{% endmessage %}
+
+{% message role="user" %}
+Question: {{ question }}
+
+{% for img in image_contents %}
+{{ img | templatize_part }}
+{% endfor %}
+{% endmessage %}
+""",
+ ),
+)
+pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+
+pipeline.connect("image_converter", "chat_prompt_builder.image_contents")
+pipeline.connect("chat_prompt_builder", "llm")
+
+sources = ["flan_paper.pdf"]
+
+result = pipeline.run(
+ data={
+ "image_converter": {"sources": ["flan_paper.pdf"], "page_range": "9"},
+ "chat_prompt_builder": {"question": "What is the main takeaway of Figure 6?"},
+ },
+)
+print(result["replies"][0].text)
+
+## ('The main takeaway of Figure 6 is that Flan-PaLM demonstrates improved '
+## 'performance in zero-shot reasoning tasks when utilizing chain-of-thought '
+## '(CoT) reasoning, as indicated by higher accuracy across different model '
+## 'sizes compared to PaLM without finetuning. This highlights the importance of '
+## 'instruction finetuning combined with CoT for enhancing reasoning '
+## 'capabilities in models.')
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Introduction to Multimodality](https://haystack.deepset.ai/cookbook/multimodal_intro)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/pptxtodocument.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/pptxtodocument.mdx
new file mode 100644
index 0000000000..3d7bbc6537
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/pptxtodocument.mdx
@@ -0,0 +1,79 @@
+---
+title: "PPTXToDocument"
+id: pptxtodocument
+slug: "/pptxtodocument"
+description: "Convert PPTX files to documents."
+---
+
+# PPTXToDocument
+
+Convert PPTX files to documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: PPTX file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/pptx.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `PPTXToDocument` component converts PPTX files into documents. It takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+## Usage
+
+First, install the`python-pptx` package to start using this converter:
+
+```shell
+pip install python-pptx
+```
+
+### On its own
+
+```python
+from haystack.components.converters import PPTXToDocument
+
+converter = PPTXToDocument()
+results = converter.run(
+ sources=["sample.pptx"],
+ meta={"date_added": datetime.now().isoformat()},
+)
+documents = results["documents"]
+
+print(documents[0].content)
+
+## 'This is the text from the PPTX file.'
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import PPTXToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", PPTXToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/pypdftodocument.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/pypdftodocument.mdx
new file mode 100644
index 0000000000..b1ad0075ff
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/pypdftodocument.mdx
@@ -0,0 +1,79 @@
+---
+title: "PyPDFToDocument"
+id: pypdftodocument
+slug: "/pypdftodocument"
+description: "A component that converts PDF files to Documents."
+---
+
+# PyPDFToDocument
+
+A component that converts PDF files to Documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: PDF file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/pypdf.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `PyPDFToDocument` component converts PDF files into documents. You can use it in an indexing pipeline to index the contents of a PDF file into a Document Store. It takes a list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+## Usage
+
+You need to install `pypdf` package to use the `PyPDFToDocument` converter:
+
+```shell
+pip install pypdf
+```
+
+### On its own
+
+```python
+from pathlib import Path
+from haystack.components.converters import PyPDFToDocument
+
+converter = PyPDFToDocument()
+
+docs = converter.run(sources=[Path("my_file.pdf")])
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import PyPDFToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", PyPDFToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
+
+📓 Tutorial: [Preprocessing Different File Types](https://haystack.deepset.ai/tutorials/30_file_type_preprocessing_index_pipeline)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/textfiletodocument.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/textfiletodocument.mdx
new file mode 100644
index 0000000000..7f7866dfe9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/textfiletodocument.mdx
@@ -0,0 +1,73 @@
+---
+title: "TextFileToDocument"
+id: textfiletodocument
+slug: "/textfiletodocument"
+description: "Converts text files to documents."
+---
+
+# TextFileToDocument
+
+Converts text files to documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of paths to text files you want to convert |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/txt.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `TextFileToDocument` component converts text files into documents. You can use it in an indexing pipeline to index the contents of text files into a Document Store. It takes a list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+When you initialize the component, you can optionally set the default encoding of the text files through the `encoding` parameter. If you don't provide any value, the component uses `"utf-8"` by default. Note that if the encoding is specified in the metadata of an input ByteStream, it will override this parameter's setting.
+
+## Usage
+
+### On its own
+
+```python
+from pathlib import Path
+from haystack.components.converters import TextFileToDocument
+
+converter = TextFileToDocument()
+
+docs = converter.run(sources=[Path("my_file.txt")])
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", TextFileToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
+
+## Additional References
+
+:notebook: Tutorial: [Preprocessing Different File Types](https://haystack.deepset.ai/tutorials/30_file_type_preprocessing_index_pipeline)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/tikadocumentconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/tikadocumentconverter.mdx
new file mode 100644
index 0000000000..b2315087c5
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/tikadocumentconverter.mdx
@@ -0,0 +1,80 @@
+---
+title: "TikaDocumentConverter"
+id: tikadocumentconverter
+slug: "/tikadocumentconverter"
+description: "An integration for converting files of different types (PDF, DOCX, HTML, and more) to documents."
+---
+
+# TikaDocumentConverter
+
+An integration for converting files of different types (PDF, DOCX, HTML, and more) to documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: File paths |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/tika.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `TikaDocumentConverter` component converts files of different types (pdf, docx, html, and others) into documents. You can use it in an indexing pipeline to index the contents of files into a Document Store. It takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+This integration uses [Apache Tika](https://tika.apache.org/) to parse the files and requires a running Tika server.
+
+The easiest way to run Tika is by using Docker: `docker run -d -p 127.0.0.1:9998:9998 apache/tika:latest`.
+For more options on running Tika on Docker, see the [Tika documentation](https://github.com/apache/tika-docker/blob/main/README.md#usage).
+
+When you initialize the `TikaDocumentConverter` component, you can specify a custom URL of the Tika server you are using through the parameter `tika_url`. The default URL is `"http://localhost:9998/tika"`.
+
+## Usage
+
+You need to install `tika` package to use the `TikaDocumentConverter` component:
+
+```shell
+pip install tika
+```
+
+### On its own
+
+```python
+from haystack.components.converters import TikaDocumentConverter
+from pathlib import Path
+
+converter = TikaDocumentConverter()
+
+converter.run(sources=[Path("my_file.pdf")])
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import TikaDocumentConverter
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", TikaDocumentConverter())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_paths}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/unstructuredfileconverter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/unstructuredfileconverter.mdx
new file mode 100644
index 0000000000..07b00ca2ae
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/unstructuredfileconverter.mdx
@@ -0,0 +1,116 @@
+---
+title: "UnstructuredFileConverter"
+id: unstructuredfileconverter
+slug: "/unstructuredfileconverter"
+description: "Use this component to convert text files and directories to a document."
+---
+
+# UnstructuredFileConverter
+
+Use this component to convert text files and directories to a document.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `paths`: A union of lists of paths |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Unstructured](/reference/integrations-unstructured) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/unstructured |
+| **Package name** | `unstructured-fileconverter-haystack` |
+
+
+
+## Overview
+
+`UnstructuredFileConverter` converts files and directories into documents using the Unstructured API.
+
+[Unstructured](https://docs.unstructured.io/) provides a series of tools to do ETL for LLMs. The `UnstructuredFileConverter` calls the Unstructured API that extracts text and other information from a vast range of file [formats](https://docs.unstructured.io/api-reference/api-services/overview#supported-file-types).
+
+This Converter supports different modes for creating documents from the elements returned by Unstructured:
+
+- `"one-doc-per-file"`: One Haystack document per file. All elements are concatenated into one text field.
+- `"one-doc-per-page"`: One Haystack document per page. All elements on a page are concatenated into one text field.
+- `"one-doc-per-element"`: One Haystack document per element. Each element is converted to a Haystack document.
+
+## Usage
+
+Install the Unstructured integration to use `UnstructuredFileConverter`component:
+
+```shell
+pip install unstructured-fileconverter-haystack
+```
+
+There are free and paid versions of Unstructured API: **Free Unstructured API** and **Unstructured Serverless API**.
+
+1. **Free Unstructured API**:
+ - API URL: `https://api.unstructured.io/general/v0/general`
+ - This version is free, but comes with certain limitations.
+
+2. **Unstructured Serverless API**:
+ - You'll find your unique API URL in your Unstructured account after signing up for the paid version.
+ - This is a full-tier paid version of Unstructured.
+
+ For more details about the two tiers refer to Unstructured [FAQ](https://docs.unstructured.io/faq/faq).
+
+> ❗️ The API keys for the free and paid versions are different and cannot be used interchangeably.
+
+Regardless of the chosen tier, we recommend to set the Unstructured API key as an environment variable `UNSTRUCTURED_API_KEY`:
+
+```shell
+export UNSTRUCTURED_API_KEY=your_api_key
+```
+
+### On its own
+
+```python
+import os
+from haystack_integrations.components.converters.unstructured import (
+ UnstructuredFileConverter,
+)
+
+converter = UnstructuredFileConverter()
+documents = converter.run(paths=["a/file/path.pdf", "a/directory/path"])["documents"]
+```
+
+### In a pipeline
+
+```python
+import os
+from haystack import Pipeline
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.converters.unstructured import (
+ UnstructuredFileConverter,
+)
+
+document_store = InMemoryDocumentStore()
+
+indexing = Pipeline()
+indexing.add_component("converter", UnstructuredFileConverter())
+indexing.add_component("writer", DocumentWriter(document_store))
+indexing.connect("converter", "writer")
+
+indexing.run({"converter": {"paths": ["a/file/path.pdf", "a/directory/path"]}})
+```
+
+### With Docker
+
+To use `UnstructuredFileConverter` through Docker, first, set up an Unstructured Docker container:
+
+```
+docker run -p 8000:8000 -d --rm --name unstructured-api quay.io/unstructured-io/unstructured-api:latest --port 8000 --host 0.0.0.0
+```
+
+When initializing the component, specify the localhost URL:
+
+```python
+from haystack_integrations.components.converters.unstructured import (
+ UnstructuredFileConverter,
+)
+
+converter = UnstructuredFileConverter(
+ api_url="http://localhost:8000/general/v0/general",
+)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/xlsxtodocument.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/xlsxtodocument.mdx
new file mode 100644
index 0000000000..ee647256f8
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/converters/xlsxtodocument.mdx
@@ -0,0 +1,80 @@
+---
+title: "XLSXToDocument"
+id: xlsxtodocument
+slug: "/xlsxtodocument"
+description: "Converts Excel files into documents."
+---
+
+# XLSXToDocument
+
+Converts Excel files into documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: File paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/xlsx.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `XLSXToDocument` component converts XLSX files into Haystack Documents with a CSV (default) or Markdown format. It takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+To see the additional parameters that you can specify with the component initialization, check out the [API Reference](/reference/converters-api#xlsxtodocument).
+
+## Usage
+
+First, install the openpyxl and tabulate packages to start using this converter:
+
+```shell
+pip install pandas openpyxl
+pip install tabulate
+```
+
+### On its own
+
+```python
+from haystack.components.converters import XLSXToDocument
+
+converter = XLSXToDocument()
+results = converter.run(
+ sources=["sample.xlsx"],
+ meta={"date_added": datetime.now().isoformat()},
+)
+documents = results["documents"]
+print(documents[0].content)
+## ",A,B\n1,col_a,col_b\n2,1.5,test\n"
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import XLSXToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", XLSXToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component(
+ "splitter",
+ DocumentSplitter(split_by="sentence", split_length=5),
+)
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/downloaders/s3downloader.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/downloaders/s3downloader.mdx
new file mode 100644
index 0000000000..87180789d1
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/downloaders/s3downloader.mdx
@@ -0,0 +1,273 @@
+---
+title: "S3Downloader"
+id: s3downloader
+slug: "/s3downloader"
+description: "`S3Downloader` downloads files from AWS S3 buckets to the local filesystem and enriches documents with the local file path."
+---
+
+# S3Downloader
+
+`S3Downloader` downloads files from AWS S3 buckets to the local filesystem and enriches documents with the local file path.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before File Converters or Routers that need local file paths |
+| **Mandatory init variables** | `file_root_path`: Path where files will be downloaded. Can be set with `FILE_ROOT_PATH` env var.
`aws_access_key_id`: AWS access key ID. Can be set with AWS_ACCESS_KEY_ID env var.
`aws_secret_access_key`: AWS secret access key. Can be set with AWS_SECRET_ACCESS_KEY env var.
`aws_region_name`: AWS region name. Can be set with AWS_DEFAULT_REGION env var. | +| **Mandatory run variables** | `documents`: A list of documents containing name of the file to download in metadata. | +| **Output variables** | `documents`: A list of documents enriched with the local file path in `meta['file_path']` | +| **API reference** | [S3Downloader](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+## Overview
+
+`S3Downloader` downloads files from AWS S3 buckets to your local filesystem and enriches Document objects with the local file path. This component is useful for pipelines that need to process files stored in S3, such as PDFs, images, or text files.
+
+The component supports AWS authentication through environment variables by default. You can set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_DEFAULT_REGION` environment variables. Alternatively, you can pass credentials directly at initialization using the [Secret API](../../concepts/secret-management.mdx):
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.downloaders.s3 import S3Downloader
+
+downloader = S3Downloader(
+ aws_access_key_id=Secret.from_token("`aws_access_key_id`: AWS access key ID. Can be set with AWS_ACCESS_KEY_ID env var.
`aws_secret_access_key`: AWS secret access key. Can be set with AWS_SECRET_ACCESS_KEY env var.
`aws_region_name`: AWS region name. Can be set with AWS_DEFAULT_REGION env var. | +| **Mandatory run variables** | `documents`: A list of documents containing name of the file to download in metadata. | +| **Output variables** | `documents`: A list of documents enriched with the local file path in `meta['file_path']` | +| **API reference** | [S3Downloader](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `model`: The embedding model to use
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `documents`: A list of documents to be embedded | +| **Output variables** | `documents`: A list of documents (enriched with embeddings) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+## Overview
+
+[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) is a fully managed service that makes language models from leading AI startups and Amazon available for your use through a unified API.
+
+Supported models are `amazon.titan-embed-text-v1`, `cohere.embed-english-v3`, `cohere.embed-multilingual-v3`, and `amazon.titan-embed-text-v2:0`.
+
+:::info[Batch Inference]
+
+Note that only Cohere models support batch inference – computing embeddings for more documents with the same request.
+:::
+
+This component should be used to embed a list of documents. To embed a string, you should use the [`AmazonBedrockTextEmbedder`](amazonbedrocktextembedder.mdx).
+
+### Authentication
+
+`AmazonBedrockDocumentEmbedder` uses AWS for authentication. You can either provide credentials as parameters directly to the component or use the AWS CLI and authenticate through your IAM. For more information on how to set 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).
+To initialize `AmazonBedrockDocumentEmbedder` and authenticate by providing credentials, provide the `model_name`, as well as `aws_access_key_id`, `aws_secret_access_key` and `aws_region_name`. Other parameters are optional. You can check them out in our [API reference](/reference/integrations-amazon-bedrock#amazonbedrockdocumentembedder).
+
+### Model-specific parameters
+
+Even if Haystack provides a unified interface, each model offered by Bedrock can accept specific parameters. You can pass these parameters at initialization.
+
+For example, Cohere models support `input_type` and `truncate`, as seen in [Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html).
+
+```python
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentEmbedder,
+)
+
+embedder = AmazonBedrockDocumentEmbedder(
+ model="cohere.embed-english-v3",
+ input_type="search_document",
+ truncate="LEFT",
+)
+```
+
+### Embedding Metadata
+
+Text documents often come with a set of metadata. If they are distinctive and semantically meaningful, you can embed them along with the text of the document to improve retrieval.
+
+You can do this easily by using the Document Embedder:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentEmbedder,
+)
+
+doc = Document(content="some text", meta={"title": "relevant title", "page number": 18})
+
+embedder = AmazonBedrockDocumentEmbedder(
+ model="cohere.embed-english-v3",
+ meta_fields_to_embed=["title"],
+)
+
+docs_w_embeddings = embedder.run(documents=[doc])["documents"]
+```
+
+## Usage
+
+### Installation
+
+You need to install `amazon-bedrock-haystack` package to use the `AmazonBedrockTextEmbedder`:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import os
+from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockDocumentEmbedder
+from haystack.dataclasses import DOcument
+
+os.environ["AWS_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
+os.environ["AWS_DEFAULT_REGION"] = "us-east-1" # just an example
+
+doc = Document(content="I love pizza!")
+
+embedder = AmazonBedrockDocumentEmbedder(model="cohere.embed-english-v3",
+ input_type="search_document"
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+## [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentEmbedder,
+ AmazonBedrockTextEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(
+ "embedder",
+ AmazonBedrockDocumentEmbedder(model="cohere.embed-english-v3"),
+)
+indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+indexing_pipeline.connect("embedder", "writer")
+
+indexing_pipeline.run({"embedder": {"documents": documents}})
+
+query_pipeline = Pipeline()
+query_pipeline.add_component(
+ "text_embedder",
+ AmazonBedrockTextEmbedder(model="cohere.embed-english-v3"),
+)
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin')
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/amazonbedrockdocumentimageembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/amazonbedrockdocumentimageembedder.mdx
new file mode 100644
index 0000000000..e2ba93774d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/amazonbedrockdocumentimageembedder.mdx
@@ -0,0 +1,165 @@
+---
+title: "AmazonBedrockDocumentImageEmbedder"
+id: amazonbedrockdocumentimageembedder
+slug: "/amazonbedrockdocumentimageembedder"
+description: "`AmazonBedrockDocumentImageEmbedder` computes image embeddings for documents using models exposed through the Amazon Bedrock API. It stores the obtained vectors in the embedding field of each document."
+---
+
+# AmazonBedrockDocumentImageEmbedder
+
+`AmazonBedrockDocumentImageEmbedder` computes image embeddings for documents using models exposed through the Amazon Bedrock API. It stores the obtained vectors in the embedding field of each document.
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `documents`: A list of documents to be embedded | +| **Output variables** | `documents`: A list of documents (enriched with embeddings) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `model`: The multimodal embedding model to use.
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `documents`: A list of documents, with a meta field containing an image file path | +| **Output variables** | `documents`: A list of documents (enriched with embeddings) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+## Overview
+
+Amazon Bedrock is a fully managed service that provides access to foundation models through a unified API.
+
+`AmazonBedrockDocumentImageEmbedder` expects a list of documents containing an image or a PDF file path in a meta field. The meta field can be specified with the `file_path_meta_field` init parameter of this component.
+
+The embedder efficiently loads the images, computes the embeddings using selected Bedrock model, and stores each of them in the `embedding` field of the document.
+
+Supported models are `amazon.titan-embed-image-v1`, `cohere.embed-english-v3` , and `cohere.embed-multilingual-v3`.
+
+`AmazonBedrockDocumentImageEmbedder` is commonly used in indexing pipelines. At retrieval time, you need to use the same model with `AmazonBedrockTextEmbedder` to embed the query, before using an Embedding Retriever.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### Authentication
+
+`AmazonBedrockDocumentImageEmbedder` uses AWS for authentication. You can either provide credentials as parameters directly to the component or use the AWS CLI and authenticate through your IAM. For more information on how to set 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).
+
+To initialize `AmazonBedrockDocumentImageEmbedder` and authenticate by providing credentials, provide the `model` name, as well as `aws_access_key_id`, `aws_secret_access_key`, and `aws_region_name`. Other parameters are optional, you can check them out in our [API reference](/reference/integrations-amazon-bedrock#amazonbedrocktextembedder).
+
+### Model-specific parameters
+
+Even if Haystack provides a unified interface, each model offered by Bedrock can accept specific parameters. You can pass these parameters at initialization.
+
+- **Amazon Titan**: Use `embeddingConfig` to control embedding behavior.
+- **Cohere v3**: Use `embedding_types` to select a single embedding type for images.
+
+```python
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentImageEmbedder,
+)
+
+embedder = AmazonBedrockDocumentImageEmbedder(
+ model="cohere.embed-english-v3",
+ embedding_types=["float"], # single value only
+)
+```
+
+Note that only _one_ value in `embedding_types` is supported by this component. Passing multiple values raises an error.
+
+## Usage
+
+### On its own
+
+```python
+import os
+from haystack import Document
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentImageEmbedder,
+)
+
+os.environ["AWS_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
+os.environ["AWS_DEFAULT_REGION"] = "us-east-1" # example
+
+## Point Documents to image/PDF files via metadata (default key: "file_path")
+documents = [
+ Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
+ Document(
+ content="Invoice page",
+ meta={
+ "file_path": "invoice.pdf",
+ "mime_type": "application/pdf",
+ "page_number": 1,
+ },
+ ),
+]
+
+embedder = AmazonBedrockDocumentImageEmbedder(
+ model="amazon.titan-embed-image-v1",
+ image_size=(1024, 1024), # optional downscaling
+)
+
+result = embedder.run(documents=documents)
+embedded_docs = result["documents"]
+```
+
+### In a pipeline
+
+In this example, we can see an indexing pipeline with 3 components:
+
+- `ImageFileToDocument` Converter that creates empty documents with a reference to an image in the `meta.file_path` field;
+- `AmazonBedrockDocumentImageEmbedder` that loads the images, computes embeddings and stores them in documents;
+- `DocumentWriter` that write the documents in the `InMemoryDocumentStore`.
+
+There is also a multimodal retrieval pipeline, composed of an `AmazonBedrockTextEmbedder` (using the same model as before) and an `InMemoryEmbeddingRetriever`.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.writers import DocumentWriter
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentImageEmbedder,
+ AmazonBedrockTextEmbedder,
+)
+
+## Document store using vector similarity for retrieval
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+## Sample corpus with file paths in metadata
+documents = [
+ Document(content="A sketch of a horse", meta={"file_path": "horse.png"}),
+ Document(content="A city map", meta={"file_path": "map.jpg"}),
+]
+
+## Indexing pipeline: image embeddings -> write to store
+indexing = Pipeline()
+indexing.add_component(
+ "image_embedder",
+ AmazonBedrockDocumentImageEmbedder(model="cohere.embed-english-v3"),
+)
+indexing.add_component("writer", DocumentWriter(document_store=document_store))
+indexing.connect("image_embedder", "writer")
+indexing.run({"image_embedder": {"documents": documents}})
+
+## Query pipeline: text -> embedding -> vector retriever
+query = Pipeline()
+query.add_component(
+ "text_embedder",
+ AmazonBedrockTextEmbedder(model="cohere.embed-english-v3"),
+)
+query.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query.connect("text_embedder.embedding", "retriever.query_embedding")
+
+res = query.run({"text_embedder": {"text": "Which document shows a horse?"}})
+```
+
+## Additional References
+
+:notebook: Tutorial: [Creating Vision+Text RAG Pipelines](https://haystack.deepset.ai/tutorials/46_multimodal_rag)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/amazonbedrocktextembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/amazonbedrocktextembedder.mdx
new file mode 100644
index 0000000000..1895a8a860
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/amazonbedrocktextembedder.mdx
@@ -0,0 +1,140 @@
+---
+title: "AmazonBedrockTextEmbedder"
+id: amazonbedrocktextembedder
+slug: "/amazonbedrocktextembedder"
+description: "This component computes embeddings for text (such as a query) using models through Amazon Bedrock API."
+---
+
+# AmazonBedrockTextEmbedder
+
+This component computes embeddings for text (such as a query) using models through Amazon Bedrock API.
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `documents`: A list of documents, with a meta field containing an image file path | +| **Output variables** | `documents`: A list of documents (enriched with embeddings) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `model`: The embedding model to use
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers (vector) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+## Overview
+
+[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) is a fully managed service that makes language models from leading AI startups and Amazon available for your use through a unified API.
+
+Supported models are `amazon.titan-embed-text-v1`, `cohere.embed-english-v3` and `cohere.embed-multilingual-v3`.
+
+Use `AmazonBedrockTextEmbedder` to embed a simple string (such as a query) into a vector. Use the [`AmazonBedrockDocumentEmbedder`](amazonbedrockdocumentembedder.mdx) to enrich the documents with the computed embedding, also known as vector.
+
+### Authentication
+
+`AmazonBedrockTextEmbedder` uses AWS for authentication. You can either provide credentials as parameters directly to the component or use the AWS CLI and authenticate through your IAM. For more information on how to set 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).
+To initialize `AmazonBedrockTextEmbedder` and authenticate by providing credentials, provide the `model` name, as well as `aws_access_key_id`, `aws_secret_access_key`, and `aws_region_name`. Other parameters are optional, you can check them out in our [API reference](/reference/integrations-amazon-bedrock#amazonbedrocktextembedder).
+
+### Model-specific parameters
+
+Even if Haystack provides a unified interface, each model offered by Bedrock can accept specific parameters. You can pass these parameters at initialization.
+
+For example, the Cohere models support `input_type` and `truncate`, as seen in [Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html).
+
+```python
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockTextEmbedder,
+)
+
+embedder = AmazonBedrockTextEmbedder(
+ model="cohere.embed-english-v3",
+ input_type="search_query",
+ truncate="LEFT",
+)
+```
+
+## Usage
+
+### Installation
+
+You need to install `amazon-bedrock-haystack` package to use the `AmazonBedrockTextEmbedder`:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import os
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockTextEmbedder,
+)
+
+os.environ["AWS_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
+os.environ["AWS_DEFAULT_REGION"] = "us-east-1" # just an example
+
+text_to_embed = "I love pizza!"
+
+text_embedder = AmazonBedrockTextEmbedder(
+ model="cohere.embed-english-v3",
+ input_type="search_query",
+)
+
+print(text_embedder.run(text_to_embed))
+## {'embedding': [-0.453125, 1.2236328, 2.0058594, 0.67871094...]}
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentEmbedder,
+ AmazonBedrockTextEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+document_embedder = AmazonBedrockDocumentEmbedder(model="cohere.embed-english-v3")
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component(
+ "text_embedder",
+ AmazonBedrockTextEmbedder(model="cohere.embed-english-v3"),
+)
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin')
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/azureopenaidocumentembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/azureopenaidocumentembedder.mdx
new file mode 100644
index 0000000000..9e5066e8a5
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/azureopenaidocumentembedder.mdx
@@ -0,0 +1,128 @@
+---
+title: "AzureOpenAIDocumentEmbedder"
+id: azureopenaidocumentembedder
+slug: "/azureopenaidocumentembedder"
+description: "This component computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses Azure cognitive services for text and document embedding with models deployed on Azure."
+---
+
+# AzureOpenAIDocumentEmbedder
+
+This component computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses Azure cognitive services for text and document embedding with models deployed on Azure.
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers (vector) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) |
+| **Mandatory init variables** | `api_key`: The Azure OpenAI API key. Can be set with `AZURE_OPENAI_API_KEY` env var.
`azure_endpoint`: The endpoint of the model deployed on Azure. | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/azure_document_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector representing the query is compared with those of the documents to find the most similar or relevant documents.
+
+To see the list of compatible embedding models, head over to Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?source=recommendations). The default model for `AzureOpenAITextEmbedder` is `text-embedding-ada-002`.
+
+This component should be used to embed a list of documents. To embed a string, you should use the [`AzureOpenAITextEmbedder`](azureopenaitextembedder.mdx).
+
+To work with Azure components, you will need an Azure OpenAI API key, as well as an Azure OpenAI Endpoint. You can learn more about them in Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
+
+The component uses `AZURE_OPENAI_API_KEY` or `AZURE_OPENAI_AD_TOKEN` environment variables by default. Otherwise, you can pass `api_key` or `azure_ad_token` at initialization:
+
+```python
+client = AzureOpenAIDocumentEmbedder(
+ azure_endpoint="`azure_endpoint`: The endpoint of the model deployed on Azure. | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/azure_document_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The Azure OpenAI API key. Can be set with `AZURE_OPENAI_API_KEY` env var.
`azure_endpoint`: The endpoint of the model deployed on Azure. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/azure_text_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`AzureOpenAITextEmbedder` transforms a string into a vector that captures its semantics using an OpenAI embedding model. It uses Azure cognitive services for text and document embedding with models deployed on Azure.
+
+To see the list of compatible embedding models, head over to Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?source=recommendations). The default model for `AzureOpenAITextEmbedder` is `text-embedding-ada-002`.
+
+Use `AzureOpenAITextEmbedder` to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [`AzureOpenAIDocumentEmbedder`](azureopenaidocumentembedder.mdx), which enriches the documents with the computed embedding, also known as vector.
+
+To work with Azure components, you will need an Azure OpenAI API key, as well as an Azure OpenAI Endpoint. You can learn more about them in Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
+
+The component uses `AZURE_OPENAI_API_KEY` or `AZURE_OPENAI_AD_TOKEN` environment variables by default. Otherwise, you can pass `api_key` or `azure_ad_token` at initialization:
+
+```python
+client = AzureOpenAITextEmbedder(
+ azure_endpoint="`azure_endpoint`: The endpoint of the model deployed on Azure. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/azure_text_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **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 documents to be embedded |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata strings | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | +| **Package name** | `cohere-haystack` | + +
+
+## Overview
+
+`CohereDocumentEmbedder` enriches the metadata of documents with an embedding of their content. To embed a string, you should use the [`CohereTextEmbedder`](coheretextembedder.mdx).
+
+The component supports the following Cohere models:
+`"embed-english-v3.0"`, `"embed-english-light-v3.0"`, `"embed-multilingual-v3.0"`,
+`"embed-multilingual-light-v3.0"`, `"embed-english-v2.0"`, `"embed-english-light-v2.0"`,
+`"embed-multilingual-v2.0"`. The default model is `embed-english-v2.0`. This list of all supported models can be found in Cohere’s [model documentation](https://docs.cohere.com/docs/models#representation).
+
+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 an API key at initialization with `api_key`:
+
+```python
+embedder = CohereDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | +| **Package name** | `cohere-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **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 documents, with a meta field containing an image file path |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [Cohere](/reference/integrations-cohere) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere |
+| **Package name** | `cohere-haystack` |
+
+
+
+## Overview
+
+`CohereDocumentImageEmbedder` expects a list of documents containing an image or a PDF file path in a meta field. The meta field can be specified with the `file_path_meta_field` init parameter of this component.
+
+The embedder efficiently loads the images, computes the embeddings using a Cohere model, and stores each of them in the `embedding` field of the document.
+
+`CohereDocumentImageEmbedder` is commonly used in indexing pipelines. At retrieval time, you need to use the same model with a `CohereTextEmbedder` to embed the query, before using an Embedding Retriever.
+
+This component is compatible with Cohere Embed models v3 and later. For a complete list of supported models, see the [Cohere documentation](https://docs.cohere.com/docs/models#embed).
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install cohere-haystack
+```
+
+### Authentication
+
+The component uses a `COHERE_API_KEY` or `CO_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` method:
+
+```python
+embedder = CohereTextEmbedder(api_key=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **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** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers (vectors)
`meta`: A dictionary of metadata strings | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | +| **Package name** | `cohere-haystack` | + +
+
+## Overview
+
+`CohereTextEmbedder` embeds a simple string (such as a query) into a vector. For embedding lists of documents, use the use the [`CohereDocumentEmbedder`](coheredocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+The component supports the following Cohere models:
+`"embed-english-v3.0"`, `"embed-english-light-v3.0"`, `"embed-multilingual-v3.0"`,
+`"embed-multilingual-light-v3.0"`, `"embed-english-v2.0"`, `"embed-english-light-v2.0"`,
+`"embed-multilingual-v2.0"`. The default model is `embed-english-v2.0`. This list of all supported models can be found in Cohere’s [model documentation](https://docs.cohere.com/docs/models#representation).
+
+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 an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` static method:
+
+```python
+embedder = CohereTextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | +| **Package name** | `cohere-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [FastEmbed](/reference/fastembed-embedders) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed |
+| **Package name** | `fastembed-haystack` |
+
+
+
+This component should be used to embed a list of documents. To embed a string, use the [`FastembedTextEmbedder`](fastembedtextembedder.mdx).
+
+## Overview
+
+`FastembedDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses embedding [models supported by FastEmbed](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents in order to find the most similar or relevant documents.
+
+### Compatible models
+
+You can find the original models in the [FastEmbed documentation](https://qdrant.github.io/fastembed/).
+
+Nowadays, most of the models in the [Massive Text Embedding Benchmark (MTEB) Leaderboard](https://huggingface.co/spaces/mteb/leaderboard) are compatible with FastEmbed. You can look for compatibility in the [supported model list](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 will be stored in a cache directory. Also, you can set the number of threads a single `onnxruntime` session can use.
+
+```python
+cache_dir= "/your_cacheDirectory"
+embedder = FastembedDocumentEmbedder(
+ *model="*BAAI/bge-large-en-v1.5",
+ 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.
+
+:::tip
+If you create a Text Embedder and a Document Embedder based on the same model, Haystack uses the same resource behind the scenes to save resources.
+:::
+
+### Embedding Metadata
+
+Text documents often come with a set of metadata. If they are distinctive and semantically meaningful, you can embed them along with the text of the document to improve retrieval.
+
+You can do this easily by using the Document Embedder:
+
+```python
+from haystack.preview import Document
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedDocumentEmbedder,
+)
+
+doc = Document(
+ text="some text",
+ metadata={"title": "relevant title", "page number": 18},
+)
+
+embedder = FastembedDocumentEmbedder(
+ model="BAAI/bge-small-en-v1.5",
+ batch_size=256,
+ metadata_fields_to_embed=["title"],
+)
+
+docs_w_embeddings = embedder.run(documents=[doc])["documents"]
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedDocumentEmbedder,
+)
+
+document_list = [
+ Document(content="I love pizza!"),
+ Document(content="I like spaghetti"),
+]
+
+doc_embedder = FastembedDocumentEmbedder()
+
+result = doc_embedder.run(document_list)
+print(result["documents"][0].embedding)
+
+## [-0.04235665127635002, 0.021791068837046623, ...]
+```
+
+### In a pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.writers import DocumentWriter
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedDocumentEmbedder,
+ FastembedTextEmbedder,
+)
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+ Document(content="fastembed is supported by and maintained by Qdrant."),
+]
+
+document_embedder = FastembedDocumentEmbedder()
+writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.OVERWRITE)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("document_embedder", document_embedder)
+indexing_pipeline.add_component("writer", writer)
+indexing_pipeline.connect("document_embedder", "writer")
+
+indexing_pipeline.run({"document_embedder": {"documents": documents}})
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", FastembedTextEmbedder())
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who supports fastembed?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0]) # noqa: T201
+
+## Document(id=...,
+## content: 'fastembed is supported by and maintained by Qdrant.',
+## score: 0.758..)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [RAG Pipeline Using FastEmbed for Embeddings Generation](https://haystack.deepset.ai/cookbook/rag_fastembed)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/fastembedsparsedocumentembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/fastembedsparsedocumentembedder.mdx
new file mode 100644
index 0000000000..c3f3d6d9e7
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/fastembedsparsedocumentembedder.mdx
@@ -0,0 +1,191 @@
+---
+title: "FastembedSparseDocumentEmbedder"
+id: fastembedsparsedocumentembedder
+slug: "/fastembedsparsedocumentembedder"
+description: "Use this component to enrich a list of documents with their sparse embeddings."
+---
+
+# FastembedSparseDocumentEmbedder
+
+Use this component to enrich a list of documents with their sparse embeddings.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with sparse embeddings) |
+| **API reference** | [FastEmbed](/reference/fastembed-embedders) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed |
+| **Package name** | `fastembed-haystack` |
+
+
+
+To compute a sparse embedding for a string, use the [`FastembedSparseTextEmbedder`](fastembedsparsetextembedder.mdx).
+
+## Overview
+
+`FastembedSparseDocumentEmbedder` computes the sparse embeddings of a list of documents and stores the obtained vectors in the `sparse_embedding` field of each document. It uses sparse embedding [models](https://qdrant.github.io/fastembed/examples/Supported_Models/#supported-sparse-text-embedding-models) supported by FastEmbed.
+
+The vectors calculated by this component are necessary for performing sparse embedding retrieval on a set of documents. During retrieval, the sparse vector representing the query is compared to those of the documents to identify the most similar or relevant ones.
+
+### Compatible models
+
+You can find the supported models in the [FastEmbed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/#supported-sparse-text-embedding-models).
+
+Currently, supported models are based on SPLADE, a technique for producing sparse representations for text, where each non-zero value in the embedding is the importance weight of a term in the BERT WordPiece vocabulary. For more information, see [our docs](../retrievers.mdx#sparse-embedding-based-retrievers) that explain sparse embedding-based Retrievers further.
+
+### 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 will be stored in a cache directory. Also, you can set the number of threads a single `onnxruntime` session can use:
+
+```python
+cache_dir = "/your_cacheDirectory"
+embedder = FastembedSparseDocumentEmbedder(
+ model="prithivida/Splade_PP_en_v1",
+ 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.
+
+:::tip
+If you create both a Sparse Text Embedder and a Sparse Document Embedder based on the same model, Haystack utilizes a shared resource behind the scenes to conserve resources.
+:::
+
+### Embedding Metadata
+
+Text documents often include metadata. If the metadata is distinctive and semantically meaningful, you can embed it along with the document's text to improve retrieval.
+
+You can do this easily by using the sparse Document Embedder:
+
+```python
+from haystack.preview import Document
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedSparseDocumentEmbedder,
+)
+
+doc = Document(
+ text="some text",
+ metadata={"title": "relevant title", "page number": 18},
+)
+
+embedder = FastembedSparseDocumentEmbedder(
+ model="prithivida/Splade_PP_en_v1",
+ metadata_fields_to_embed=["title"],
+)
+
+docs_w_sparse_embeddings = embedder.run(documents=[doc])["documents"]
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedSparseDocumentEmbedder,
+)
+
+document_list = [
+ Document(content="I love pizza!"),
+ Document(content="I like spaghetti"),
+]
+
+doc_embedder = FastembedSparseDocumentEmbedder()
+
+result = doc_embedder.run(document_list)
+print(result["documents"][0])
+
+## Document(id=...,
+## content: 'I love pizza!',
+## sparse_embedding: vector with 24 non-zero elements)
+```
+
+### In a pipeline
+
+Currently, sparse embedding retrieval is only supported by `QdrantDocumentStore`.
+First, install the package with:
+
+```shell
+pip install qdrant-haystack
+```
+
+Then, try out this pipeline:
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.writers import DocumentWriter
+from haystack_integrations.components.retrievers.qdrant import (
+ QdrantSparseEmbeddingRetriever,
+)
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedDocumentEmbedder,
+ FastembedTextEmbedder,
+)
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ use_sparse_embeddings=True,
+)
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+ Document(content="fastembed is supported by and maintained by Qdrant."),
+]
+
+sparse_document_embedder = FastembedSparseDocumentEmbedder()
+writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.OVERWRITE)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("sparse_document_embedder", sparse_document_embedder)
+indexing_pipeline.add_component("writer", writer)
+indexing_pipeline.connect("sparse_document_embedder", "writer")
+
+indexing_pipeline.run({"sparse_document_embedder": {"documents": documents}})
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("sparse_text_embedder", FastembedSparseTextEmbedder())
+query_pipeline.add_component(
+ "sparse_retriever",
+ QdrantSparseEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect(
+ "sparse_text_embedder.sparse_embedding",
+ "sparse_retriever.query_sparse_embedding",
+)
+
+query = "Who supports fastembed?"
+
+result = query_pipeline.run({"sparse_text_embedder": {"text": query}})
+
+print(result["sparse_retriever"]["documents"][0]) # noqa: T201
+
+## Document(id=...,
+## content: 'fastembed is supported by and maintained by Qdrant.',
+## score: 0.758..)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Sparse Embedding Retrieval with Qdrant and FastEmbed](https://haystack.deepset.ai/cookbook/sparse_embedding_retrieval)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/fastembedsparsetextembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/fastembedsparsetextembedder.mdx
new file mode 100644
index 0000000000..96700ba756
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/fastembedsparsetextembedder.mdx
@@ -0,0 +1,155 @@
+---
+title: "FastembedSparseTextEmbedder"
+id: fastembedsparsetextembedder
+slug: "/fastembedsparsetextembedder"
+description: "Use this component to embed a simple string (such as a query) into a sparse vector."
+---
+
+# FastembedSparseTextEmbedder
+
+Use this component to embed a simple string (such as a query) into a sparse vector.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a sparse embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `sparse_embedding`: A [`SparseEmbedding`](../../concepts/data-classes.mdx#sparseembedding) object |
+| **API reference** | [FastEmbed](/reference/fastembed-embedders) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed |
+| **Package name** | `fastembed-haystack` |
+
+
+
+For embedding lists of documents, use the [`FastembedSparseDocumentEmbedder`](fastembedsparsedocumentembedder.mdx), which enriches the document with the computed sparse embedding.
+
+## Overview
+
+`FastembedSparseTextEmbedder` transforms a string into a sparse vector using sparse embedding [models](https://qdrant.github.io/fastembed/examples/Supported_Models/#supported-sparse-text-embedding-models) supported by FastEmbed.
+
+When you perform sparse embedding retrieval, use this component first to transform your query into a sparse vector. Then, the sparse embedding Retriever will use the vector to search for similar or relevant documents.
+
+### Compatible Models
+
+You can find the supported models in the [FastEmbed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/#supported-sparse-text-embedding-models).
+
+Currently, supported models are based on SPLADE, a technique for producing sparse representations for text, where each non-zero value in the embedding is the importance weight of a term in the BERT WordPiece vocabulary. For more information, see [our docs](../retrievers.mdx#sparse-embedding-based-retrievers) that explain sparse embedding-based Retrievers further.
+
+### 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 will be stored in a cache directory. Also, you can set the number of threads a single `onnxruntime` session can use:
+
+```python
+cache_dir = "/your_cacheDirectory"
+embedder = FastembedSparseTextEmbedder(
+ model="prithivida/Splade_PP_en_v1",
+ cache_dir=cache_dir,
+ threads=2,
+)
+```
+
+If you want to use the data parallel encoding, you can set the `parallel` parameter.
+
+- 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 the default `onnxruntime` threading instead.
+
+:::tip
+If you create both a Sparse Text Embedder and a Sparse Document Embedder based on the same model, Haystack utilizes a shared resource behind the scenes to conserve resources.
+:::
+
+## Usage
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedSparseTextEmbedder,
+)
+
+text = """It clearly says online this will work on a Mac OS system.
+The disk comes and it does not, only Windows.
+Do Not order this if you have a Mac!!"""
+
+text_embedder = FastembedSparseTextEmbedder(model="prithivida/Splade_PP_en_v1")
+
+sparse_embedding = text_embedder.run(text)["sparse_embedding"]
+```
+
+### In a pipeline
+
+Currently, sparse embedding retrieval is only supported by `QdrantDocumentStore`.
+First, install the package with:
+
+```shell
+pip install qdrant-haystack
+```
+
+Then, try out this pipeline:
+
+```python
+from haystack import Document, Pipeline
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack_integrations.components.retrievers.qdrant import (
+ QdrantSparseEmbeddingRetriever,
+)
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedSparseTextEmbedder,
+ FastembedSparseDocumentEmbedder,
+ FastembedTextEmbedder,
+)
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ use_sparse_embeddings=True,
+)
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+ Document(content="fastembed is supported by and maintained by Qdrant."),
+]
+
+sparse_document_embedder = FastembedSparseDocumentEmbedder(
+ model="prithivida/Splade_PP_en_v1",
+)
+
+documents_with_sparse_embeddings = sparse_document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_sparse_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("sparse_text_embedder", FastembedSparseTextEmbedder())
+query_pipeline.add_component(
+ "sparse_retriever",
+ QdrantSparseEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect(
+ "sparse_text_embedder.sparse_embedding",
+ "sparse_retriever.query_sparse_embedding",
+)
+
+query = "Who supports fastembed?"
+
+result = query_pipeline.run({"sparse_text_embedder": {"text": query}})
+
+print(result["sparse_retriever"]["documents"][0]) # noqa: T201
+
+## Document(id=...,
+## content: 'fastembed is supported by and maintained by Qdrant.',
+## score: 0.561..)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Sparse Embedding Retrieval with Qdrant and FastEmbed](https://haystack.deepset.ai/cookbook/sparse_embedding_retrieval)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/fastembedtextembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/fastembedtextembedder.mdx
new file mode 100644
index 0000000000..7aa40f52fa
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/fastembedtextembedder.mdx
@@ -0,0 +1,143 @@
+---
+title: "FastembedTextEmbedder"
+id: fastembedtextembedder
+slug: "/fastembedtextembedder"
+description: "This component computes the embeddings of a string using embedding models supported by FastEmbed."
+---
+
+# FastembedTextEmbedder
+
+This component computes the embeddings of a string using embedding models supported by FastEmbed.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A vector (list of float numbers) |
+| **API reference** | [FastEmbed](/reference/fastembed-embedders) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed |
+| **Package name** | `fastembed-haystack` |
+
+
+
+This component should be used to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [`FastembedDocumentEmbedder`](fastembeddocumentembedder.mdx), which enriches the document with the computed embedding, known as vector.
+
+## Overview
+
+`FastembedTextEmbedder` transforms a string into a vector that captures its semantics using embedding [models supported by FastEmbed](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+
+When you perform embedding retrieval, use this component first to transform your query into a vector. Then, the embedding Retriever will use the vector to search for similar or relevant documents.
+
+### Compatible models
+
+You can find the original models in the [FastEmbed documentation](https://qdrant.github.io/fastembed/).
+
+Currently, most of the models in the [Massive Text Embedding Benchmark (MTEB) Leaderboard](https://huggingface.co/spaces/mteb/leaderboard) are compatible with FastEmbed. You can look for compatibility in the [supported model list](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```bash
+pip install fastembed-haystack
+```
+
+### Instructions
+
+Some recent models that you can find in MTEB require prepending the text with an instruction to work better for retrieval.
+For example, if you use `[BAAI/bge-large-en-v1.5](https://huggingface.co/BAAI/bge-large-en-v1.5#model-list)` model, you should prefix your query with the `instruction: “passage:”`.
+
+This is how it works with `FastembedTextEmbedder`:
+
+```python
+instruction = "passage:"
+embedder = FastembedTextEmbedder(
+ *model="*BAAI/bge-large-en-v1.5",
+ prefix=instruction)
+```
+
+### Parameters
+
+You can set the path where the model will be stored in a cache directory. Also, you can set the number of threads a single `onnxruntime` session can use.
+
+```python
+cache_dir= "/your_cacheDirectory"
+embedder = FastembedTextEmbedder(
+ *model="*BAAI/bge-large-en-v1.5",
+ 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.
+
+:::tip
+If you create a Text Embedder and a Document Embedder based on the same model, Haystack uses the same resource behind the scenes to save resources.
+:::
+
+## Usage
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.fastembed import FastembedTextEmbedder
+
+text = """It clearly says online this will work on a Mac OS system.
+The disk comes and it does not, only Windows.
+Do Not order this if you have a Mac!!"""
+text_embedder = FastembedTextEmbedder(model="BAAI/bge-small-en-v1.5")
+embedding = text_embedder.run(text)["embedding"]
+```
+
+### In a pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedDocumentEmbedder,
+ FastembedTextEmbedder,
+)
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+ Document(content="fastembed is supported by and maintained by Qdrant."),
+]
+
+document_embedder = FastembedDocumentEmbedder()
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", FastembedTextEmbedder())
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who supports FastEmbed?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0]) # noqa: T201
+
+## Document(id=...,
+## content: 'FastEmbed is supported by and maintained by Qdrant.',
+## score: 0.758..)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [RAG Pipeline Using FastEmbed for Embeddings Generation](https://haystack.deepset.ai/cookbook/rag_fastembed)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/googlegenaidocumentembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/googlegenaidocumentembedder.mdx
new file mode 100644
index 0000000000..5ddb40aef8
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/googlegenaidocumentembedder.mdx
@@ -0,0 +1,182 @@
+---
+title: "GoogleGenAIDocumentEmbedder"
+id: googlegenaidocumentembedder
+slug: "/googlegenaidocumentembedder"
+description: "The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector representing the query is compared with those of the documents to find the most similar or relevant documents."
+---
+
+# GoogleGenAIDocumentEmbedder
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector representing the query is compared with those of the documents to find the most similar or relevant documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [DocumentWriter](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Google API key. Can be set with `GOOGLE_API_KEY` or `GEMINI_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Google GenAI](/reference/integrations-google-genai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai | +| **Package name** | `google-genai-haystack` | + +
+
+## Overview
+
+`GoogleGenAIDocumentEmbedder` enriches the metadata of documents with an embedding of their content. To embed a string, you should use the [`GoogleGenAITextEmbedder`](googlegenaitextembedder.mdx).
+
+The component supports [Google AI Embedding models](https://ai.google.dev/gemini-api/docs/embeddings#model-versions).
+
+`gemini-embedding-001` is the default model.
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install google-genai-haystack
+```
+
+### Authentication
+
+Google Gen AI is compatible with both the Gemini Developer API and the Vertex AI API.
+
+To use this component with the Gemini Developer API and get an API key, visit [Google AI Studio](https://aistudio.google.com/).
+To use this component with the Vertex AI API, visit [Google Cloud > Vertex AI](https://cloud.google.com/vertex-ai).
+
+The component uses a `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` static method:
+
+```python
+embedder = GoogleGenAIDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Google GenAI](/reference/integrations-google-genai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai | +| **Package name** | `google-genai-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [DocumentWriter](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Google API key. Can be set with `GOOGLE_API_KEY` or `GEMINI_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents, with a meta field containing an image file path |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Google GenAI](/reference/integrations-google-genai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai | +| **Package name** | `google-genai-haystack` | + +
+
+## Overview
+
+`GoogleGenAIMultimodalDocumentEmbedder` expects a list of documents containing a file path in a meta field. The meta field can be specified with the `file_path_meta_field` init parameter of this component.
+
+The embedder efficiently loads the files, computes the embeddings using a Google AI model, and stores each of them in the `embedding` field of the document.
+
+`GoogleGenAIMultimodalDocumentEmbedder` is commonly used in indexing pipelines. At retrieval time, you need to use the same model with a `GoogleGenAITextEmbedder` to embed the query, before using an Embedding Retriever.
+
+This component is compatible with Gemini multimodal models: `gemini-embedding-2` and later. For a complete list of supported models, see the [Google AI documentation](https://ai.google.dev/gemini-api/docs/embeddings).
+
+To embed a textual document, you should use the [`GoogleGenAIDocumentEmbedder`](googlegenaidocumentembedder.mdx).
+To embed a string, you should use the [`GoogleGenAITextEmbedder`](googlegenaitextembedder.mdx).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install google-genai-haystack
+```
+
+### Authentication
+
+Google Gen AI is compatible with both the Gemini Developer API and the Vertex AI API.
+
+To use this component with the Gemini Developer API and get an API key, visit [Google AI Studio](https://aistudio.google.com/).
+To use this component with the Vertex AI API, visit [Google Cloud > Vertex AI](https://cloud.google.com/vertex-ai).
+
+The component uses a `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` static method:
+
+```python
+embedder = GoogleGenAIMultimodalDocumentEmbedder(
+ api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Google GenAI](/reference/integrations-google-genai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai | +| **Package name** | `google-genai-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The Google API key. Can be set with `GOOGLE_API_KEY` or `GEMINI_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Google GenAI](/reference/integrations-google-genai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai | +| **Package name** | `google-genai-haystack` | + +
+
+## Overview
+
+`GoogleGenAITextEmbedder` embeds a simple string (such as a query) into a vector. For embedding lists of documents, use the [`GoogleGenAIDocumentEmbedder`](googlegenaidocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+The component supports [Google AI Embedding models](https://ai.google.dev/gemini-api/docs/embeddings#model-versions).
+
+`gemini-embedding-001` is the default model.
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install google-genai-haystack
+```
+
+### Authentication
+
+Google Gen AI is compatible with both the Gemini Developer API and the Vertex AI API.
+
+To use this component with the Gemini Developer API and get an API key, visit [Google AI Studio](https://aistudio.google.com/).
+To use this component with the Vertex AI API, visit [Google Cloud > Vertex AI](https://cloud.google.com/vertex-ai).
+
+The component uses a `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` static method:
+
+```python
+embedder = GoogleGenAITextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Google GenAI](/reference/integrations-google-genai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai | +| **Package name** | `google-genai-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_type`: The type of Hugging Face API to use
`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.
`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 to be embedded | +| **Output variables** | `documents`: A list of documents to be embedded (enriched with embeddings) | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_document_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`HuggingFaceAPIDocumentEmbedder` can be used to compute document embeddings using different Hugging Face APIs:
+
+- [Free Serverless Inference API](https://huggingface.co/inference-api)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+
+:::info
+This component should be used to embed a list of documents. To embed a string, use [`HuggingFaceAPITextEmbedder`](huggingfaceapitextembedder.mdx).
+:::
+
+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.
+The token is needed:
+
+- If you use the Serverless Inference API, or
+- If you use the Inference Endpoints.
+
+## Usage
+
+Similarly to other Document Embedders, this component allows adding prefixes (and postfixes) to include instruction and embedding metadata.
+For more fine-grained details, refer to the component’s [API reference](/reference/embedders-api#huggingfaceapidocumentembedder).
+
+### On its own
+
+#### Using Free Serverless Inference API
+
+Formerly known as (free) Hugging Face Inference API, this API allows you to quickly experiment with many models hosted on the Hugging Face Hub, offloading the inference to Hugging Face servers. It’s rate-limited and not meant for production.
+
+To use this API, you need a [free Hugging Face token](https://huggingface.co/settings/tokens).
+The Embedder expects the `model` in `api_params`.
+
+```python
+from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
+from haystack.utils import Secret
+from haystack.dataclasses import Document
+
+doc = Document(content="I love pizza!")
+
+document_embedder = HuggingFaceAPIDocumentEmbedder(
+ api_type="serverless_inference_api",
+ api_params={"model": "BAAI/bge-small-en-v1.5"},
+ token=Secret.from_token("`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.
`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 to be embedded | +| **Output variables** | `documents`: A list of documents to be embedded (enriched with embeddings) | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_document_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_type`: The type of Hugging Face API to use
`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.
`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_text_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`HuggingFaceAPITextEmbedder` can be used to embed strings using different Hugging Face APIs:
+
+- [Free Serverless Inference API](https://huggingface.co/inference-api)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+
+:::info
+This component should be used to embed plain text. To embed a list of documents, use [`HuggingFaceAPIDocumentEmbedder`](huggingfaceapidocumentembedder.mdx).
+:::
+
+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.
+The token is needed:
+
+- If you use the Serverless Inference API, or
+- If you use the Inference Endpoints.
+
+## Usage
+
+Similarly to other text Embedders, this component allows adding prefixes (and postfixes) to include instructions.
+For more fine-grained details, refer to the component’s [API reference](/reference/embedders-api#huggingfaceapitextembedder).
+
+### On its own
+
+#### Using Free Serverless Inference API
+
+Formerly known as (free) Hugging Face Inference API, this API allows you to quickly experiment with many models hosted on the Hugging Face Hub, offloading the inference to Hugging Face servers. It’s rate-limited and not meant for production.
+
+To use this API, you need a [free Hugging Face token](https://huggingface.co/settings/tokens).
+The Embedder expects the `model` in `api_params`.
+
+```python
+from haystack.components.embedders import HuggingFaceAPITextEmbedder
+from haystack.utils import Secret
+
+text_embedder = HuggingFaceAPITextEmbedder(
+ api_type="serverless_inference_api",
+ api_params={"model": "BAAI/bge-small-en-v1.5"},
+ token=Secret.from_token("`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.
`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_text_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Jina API key. Can be set with `JINA_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Jina](/reference/integrations-jina) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina | +| **Package name** | `jina-haystack` | + +
+
+## Overview
+
+`JinaDocumentEmbedder` enriches the metadata of documents with an embedding of their content. To embed a string, you should use the [`JinaTextEmbedder`](jinatextembedder.mdx). To see the list of compatible Jina Embeddings models, head to Jina AI’s [website](https://jina.ai/embeddings/). The default model for `JinaDocumentEmbedder` is `jina-embeddings-v2-base-en`.
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install jina-haystack
+```
+
+The component uses a `JINA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = JinaDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Jina](/reference/integrations-jina) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina | +| **Package name** | `jina-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Jina API key. Can be set with `JINA_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents, with a meta field containing an image file path |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [Jina](/reference/integrations-jina) |
+| **GitHub link** | [https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere) |
+| **Package name** | `jina-haystack` |
+
+
+
+## Overview
+
+`JinaDocumentImageEmbedder` expects a list of documents containing an image or a PDF file path in a meta field. The meta field can be specified with the `file_path_meta_field` init parameter of this component.
+
+The embedder efficiently loads the images, computes the embeddings using a Jina model, and stores each of them in the `embedding` field of the document.
+
+`JinaDocumentImageEmbedder` is commonly used in indexing pipelines. At retrieval time, you need to use the same model with a `JinaTextEmbedder` to embed the query, before using an Embedding Retriever.
+
+This component is compatible with Jina multimodal embedding models:
+
+- `jina-clip-v1`
+- `jina-clip-v2` (default)
+- `jina-embeddings-v4` (non-commercial research only)
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install jina-haystack
+```
+
+### Authentication
+
+The component uses a `JINA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` method:
+
+```python
+embedder = JinaDocumentImageEmbedder(api_key=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The Jina API key. Can be set with `JINA_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Jina](/reference/integrations-jina) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina | +| **Package name** | `jina-haystack` | + +
+
+## Overview
+
+`JinaTextEmbedder` embeds a simple string (such as a query) into a vector. For embedding lists of documents, use the use the [`JinaDocumentEmbedder`](jinadocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector. To see the list of compatible Jina Embeddings models, head to Jina AI’s [website](https://jina.ai/embeddings/). The default model for `JinaTextEmbedder` is `jina-embeddings-v2-base-en`.
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install jina-haystack
+```
+
+The component uses a `JINA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = JinaTextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Jina](/reference/integrations-jina) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina | +| **Package name** | `jina-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Mistral API key. Can be set with `MISTRAL_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata strings | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | +| **Package name** | `mistral-haystack` | + +
+
+This component should be used to embed a list of Documents. To embed a string, use the [`MistralTextEmbedder`](mistraltextembedder.mdx).
+
+## Overview
+
+`MistralDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses the Mistral API and its embedding models.
+
+The component currently supports the `mistral-embed` embedding model. The list of all supported models can be found in Mistral’s [embedding models documentation](https://docs.mistral.ai/platform/endpoints/#embedding-models).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install mistral-haystack
+```
+
+`MistralDocumentEmbedder` needs a Mistral API key to work. It uses an `MISTRAL_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = MistralDocumentEmbedder(
+ api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | +| **Package name** | `mistral-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The Mistral API key. Can be set with `MISTRAL_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers (vectors)
`meta`: A dictionary of metadata strings | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | +| **Package name** | `mistral-haystack` | + +
+
+Use `MistalTextEmbedder` to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [`MistralDocumentEmbedder`](mistraldocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+## Overview
+
+`MistralTextEmbedder` transforms a string into a vector that captures its semantics using a Mistral embedding model.
+
+The component currently supports the `mistral-embed` embedding model. The list of all supported models can be found in Mistral’s [embedding models documentation](https://docs.mistral.ai/platform/endpoints/#embedding-models).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install mistral-haystack
+```
+
+`MistralTextEmbedder` needs a Mistral API key to work. It uses a `MISTRAL_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = MistralTextEmbedder(
+ api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | +| **Package name** | `mistral-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: API key for the NVIDIA NIM. Can be set with `NVIDIA_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [NVIDIA](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | +| **Package name** | `nvidia-haystack` | + +
+
+## Overview
+
+`NvidiaDocumentEmbedder` enriches documents with an embedding of their content.
+
+You can use this component with self-hosted models using NVIDIA NIM or models hosted on the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover).
+
+To embed a string, use [`NvidiaTextEmbedder`](nvidiatextembedder.mdx).
+
+## Usage
+
+To start using `NvidiaDocumentEmbedder`, install the `nvidia-haystack` package:
+
+```shell
+pip install nvidia-haystack
+```
+
+You can use `NvidiaDocumentEmbedder` with all the embedding models available on the [NVIDIA API Catalog](https://docs.api.nvidia.com/nim/reference) or with a model deployed using NVIDIA NIM. For more information, refer to [Deploying Text Embedding Models](https://developer.nvidia.com/docs/nemo-microservices/embedding/source/deploy.html).
+
+### On its own
+
+To use models from the NVIDIA API Catalog, you need to specify the `api_url` and your API key. You can get your API key from the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover).
+
+`NvidiaDocumentEmbedder` uses the `NVIDIA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with the `api_key` parameter:
+
+```python
+from haystack import Document
+from haystack.utils.auth import Secret
+from haystack_integrations.components.embedders.nvidia import NvidiaDocumentEmbedder
+
+documents = [
+ Document(content="A transformer is a deep learning architecture"),
+ Document(content="Large language models use transformer architectures"),
+]
+
+embedder = NvidiaDocumentEmbedder(
+ model="nvidia/nv-embedqa-e5-v5",
+ api_url="https://integrate.api.nvidia.com/v1",
+ api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [NVIDIA](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | +| **Package name** | `nvidia-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: API key for the NVIDIA NIM. Can be set with `NVIDIA_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers (vectors)
`meta`: A dictionary of metadata strings | +| **API reference** | [NVIDIA](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | +| **Package name** | `nvidia-haystack` | + +
+
+## Overview
+
+`NvidiaTextEmbedder` embeds a simple string (such as a query) into a vector.
+
+You can use this component with self-hosted models using NVIDIA NIM or models hosted on the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover).
+
+To embed a list of documents, use [`NvidiaDocumentEmbedder`](nvidiadocumentembedder.mdx), which enriches each document with the computed embedding.
+
+## Usage
+
+To start using `NvidiaTextEmbedder`, install the `nvidia-haystack` package:
+
+```shell
+pip install nvidia-haystack
+```
+
+You can use `NvidiaTextEmbedder` with all the embedding models available on the [NVIDIA API Catalog](https://docs.api.nvidia.com/nim/reference) or with a model deployed using NVIDIA NIM. For more information, refer to [Deploying Text Embedding Models](https://developer.nvidia.com/docs/nemo-microservices/embedding/source/deploy.html).
+
+### On its own
+
+To use models from the NVIDIA API Catalog, you need to specify the `api_url` and your API key. You can get your API key from the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover).
+
+`NvidiaTextEmbedder` uses the `NVIDIA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with the `api_key` parameter:
+
+```python
+from haystack.utils.auth import Secret
+from haystack_integrations.components.embedders.nvidia import NvidiaTextEmbedder
+
+embedder = NvidiaTextEmbedder(
+ model="nvidia/nv-embedqa-e5-v5",
+ api_url="https://integrate.api.nvidia.com/v1",
+ api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [NVIDIA](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | +| **Package name** | `nvidia-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata strings | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | +| **Package name** | `ollama-haystack` | + +
+
+`OllamaDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses embedding models compatible with the Ollama Library.
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant documents.
+
+## Overview
+
+`OllamaDocumentEmbedder` should be used to embed a list of documents. For embedding a string only, use the [`OllamaTextEmbedder`](ollamatextembedder.mdx).
+
+The component uses `http://localhost:11434` as the default URL as most available setups (Mac, Linux, Docker) default to port 11434.
+
+### Compatible Models
+
+Unless specified otherwise while initializing this component, the default embedding model is "nomic-embed-text". See other possible pre-built models in Ollama's [library](https://ollama.ai/library). To load your own custom model, follow the [instructions](https://github.com/ollama/ollama/blob/main/docs/modelfile.md) from Ollama.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install ollama-haystack
+```
+
+Make sure that you have a running Ollama model (either through a docker container, or locally hosted). No other configuration is necessary as Ollama has the embedding API built in.
+
+### Embedding Metadata
+
+Most embedded metadata contains information about the model name and type. You can pass [optional arguments](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values), such as temperature, top_p, and others, to the Ollama generation endpoint.
+
+The name of the model used will be automatically appended as part of the document metadata. An example payload using the nomic-embed-text model will look like this:
+
+```python
+{"meta": {"model": "nomic-embed-text"}}
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.ollama import OllamaDocumentEmbedder
+
+doc = Document(content="What do llamas say once you have thanked them? No probllama!")
+document_embedder = OllamaDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+## Calculating embeddings: 100%|██████████| 1/1 [00:02<00:00, 2.82s/it]
+
+## [-0.16412407159805298, -3.8359334468841553, ... ]
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+
+from haystack_integrations.components.embedders.ollama import OllamaDocumentEmbedder
+
+from haystack.components.preprocessors import DocumentCleaner, DocumentSplitter
+
+from haystack.components.converters import PyPDFToDocument
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+embedder = OllamaDocumentEmbedder(
+ model="nomic-embed-text",
+ url="http://localhost:11434",
+) # This is the default model and URL
+
+cleaner = DocumentCleaner()
+splitter = DocumentSplitter()
+file_converter = PyPDFToDocument()
+writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.OVERWRITE)
+
+indexing_pipeline = Pipeline()
+
+## Add components to pipeline
+indexing_pipeline.add_component("embedder", embedder)
+indexing_pipeline.add_component("converter", file_converter)
+indexing_pipeline.add_component("cleaner", cleaner)
+indexing_pipeline.add_component("splitter", splitter)
+indexing_pipeline.add_component("writer", writer)
+
+## Connect components in pipeline
+indexing_pipeline.connect("converter", "cleaner")
+indexing_pipeline.connect("cleaner", "splitter")
+indexing_pipeline.connect("splitter", "embedder")
+indexing_pipeline.connect("embedder", "writer")
+
+## Run Pipeline
+indexing_pipeline.run({"converter": {"sources": ["files/test_pdf_data.pdf"]}})
+
+## Calculating embeddings: 100%|██████████| 115/115
+## {'embedder': {'meta': {'model': 'nomic-embed-text'}}, 'writer': {'documents_written': 115}}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/ollamatextembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/ollamatextembedder.mdx
new file mode 100644
index 0000000000..a99fd0742b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/ollamatextembedder.mdx
@@ -0,0 +1,110 @@
+---
+title: "OllamaTextEmbedder"
+id: ollamatextembedder
+slug: "/ollamatextembedder"
+description: "This component computes the embeddings of a string using embedding models compatible with the Ollama Library."
+---
+
+# OllamaTextEmbedder
+
+This component computes the embeddings of a string using embedding models compatible with the Ollama Library.
+
+`meta`: A dictionary of metadata strings | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | +| **Package name** | `ollama-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers (vectors)
`meta`: A dictionary of metadata strings | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | +| **Package name** | `ollama-haystack` | + +
+
+`OllamaDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses embedding models compatible with the Ollama Library.
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant documents.
+
+## Overview
+
+`OllamaTextEmbedder` should be used to embed a string. For embedding a list of documents, use the [`OllamaDocumentEmbedder`](ollamadocumentembedder.mdx).
+
+The component uses `http://localhost:11434` as the default URL as most available setups (Mac, Linux, Docker) default to port 11434.
+
+### Compatible Models
+
+Unless specified otherwise while initializing this component, the default embedding model is "nomic-embed-text". See other possible pre-built models in Ollama's [library](https://ollama.ai/library). To load your own custom model, follow the [instructions](https://github.com/ollama/ollama/blob/main/docs/modelfile.md) from Ollama.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install ollama-haystack
+```
+
+Make sure that you have a running Ollama model (either through a docker container, or locally hosted). No other configuration is necessary as Ollama has the embedding API built in.
+
+### Embedding Metadata
+
+Most embedded metadata contains information about the model name and type. You can pass [optional arguments](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values), such as temperature, top_p, and others, to the Ollama generation endpoint.
+
+The name of the model used will be automatically appended as part of the metadata. An example payload using the nomic-embed-text model will look like this:
+
+```python
+{"meta": {"model": "nomic-embed-text"}}
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.ollama import OllamaTextEmbedder
+
+embedder = OllamaTextEmbedder()
+
+result = embedder.run(
+ text="What do llamas say once you have thanked them? No probllama!",
+)
+
+print(result["embedding"])
+```
+
+### In a pipeline
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from cohere_haystack.embedders.text_embedder import OllamaTextEmbedder
+from cohere_haystack.embedders.document_embedder import OllamaDocumentEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+document_embedder = OllamaDocumentEmbedder()
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", OllamaTextEmbedder())
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/openaidocumentembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/openaidocumentembedder.mdx
new file mode 100644
index 0000000000..e4cc0c8559
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/openaidocumentembedder.mdx
@@ -0,0 +1,120 @@
+---
+title: "OpenAIDocumentEmbedder"
+id: openaidocumentembedder
+slug: "/openaidocumentembedder"
+description: "OpenAIDocumentEmbedder computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses OpenAI embedding models."
+---
+
+# OpenAIDocumentEmbedder
+
+OpenAIDocumentEmbedder computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses OpenAI embedding models.
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector representing the query is compared with those of the documents to find the most similar or relevant documents.
+
+`meta`: A dictionary of metadata strings | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | +| **Package name** | `ollama-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/openai_document_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+To see the list of compatible OpenAI embedding models, head over to OpenAI [documentation](https://platform.openai.com/docs/guides/embeddings/embedding-models). The default model for `OpenAIDocumentEmbedder` is `text-embedding-ada-002`. You can specify another model with the `model` parameter when initializing this component.
+
+This component should be used to embed a list of documents. To embed a string, use the [OpenAITextEmbedder](openaitextembedder.mdx).
+
+The component uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```
+embedder = OpenAIDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/openai_document_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/openai_text_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+To see the list of compatible OpenAI embedding models, head over to OpenAI [documentation](https://platform.openai.com/docs/guides/embeddings/embedding-models). The default model for `OpenAITextEmbedder` is `text-embedding-ada-002`. You can specify another model with the `model` parameter when initializing this component.
+
+Use `OpenAITextEmbedder` to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [OpenAIDocumentEmbedder](openaidocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+The component uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = OpenAITextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/openai_text_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents enriched with embeddings |
+| **API reference** | [Optimum](/reference/integrations-optimum) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/optimum |
+| **Package name** | `optimum-haystack` |
+
+
+
+## Overview
+
+`OptimumDocumentEmbedder` embeds text strings using models loaded with the [HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library. It uses the [ONNX runtime](https://onnxruntime.ai/) for high-speed inference.
+
+The default model is `sentence-transformers/all-mpnet-base-v2`.
+
+Similarly to other Embedders, this component allows adding prefixes (and suffixes) to include instructions. For more details, refer to the component’s API reference.
+
+There are three useful parameters specific to the Optimum Embedder that you can control with various modes:
+
+- [Pooling](/reference/integrations-optimum#optimumembedderpooling): generate a fixed-sized sentence embedding from a variable-sized sentence embedding
+- [Optimization](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/optimization): apply graph optimization to the model and improve inference speed
+- [Quantization](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/quantization): reduce the computational and memory costs
+
+Find all the available mode details in our Optimum [API Reference](/reference/integrations-optimum).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models through Serverless Inference API or the Inference Endpoints.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+## Usage
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install optimum-haystack
+```
+
+### On its own
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.embedders.optimum import OptimumDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = OptimumDocumentEmbedder(
+ model="sentence-transformers/all-mpnet-base-v2",
+)
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+## [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack import Document
+from haystack_integrations.components.embedders.optimum import (
+ OptimumDocumentEmbedder,
+ OptimumEmbedderPooling,
+ OptimumEmbedderOptimizationConfig,
+ OptimumEmbedderOptimizationMode,
+)
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+embedder = OptimumDocumentEmbedder(
+ model="intfloat/e5-base-v2",
+ normalize_embeddings=True,
+ onnx_execution_provider="CUDAExecutionProvider",
+ optimizer_settings=OptimumEmbedderOptimizationConfig(
+ mode=OptimumEmbedderOptimizationMode.O4,
+ for_gpu=True,
+ ),
+ working_dir="/tmp/optimum",
+ pooling_mode=OptimumEmbedderPooling.MEAN,
+)
+
+pipeline = Pipeline()
+pipeline.add_component("embedder", embedder)
+
+pipeline.run({"embedder": {"documents": documents}})
+
+print(results["embedder"]["embedding"])
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/optimumtextembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/optimumtextembedder.mdx
new file mode 100644
index 0000000000..54847906fe
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/optimumtextembedder.mdx
@@ -0,0 +1,106 @@
+---
+title: "OptimumTextEmbedder"
+id: optimumtextembedder
+slug: "/optimumtextembedder"
+description: "A component to embed text using models loaded with the Hugging Face Optimum library."
+---
+
+# OptimumTextEmbedder
+
+A component to embed text using models loaded with the Hugging Face Optimum library.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers (vectors) |
+| **API reference** | [Optimum](/reference/integrations-optimum) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/optimum |
+| **Package name** | `optimum-haystack` |
+
+
+
+## Overview
+
+`OptimumTextEmbedder` embeds text strings using models loaded with the [HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library. It uses the [ONNX runtime](https://onnxruntime.ai/) for high-speed inference.
+
+The default model is `sentence-transformers/all-mpnet-base-v2`.
+
+Similarly to other Embedders, this component allows adding prefixes (and suffixes) to include instructions. For more details, refer to the component’s API reference.
+
+There are three useful parameters specific to the Optimum Embedder that you can control with various modes:
+
+- [Pooling](/reference/integrations-optimum#optimumembedderpooling): generate a fixed-sized sentence embedding from a variable-sized sentence embedding
+- [Optimization](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/optimization): apply graph optimization to the model and improve inference speed
+- [Quantization](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/quantization): reduce the computational and memory costs
+
+Find all the available mode details in our Optimum [API Reference](/reference/integrations-optimum).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models through Serverless Inference API or the Inference Endpoints.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+## Usage
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install optimum-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.optimum import OptimumTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = OptimumTextEmbedder(model="sentence-transformers/all-mpnet-base-v2")
+
+print(text_embedder.run(text_to_embed))
+
+## {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]}
+```
+
+### In a pipeline
+
+Note that this example requires GPU support to execute.
+
+```python
+from haystack import Pipeline
+
+from haystack_integrations.components.embedders.optimum import (
+ OptimumTextEmbedder,
+ OptimumEmbedderPooling,
+ OptimumEmbedderOptimizationConfig,
+ OptimumEmbedderOptimizationMode,
+)
+
+pipeline = Pipeline()
+embedder = OptimumTextEmbedder(
+ model="intfloat/e5-base-v2",
+ normalize_embeddings=True,
+ onnx_execution_provider="CUDAExecutionProvider",
+ optimizer_settings=OptimumEmbedderOptimizationConfig(
+ mode=OptimumEmbedderOptimizationMode.O4,
+ for_gpu=True,
+ ),
+ working_dir="/tmp/optimum",
+ pooling_mode=OptimumEmbedderPooling.MEAN,
+)
+pipeline.add_component("embedder", embedder)
+
+results = pipeline.run(
+ {
+ "embedder": {
+ "text": "Ex profunditate antique doctrinae, Ad caelos supra semper, Hoc incantamentum evoco, draco apparet, Incantamentum iam transactum est",
+ },
+ },
+)
+
+print(results["embedder"]["embedding"])
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/sentencetransformersdocumentembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/sentencetransformersdocumentembedder.mdx
new file mode 100644
index 0000000000..da9aec9f23
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/sentencetransformersdocumentembedder.mdx
@@ -0,0 +1,143 @@
+---
+title: "SentenceTransformersDocumentEmbedder"
+id: sentencetransformersdocumentembedder
+slug: "/sentencetransformersdocumentembedder"
+description: "SentenceTransformersDocumentEmbedder computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses embedding models compatible with the Sentence Transformers library."
+---
+
+# SentenceTransformersDocumentEmbedder
+
+SentenceTransformersDocumentEmbedder computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses embedding models compatible with the Sentence Transformers library.
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [Embedders](/reference/embedders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/sentence_transformers_document_embedder.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`SentenceTransformersDocumentEmbedder` should be used to embed a list of documents. To embed a string, use the [SentenceTransformersTextEmbedder](sentencetransformerstextembedder.mdx).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models through Serverless Inference API or the Inference Endpoints.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+```python
+document_embedder = SentenceTransformersDocumentEmbedder(
+ token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **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, with a meta field containing an image file path |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [Embedders](/reference/embedders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/image/sentence_transformers_doc_image_embedder.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`SentenceTransformersDocumentImageEmbedder` expects a list of documents containing an image or a PDF file path in a meta field. The meta field can be specified with the `file_path_meta_field` init parameter of this component.
+
+The embedder efficiently loads the images, computes the embeddings using a Sentence Transformers models, and stores each of them in the `embedding` field of the document.
+
+`SentenceTransformersDocumentImageEmbedder` is commonly used in indexing pipelines. At retrieval time, you need to use the same model with a `SentenceTransformersTextEmbedder` to embed the query before using an Embedding Retriever.
+
+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` parameterl: `torch` (default), `onnx`, or `openvino`. ONNX and OpenVINO allow specific speed optimizations; for more information, read the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+### Compatible Models
+
+To be used with this component, the model must be compatible with Sentence Transformers and
+
+able to embed images and text into the same vector space. Compatible models include:
+
+- `sentence-transformers/clip-ViT-B-32` (default)
+- `sentence-transformers/clip-ViT-L-14`
+- `sentence-transformers/clip-ViT-B-16`
+- `sentence-transformers/clip-ViT-B-32-multilingual-v1`
+- `jinaai/jina-embeddings-v4`
+- `jinaai/jina-clip-v1`
+- `jinaai/jina-clip-v2`
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.embedders.image import (
+ SentenceTransformersDocumentImageEmbedder,
+)
+
+embedder = SentenceTransformersDocumentImageEmbedder(
+ model="sentence-transformers/clip-ViT-B-32",
+)
+
+documents = [
+ Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
+ Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}),
+]
+
+result = embedder.run(documents=documents)
+documents_with_embeddings = result["documents"]
+print(documents_with_embeddings)
+
+## [Document(id=...,
+## content='A photo of a cat',
+## meta={'file_path': 'cat.jpg',
+## 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}},
+## embedding=vector of size 512),
+## ...]
+```
+
+### In a pipeline
+
+In this example, we can see an indexing pipeline with 3 components:
+
+- `ImageFileToDocument` Converter that creates empty documents with a reference to an image in the `meta.file_path` field,
+- `SentenceTransformersDocumentImageEmbedder` that loads the images, computes embeddings and stores them in documents,
+- `DocumentWriter` that writes the documents in the `InMemoryDocumentStore`
+
+There is also a multimodal retrieval pipeline, composed by a `SentenceTransformersTextEmbedder` (using the same model as before) and an `InMemoryEmbeddingRetriever`.
+
+```python
+from haystack import Pipeline
+from haystack.components.converters.image import ImageFileToDocument
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack.components.embedders.image import (
+ SentenceTransformersDocumentImageEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+
+## Indexing pipeline
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("image_converter", ImageFileToDocument())
+indexing_pipeline.add_component(
+ "embedder",
+ SentenceTransformersDocumentImageEmbedder(
+ model="sentence-transformers/clip-ViT-B-32",
+ ),
+)
+indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+indexing_pipeline.connect("image_converter", "embedder")
+indexing_pipeline.connect("embedder", "writer")
+
+indexing_pipeline.run(data={"image_converter": {"sources": ["dog.jpg", "hyena.jpeg"]}})
+
+## Multimodal retrieval pipeline
+retrieval_pipeline = Pipeline()
+retrieval_pipeline.add_component(
+ "embedder",
+ SentenceTransformersTextEmbedder(model="sentence-transformers/clip-ViT-B-32"),
+)
+retrieval_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store, top_k=2),
+)
+retrieval_pipeline.connect("embedder", "retriever")
+
+result = retrieval_pipeline.run(data={"text": "man's best friend"})
+print(result)
+
+## {
+## 'retriever': {
+## 'documents': [
+## Document(
+## id=0c96...,
+## meta={
+## 'file_path': 'dog.jpg',
+## 'embedding_source': {
+## 'type': 'image',
+## 'file_path_meta_field': 'file_path'
+## }
+## },
+## score=32.025817780129856
+## ),
+## Document(
+## id=5e76...,
+## meta={
+## 'file_path': 'hyena.jpeg',
+## 'embedding_source': {
+## 'type': 'image',
+## 'file_path_meta_field': 'file_path'
+## }
+## },
+## score=20.648225327085242
+## )
+## ]
+## }
+## }
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Introduction to Multimodality](https://haystack.deepset.ai/cookbook/multimodal_intro)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/sentencetransformerssparsedocumentembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/sentencetransformerssparsedocumentembedder.mdx
new file mode 100644
index 0000000000..02d4426510
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/sentencetransformerssparsedocumentembedder.mdx
@@ -0,0 +1,185 @@
+---
+title: "SentenceTransformersSparseDocumentEmbedder"
+id: sentencetransformerssparsedocumentembedder
+slug: "/sentencetransformerssparsedocumentembedder"
+description: "Use this component to enrich a list of documents with their sparse embeddings using Sentence Transformers models."
+---
+
+# SentenceTransformersSparseDocumentEmbedder
+
+Use this component to enrich a list of documents with their sparse embeddings using Sentence Transformers models.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with sparse embeddings) |
+| **API reference** | [Embedders](/reference/embedders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/sentence_transformers_sparse_document_embedder.py |
+| **Package name** | `haystack-ai` |
+
+
+
+To compute a sparse embedding for a string, use the [`SentenceTransformersSparseTextEmbedder`](sentencetransformerssparsetextembedder.mdx).
+
+## Overview
+
+`SentenceTransformersSparseDocumentEmbedder` computes the sparse embeddings of a list of documents and stores the obtained vectors in the `sparse_embedding` field of each document. It uses sparse embedding models supported by the Sentence Transformers library.
+
+The vectors computed by this component are necessary to perform sparse embedding retrieval on a collection of documents. At retrieval time, the sparse vector representing the query is compared with those of the documents to find the most similar or relevant ones.
+
+### Compatible Models
+
+The default embedding model is [`prithivida/Splade_PP_en_v2`](https://huggingface.co/prithivida/Splade_PP_en_v2). You can specify another model with the `model` parameter when initializing this component.
+
+Compatible models are based on SPLADE (SParse Lexical AnD Expansion), a technique for producing sparse representations for text, where each non-zero value in the embedding is the importance weight of a term in the vocabulary. This approach combines the benefits of learned sparse representations with the efficiency of traditional sparse retrieval methods. For more information, see [our docs](../retrievers.mdx#sparse-embedding-based-retrievers) that explain sparse embedding-based Retrievers further.
+
+You can find compatible SPLADE models on the [Hugging Face Model Hub](https://huggingface.co/models?search=splade).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+```python
+from haystack.utils import Secret
+from haystack.components.embedders import SentenceTransformersSparseDocumentEmbedder
+
+document_embedder = SentenceTransformersSparseDocumentEmbedder(
+ token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a sparse embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `sparse_embedding`: A [`SparseEmbedding`](../../concepts/data-classes.mdx#sparseembedding) object |
+| **API reference** | [Embedders](/reference/embedders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/sentence_transformers_sparse_text_embedder.py |
+| **Package name** | `haystack-ai` |
+
+
+
+For embedding lists of documents, use the [`SentenceTransformersSparseDocumentEmbedder`](sentencetransformerssparsedocumentembedder.mdx), which enriches the document with the computed sparse embedding.
+
+## Overview
+
+`SentenceTransformersSparseTextEmbedder` transforms a string into a sparse vector using sparse embedding models supported by the Sentence Transformers library.
+
+When you perform sparse embedding retrieval, use this component first to transform your query into a sparse vector. Then, the Retriever will use the sparse vector to search for similar or relevant documents.
+
+### Compatible Models
+
+The default embedding model is [`prithivida/Splade_PP_en_v2`](https://huggingface.co/prithivida/Splade_PP_en_v2). You can specify another model with the `model` parameter when initializing this component.
+
+Compatible models are based on SPLADE (SParse Lexical AnD Expansion), a technique for producing sparse representations for text, where each non-zero value in the embedding is the importance weight of a term in the vocabulary. This approach combines the benefits of learned sparse representations with the efficiency of traditional sparse retrieval methods. For more information, see [our docs](../retrievers.mdx#sparse-embedding-based-retrievers) that explain sparse embedding-based Retrievers further.
+
+You can find compatible SPLADE models on the [Hugging Face Model Hub](https://huggingface.co/models?search=splade).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+```python
+from haystack.utils import Secret
+from haystack.components.embedders import SentenceTransformersSparseTextEmbedder
+
+text_embedder = SentenceTransformersSparseTextEmbedder(
+ token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers |
+| **API reference** | [Embedders](/reference/embedders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/sentence_transformers_text_embedder.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+This component should be used to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [SentenceTransformersDocumentEmbedder](sentencetransformersdocumentembedder.mdx), which enriches the document with the computed embedding, known as vector.
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models through Serverless Inference API or the Inference Endpoints.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+```python
+text_embedder = SentenceTransformersTextEmbedder(
+ token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [DocumentWriter](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `model`: The model used through the STACKIT API |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents enriched with embeddings |
+| **API reference** | [STACKIT](/reference/integrations-stackit) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit |
+| **Package name** | `stackit-haystack` |
+
+
+
+## Overview
+
+`STACKITDocumentEmbedder` enables document embedding models served by STACKIT through their API.
+
+### Parameters
+
+To use the `STACKITDocumentEmbedder`, ensure you have set a `STACKIT_API_KEY` as an environment variable. Alternatively, provide the API key as an environment variable with a different name or a token by setting `api_key` and using Haystack’s [secret management](../../concepts/secret-management.mdx).
+
+Set your preferred supported model with the `model` parameter when initializing the component. See the full list of all supported models on the [STACKIT website](https://docs.stackit.cloud/stackit/en/models-licenses-319914532.html).
+
+Optionally, you can change the default `api_base_url`, which is `"https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1"`.
+
+You can pass any text generation parameters valid for the STACKIT Chat Completion API directly to this component with the `generation_kwargs` parameter in the init or run methods.
+
+Then component needs a list of documents as input to operate.
+
+## Usage
+
+Install the `stackit-haystack` package to use the `STACKITDocumentEmbedder` and set an environment variable called `STACKIT_API_KEY` to your API key.
+
+```shell
+pip install stackit-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.stackit import STACKITDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = STACKITDocumentEmbedder(model="intfloat/e5-mistral-7b-instruct")
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+## [0.0215301513671875, 0.01499176025390625, ...]
+```
+
+### In a pipeline
+
+You can also use `STACKITDocumentEmbedder` in your pipeline in a following way.
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.stackit import (
+ STACKITTextEmbedder,
+ STACKITDocumentEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore()
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+document_embedder = STACKITDocumentEmbedder(model="intfloat/e5-mistral-7b-instruct")
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+text_embedder = STACKITTextEmbedder(model="intfloat/e5-mistral-7b-instruct")
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", text_embedder)
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Where does Wolfgang live?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin', score: ...)
+```
+
+You can find more usage examples in the STACKIT integration [repository](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit/examples) and its [integration page](https://haystack.deepset.ai/integrations/stackit).
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/stackittextembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/stackittextembedder.mdx
new file mode 100644
index 0000000000..77ecafc792
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/stackittextembedder.mdx
@@ -0,0 +1,107 @@
+---
+title: "STACKITTextEmbedder"
+id: stackittextembedder
+slug: "/stackittextembedder"
+description: "This component enables text embedding using the STACKIT API."
+---
+
+# STACKITTextEmbedder
+
+This component enables text embedding using the STACKIT API.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `model`: The model used through the STACKIT API |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers |
+| **API reference** | [STACKIT](/reference/integrations-stackit) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit |
+| **Package name** | `stackit-haystack` |
+
+
+
+## Overview
+
+`STACKITTextEmbedder` enables text embedding models served by STACKIT through their API.
+
+### Parameters
+
+To use the `STACKITTextEmbedder`, ensure you have set a `STACKIT_API_KEY` as an environment variable. Alternatively, provide the API key as an environment variable with a different name or a token by setting `api_key` and using Haystack’s [secret management](../../concepts/secret-management.mdx).
+
+Set your preferred supported model with the `model` parameter when initializing the component. See the full list of all supported models on the [STACKIT website](https://docs.stackit.cloud/stackit/en/models-licenses-319914532.html).
+
+Optionally, you can change the default `api_base_url`, which is `"https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1"`.
+
+You can pass any text generation parameters valid for the STACKIT Chat Completion API directly to this component with the `generation_kwargs` parameter in the init or run methods.
+
+The component needs a text input to operate.
+
+## Usage
+
+Install the `stackit-haystack` package to use the `STACKITTextEmbedder` and set an environment variable called `STACKIT_API_KEY` to your API key.
+
+```shell
+pip install stackit-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.stackit import STACKITTextEmbedder
+
+text_embedder = STACKITTextEmbedder(model="intfloat/e5-mistral-7b-instruct")
+
+print(text_embedder.run("I love pizza!"))
+
+## {'embedding': [0.0215301513671875, 0.01499176025390625, ...]}
+```
+
+### In a pipeline
+
+You can also use `STACKITTextEmbedder` in your pipeline.
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.stackit import (
+ STACKITTextEmbedder,
+ STACKITDocumentEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore()
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+document_embedder = STACKITDocumentEmbedder(model="intfloat/e5-mistral-7b-instruct")
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+text_embedder = STACKITTextEmbedder(model="intfloat/e5-mistral-7b-instruct")
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", text_embedder)
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Where does Wolfgang live?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin', score: ...)
+```
+
+You can find more usage examples in the STACKIT integration [repository](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit/examples) and its [integration page](https://haystack.deepset.ai/integrations/stackit).
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vertexaidocumentembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vertexaidocumentembedder.mdx
new file mode 100644
index 0000000000..bc45ab506e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vertexaidocumentembedder.mdx
@@ -0,0 +1,122 @@
+---
+title: "VertexAIDocumentEmbedder"
+id: vertexaidocumentembedder
+slug: "/vertexaidocumentembedder"
+description: "This component computes embeddings for documents using models through VertexAI Embeddings API."
+---
+
+# VertexAIDocumentEmbedder
+
+This component computes embeddings for documents using models through VertexAI Embeddings API.
+
+:::warning[Deprecation Notice]
+
+This integration uses the deprecated google-generativeai SDK, which will lose support after August 2025.
+
+We recommend switching to the new [GoogleGenAIDocumentEmbedder](googlegenaidocumentembedder.mdx) integration instead.
+:::
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [DocumentWriter](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `model`: The model used through the VertexAI Embeddings API |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents enriched with embeddings |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+| **Package name** | `google-vertex-haystack` |
+
+
+
+`VertexAIDocumentEmbedder` enriches the metadata of documents with an embedding of their content. To embed a string, use the [`VertexAITextEmbedder`](vertexaitextembedder.mdx).
+
+To use the `VertexAIDocumentEmbedder`, initialize it with:
+
+- `model`: The supported models are:
+ - "text-embedding-004"
+ - "text-embedding-005"
+ - "textembedding-gecko-multilingual@001"
+ - "text-multilingual-embedding-002"
+ - "text-embedding-large-exp-03-07"
+- `task_type`: "RETRIEVAL_DOCUMENT” is the default. You can find all task types in the official [Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#tasktype).
+
+### Authentication
+
+`VertexAIDocumentEmbedder` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+Install the `google-vertex-haystack` package to use this Embedder:
+
+```shell
+pip install google-vertex-haystack
+```
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.google_vertex import (
+ VertexAIDocumentEmbedder,
+)
+
+doc = Document(content="I love pizza!")
+
+document_embedder = VertexAIDocumentEmbedder(model="text-embedding-005")
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+## [-0.044606007635593414, 0.02857724390923977, -0.03549133986234665,
+```
+
+### In a pipeline
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.google_vertex import (
+ VertexAITextEmbedder,
+)
+from haystack_integrations.components.embedders.google_vertex import (
+ VertexAIDocumentEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+document_embedder = VertexAIDocumentEmbedder(model="text-embedding-005")
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component(
+ "text_embedder",
+ VertexAITextEmbedder(model="text-embedding-005"),
+)
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin')
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vertexaitextembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vertexaitextembedder.mdx
new file mode 100644
index 0000000000..2debb02f9b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vertexaitextembedder.mdx
@@ -0,0 +1,122 @@
+---
+title: "VertexAITextEmbedder"
+id: vertexaitextembedder
+slug: "/vertexaitextembedder"
+description: "This component computes embeddings for text (such as a query) using models through VertexAI Embeddings API."
+---
+
+# VertexAITextEmbedder
+
+This component computes embeddings for text (such as a query) using models through VertexAI Embeddings API.
+
+:::warning[Deprecation Notice]
+
+This integration uses the deprecated google-generativeai SDK, which will lose support after August 2025.
+
+We recommend switching to the new [GoogleGenAITextEmbedder](googlegenaitextembedder.mdx) integration instead.
+:::
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `model`: The model used through the VertexAI Embeddings API |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+| **Package name** | `google-vertex-haystack` |
+
+
+
+## Overview
+
+`VertexAITextEmbedder` embeds a simple string (such as a query) into a vector. For embedding lists of documents, use the [`VertexAIDocumentEmbedder`](vertexaidocumentembedder.mdx) which enriches the document with the computed embedding, also known as vector.
+
+To start using the `VertexAITextEmbedder`, initialize it with:
+
+- `model`: The supported models are:
+ - "text-embedding-004"
+ - "text-embedding-005"
+ - "textembedding-gecko-multilingual@001"
+ - "text-multilingual-embedding-002"
+ - "text-embedding-large-exp-03-07"
+- `task_type`: "RETRIEVAL_QUERY” is the default. You can find all task types in the official [Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#tasktype).
+
+### Authentication
+
+`VertexAITextEmbedder` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+Install the `google-vertex-haystack` package to use this Embedder:
+
+```shell
+pip install google-vertex-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.google_vertex import (
+ VertexAITextEmbedder,
+)
+
+text_to_embed = "I love pizza!"
+
+text_embedder = VertexAITextEmbedder(model="text-embedding-005")
+
+print(text_embedder.run(text_to_embed))
+## {'embedding': [-0.08127457648515701, 0.03399784862995148, -0.05116401985287666, ...]
+```
+
+### In a pipeline
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.google_vertex import (
+ VertexAITextEmbedder,
+)
+from haystack_integrations.components.embedders.google_vertex import (
+ VertexAIDocumentEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+document_embedder = VertexAIDocumentEmbedder(model="text-embedding-005")
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component(
+ "text_embedder",
+ VertexAITextEmbedder(model="text-embedding-005"),
+)
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin')
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vllmdocumentembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vllmdocumentembedder.mdx
new file mode 100644
index 0000000000..3daed1b8a1
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vllmdocumentembedder.mdx
@@ -0,0 +1,176 @@
+---
+title: "VLLMDocumentEmbedder"
+id: vllmdocumentembedder
+slug: "/vllmdocumentembedder"
+description: "This component computes the embeddings of a list of documents using models served with vLLM."
+---
+
+# VLLMDocumentEmbedder
+
+This component computes the embeddings of a list of documents using models served with [vLLM](https://docs.vllm.ai/).
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `model`: The name of the model served by vLLM |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [vLLM](/reference/integrations-vllm) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/vllm |
+| **Package name** | `vllm-haystack` |
+
+
+
+## Overview
+
+[vLLM](https://docs.vllm.ai/) is a high-throughput and memory-efficient inference and serving engine for LLMs. It exposes an OpenAI-compatible HTTP server, which `VLLMDocumentEmbedder` uses to compute embeddings through the Embeddings API.
+
+`VLLMDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the `embedding` field of each document. It expects a vLLM server to be running and accessible at the `api_base_url` parameter (by default, `http://localhost:8000/v1`). To embed a string (such as a query), use the [`VLLMTextEmbedder`](vllmtextembedder.mdx).
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant ones.
+
+If the vLLM server was started with `--api-key`, provide the API key through the `VLLM_API_KEY` environment variable or the `api_key` init parameter using Haystack's [Secret](../../concepts/secret-management.mdx) API.
+
+### Compatible models
+
+vLLM supports a range of embedding models. Check the [vLLM pooling models docs](https://docs.vllm.ai/en/stable/models/pooling_models) for the list of supported architectures and models.
+
+### vLLM-specific parameters
+
+You can pass vLLM-specific parameters through the `extra_parameters` dictionary. These are forwarded as `extra_body` to the OpenAI-compatible embeddings endpoint. Use this to pass parameters that are not part of the standard OpenAI Embeddings API, such as `truncate_prompt_tokens` or `truncation_side`. See the [vLLM Embeddings API docs](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#openai-compatible-embeddings-api) for details.
+
+```python
+embedder = VLLMDocumentEmbedder(
+ model="google/embeddinggemma-300m",
+ extra_parameters={"truncate_prompt_tokens": 256, "truncation_side": "right"},
+)
+```
+
+### Matryoshka embeddings
+
+If the model was trained with Matryoshka Representation Learning, you can reduce the dimensionality of the output vector through the `dimensions` parameter. See the [vLLM Matryoshka docs](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#matryoshka-embeddings) for details.
+
+### Batching and failure handling
+
+`VLLMDocumentEmbedder` encodes documents in batches. Use `batch_size` (default `32`) to control how many documents are sent in a single request to the vLLM server, and `progress_bar` to toggle the progress indicator.
+
+By default (`raise_on_failure=False`), failed embedding requests are logged and processing continues with the remaining documents. Set `raise_on_failure=True` to raise an exception instead.
+
+### Instructions
+
+Some embedding models require prepending the document text with an instruction to work better for retrieval. For example, if you use [intfloat/e5-large-v2](https://huggingface.co/intfloat/e5-large-v2), you should prefix your document with the following instruction: "passage:".
+
+This is how it works with `VLLMDocumentEmbedder`:
+
+```python
+instruction = "passage:"
+embedder = VLLMDocumentEmbedder(
+ model="intfloat/e5-large-v2",
+ prefix=instruction,
+)
+```
+
+### Embedding metadata
+
+Documents often come with a set of metadata. If they are distinctive and semantically meaningful, you can embed them along with the text of the document to improve retrieval. Pass the relevant fields through `meta_fields_to_embed`; they are concatenated to the document text using `embedding_separator` (a newline by default):
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.vllm import VLLMDocumentEmbedder
+
+doc = Document(content="some text", meta={"title": "relevant title", "page_number": 18})
+
+embedder = VLLMDocumentEmbedder(
+ model="google/embeddinggemma-300m",
+ meta_fields_to_embed=["title"],
+)
+
+docs_with_embeddings = embedder.run(documents=[doc])["documents"]
+```
+
+## Usage
+
+Install the `vllm-haystack` package to use the `VLLMDocumentEmbedder`:
+
+```shell
+pip install vllm-haystack
+```
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server with an embedding model:
+
+```bash
+vllm serve google/embeddinggemma-300m
+```
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.vllm import VLLMDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = VLLMDocumentEmbedder(model="google/embeddinggemma-300m")
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+## [-0.0215301513671875, 0.01499176025390625, ...]
+```
+
+### In a pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack_integrations.components.embedders.vllm import (
+ VLLMDocumentEmbedder,
+ VLLMTextEmbedder,
+)
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+document_embedder = VLLMDocumentEmbedder(model="google/embeddinggemma-300m")
+writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.OVERWRITE)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("document_embedder", document_embedder)
+indexing_pipeline.add_component("writer", writer)
+indexing_pipeline.connect("document_embedder", "writer")
+
+indexing_pipeline.run({"document_embedder": {"documents": documents}})
+
+query_pipeline = Pipeline()
+query_pipeline.add_component(
+ "text_embedder",
+ VLLMTextEmbedder(model="google/embeddinggemma-300m"),
+)
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin', score: ...)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vllmtextembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vllmtextembedder.mdx
new file mode 100644
index 0000000000..f000430dbe
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/vllmtextembedder.mdx
@@ -0,0 +1,139 @@
+---
+title: "VLLMTextEmbedder"
+id: vllmtextembedder
+slug: "/vllmtextembedder"
+description: "This component computes the embeddings of a string using models served with vLLM."
+---
+
+# VLLMTextEmbedder
+
+This component computes the embeddings of a string using models served with [vLLM](https://docs.vllm.ai/).
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `model`: The name of the model served by vLLM |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A vector (list of float numbers) |
+| **API reference** | [vLLM](/reference/integrations-vllm) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/vllm |
+| **Package name** | `vllm-haystack` |
+
+
+
+## Overview
+
+[vLLM](https://docs.vllm.ai/) is a high-throughput and memory-efficient inference and serving engine for LLMs. It exposes an OpenAI-compatible HTTP server, which `VLLMTextEmbedder` uses to compute embeddings through the Embeddings API.
+
+`VLLMTextEmbedder` expects a vLLM server to be running and accessible at the `api_base_url` parameter (by default, `http://localhost:8000/v1`). Use this component to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [`VLLMDocumentEmbedder`](vllmdocumentembedder.mdx).
+
+When you perform embedding retrieval, use this component first to transform your query into a vector. Then, the embedding Retriever will use the vector to search for similar or relevant documents.
+
+If the vLLM server was started with `--api-key`, provide the API key through the `VLLM_API_KEY` environment variable or the `api_key` init parameter using Haystack's [Secret](../../concepts/secret-management.mdx) API.
+
+### Compatible models
+
+vLLM supports a range of embedding models. Check the [vLLM pooling models docs](https://docs.vllm.ai/en/stable/models/pooling_models) for the list of supported architectures and models.
+
+### vLLM-specific parameters
+
+You can pass vLLM-specific parameters through the `extra_parameters` dictionary. These are forwarded as `extra_body` to the OpenAI-compatible embeddings endpoint. Use this to pass parameters that are not part of the standard OpenAI Embeddings API, such as `truncate_prompt_tokens` or `truncation_side`. See the [vLLM Embeddings API docs](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#openai-compatible-embeddings-api) for details.
+
+```python
+embedder = VLLMTextEmbedder(
+ model="google/embeddinggemma-300m",
+ extra_parameters={"truncate_prompt_tokens": 256, "truncation_side": "right"},
+)
+```
+
+### Matryoshka embeddings
+
+If the model was trained with Matryoshka Representation Learning, you can reduce the dimensionality of the output vector through the `dimensions` parameter. See the [vLLM Matryoshka docs](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#matryoshka-embeddings) for details.
+
+### Instructions
+
+Some embedding models require prepending the text with an instruction to work better for retrieval. For example, if you use [BAAI/bge-large-en-v1.5](https://huggingface.co/BAAI/bge-large-en-v1.5#model-list), you should prefix your query with the following instruction: "Represent this sentence for searching relevant passages:".
+
+This is how it works with `VLLMTextEmbedder`:
+
+```python
+instruction = "Represent this sentence for searching relevant passages:"
+embedder = VLLMTextEmbedder(
+ model="BAAI/bge-large-en-v1.5",
+ prefix=instruction,
+)
+```
+
+## Usage
+
+Install the `vllm-haystack` package to use the `VLLMTextEmbedder`:
+
+```shell
+pip install vllm-haystack
+```
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server with an embedding model:
+
+```bash
+vllm serve google/embeddinggemma-300m
+```
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.vllm import VLLMTextEmbedder
+
+text_embedder = VLLMTextEmbedder(model="google/embeddinggemma-300m")
+print(text_embedder.run("I love pizza!"))
+
+## {'embedding': [-0.0215301513671875, 0.01499176025390625, ...], 'meta': {...}}
+```
+
+### In a pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.vllm import (
+ VLLMDocumentEmbedder,
+ VLLMTextEmbedder,
+)
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+document_embedder = VLLMDocumentEmbedder(model="google/embeddinggemma-300m")
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component(
+ "text_embedder",
+ VLLMTextEmbedder(model="google/embeddinggemma-300m"),
+)
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin', score: ...)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/watsonxdocumentembedder.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/watsonxdocumentembedder.mdx
new file mode 100644
index 0000000000..c03d268a27
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/embedders/watsonxdocumentembedder.mdx
@@ -0,0 +1,147 @@
+---
+title: "WatsonxDocumentEmbedder"
+id: watsonxdocumentembedder
+slug: "/watsonxdocumentembedder"
+description: "The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant documents."
+---
+
+# WatsonxDocumentEmbedder
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The IBM Cloud API key. Can be set with `WATSONX_API_KEY` env var.
`project_id`: The IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `documents`: A list of documents to be embedded | +| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata strings | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | +| **Package name** | `watsonx-haystack` | + +
+
+## Overview
+
+`WatsonxDocumentEmbedder` enriches the metadata of documents with an embedding of their content. To embed a string, you should use the [`WatsonxTextEmbedder`](watsonxtextembedder.mdx).
+
+The component supports IBM watsonx.ai embedding models such as `ibm/slate-30m-english-rtrvr` and similar. The default model is `ibm/slate-30m-english-rtrvr`. This list of all supported models can be found in IBM's [model documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-embed.html?context=wx).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install watsonx-haystack
+```
+
+The component uses `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` environment variables by default. Otherwise, you can pass API credentials at initialization with `api_key` and `project_id`:
+
+```python
+embedder = WatsonxDocumentEmbedder(
+ api_key=Secret.from_token("`project_id`: The IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `documents`: A list of documents to be embedded | +| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata strings | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | +| **Package name** | `watsonx-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: An IBM Cloud API key. Can be set with `WATSONX_API_KEY` env var.
`project_id`: An IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | +| **Package name** | `watsonx-haystack` | + +
+
+## Overview
+
+To see the list of compatible IBM watsonx.ai embedding models, head over to IBM [documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-embed.html?context=wx). The default model for `WatsonxTextEmbedder` is `ibm/slate-30m-english-rtrvr`. You can specify another model with the `model` parameter when initializing this component.
+
+Use `WatsonxTextEmbedder` to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [`WatsonxDocumentEmbedder`](watsonxdocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+The component uses `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` environment variables by default. Otherwise, you can pass API credentials at initialization with `api_key` and `project_id`:
+
+```python
+embedder = WatsonxTextEmbedder(
+ api_key=Secret.from_token("`project_id`: An IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | +| **Package name** | `watsonx-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `ground_truth_answers`: A list of strings containing the ground truth answers
`predicted_answers`: A list of strings containing the predicted answers to be evaluated | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 representing the proportion of questions in which any predicted answer matched the ground truth answers
- `individual_scores`: A list of 0s and 1s, where 1 means that the predicted answer matched one of the ground truths | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/answer_exact_match.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+You can use the `AnswerExactMatchEvaluator` component to evaluate answers predicted by a Haystack pipeline, such as an extractive question answering pipeline, against ground truth labels. As the `AnswerExactMatchEvaluator` checks whether a predicted answer exactly matches the ground truth answer. It is not suited to evaluate answers generated by LLMs, for example, in a RAG pipeline. Use `FaithfulnessEvaluator` or `SASEvaluator` instead.
+
+To initialize an `AnswerExactMatchEvaluator`, there are no parameters required.
+
+Note that only _one_ predicted answer is compared to _one_ ground truth answer at a time. The component does not support multiple ground truth answers for the same question or multiple answers predicted for the same question.
+
+## Usage
+
+### On its own
+
+Below is an example of using an `AnswerExactMatchEvaluator` component to evaluate two answers and compare them to ground truth answers.
+
+```python
+from haystack.components.evaluators import AnswerExactMatchEvaluator
+
+evaluator = AnswerExactMatchEvaluator()
+result = evaluator.run(
+ ground_truth_answers=["Berlin", "Paris"],
+ predicted_answers=["Berlin", "Lyon"],
+)
+
+print(result["individual_scores"])
+## [1, 0]
+print(result["score"])
+## 0.5
+```
+
+### In a pipeline
+
+Below is an example where we use an `AnswerExactMatchEvaluator` and a `SASEvaluator` in a pipeline to evaluate two answers and compare them to ground truth answers. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Pipeline
+from haystack.components.evaluators import AnswerExactMatchEvaluator
+from haystack.components.evaluators import SASEvaluator
+
+pipeline = Pipeline()
+em_evaluator = AnswerExactMatchEvaluator()
+sas_evaluator = SASEvaluator()
+pipeline.add_component("em_evaluator", em_evaluator)
+pipeline.add_component("sas_evaluator", sas_evaluator)
+
+ground_truth_answers = ["Berlin", "Paris"]
+predicted_answers = ["Berlin", "Lyon"]
+
+result = pipeline.run(
+ {
+ "em_evaluator": {
+ "ground_truth_answers": ground_truth_answers,
+ "predicted_answers": predicted_answers,
+ },
+ "sas_evaluator": {
+ "ground_truth_answers": ground_truth_answers,
+ "predicted_answers": predicted_answers,
+ },
+ },
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1, 0]
+## [array([[0.99999994]], dtype=float32), array([[0.51747656]], dtype=float32)]
+
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 0.5
+## 0.7587383
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/contextrelevanceevaluator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/contextrelevanceevaluator.mdx
new file mode 100644
index 0000000000..aadfbf4e54
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/contextrelevanceevaluator.mdx
@@ -0,0 +1,137 @@
+---
+title: "ContextRelevanceEvaluator"
+id: contextrelevanceevaluator
+slug: "/contextrelevanceevaluator"
+description: "The `ContextRelevanceEvaluator` uses an LLM to evaluate whether contexts are relevant to a question. It does not require ground truth labels."
+---
+
+# ContextRelevanceEvaluator
+
+The `ContextRelevanceEvaluator` uses an LLM to evaluate whether contexts are relevant to a question. It does not require ground truth labels.
+
+`predicted_answers`: A list of strings containing the predicted answers to be evaluated | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 representing the proportion of questions in which any predicted answer matched the ground truth answers
- `individual_scores`: A list of 0s and 1s, where 1 means that the predicted answer matched one of the ground truths | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/answer_exact_match.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `questions`: A list of questions
`contexts`: A list of a list of contexts, which are the contents of documents. This accounts for one list of contexts per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean average precision
- `individual_scores`: A list of the individual average precision scores ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents
- `results`: A list of dictionaries with keys `statements` and `statement_scores`. They contain the statements extracted by an LLM from each context and the corresponding context relevance scores per statement, which are either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/context_relevance.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+You can use the `ContextRelevanceEvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG pipeline, without ground truth labels. The component breaks up the context into multiple statements and checks whether each statement is relevant for answering a question. The final score for the context relevance is a number from 0.0 to 1.0 and represents the proportion of statements that are relevant to the provided question.
+
+### Parameters
+
+The default model for this Evaluator is `gpt-4o-mini`. You can override the model using the `chat_generator` parameter during initialization. This needs to be a Chat Generator instance configured to return a JSON object. For example, when using the [`OpenAIChatGenerator`](../generators/openaichatgenerator.mdx), you should pass `{"response_format": {"type": "json_object"}}` in its `generation_kwargs`.
+
+If you are not initializing the Evaluator with your own Chat Generator other than OpenAI, a valid OpenAI API key must be set as an `OPENAI_API_KEY` environment variable. For details, see our [documentation page on secret management](../../concepts/secret-management.mdx).
+
+Two optional initialization parameters are:
+
+- `raise_on_failure`: If True, raise an exception on an unsuccessful API call.
+- `progress_bar`: Whether to show a progress bar during the evaluation.
+
+`ContextRelevanceEvaluator` has an optional `examples` parameter that can be used to pass few-shot examples conforming to the expected input and output format of `ContextRelevanceEvaluator`. These examples are included in the prompt that is sent to the LLM. Examples, therefore, increase the number of tokens of the prompt and make each request more costly. Adding examples is helpful if you want to improve the quality of the evaluation at the cost of more tokens.
+
+Each example must be a dictionary with keys `inputs` and `outputs`.
+`inputs` must be a dictionary with keys `questions` and `contexts`.
+`outputs` must be a dictionary with `statements` and `statement_scores`.
+Here is the expected format:
+
+```python
+[
+ {
+ "inputs": {
+ "questions": "What is the capital of Italy?",
+ "contexts": ["Rome is the capital of Italy."],
+ },
+ "outputs": {
+ "statements": [
+ "Rome is the capital of Italy.",
+ "Rome has more than 4 million inhabitants.",
+ ],
+ "statement_scores": [1, 0],
+ },
+ },
+]
+```
+
+## Usage
+
+### On its own
+
+Below is an example where we use a `ContextRelevanceEvaluator` component to evaluate a response generated based on a provided question and context. The `ContextRelevanceEvaluator` returns a score of 1.0 because it detects one statement in the context, which is relevant to the question.
+
+```python
+from haystack.components.evaluators import ContextRelevanceEvaluator
+
+questions = ["Who created the Python language?"]
+contexts = [
+ [
+ "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language. Its design philosophy emphasizes code readability, and its language constructs aim to help programmers write clear, logical code for both small and large-scale software projects.",
+ ],
+]
+
+evaluator = ContextRelevanceEvaluator()
+result = evaluator.run(questions=questions, contexts=contexts)
+print(result["score"])
+## 1.0
+print(result["individual_scores"])
+## [1.0]
+print(result["results"])
+## [{'statements': ['Python, created by Guido van Rossum in the late 1980s.'], 'statement_scores': [1], 'score': 1.0}]
+```
+
+### In a pipeline
+
+Below is an example where we use a `FaithfulnessEvaluator` and a `ContextRelevanceEvaluator` in a pipeline to evaluate responses and contexts (the content of documents) received by a RAG pipeline based on provided questions. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Pipeline
+from haystack.components.evaluators import (
+ ContextRelevanceEvaluator,
+ FaithfulnessEvaluator,
+)
+
+pipeline = Pipeline()
+context_relevance_evaluator = ContextRelevanceEvaluator()
+faithfulness_evaluator = FaithfulnessEvaluator()
+pipeline.add_component("context_relevance_evaluator", context_relevance_evaluator)
+pipeline.add_component("faithfulness_evaluator", faithfulness_evaluator)
+
+questions = ["Who created the Python language?"]
+contexts = [
+ [
+ "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language. Its design philosophy emphasizes code readability, and its language constructs aim to help programmers write clear, logical code for both small and large-scale software projects.",
+ ],
+]
+responses = [
+ "Python is a high-level general-purpose programming language that was created by George Lucas.",
+]
+
+result = pipeline.run(
+ {
+ "context_relevance_evaluator": {"questions": questions, "contexts": contexts},
+ "faithfulness_evaluator": {
+ "questions": questions,
+ "contexts": contexts,
+ "responses": responses,
+ },
+ },
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1.0]
+## [0.5]
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 1.0
+## 0.5
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/deepevalevaluator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/deepevalevaluator.mdx
new file mode 100644
index 0000000000..14e850487c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/deepevalevaluator.mdx
@@ -0,0 +1,106 @@
+---
+title: "DeepEvalEvaluator"
+id: deepevalevaluator
+slug: "/deepevalevaluator"
+description: "The DeepEvalEvaluator evaluates Haystack pipelines using LLM-based metrics. It supports metrics like answer relevancy, faithfulness, contextual relevance, and more."
+---
+
+# DeepEvalEvaluator
+
+The DeepEvalEvaluator evaluates Haystack pipelines using LLM-based metrics. It supports metrics like answer relevancy, faithfulness, contextual relevance, and more.
+
+`contexts`: A list of a list of contexts, which are the contents of documents. This accounts for one list of contexts per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean average precision
- `individual_scores`: A list of the individual average precision scores ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents
- `results`: A list of dictionaries with keys `statements` and `statement_scores`. They contain the statements extracted by an LLM from each context and the corresponding context relevance scores per statement, which are either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/context_relevance.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `metric`: One of the DeepEval metrics to use for evaluation |
+| **Mandatory run variables** | `**inputs`: A keyword arguments dictionary containing the expected inputs. The expected inputs will change based on the metric you are evaluating. See below for more details. |
+| **Output variables** | `results`: A nested list of metric results. There can be one or more results, depending on the metric. Each result is a dictionary containing:
- `name` - The name of the metric
- `score` - The score of the metric
- `explanation` - An optional explanation of the score | +| **API reference** | [DeepEval](/reference/integrations-deepeval) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/deepeval | +| **Package name** | `deepeval-haystack` | + +
+
+DeepEval is an evaluation framework that provides a number of LLM-based evaluation metrics. You can use the `DeepEvalEvaluator` component to evaluate a Haystack pipeline, such as a retrieval-augmented generated pipeline, against one of the metrics provided by DeepEval.
+
+## Supported Metrics
+
+DeepEval supports a number of metrics, which we expose through the [DeepEval metric enumeration.](/reference/integrations-deepeval#deepevalmetric) [`DeepEvalEvaluator`](/reference/integrations-deepeval#deepevalevaluator) in Haystack supports the metrics listed below with the expected `metric_params` while initializing the Evaluator. Many metrics use OpenAI models and require you to set an environment variable `OPENAI_API_KEY`. For a complete guide on these metrics, visit the [DeepEval documentation](https://docs.confident-ai.com/docs/getting-started).
+
+- `name` - The name of the metric
- `score` - The score of the metric
- `explanation` - An optional explanation of the score | +| **API reference** | [DeepEval](/reference/integrations-deepeval) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/deepeval | +| **Package name** | `deepeval-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `metric`: One of the DeepEval metrics to use for evaluation |
+| **Mandatory run variables** | “\*\*inputs”: A keyword arguments dictionary containing the expected inputs. The expected inputs will change based on the metric you are evaluating. See below for more details. |
+| **Output variables** | `results`: A nested list of metric results. There can be one or more results, depending on the metric. Each result is a dictionary containing:
- `name` - The name of the metric
- `score` - The score of the metric
- `explanation` - An optional explanation of the score | +| **API reference** | [DeepEval](/reference/integrations-deepeval) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/deepeval | +| **Package name** | `deepeval-haystack` | + +
+
+## Parameters Overview
+
+To initialize a `DeepEvalEvaluator`, you need to provide the following parameters :
+
+- `metric`: A `DeepEvalMetric`.
+- `metric_params`: Optionally, if the metric calls for any additional parameters, you should provide them here.
+
+## Usage
+
+To use the `DeepEvalEvaluator`, you first need to install the integration:
+
+```bash
+pip install deepeval-haystack
+```
+
+To use the `DeepEvalEvaluator` you need to follow these steps:
+
+1. Initialize the `DeepEvalEvaluator` while providing the correct `metric_params` for the metric you are using.
+2. Run the `DeepEvalEvaluator` on its own or in a pipeline by providing the expected input for the metric you are using.
+
+### Examples
+
+**Evaluate Faithfulness**
+
+To create a faithfulness evaluation pipeline:
+
+```python
+from haystack import Pipeline
+from haystack_integrations.components.evaluators.deepeval import (
+ DeepEvalEvaluator,
+ DeepEvalMetric,
+)
+
+pipeline = Pipeline()
+evaluator = DeepEvalEvaluator(
+ metric=DeepEvalMetric.FAITHFULNESS,
+ metric_params={"model": "gpt-4"},
+)
+pipeline.add_component("evaluator", evaluator)
+```
+
+To run the evaluation pipeline, you should have the _expected inputs_ for the metric ready at hand. This metric expects a list of `questions` and `contexts`. These should come from the results of the pipeline you want to evaluate.
+
+```python
+results = pipeline.run(
+ {
+ "evaluator": {
+ "questions": [
+ "When was the Rhodes Statue built?",
+ "Where is the Pyramid of Giza?",
+ ],
+ "contexts": [["Context for question 1"], ["Context for question 2"]],
+ "responses": ["Response for question 1", "response for question 2"],
+ },
+ },
+)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [RAG Pipeline Evaluation Using DeepEval](https://haystack.deepset.ai/cookbook/rag_eval_deep_eval)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentmapevaluator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentmapevaluator.mdx
new file mode 100644
index 0000000000..99848a373c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentmapevaluator.mdx
@@ -0,0 +1,110 @@
+---
+title: "DocumentMAPEvaluator"
+id: documentmapevaluator
+slug: "/documentmapevaluator"
+description: "The `DocumentMAPEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks to what extent the list of retrieved documents contains only relevant documents as specified in the ground truth labels or also non-relevant documents. This metric is called mean average precision (MAP)."
+---
+
+# DocumentMAPEvaluator
+
+The `DocumentMAPEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks to what extent the list of retrieved documents contains only relevant documents as specified in the ground truth labels or also non-relevant documents. This metric is called mean average precision (MAP).
+
+- `name` - The name of the metric
- `score` - The score of the metric
- `explanation` - An optional explanation of the score | +| **API reference** | [DeepEval](/reference/integrations-deepeval) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/deepeval | +| **Package name** | `deepeval-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `ground_truth_documents`: A list of a list of ground truth documents. This accounts for one list of ground truth documents per question.
`retrieved_documents`: A list of a list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean average precision
- `individual_scores`: A list of the individual average precision scores ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_map.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+You can use the `DocumentMAPEvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG pipeline, against ground truth labels. A higher mean average precision is better, indicating that the list of retrieved documents contains many relevant documents and only a few non-relevant documents or none at all.
+
+To initialize a `DocumentMAPEvaluator`, there are no parameters required.
+
+## Usage
+
+### On its own
+
+Below is an example where we use a `DocumentMAPEvaluator` component to evaluate documents retrieved for two queries. For the first query, there is one ground truth document and one retrieved document. For the second query, there are two ground truth documents and three retrieved documents.
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentMAPEvaluator
+
+evaluator = DocumentMAPEvaluator()
+result = evaluator.run(
+ ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+ ],
+ retrieved_documents=[
+ [Document(content="France")],
+ [
+ Document(content="9th century"),
+ Document(content="10th century"),
+ Document(content="9th"),
+ ],
+ ],
+)
+print(result["individual_scores"])
+## [1.0, 0.8333333333333333]
+print(result["score"])
+## 0.9166666666666666
+```
+
+### In a pipeline
+
+Below is an example where we use a `DocumentMAPEvaluator` and a `DocumentMRREvaluator` in a pipeline to evaluate two answers and compare them to ground truth answers. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.evaluators import DocumentMRREvaluator, DocumentMAPEvaluator
+
+pipeline = Pipeline()
+mrr_evaluator = DocumentMRREvaluator()
+map_evaluator = DocumentMAPEvaluator()
+pipeline.add_component("mrr_evaluator", mrr_evaluator)
+pipeline.add_component("map_evaluator", map_evaluator)
+
+ground_truth_documents = [
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+]
+retrieved_documents = [
+ [Document(content="France")],
+ [
+ Document(content="9th century"),
+ Document(content="10th century"),
+ Document(content="9th"),
+ ],
+]
+
+result = pipeline.run(
+ {
+ "mrr_evaluator": {
+ "ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents,
+ },
+ "map_evaluator": {
+ "ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents,
+ },
+ },
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1.0, 1.0]
+## [1.0, 0.8333333333333333]
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 1.0
+## 0.9166666666666666
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentmrrevaluator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentmrrevaluator.mdx
new file mode 100644
index 0000000000..3b5b4df625
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentmrrevaluator.mdx
@@ -0,0 +1,110 @@
+---
+title: "DocumentMRREvaluator"
+id: documentmrrevaluator
+slug: "/documentmrrevaluator"
+description: "The `DocumentMRREvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks at what rank ground truth documents appear in the list of retrieved documents. This metric is called mean reciprocal rank (MRR)."
+---
+
+# DocumentMRREvaluator
+
+The `DocumentMRREvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks at what rank ground truth documents appear in the list of retrieved documents. This metric is called mean reciprocal rank (MRR).
+
+`retrieved_documents`: A list of a list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean average precision
- `individual_scores`: A list of the individual average precision scores ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_map.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `ground_truth_documents`: A list containing another list of ground truth documents. This accounts for one list of ground truth documents per question.
`retrieved_documents`: A list containing another list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean reciprocal rank
- `individual_scores`: A list of the individual reciprocal ranks ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_mrr.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+You can use the `DocumentMRREvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG pipeline, against ground truth labels. A higher mean reciprocal rank is better and indicates that relevant documents appear at an earlier position in the list of retrieved documents.
+
+To initialize a `DocumentMRREvaluator`, there are no parameters required.
+
+## Usage
+
+### On its own
+
+Below is an example where we use a `DocumentMRREvaluator` component to evaluate documents retrieved for two queries. For the first query, there is one ground truth document and one retrieved document. For the second query, there are two ground truth documents and three retrieved documents.
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentMRREvaluator
+
+evaluator = DocumentMRREvaluator()
+result = evaluator.run(
+ ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+ ],
+ retrieved_documents=[
+ [Document(content="France")],
+ [
+ Document(content="9th century"),
+ Document(content="10th century"),
+ Document(content="9th"),
+ ],
+ ],
+)
+print(result["individual_scores"])
+## [1.0, 1.0]
+print(result["score"])
+## 1.0
+```
+
+### In a pipeline
+
+Below is an example where we use a `DocumentRecallEvaluator` and a `DocumentMRREvaluator` in a pipeline to evaluate two answers and compare them to ground truth answers. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.evaluators import DocumentMRREvaluator, DocumentRecallEvaluator
+
+pipeline = Pipeline()
+mrr_evaluator = DocumentMRREvaluator()
+recall_evaluator = DocumentRecallEvaluator()
+pipeline.add_component("mrr_evaluator", mrr_evaluator)
+pipeline.add_component("recall_evaluator", recall_evaluator)
+
+ground_truth_documents = [
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+]
+retrieved_documents = [
+ [Document(content="France")],
+ [
+ Document(content="9th century"),
+ Document(content="10th century"),
+ Document(content="9th"),
+ ],
+]
+
+result = pipeline.run(
+ {
+ "mrr_evaluator": {
+ "ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents,
+ },
+ "recall_evaluator": {
+ "ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents,
+ },
+ },
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1.0, 1.0]
+## [1.0, 1.0]
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 1.0
+## 1.0
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentndcgevaluator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentndcgevaluator.mdx
new file mode 100644
index 0000000000..be8298f7f7
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentndcgevaluator.mdx
@@ -0,0 +1,102 @@
+---
+title: "DocumentNDCGEvaluator"
+id: documentndcgevaluator
+slug: "/documentndcgevaluator"
+description: "The `DocumentNDCGEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks at what rank ground truth documents appear in the list of retrieved documents. This metric is called normalized discounted cumulative gain (NDCG)."
+---
+
+# DocumentNDCGEvaluator
+
+The `DocumentNDCGEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks at what rank ground truth documents appear in the list of retrieved documents. This metric is called normalized discounted cumulative gain (NDCG).
+
+`retrieved_documents`: A list containing another list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean reciprocal rank
- `individual_scores`: A list of the individual reciprocal ranks ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_mrr.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `ground_truth_documents`: A list containing another list of ground truth documents, one list per question
`retrieved_documents`: A list containing another list of retrieved documents, one list per question | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the NDCG
- `individual_scores`: A list of individual NDCG values ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_ndcg.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+You can use the `DocumentNDCGEvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG pipeline, against ground truth labels. A higher NDCG is better and indicates that relevant documents appear at an earlier position in the list of retrieved documents.
+
+If the ground truth documents have scores, a higher NDCG indicates that documents with a higher score appear at an earlier position in the list of retrieved documents. If the ground truth documents have no scores, binary relevance is assumed, meaning that all ground truth documents are equally relevant, and the order in which they are in the list of retrieved documents does not matter for the NDCG.
+
+No parameters are required to initialize a `DocumentNDCGEvaluator`.
+
+## Usage
+
+### On its own
+
+Below is an example where we use the `DocumentNDCGEvaluator` to evaluate documents retrieved for a query. There are two ground truth documents and three retrieved documents. All ground truth documents are retrieved, but one non-relevant document is ranked higher than one of the ground truth documents, which lowers the NDCG score.
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentNDCGEvaluator
+
+evaluator = DocumentNDCGEvaluator()
+result = evaluator.run(
+ ground_truth_documents=[
+ [Document(content="France", score=1.0), Document(content="Paris", score=0.5)],
+ ],
+ retrieved_documents=[
+ [
+ Document(content="France"),
+ Document(content="Germany"),
+ Document(content="Paris"),
+ ],
+ ],
+)
+print(result["individual_scores"])
+## [0.8869]
+print(result["score"])
+## 0.8869
+```
+
+### In a pipeline
+
+Below is an example of using a `DocumentNDCGEvaluator` and `DocumentMRREvaluator` in a pipeline to evaluate retrieved documents and compare them to ground truth documents. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.evaluators import DocumentMRREvaluator, DocumentNDCGEvaluator
+
+pipeline = Pipeline()
+pipeline.add_component("ndcg_evaluator", DocumentNDCGEvaluator())
+pipeline.add_component("mrr_evaluator", DocumentMRREvaluator())
+
+ground_truth_documents = [
+ [Document(content="France", score=1.0), Document(content="Paris", score=0.5)],
+]
+retrieved_documents = [
+ [
+ Document(content="France"),
+ Document(content="Germany"),
+ Document(content="Paris"),
+ ],
+]
+
+result = pipeline.run(
+ {
+ "ndcg_evaluator": {
+ "ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents,
+ },
+ "mrr_evaluator": {
+ "ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents,
+ },
+ },
+)
+
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 0.9502
+## 1.0
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentrecallevaluator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentrecallevaluator.mdx
new file mode 100644
index 0000000000..3b9d1f8dc9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/documentrecallevaluator.mdx
@@ -0,0 +1,115 @@
+---
+title: "DocumentRecallEvaluator"
+id: documentrecallevaluator
+slug: "/documentrecallevaluator"
+description: "The `DocumentRecallEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks how many of the ground truth documents were retrieved. This metric is called recall."
+---
+
+# DocumentRecallEvaluator
+
+The `DocumentRecallEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks how many of the ground truth documents were retrieved. This metric is called recall.
+
+`retrieved_documents`: A list containing another list of retrieved documents, one list per question | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the NDCG
- `individual_scores`: A list of individual NDCG values ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_ndcg.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `ground_truth_documents`: A list of a list of ground truth documents. This accounts for one list of ground truth documents per question.
`retrieved_documents`: A list of a list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean recall score over all inputs
- `individual_scores`: A list of the individual recall scores ranging from 0.0 to 1.0 of each input pair of a list of retrieved documents and a list of ground truth documents. If the mode is set to single_hit, each individual score is either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_recall.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+You can use the `DocumentRecallEvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG Pipeline, against ground truth labels.
+
+When initializing a `DocumentRecallEvaluator`, you can set the `mode` parameter to
+`RecallMode.SINGLE_HIT` or `RecallMode.MULTI_HIT`. By default, `RecallMode.SINGLE_HIT` is used.
+
+`RecallMode.SINGLE_HIT` means that _any_ of the ground truth documents need to be retrieved to count as a correct retrieval with a recall score of 1. A single retrieved document can achieve the full score.
+
+`RecallMode.MULTI_HIT` means that _all_ of the ground truth documents need to be retrieved to count as a correct retrieval with a recall score of 1. The number of retrieved documents must be at least the number of ground truth documents to achieve the full score.
+
+## Usage
+
+### On its own
+
+Below is an example where we use a `DocumentRecallEvaluator` component to evaluate documents retrieved for two queries. For the first query, there is one ground truth document and one retrieved document. For the second query, there are two ground truth documents and three retrieved documents.
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentRecallEvaluator
+
+evaluator = DocumentRecallEvaluator()
+result = evaluator.run(
+ ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+ ],
+ retrieved_documents=[
+ [Document(content="France")],
+ [
+ Document(content="9th century"),
+ Document(content="10th century"),
+ Document(content="9th"),
+ ],
+ ],
+)
+print(result["individual_scores"])
+## [1.0, 1.0]
+print(result["score"])
+## 1.0
+```
+
+### In a pipeline
+
+Below is an example where we use a `DocumentRecallEvaluator` and a `DocumentMRREvaluator` in a pipeline to evaluate two answers and compare them to ground truth answers. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.evaluators import DocumentMRREvaluator, DocumentRecallEvaluator
+
+pipeline = Pipeline()
+mrr_evaluator = DocumentMRREvaluator()
+recall_evaluator = DocumentRecallEvaluator()
+pipeline.add_component("mrr_evaluator", mrr_evaluator)
+pipeline.add_component("recall_evaluator", recall_evaluator)
+
+ground_truth_documents = [
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+]
+retrieved_documents = [
+ [Document(content="France")],
+ [
+ Document(content="9th century"),
+ Document(content="10th century"),
+ Document(content="9th"),
+ ],
+]
+
+result = pipeline.run(
+ {
+ "mrr_evaluator": {
+ "ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents,
+ },
+ "recall_evaluator": {
+ "ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents,
+ },
+ },
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1.0, 1.0]
+## [1.0, 1.0]
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 1.0
+## 1.0
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/external-integrations-evaluators.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/external-integrations-evaluators.mdx
new file mode 100644
index 0000000000..e90faec7aa
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/external-integrations-evaluators.mdx
@@ -0,0 +1,11 @@
+---
+title: "External Integrations"
+id: external-integrations-evaluators
+slug: "/external-integrations-evaluators"
+---
+
+# External Integrations
+
+| Name | Description |
+| --- | --- |
+| [Flow Judge](https://haystack.deepset.ai/integrations/flow-judge) | Evaluate Haystack pipelines using Flow Judge model. |
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/faithfulnessevaluator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/faithfulnessevaluator.mdx
new file mode 100644
index 0000000000..c568d3491c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/faithfulnessevaluator.mdx
@@ -0,0 +1,144 @@
+---
+title: "FaithfulnessEvaluator"
+id: faithfulnessevaluator
+slug: "/faithfulnessevaluator"
+description: "The `FaithfulnessEvaluator` uses an LLM to evaluate whether a generated answer can be inferred from the provided contexts. It does not require ground truth labels. This metric is called faithfulness, sometimes also referred to as groundedness or hallucination."
+---
+
+# FaithfulnessEvaluator
+
+The `FaithfulnessEvaluator` uses an LLM to evaluate whether a generated answer can be inferred from the provided contexts. It does not require ground truth labels. This metric is called faithfulness, sometimes also referred to as groundedness or hallucination.
+
+`retrieved_documents`: A list of a list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean recall score over all inputs
- `individual_scores`: A list of the individual recall scores ranging from 0.0 to 1.0 of each input pair of a list of retrieved documents and a list of ground truth documents. If the mode is set to single_hit, each individual score is either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_recall.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `questions`: A list of questions
`contexts`: A list of a list of contexts, which are the contents of documents. This accounts for one list of contexts per question.
`predicted_answers`: A list of predicted answers, for example, the outputs of a Generator in a RAG pipeline | +| **Output variables** | A dictionary containing:
- `score`: A number from 0.0 to 1.0 that represents the average faithfulness score across all questions
- `individual_scores`: A list of the individual faithfulness scores ranging from 0.0 to 1.0 for each input triple of a question, a list of contexts, and a predicted answer.
- `results`: A list of dictionaries with `statements` and `statement_scores` keys. They contain the statements extracted by an LLM from each predicted answer and the corresponding faithfulness scores per statement, which are either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/faithfulness.py | +| **Package name** | `haystack-ai` | + +
+
+You can use the `FaithfulnessEvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG pipeline, without ground truth labels. The component splits the generated answer into statements and checks each of them against the provided contexts with an LLM. A higher faithfulness score is better, and it indicates that a larger number of statements in the generated answers can be inferred from the contexts. The faithfulness score can be used to better understand how often and when the Generator in a RAG pipeline hallucinates.
+
+### Parameters
+
+The default model for this Evaluator is `gpt-4o-mini`. You can override the model using the `chat_generator` parameter during initialization. This needs to be a Chat Generator instance configured to return a JSON object. For example, when using the [`OpenAIChatGenerator`](../generators/openaichatgenerator.mdx), you should pass `{"response_format": {"type": "json_object"}}` in its `generation_kwargs`.
+
+If you are not initializing the Evaluator with your own Chat Generator other than OpenAI, a valid OpenAI API key must be set as an `OPENAI_API_KEY` environment variable. For details, see our [documentation page on secret management](../../concepts/secret-management.mdx).
+
+Two other optional initialization parameters are:
+
+- `raise_on_failure`: If True, raise an exception on an unsuccessful API call.
+- `progress_bar`: Whether to show a progress bar during the evaluation.
+
+`FaithfulnessEvaluator` has an optional `examples` parameter that can be used to pass few-shot examples conforming to the expected input and output format of `FaithfulnessEvaluator`. These examples are included in the prompt that is sent to the LLM. Examples, therefore, increase the number of tokens of the prompt and make each request more costly. Adding examples is helpful if you want to improve the quality of the evaluation at the cost of more tokens.
+
+Each example must be a dictionary with keys `inputs` and `outputs`.
+`inputs` must be a dictionary with keys `questions`, `contexts`, and `predicted_answers`.
+`outputs` must be a dictionary with `statements` and `statement_scores`.
+Here is the expected format:
+
+```python
+[
+ {
+ "inputs": {
+ "questions": "What is the capital of Italy?",
+ "contexts": ["Rome is the capital of Italy."],
+ "predicted_answers": "Rome is the capital of Italy with more than 4 million inhabitants.",
+ },
+ "outputs": {
+ "statements": [
+ "Rome is the capital of Italy.",
+ "Rome has more than 4 million inhabitants.",
+ ],
+ "statement_scores": [1, 0],
+ },
+ },
+]
+```
+
+## Usage
+
+### On its own
+
+Below is an example of using a `FaithfulnessEvaluator` component to evaluate a predicted answer generated based on a provided question and context. The `FaithfulnessEvaluator` returns a score of 0.5 because it detects two statements in the answer, of which only one is correct.
+
+```python
+from haystack.components.evaluators import FaithfulnessEvaluator
+
+questions = ["Who created the Python language?"]
+contexts = [
+ [
+ "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language. Its design philosophy emphasizes code readability, and its language constructs aim to help programmers write clear, logical code for both small and large-scale software projects.",
+ ],
+]
+predicted_answers = [
+ "Python is a high-level general-purpose programming language that was created by George Lucas.",
+]
+evaluator = FaithfulnessEvaluator()
+result = evaluator.run(
+ questions=questions,
+ contexts=contexts,
+ predicted_answers=predicted_answers,
+)
+
+print(result["individual_scores"])
+## [0.5]
+print(result["score"])
+## 0.5
+print(result["results"])
+## [{'statements': ['Python is a high-level general-purpose programming language.',
+## 'Python was created by George Lucas.'], 'statement_scores': [1, 0], 'score': 0.5}]
+```
+
+### In a pipeline
+
+Below is an example where we use a `FaithfulnessEvaluator` and a `ContextRelevanceEvaluator` in a pipeline to evaluate predicted answers and contexts (the content of documents) received by a RAG pipeline based on provided questions. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Pipeline
+from haystack.components.evaluators import (
+ ContextRelevanceEvaluator,
+ FaithfulnessEvaluator,
+)
+
+pipeline = Pipeline()
+context_relevance_evaluator = ContextRelevanceEvaluator()
+faithfulness_evaluator = FaithfulnessEvaluator()
+pipeline.add_component("context_relevance_evaluator", context_relevance_evaluator)
+pipeline.add_component("faithfulness_evaluator", faithfulness_evaluator)
+
+questions = ["Who created the Python language?"]
+contexts = [
+ [
+ "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language. Its design philosophy emphasizes code readability, and its language constructs aim to help programmers write clear, logical code for both small and large-scale software projects.",
+ ],
+]
+predicted_answers = [
+ "Python is a high-level general-purpose programming language that was created by George Lucas.",
+]
+
+result = pipeline.run(
+ {
+ "context_relevance_evaluator": {"questions": questions, "contexts": contexts},
+ "faithfulness_evaluator": {
+ "questions": questions,
+ "contexts": contexts,
+ "predicted_answers": predicted_answers,
+ },
+ },
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## ...
+## [0.5]
+for evaluator in result:
+ print(result[evaluator]["score"])
+##
+## 0.5
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/llmevaluator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/llmevaluator.mdx
new file mode 100644
index 0000000000..758a29da9a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/llmevaluator.mdx
@@ -0,0 +1,141 @@
+---
+title: "LLMEvaluator"
+id: llmevaluator
+slug: "/llmevaluator"
+description: "This Evaluator uses an LLM to evaluate inputs based on a prompt containing user-defined instructions and examples."
+---
+
+# LLMEvaluator
+
+This Evaluator uses an LLM to evaluate inputs based on a prompt containing user-defined instructions and examples.
+
+`contexts`: A list of a list of contexts, which are the contents of documents. This accounts for one list of contexts per question.
`predicted_answers`: A list of predicted answers, for example, the outputs of a Generator in a RAG pipeline | +| **Output variables** | A dictionary containing:
- `score`: A number from 0.0 to 1.0 that represents the average faithfulness score across all questions
- `individual_scores`: A list of the individual faithfulness scores ranging from 0.0 to 1.0 for each input triple of a question, a list of contexts, and a predicted answer.
- `results`: A list of dictionaries with `statements` and `statement_scores` keys. They contain the statements extracted by an LLM from each predicted answer and the corresponding faithfulness scores per statement, which are either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/faithfulness.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `instructions`: The prompt instructions string
`inputs`: The expected inputs
`outputs`: The output names of the evaluation results
`examples`: Few-shot examples conforming to the input and output format | +| **Mandatory run variables** | `inputs`: Defined by the user – for example, questions or responses | +| **Output variables** | `results`: A dictionary containing keys defined by the user, such as score | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/llm_evaluator.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+The `LLMEvaluator` component can evaluate answers, documents, or any other outputs of a Haystack pipeline based on a user-defined aspect. The component combines the instructions, examples, and expected output names into one prompt. It is meant for calculating user-defined model-based evaluation metrics. If you are looking for pre-defined model-based evaluators that work out of the box, have a look at Haystack’s [`FaithfulnessEvaluator`](faithfulnessevaluator.mdx) and [`ContextRelevanceEvaluator`](contextrelevanceevaluator.mdx) components instead.
+
+### Parameters
+
+The default model for this Evaluator is `gpt-4o-mini`. You can override the model using the `chat_generator` parameter during initialization. This needs to be a Chat Generator instance configured to return a JSON object. For example, when using the [`OpenAIChatGenerator`](../generators/openaichatgenerator.mdx), you should pass `{"response_format": {"type": "json_object"}}` in its `generation_kwargs`.
+
+If you are not initializing the Evaluator with your own Chat Generator other than OpenAI, a valid OpenAI API key must be set as an `OPENAI_API_KEY` environment variable. For details, see our [documentation page on secret management](../../concepts/secret-management.mdx).
+
+`LLMEvaluator` requires six parameters for initialization:
+
+- `instructions`: The prompt instructions to use for evaluation, such as a question about the inputs that the LLM can answer with _yes,_ _no_, or a score.
+- `inputs`: The inputs that the `LLMEvaluator` expects and that it evaluates. The inputs determine the incoming connections of the component. Each input is a tuple of an input name and input type. Input types must be lists. An example could be `[("responses", List[str])]`.
+- `outputs`: Output names of the evaluation results corresponding to keys in the output dictionary. An example could be a `["score"]`.
+- `examples`: Use this parameter to pass few-shot examples conforming to the expected input and output format. These examples are included in the prompt that is sent to the LLM. Examples increase the number of tokens of the prompt and make each request more costly. Adding more than one or two examples can be helpful if you want to improve the quality of the evaluation at the cost of more tokens.
+- `raise_on_failure`: If True (default), raise an exception on an unsuccessful API call.
+- `progress_bar`: Whether to show a progress bar during the evaluation. None is the default.
+
+Each example must be a dictionary with keys `inputs` and `outputs`.
+`inputs` must be a dictionary with keys `questions` and `contexts`.
+`outputs` must be a dictionary with `statements` and `statement_scores`.
+
+Here is the expected format:
+
+```python
+[
+ {
+ "inputs": {
+ "questions": "What is the capital of Italy?",
+ "contexts": ["Rome is the capital of Italy."],
+ },
+ "outputs": {
+ "statements": [
+ "Rome is the capital of Italy.",
+ "Rome has more than 4 million inhabitants.",
+ ],
+ "statement_scores": [1, 0],
+ },
+ },
+]
+```
+
+## Usage
+
+### On its own
+
+Below is an example where we use an `LLMEvaluator` component to evaluate a generated response. The aspect we evaluate is whether the response is problematic for children as defined in the instructions. The `LLMEvaluator` returns one binary score per input response with the result that both responses are not problematic.
+
+```python
+from typing import List
+from haystack.components.evaluators import LLMEvaluator
+
+llm_evaluator = LLMEvaluator(
+ instructions="Is this answer problematic for children?",
+ inputs=[("responses", List[str])],
+ outputs=["score"],
+ examples=[
+ {
+ "inputs": {"responses": "Damn, this is straight outta hell!!!"},
+ "outputs": {"score": 1},
+ },
+ {
+ "inputs": {"responses": "Football is the most popular sport."},
+ "outputs": {"score": 0},
+ },
+ ],
+)
+responses = [
+ "Football is the most popular sport with around 4 billion followers worldwide",
+ "Python language was created by Guido van Rossum.",
+]
+results = llm_evaluator.run(responses=responses)
+print(results)
+## {'results': [{'score': 0}, {'score': 0}]}
+```
+
+### In a pipeline
+
+Below is an example where we use an `LLMEvaluator` in a pipeline to evaluate a response.
+
+```python
+from typing import List
+from haystack import Pipeline
+from haystack.components.evaluators import LLMEvaluator
+
+pipeline = Pipeline()
+llm_evaluator = LLMEvaluator(
+ instructions="Is this answer problematic for children?",
+ inputs=[("responses", List[str])],
+ outputs=["score"],
+ examples=[
+ {
+ "inputs": {"responses": "Damn, this is straight outta hell!!!"},
+ "outputs": {"score": 1},
+ },
+ {
+ "inputs": {"responses": "Football is the most popular sport."},
+ "outputs": {"score": 0},
+ },
+ ],
+)
+
+pipeline.add_component("llm_evaluator", llm_evaluator)
+
+responses = [
+ "Football is the most popular sport with around 4 billion followers worldwide",
+ "Python language was created by Guido van Rossum.",
+]
+
+result = pipeline.run({"llm_evaluator": {"responses": responses}})
+
+for evaluator in result:
+ print(result[evaluator]["results"])
+## [{'score': 0}, {'score': 0}]
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/ragasevaluator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/ragasevaluator.mdx
new file mode 100644
index 0000000000..a38c883253
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/ragasevaluator.mdx
@@ -0,0 +1,131 @@
+---
+title: "RagasEvaluator"
+id: ragasevaluator
+slug: "/ragasevaluator"
+description: "This component evaluates Haystack pipelines using LLM-based metrics. It supports metrics like context relevance, factual accuracy, response relevance, and more."
+---
+
+# RagasEvaluator
+
+This component evaluates Haystack pipelines using LLM-based metrics. It supports metrics like context relevance, factual accuracy, response relevance, and more.
+
+`inputs`: The expected inputs
`outputs`: The output names of the evaluation results
`examples`: Few-shot examples conforming to the input and output format | +| **Mandatory run variables** | `inputs`: Defined by the user – for example, questions or responses | +| **Output variables** | `results`: A dictionary containing keys defined by the user, such as score | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/llm_evaluator.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `ragas_metrics`: A list of modern Ragas metrics from `ragas.metrics.collections`. Each metric must be fully configured (including its LLM) at construction time. |
+| **Mandatory run variables** | The expected inputs will change based on the metrics you are evaluating, but can include `query`, `response`, `documents`, `reference_contexts`, `multi_responses`, `reference`, and `rubrics`. |
+| **Output variables** | `result`: A dictionary mapping metric names to their `MetricResult`. |
+| **API reference** | [Ragas](/reference/integrations-ragas) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ragas |
+| **Package name** | `ragas-haystack` |
+
+
+
+Ragas is an evaluation framework that provides a number of LLM-based evaluation metrics. You can use the `RagasEvaluator` component to evaluate a Haystack pipeline, such as a retrieval-augmented generative pipeline, against one of the metrics provided by Ragas.
+
+## Supported Metrics
+
+The `RagasEvaluator` supports the modern Ragas metrics API. You can pass any metric from `ragas.metrics.collections` (such as `Faithfulness`, `AnswerRelevancy`, `ContextPrecision`, etc.) as long as it is a `SimpleBaseMetric` instance. Each metric must be fully configured (including its LLM and embeddings) at construction time.
+
+For a complete guide on these metrics, visit the [Ragas documentation](https://docs.ragas.io/).
+
+## Parameters Overview
+
+To initialize a `RagasEvaluator`, you need to provide the following parameters:
+
+- `ragas_metrics`: A list of modern Ragas metrics from `ragas.metrics.collections`. Each metric must be fully configured (including its LLM) at construction time.
+
+## Usage
+
+To use the `RagasEvaluator`, you first need to install the integration:
+
+```bash
+pip install ragas-haystack
+```
+
+To use the `RagasEvaluator` you need to follow these steps:
+
+1. Initialize the `RagasEvaluator` while providing the fully configured metrics you want to use.
+2. Run the `RagasEvaluator`, either on its own or in a pipeline, by providing the expected inputs for the metrics you are using (e.g. `query`, `documents`, `response`, etc.).
+
+### Examples
+
+#### Evaluate Answer Relevancy
+
+To create an answer relevancy evaluation pipeline (note that the `OPENAI_API_KEY` environment variable must be set for this example to work):
+
+```python
+from haystack import Pipeline
+from haystack_integrations.components.evaluators.ragas import RagasEvaluator
+from openai import AsyncOpenAI
+from ragas.llms import llm_factory
+from ragas.embeddings import embedding_factory
+from ragas.metrics.collections import AnswerRelevancy
+
+client = AsyncOpenAI()
+llm = llm_factory("gpt-4o-mini", client=client)
+embeddings = embedding_factory("openai", model="text-embedding-3-small", client=client)
+
+pipeline = Pipeline()
+evaluator = RagasEvaluator(
+ ragas_metrics=[AnswerRelevancy(llm=llm, embeddings=embeddings)],
+)
+pipeline.add_component("evaluator", evaluator)
+```
+
+To run the evaluation pipeline, you should have the _expected inputs_ for the metric ready at hand. This metric expects a `query` and `response`, which should come from the results of the pipeline you want to evaluate.
+
+```python
+results = pipeline.run(
+ {
+ "evaluator": {
+ "query": "Where is the Pyramid of Giza?",
+ "response": "The Pyramid of Giza is located in Egypt.",
+ },
+ },
+)
+```
+
+#### Evaluate Context Precision and Faithfulness
+
+To create a pipeline that evaluates multiple metrics at once:
+
+```python
+from haystack import Pipeline
+from haystack_integrations.components.evaluators.ragas import RagasEvaluator
+from openai import AsyncOpenAI
+from ragas.llms import llm_factory
+from ragas.metrics.collections import ContextPrecision, Faithfulness
+
+client = AsyncOpenAI()
+llm = llm_factory("gpt-4o-mini", client=client)
+
+pipeline = Pipeline()
+evaluator = RagasEvaluator(
+ ragas_metrics=[ContextPrecision(llm=llm), Faithfulness(llm=llm)],
+)
+pipeline.add_component("evaluator", evaluator)
+```
+
+To run the evaluation pipeline, you should provide the combined inputs required by all metrics.
+
+```python
+results = pipeline.run(
+ {
+ "evaluator": {
+ "query": "Which is the most popular global sport?",
+ "documents": [
+ "The popularity of sports can be measured in various ways, including TV viewership, social media presence, number of participants, and economic impact. Football is undoubtedly the world's most popular sport with major events like the FIFA World Cup and sports personalities like Ronaldo and Messi, drawing a followership of more than 4 billion people."
+ ],
+ "response": "Football is the most popular sport with around 4 billion followers worldwide",
+ "reference": "Football is the most popular sport",
+ },
+ },
+)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Evaluate a RAG pipeline using Ragas integration](https://haystack.deepset.ai/cookbook/rag_eval_ragas)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/sasevaluator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/sasevaluator.mdx
new file mode 100644
index 0000000000..02f2feca38
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/evaluators/sasevaluator.mdx
@@ -0,0 +1,97 @@
+---
+title: "SASEvaluator"
+id: sasevaluator
+slug: "/sasevaluator"
+description: "The `SASEvaluator` evaluates answers predicted by Haystack pipelines using ground truth labels. It checks the semantic similarity of a predicted answer and the ground truth answer using a fine-tuned language model. This metric is called semantic answer similarity."
+---
+
+# SASEvaluator
+
+The `SASEvaluator` evaluates answers predicted by Haystack pipelines using ground truth labels. It checks the semantic similarity of a predicted answer and the ground truth answer using a fine-tuned language model. This metric is called semantic answer similarity.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `token`: A HF API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `ground_truth_answers`: A list of strings containing the ground truth answers
`predicted_answers`: A list of strings containing the predicted answers to be evaluated | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 representing the mean SAS score for all pairs of predicted answers and ground truth answers
- `individual_scores`: A list of the SAS scores ranging from 0.0 to 1.0 of all pairs of predicted answers and ground truth answers | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/sas_evaluator.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+You can use the `SASEvaluator` component to evaluate answers predicted by a Haystack pipeline, such as a RAG pipeline, against ground truth labels.
+
+You can provide a bi-encoder or cross-encoder model to initialize a `SASEvaluator`. By default, `sentence-transformers/paraphrase-multilingual-mpnet-base-v2` model is used.
+
+Note that only _one_ predicted answer is compared to _one_ ground truth answer at a time. The component does not support multiple ground truth answers for the same question or multiple answers predicted for the same question.
+
+## Usage
+
+### On its own
+
+Below is an example of using a `SASEvaluator` component to evaluate two answers and compare them to ground truth answers.
+
+```python
+from haystack.components.evaluators import SASEvaluator
+
+sas_evaluator = SASEvaluator()
+result = sas_evaluator.run(
+ ground_truth_answers=["Berlin", "Paris"],
+ predicted_answers=["Berlin", "Lyon"],
+)
+print(result["individual_scores"])
+## [[array([[0.99999994]], dtype=float32), array([[0.51747656]], dtype=float32)]
+print(result["score"])
+## 0.7587383
+```
+
+### In a pipeline
+
+Below is an example where we use an `AnswerExactMatchEvaluator` and a `SASEvaluator` in a pipeline to evaluate two answers and compare them to ground truth answers. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Pipeline
+from haystack.components.evaluators import AnswerExactMatchEvaluator, SASEvaluator
+
+pipeline = Pipeline()
+em_evaluator = AnswerExactMatchEvaluator()
+sas_evaluator = SASEvaluator()
+pipeline.add_component("em_evaluator", em_evaluator)
+pipeline.add_component("sas_evaluator", sas_evaluator)
+
+ground_truth_answers = ["Berlin", "Paris"]
+predicted_answers = ["Berlin", "Lyon"]
+
+result = pipeline.run(
+ {
+ "em_evaluator": {
+ "ground_truth_answers": ground_truth_answers,
+ "predicted_answers": predicted_answers,
+ },
+ "sas_evaluator": {
+ "ground_truth_answers": ground_truth_answers,
+ "predicted_answers": predicted_answers,
+ },
+ },
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1, 0]
+## [array([[0.99999994]], dtype=float32), array([[0.51747656]], dtype=float32)]
+
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 0.5
+## 0.7587383
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Prompt Optimization with DSPy](https://haystack.deepset.ai/cookbook/prompt_optimization_with_dspy)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors.mdx
new file mode 100644
index 0000000000..d5a13da690
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors.mdx
@@ -0,0 +1,15 @@
+---
+title: "Extractors"
+id: extractors
+slug: "/extractors"
+---
+
+# Extractors
+
+| Name | Description |
+| --- | --- |
+| [LLMDocumentContentExtractor](extractors/llmdocumentcontentextractor.mdx) | Extracts textual content from image-based documents using a vision-enabled Large Language Model (LLM). |
+| [LLMMetadataExtractor](extractors/llmmetadataextractor.mdx) | Extracts metadata from documents using a Large Language Model. The metadata is extracted by providing a prompt to a LLM that generates it. |
+| [NamedEntityExtractor](extractors/namedentityextractor.mdx) | Extracts predefined entities out of a piece of text and writes them into documents' meta field. |
+| [PresidioEntityExtractor](extractors/presidioentityextractor.mdx) | Detects PII in Documents and stores entities as structured metadata, without modifying the text. Powered by Microsoft Presidio. |
+| [RegexTextExtractor](extractors/regextextextractor.mdx) | Extracts text from chat messages or strings using a regular expression pattern. |
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/llmdocumentcontentextractor.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/llmdocumentcontentextractor.mdx
new file mode 100644
index 0000000000..2ba9848890
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/llmdocumentcontentextractor.mdx
@@ -0,0 +1,191 @@
+---
+title: "LLMDocumentContentExtractor"
+id: llmdocumentcontentextractor
+slug: "/llmdocumentcontentextractor"
+description: "Extracts textual content from image-based documents using a vision-enabled Large Language Model (LLM)."
+---
+
+# LLMDocumentContentExtractor
+
+Extracts textual content and metadata (if applicable) from image-based documents using a vision-enabled Large Language Model (LLM).
+
+`predicted_answers`: A list of strings containing the predicted answers to be evaluated | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 representing the mean SAS score for all pairs of predicted answers and ground truth answers
- `individual_scores`: A list of the SAS scores ranging from 0.0 to 1.0 of all pairs of predicted answers and ground truth answers | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/sas_evaluator.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After [Converters](../converters.mdx) in an indexing pipeline to extract text from image-based documents |
+| **Mandatory init variables** | `chat_generator`: A ChatGenerator instance that supports vision-based input
`prompt`: Instructional text for the LLM on how to extract content (no Jinja variables allowed) | +| **Mandatory run variables** | `documents`: A list of documents with file paths in metadata | +| **Output variables** | `documents`: Successfully processed documents with extracted content
`failed_documents`: Documents that failed processing with error metadata | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/image/llm_document_content_extractor.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`LLMDocumentContentExtractor` extracts textual content from image-based documents using a vision-enabled Large Language Model (LLM). This component is particularly useful for processing scanned documents, images containing text, or PDF pages that need to be converted to searchable text.
+
+The component works by:
+
+1. Converting each input document into an image using the `DocumentToImageContent` component.
+2. Using a predefined prompt to instruct the LLM on how to extract content and/or metadata.
+3. Processing the image through a vision-capable ChatGenerator to extract structured textual content.
+
+The prompt must not contain Jinja variables; it should only include instructions for the LLM. Image data and the prompt are passed together to the LLM as a Chat Message.
+
+The extractor supports both plain-text and JSON responses from the LLM:
+
+- If the LLM returns a plain string, that text is written to the document's `content`.
+- If the LLM returns a JSON object with only the `document_content` key, that value is written to `content`.
+- If the LLM returns a JSON object with multiple keys, the value of `document_content` (if present) is written to `content`, and all other keys are merged into the document's metadata.
+
+Documents for which the LLM fails to extract content are returned in a separate `failed_documents` list with an `extraction_error` entry in their metadata for debugging or reprocessing.
+
+## Usage
+
+### On its own
+
+Below is an example that uses the `LLMDocumentContentExtractor` to extract text from image-based documents:
+
+```python
+from haystack import Document
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+
+## Initialize the chat generator with vision capabilities
+chat_generator = OpenAIChatGenerator(
+ model="gpt-4o-mini",
+ generation_kwargs={"temperature": 0.0},
+)
+
+## Create the extractor
+extractor = LLMDocumentContentExtractor(
+ chat_generator=chat_generator,
+ file_path_meta_field="file_path",
+ raise_on_failure=False,
+)
+
+## Create documents with image file paths
+documents = [
+ Document(content="", meta={"file_path": "image.jpg"}),
+ Document(content="", meta={"file_path": "document.pdf", "page_number": 1}),
+]
+
+## Run the extractor
+result = extractor.run(documents=documents)
+
+## Check results
+print(f"Successfully processed: {len(result['documents'])}")
+print(f"Failed documents: {len(result['failed_documents'])}")
+
+## Access extracted content
+for doc in result["documents"]:
+ print(f"File: {doc.meta['file_path']}")
+ print(f"Extracted content: {doc.content[:100]}...")
+```
+
+### Using custom prompts
+
+You can provide a custom prompt to instruct the LLM on how to extract content:
+
+```python
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+custom_prompt = """
+Extract all text content from this image-based document.
+
+Instructions:
+- Extract text exactly as it appears
+- Preserve the reading order
+- Format tables as markdown
+- Describe any images or diagrams briefly
+- Maintain document structure
+
+Document:"""
+
+chat_generator = OpenAIChatGenerator(model="gpt-4o-mini")
+extractor = LLMDocumentContentExtractor(
+ chat_generator=chat_generator,
+ prompt=custom_prompt,
+ file_path_meta_field="file_path",
+)
+
+documents = [Document(content="", meta={"file_path": "scanned_document.pdf"})]
+result = extractor.run(documents=documents)
+```
+
+### Handling failed documents
+
+The component provides detailed error information for failed documents:
+
+```python
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+chat_generator = OpenAIChatGenerator(model="gpt-4o-mini")
+extractor = LLMDocumentContentExtractor(
+ chat_generator=chat_generator,
+ raise_on_failure=False, # Don't raise exceptions, return failed documents
+)
+
+documents = [Document(content="", meta={"file_path": "problematic_image.jpg"})]
+result = extractor.run(documents=documents)
+
+## Check for failed documents
+for failed_doc in result["failed_documents"]:
+ print(f"Failed to process: {failed_doc.meta['file_path']}")
+ print(f"Error: {failed_doc.meta['extraction_error']}")
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that uses `LLMDocumentContentExtractor` to process image-based documents and store the extracted text:
+
+```python
+from haystack import Pipeline
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.dataclasses import Document
+
+## Create document store
+document_store = InMemoryDocumentStore()
+
+## Create pipeline
+p = Pipeline()
+p.add_component(
+ instance=LLMDocumentContentExtractor(
+ chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+ file_path_meta_field="file_path",
+ ),
+ name="content_extractor",
+)
+p.add_component(instance=DocumentSplitter(), name="splitter")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+
+## Connect components
+p.connect("content_extractor.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+## Create test documents
+docs = [
+ Document(content="", meta={"file_path": "scanned_document.pdf"}),
+ Document(content="", meta={"file_path": "image_with_text.jpg"}),
+]
+
+## Run pipeline
+result = p.run({"content_extractor": {"documents": docs}})
+
+## Check results
+print(f"Successfully processed: {len(result['content_extractor']['documents'])}")
+print(f"Failed documents: {len(result['content_extractor']['failed_documents'])}")
+
+## Access documents in the store
+stored_docs = document_store.filter_documents()
+print(f"Documents in store: {len(stored_docs)}")
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/llmmetadataextractor.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/llmmetadataextractor.mdx
new file mode 100644
index 0000000000..7267bf0286
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/llmmetadataextractor.mdx
@@ -0,0 +1,149 @@
+---
+title: "LLMMetadataExtractor"
+id: llmmetadataextractor
+slug: "/llmmetadataextractor"
+description: "Extracts metadata from documents using a Large Language Model. The metadata is extracted by providing a prompt to a LLM that generates it."
+---
+
+# LLMMetadataExtractor
+
+Extracts metadata from documents using a Large Language Model. The metadata is extracted by providing a prompt to a LLM that generates it.
+
+`prompt`: Instructional text for the LLM on how to extract content (no Jinja variables allowed) | +| **Mandatory run variables** | `documents`: A list of documents with file paths in metadata | +| **Output variables** | `documents`: Successfully processed documents with extracted content
`failed_documents`: Documents that failed processing with error metadata | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/image/llm_document_content_extractor.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After [PreProcessors](../preprocessors.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `prompt`: The prompt to instruct the LLM on how to extract metadata from the document
`chat_generator`: A Chat Generator instance which represents the LLM configured to return a JSON object | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/llm_metadata_extractor.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+The `LLMMetadataExtractor` extraction relies on an LLM and a prompt to perform the metadata extraction. At initialization time, it expects an LLM, a Haystack Generator, and a prompt describing the metadata extraction process.
+
+The prompt should have a variable called `document` that will point to a single document in the list of documents. So, to access the content of the document, you can use `{{ document.content }}` in the prompt.
+
+At runtime, it expects a list of documents and will run the LLM on each document in the list, extracting metadata from the document. The metadata will be added to the document's metadata field.
+
+If the LLM fails to extract metadata from a document, it will be added to the `failed_documents` list. The failed documents' metadata will contain the keys `metadata_extraction_error` and `metadata_extraction_response`.
+
+These documents can be re-run with another extractor to extract metadata using the `metadata_extraction_response` and `metadata_extraction_error` in the prompt.
+
+The current implementation supports the following Haystack Generators:
+
+- [OpenAIChatGenerator](../generators/openaichatgenerator.mdx)
+- [AzureOpenAIChatGenerator](../generators/azureopenaichatgenerator.mdx)
+- [AmazonBedrockChatGenerator](../generators/amazonbedrockchatgenerator.mdx)
+- [VertexAIGeminiChatGenerator](../generators/vertexaigeminichatgenerator.mdx)
+
+## Usage
+
+Here's an example of using the `LLMMetadataExtractor` to extract named entities and add them to the document's metadata.
+
+First, the mandatory imports:
+
+```python
+from haystack import Document
+from haystack.components.extractors.llm_metadata_extractor import LLMMetadataExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+```
+
+Then, define some documents:
+
+```python
+docs = [
+ Document(
+ content="deepset was founded in 2018 in Berlin, and is known for its Haystack framework",
+ ),
+ Document(
+ content="Hugging Face is a company founded in New York, USA and is known for its Transformers library",
+ ),
+]
+```
+
+And now, a prompt that extracts named entities from the documents:
+
+```python
+NER_PROMPT = """
+ -Goal-
+ Given text and a list of entity types, identify all entities of those types from the text.
+
+ -Steps-
+ 1. Identify all entities. For each identified entity, extract the following information:
+ - entity_name: Name of the entity, capitalized
+ - entity_type: One of the following types: [organization, product, service, industry]
+ Format each entity as a JSON like: {"entity": `chat_generator`: A Chat Generator instance which represents the LLM configured to return a JSON object | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/llm_metadata_extractor.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After the [PreProcessor](../preprocessors.mdx) in an indexing pipeline or after a [Retriever](../retrievers.mdx) in a query pipeline |
+| **Mandatory init variables** | `backend`: The backend to use for NER
`model`: Name or path of the model to use | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/named_entity_extractor.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`NamedEntityExtractor` looks for entities, which are spans in the text. The extractor automatically recognizes and groups them depending on their class, such as people's names, organizations, locations, and other types. The exact classes are determined by the model that you initialize the component with.
+
+`NamedEntityExtractor` takes a list of documents as input and returns a list of the same documents with their `meta` data enriched with `NamedEntityAnnotations`. A `NamedEntityAnnotation` consists of the type of the entity, the start and end of the span, and a score calculated by the model, for example: `NamedEntityAnnotation(entity='PER', start=11, end=16, score=0.9)`.
+
+When the `NamedEntityExtractor` is initialized, you need to set a `model` and a `backend`. The latter can be either `"hugging_face"` or `"spacy"`. Optionally, you can set `pipeline_kwargs`, which are then passed on to the Hugging Face pipeline or the spaCy pipeline. You can additionally set the `device` that is used to run the component.
+
+## Usage
+
+The current implementation supports two NER backends: Hugging Face and spaCy. These two backends work with any HF or spaCy model that supports token classification or NER.
+
+Here’s an example of how you could initialize different backends:
+
+```python
+## Initialize with HF backend
+extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
+
+## Initialize with spaCy backend
+extractor = NamedEntityExtractor(backend="spacy", model="en_core_web_sm")
+```
+
+`NamedEntityExtractor` accepts a list of `Documents` as its input. The extractor annotates the raw text in the documents and stores the annotations in the document's `meta` dictionary under the `named_entities` key.
+
+```python
+from haystack.dataclasses import Document
+from haystack.components.extractors import NamedEntityExtractor
+
+extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
+
+documents = [
+ Document(content="My name is Clara and I live in Berkeley, California."),
+ Document(content="I'm Merlin, the happy pig!"),
+ Document(content="New York State is home to the Empire State Building."),
+]
+
+extractor.run(documents)
+print(documents)
+```
+
+Here is the example result:
+
+```python
+[Document(id=aec840d1b6c85609f4f16c3e222a5a25fd8c4c53bd981a40c1268ab9c72cee10, content: 'My name is Clara and I live in Berkeley, California.', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=11, end=16, score=0.99641764), NamedEntityAnnotation(entity='LOC', start=31, end=39, score=0.996198), NamedEntityAnnotation(entity='LOC', start=41, end=51, score=0.9990196)]}),
+Document(id=98f1dc5d0ccd9d9950cd191d1076db0f7af40c401dd7608f11c90cb3fc38c0c2, content: 'I'm Merlin, the happy pig!', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=4, end=10, score=0.99054915)]}),
+Document(id=44948ea0eec018b33aceaaedde4616eb9e93ce075e0090ec1613fc145f84b4a9, content: 'New York State is home to the Empire State Building.', meta: {'named_entities': [NamedEntityAnnotation(entity='LOC', start=0, end=14, score=0.9989541), NamedEntityAnnotation(entity='LOC', start=30, end=51, score=0.95746297)]})]
+```
+
+### Get stored annotations
+
+This component includes the `get_stored_annotations` helper class method that allows you to retrieve the annotations stored in a `Document` transparently:
+
+```python
+from haystack.dataclasses import Document
+from haystack.components.extractors import NamedEntityExtractor
+
+extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
+
+documents = [
+ Document(content="My name is Clara and I live in Berkeley, California."),
+ Document(content="I'm Merlin, the happy pig!"),
+ Document(content="New York State is home to the Empire State Building."),
+]
+
+extractor.run(documents)
+
+annotations = [NamedEntityExtractor.get_stored_annotations(doc) for doc in documents]
+print(annotations)
+
+## If a Document doesn't contain any annotations, this returns None.
+new_doc = Document(content="In one of many possible worlds...")
+assert NamedEntityExtractor.get_stored_annotations(new_doc) is None
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/presidioentityextractor.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/presidioentityextractor.mdx
new file mode 100644
index 0000000000..84e92ec8db
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/presidioentityextractor.mdx
@@ -0,0 +1,133 @@
+---
+title: "PresidioEntityExtractor"
+id: presidioentityextractor
+slug: "/presidioentityextractor"
+description: "Use `PresidioEntityExtractor` to detect PII in Documents and store the entities as structured metadata, powered by Microsoft Presidio."
+---
+
+# PresidioEntityExtractor
+
+`PresidioEntityExtractor` detects personally identifiable information (PII) in Documents and stores the detected entities as structured metadata under the `"entities"` key, without modifying the document text. Each entry contains the entity type, character offsets, and confidence score.
+
+`model`: Name or path of the model to use | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/named_entity_extractor.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In an indexing pipeline, before writing Documents to a Document Store |
+| **Mandatory run variables** | `documents`: A list of Document objects |
+| **Output variables** | `documents`: A list of Document objects with PII metadata added |
+| **API reference** | [Presidio](/reference/integrations-presidio) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/presidio |
+| **Package name** | `presidio-haystack` |
+
+
+
+## Overview
+
+[Microsoft Presidio](https://microsoft.github.io/presidio/) is an open-source framework for PII detection and anonymization. `PresidioEntityExtractor` uses Presidio's Analyzer Engine to scan document text and identify entities such as names, email addresses, phone numbers, and more.
+
+The extractor does **not** modify the document text. Instead, it adds the detected entities as structured metadata, letting you inspect or act on PII findings without altering the original content. This is useful when you want to audit what PII is present before deciding how to handle it — for example, routing documents to a review queue, logging PII findings, or conditionally applying anonymization.
+
+If you want to replace PII directly rather than annotate it, see [`PresidioDocumentCleaner`](../preprocessors/presidiodocumentcleaner.mdx) for Documents or [`PresidioTextCleaner`](../preprocessors/presidiotextcleaner.mdx) for plain strings.
+
+## Configuration
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `language` | `"en"` | ISO 639-1 language code for PII detection. The appropriate spaCy model is selected automatically for [supported languages](#non-english-languages). See [Presidio supported languages](https://microsoft.github.io/presidio/analyzer/languages/). |
+| `entities` | `None` | List of PII entity types to detect (e.g. `["PERSON", "EMAIL_ADDRESS"]`). If `None`, all supported types are detected. See [supported entities](https://microsoft.github.io/presidio/supported_entities/). |
+| `score_threshold` | `0.35` | Minimum confidence score (0–1) for a detected entity to be included. |
+| `models` | `None` | Advanced override: explicit list of spaCy model configs, e.g. `[{"lang_code": "fr", "model_name": "fr_core_news_md"}]`. Use this only when you need a specific model variant or a language not in the built-in mapping. If `None`, the model is selected automatically based on `language`. |
+
+## Usage
+
+Install the `presidio-haystack` package to use the `PresidioEntityExtractor`.
+
+```bash
+pip install presidio-haystack
+```
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.extractors.presidio import PresidioEntityExtractor
+
+extractor = PresidioEntityExtractor()
+result = extractor.run(
+ documents=[Document(content="Contact Alice at alice@example.com")],
+)
+print(result["documents"][0].meta["entities"])
+# [{"entity_type": "PERSON", "start": 8, "end": 13, "score": 0.85},
+# {"entity_type": "EMAIL_ADDRESS", "start": 17, "end": 34, "score": 1.0}]
+```
+
+### In a pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.extractors.presidio import PresidioEntityExtractor
+
+document_store = InMemoryDocumentStore()
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("extractor", PresidioEntityExtractor())
+indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+indexing_pipeline.connect("extractor", "writer")
+
+indexing_pipeline.run(
+ {
+ "extractor": {
+ "documents": [
+ Document(content="Alice Smith's email is alice@example.com"),
+ Document(content="Call Bob at 212-555-9876"),
+ ],
+ },
+ },
+)
+# Documents are stored with detected PII in doc.meta["entities"]
+```
+
+### Using Custom Parameters
+
+Use `entities` to limit detection to the PII types you actually care about. This reduces false positives and improves performance by skipping recognizers you don't need.
+
+Use `score_threshold` to tune the precision-recall tradeoff. The default `0.35` casts a wide net and may include some false positives. Raise it (e.g. `0.7`) when you need high confidence in each detected entity; lower it when missing any PII is the bigger risk.
+
+```python
+from haystack_integrations.components.extractors.presidio import PresidioEntityExtractor
+
+extractor = PresidioEntityExtractor(
+ language="de",
+ entities=["PERSON", "EMAIL_ADDRESS"], # only detect names and emails
+ score_threshold=0.7, # higher precision, fewer false positives
+)
+```
+
+### Non-English languages
+
+For any language in the built-in mapping, just set `language` — the right spaCy model is selected and loaded automatically at warm-up time.
+
+```python
+from haystack import Document
+from haystack_integrations.components.extractors.presidio import PresidioEntityExtractor
+
+# No `models` parameter needed — de_core_news_lg is selected automatically
+extractor = PresidioEntityExtractor(language="de")
+result = extractor.run(
+ documents=[Document(content="Kontaktieren Sie Hans Müller unter hans@example.com")],
+)
+```
+
+Supported languages and their default models are listed in `PresidioEntityExtractor.SPACY_DEFAULT_MODELS`. Using a language not in that mapping without providing `models` raises a `ValueError` at warm-up time with a list of the supported language codes.
+
+To use a non-default model variant, or a language outside the built-in mapping, pass `models` explicitly:
+
+```python
+extractor = PresidioEntityExtractor(
+ language="fr",
+ models=[{"lang_code": "fr", "model_name": "fr_core_news_md"}],
+)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/regextextextractor.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/regextextextractor.mdx
new file mode 100644
index 0000000000..60830b0b0d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/extractors/regextextextractor.mdx
@@ -0,0 +1,147 @@
+---
+title: "RegexTextExtractor"
+id: regextextextractor
+slug: "/regextextextractor"
+description: "Extracts text from chat messages or strings using a regular expression pattern."
+---
+
+# RegexTextExtractor
+
+Extracts text from chat messages or strings using a regular expression pattern.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [Chat Generator](../generators.mdx) to parse structured output from LLM responses |
+| **Mandatory init variables** | `regex_pattern`: The regular expression pattern used to extract text |
+| **Mandatory run variables** | `text_or_messages`: A string or a list of `ChatMessage` objects to search through |
+| **Output variables** | `captured_text`: The extracted text from the first capture group |
+| **API reference** | [Extractors](/reference/extractors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/regex_text_extractor.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`RegexTextExtractor` parses text input or `ChatMessage` objects using a regular expression pattern and extracts text captured by capture groups. This is useful for extracting structured information from LLM outputs that follow specific formats, such as XML-like tags or other patterns.
+
+The component works with both plain strings and lists of `ChatMessage` objects. When given a list of messages, it processes only the last message.
+
+The regex pattern should include at least one capture group (text within parentheses) to specify what text to extract. If no capture group is provided, the entire match is returned instead.
+
+### Handling no matches
+
+By default, when the pattern doesn't match, the component returns an empty dictionary `{}`. You can change this behavior with the `return_empty_on_no_match` parameter:
+
+```python
+from haystack.components.extractors import RegexTextExtractor
+
+# Default behavior - returns empty dict when no match
+extractor_default = RegexTextExtractor(regex_pattern=r"
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing or query pipelines as the data fetching step |
+| **Mandatory run variables** | `urls`: A list of URLs (strings) to start crawling from |
+| **Output variables** | `documents`: A list of [Documents](../../concepts/data-classes.mdx) |
+| **API reference** | [Firecrawl](/reference/integrations-firecrawl) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/firecrawl |
+| **Package name** | `firecrawl-haystack` |
+
+
+
+## Overview
+
+`FirecrawlCrawler` uses [Firecrawl](https://firecrawl.dev) to crawl one or more URLs and return the extracted content as Haystack `Document` objects. Starting from each given URL, it follows links to discover subpages up to a configurable limit. This makes it well-suited for ingesting entire websites or documentation sites, not just single pages.
+
+Firecrawl returns content in a structured format that works well as input for LLMs. Each crawled page becomes a separate `Document` with the page content in the `content` field and metadata, such as title, URL, and description, in the `meta` field.
+
+### Crawl parameters
+
+You can control the crawl behavior through the `params` argument. Some commonly used parameters:
+
+- `limit`: Maximum number of pages to crawl per URL. Defaults to `1`. Without a limit, Firecrawl may crawl all subpages and consume credits quickly.
+- `scrape_options`: Controls the output format. Defaults to `{"formats": ["markdown"]}`.
+
+See the [Firecrawl API reference](https://docs.firecrawl.dev/api-reference/endpoint/crawl-post) for the full list of available parameters.
+
+### Authorization
+
+`FirecrawlCrawler` uses the `FIRECRAWL_API_KEY` environment variable by default. You can also pass the key explicitly at initialization:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.fetchers.firecrawl import FirecrawlCrawler
+
+crawler = FirecrawlCrawler(api_key=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing or query pipelines as the data fetching step |
+| **Mandatory run variables** | `urls`: A list of URLs (strings) |
+| **Output variables** | `streams`: A list of [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **API reference** | [Fetchers](/reference/fetchers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/fetchers/link_content.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`LinkContentFetcher` fetches the contents of the `urls` you give it and returns a list of content streams. Each item in this list is the content of one link it successfully fetched in the form of a `ByteStream` object. Each of these objects in the returned list has metadata that contains its content type (in the `content_type` key) and its URL (in the `url` key).
+
+For example, if you pass ten URLs to `LinkContentFetcher` and it manages to fetch six of them, then the output will be a list of six `ByteStream` objects, each containing information about its content type and URL.
+
+It may happen that some sites block `LinkContentFetcher` from getting their content. In that case, it logs the error and returns the `ByteStream` objects that it successfully fetched.
+
+Often, to use this component in a pipeline, you must convert the returned list of `ByteStream` objects into a list of `Document` objects. To do so, you can use the `HTMLToDocument` component.
+
+You can use `LinkContentFetcher` at the beginning of an indexing pipeline to index the contents of URLs into a Document Store. You can also use it directly in a query pipeline, such as a retrieval-augmented generative (RAG) pipeline, to use the contents of a URL as the data source.
+
+## Security considerations
+
+`LinkContentFetcher` requests the URLs passed to it. If those URLs come directly from end users, this can expose your environment to server-side request forgery (SSRF) risks.
+
+Before calling `LinkContentFetcher`, an application should therefore validate and sanitize user-provided URLs. For example:
+
+- Allow only expected schemes, for example `https`
+- Use an allowlist of trusted domains when possible
+- Block localhost, link-local, and private-network destinations
+- Consider using an outbound proxy or network-level egress restrictions in production
+
+For example, an application could block private, loopback, link-local, reserved IPs, and custom IP ranges using the standard library's `ipaddress` module:
+
+```python
+import ipaddress
+from urllib.parse import urlparse
+
+
+PRIVATE_RANGES = (
+ ipaddress.ip_network("127.0.0.0/8"),
+ ipaddress.ip_network("10.0.0.0/8"),
+ ipaddress.ip_network("172.16.0.0/12"),
+ ipaddress.ip_network("192.168.0.0/16"),
+ ipaddress.ip_network("169.254.0.0/16"),
+)
+
+
+def is_unsafe_url(url: str) -> bool:
+ parsed = urlparse(url)
+ if parsed.scheme != "https" or not parsed.hostname:
+ return True
+ try:
+ ip = ipaddress.ip_address(parsed.hostname)
+ except ValueError:
+ # Hostname (not a raw IP). Apply your own domain allowlist policy here. Filter out "LOCALHOST" etc.
+ return False
+ return (
+ ip.is_private
+ or ip.is_loopback
+ or ip.is_link_local
+ or ip.is_reserved
+ or any(ip in net for net in PRIVATE_RANGES)
+ )
+```
+
+
+## Usage
+
+### On its own
+
+Below is an example where `LinkContentFetcher` fetches the contents of a URL. It initializes the component using the default settings. To change the default component settings, such as `retry_attempts`, check out the API reference [docs](/reference/fetchers-api).
+
+```python
+from haystack.components.fetchers import LinkContentFetcher
+
+fetcher = LinkContentFetcher()
+
+fetcher.run(urls=["https://haystack.deepset.ai"])
+```
+
+### In a pipeline
+
+Below is an example of an indexing pipeline that uses the `LinkContentFetcher` to index the contents of the specified URLs into an `InMemoryDocumentStore`. Notice how it uses the `HTMLToDocument` component to convert the list of `ByteStream` objects to `Document` objects.
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.fetchers import LinkContentFetcher
+from haystack.components.converters import HTMLToDocument
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+fetcher = LinkContentFetcher()
+converter = HTMLToDocument()
+writer = DocumentWriter(document_store=document_store)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(instance=fetcher, name="fetcher")
+indexing_pipeline.add_component(instance=converter, name="converter")
+indexing_pipeline.add_component(instance=writer, name="writer")
+
+indexing_pipeline.connect("fetcher.streams", "converter.sources")
+indexing_pipeline.connect("converter.documents", "writer.documents")
+
+indexing_pipeline.run(
+ data={
+ "fetcher": {
+ "urls": [
+ "https://haystack.deepset.ai/blog/guide-to-using-zephyr-with-haystack2",
+ ],
+ },
+ },
+)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators.mdx
new file mode 100644
index 0000000000..504e6d8af7
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators.mdx
@@ -0,0 +1,61 @@
+---
+title: "Generators"
+id: generators
+slug: "/generators"
+description: "Generators are responsible for generating text after you give them a prompt. They are specific for each LLM technology (OpenAI, local, TGI and others)."
+---
+
+# Generators
+
+Generators are responsible for generating text after you give them a prompt. They are specific for each LLM technology (OpenAI, local, TGI and others).
+
+| Generator | Description | Streaming Support |
+| --- | --- | --- |
+| [AmazonBedrockChatGenerator](generators/amazonbedrockchatgenerator.mdx) | Enables chat completion using models through Amazon Bedrock service. | ✅ |
+| [AmazonBedrockGenerator](generators/amazonbedrockgenerator.mdx) | Enables text generation using models through Amazon Bedrock service. | ✅ |
+| [AIMLAPIChatGenerator](generators/aimllapichatgenerator.mdx) | Enables chat completion using AI models through the AIMLAPI. | ✅ |
+| [AnthropicChatGenerator](generators/anthropicchatgenerator.mdx) | This component enables chat completions using Anthropic large language models (LLMs). | ✅ |
+| [AnthropicVertexChatGenerator](generators/anthropicvertexchatgenerator.mdx) | This component enables chat completions using AnthropicVertex API. | ✅ |
+| [AnthropicGenerator](generators/anthropicgenerator.mdx) | This component enables text completions using Anthropic large language models (LLMs). | ✅ |
+| [AzureOpenAIChatGenerator](generators/azureopenaichatgenerator.mdx) | Enables chat completion using OpenAI's LLMs through Azure services. | ✅ |
+| [AzureOpenAIGenerator](generators/azureopenaigenerator.mdx) | Enables text generation using OpenAI's LLMs through Azure services. | ✅ |
+| [AzureOpenAIResponsesChatGenerator](generators/azureopenairesponseschatgenerator.mdx) | Enables chat completion using OpenAI's Responses API through Azure services with support for reasoning models. | ✅ |
+| [CohereChatGenerator](generators/coherechatgenerator.mdx) | Enables chat completion using Cohere's LLMs. | ✅ |
+| [CohereGenerator](generators/coheregenerator.mdx) | Queries the LLM using Cohere API. | ✅ |
+| [CometAPIChatGenerator](generators/cometapichatgenerator.mdx) | Enables chat completion using AI models through the Comet API. | ✅ |
+| [DALLEImageGenerator](generators/dalleimagegenerator.mdx) | Generate images using OpenAI's DALL-E model. | ❌ |
+| [FallbackChatGenerator](generators/fallbackchatgenerator.mdx) | A ChatGenerator wrapper that tries multiple Chat Generators sequentially until one succeeds. | ✅ |
+| [GoogleAIGeminiChatGenerator](generators/googleaigeminichatgenerator.mdx) | Enables chat completion using Google Gemini models. **_This integration will be deprecated soon. We recommend using [GoogleGenAIChatGenerator](generators/googlegenaichatgenerator.mdx) integration instead._** | ✅ |
+| [GoogleAIGeminiGenerator](generators/googleaigeminigenerator.mdx) | Enables text generation using Google Gemini models. **_This integration will be deprecated soon. We recommend using [GoogleGenAIChatGenerator](generators/googlegenaichatgenerator.mdx) integration instead._** | ✅ |
+| [GoogleGenAIChatGenerator](generators/googlegenaichatgenerator.mdx) | Enables chat completion using Google Gemini models through Google Gen AI SDK. | ✅ |
+| [HuggingFaceAPIChatGenerator](generators/huggingfaceapichatgenerator.mdx) | Enables chat completion using various Hugging Face APIs. | ✅ |
+| [HuggingFaceAPIGenerator](generators/huggingfaceapigenerator.mdx) | Enables text generation using various Hugging Face APIs. | ✅ |
+| [HuggingFaceLocalChatGenerator](generators/huggingfacelocalchatgenerator.mdx) | Provides an interface for chat completion using a Hugging Face model that runs locally. | ✅ |
+| [HuggingFaceLocalGenerator](generators/huggingfacelocalgenerator.mdx) | Provides an interface to generate text using a Hugging Face model that runs locally. | ✅ |
+| [LlamaCppChatGenerator](generators/llamacppchatgenerator.mdx) | Enables chat completion using an LLM running on Llama.cpp. | ❌ |
+| [LlamaCppGenerator](generators/llamacppgenerator.mdx) | Generate text using an LLM running with Llama.cpp. | ❌ |
+| [LlamaStackChatGenerator](generators/llamastackchatgenerator.mdx) | Enables chat completions using an LLM model made available via Llama Stack server | ✅ |
+| [MetaLlamaChatGenerator](generators/metallamachatgenerator.mdx) | Enables chat completion with any model hosted available with Meta Llama API. | ✅ |
+| [MistralChatGenerator](generators/mistralchatgenerator.mdx) | Enables chat completion using Mistral's text generation models. | ✅ |
+| [NvidiaChatGenerator](generators/nvidiachatgenerator.mdx) | Enables chat completion using Nvidia-hosted models. | ✅ |
+| [NvidiaGenerator](generators/nvidiagenerator.mdx) | Provides an interface for generating text using LLMs self-hosted with NVIDIA NIM or models hosted on the NVIDIA API catalog. | ❌ |
+| [OllamaChatGenerator](generators/ollamachatgenerator.mdx) | Enables chat completion using an LLM running on Ollama. | ✅ |
+| [OllamaGenerator](generators/ollamagenerator.mdx) | Provides an interface to generate text using an LLM running on Ollama. | ✅ |
+| [OpenAIChatGenerator](generators/openaichatgenerator.mdx) | Enables chat completion using OpenAI's large language models (LLMs). | ✅ |
+| [OpenAIGenerator](generators/openaigenerator.mdx) | Enables text generation using OpenAI's large language models (LLMs). | ✅ |
+| [OpenAIResponsesChatGenerator](generators/openairesponseschatgenerator.mdx) | Enables chat completion using OpenAI's Responses API with support for reasoning models. | ✅ |
+| [OpenRouterChatGenerator](generators/openrouterchatgenerator.mdx) | Enables chat completion with any model hosted on OpenRouter. | ✅ |
+| [SagemakerGenerator](generators/sagemakergenerator.mdx) | Enables text generation using LLMs deployed on Amazon Sagemaker. | ❌ |
+| [STACKITChatGenerator](generators/stackitchatgenerator.mdx) | Enables chat completions using the STACKIT API. | ✅ |
+| [TogetherAIChatGenerator](generators/togetheraichatgenerator.mdx) | Enables chat completion using models hosted on Together AI. | ✅ |
+| [TogetherAIGenerator](generators/togetheraigenerator.mdx) | Enables text generation using models hosted on Together AI. | ✅ |
+| [VertexAICodeGenerator](generators/vertexaicodegenerator.mdx) | Enables code generation using Google Vertex AI generative model. | ❌ |
+| [VertexAIGeminiChatGenerator](generators/vertexaigeminichatgenerator.mdx) | Enables chat completion using Google Gemini models with GCP Vertex AI. **_This integration will be deprecated soon. We recommend using [GoogleGenAIChatGenerator](generators/googlegenaichatgenerator.mdx) integration instead._** | ✅ |
+| [VertexAIGeminiGenerator](generators/vertexaigeminigenerator.mdx) | Enables text generation using Google Gemini models with GCP Vertex AI. **_This integration will be deprecated soon. We recommend using [GoogleGenAIChatGenerator](generators/googlegenaichatgenerator.mdx) integration instead._** | ✅ |
+| [VertexAIImageCaptioner](generators/vertexaiimagecaptioner.mdx) | Enables text generation using Google Vertex AI `imagetext` generative model. | ❌ |
+| [VertexAIImageGenerator](generators/vertexaiimagegenerator.mdx) | Enables image generation using Google Vertex AI generative model. | ❌ |
+| [VertexAIImageQA](generators/vertexaiimageqa.mdx) | Enables text generation (image captioning) using Google Vertex AI generative models. | ❌ |
+| [VertexAITextGenerator](generators/vertexaitextgenerator.mdx) | Enables text generation using Google Vertex AI generative models. | ❌ |
+| [VLLMChatGenerator](generators/vllmchatgenerator.mdx) | Enables chat completion using models served with vLLM. | ✅ |
+| [WatsonxGenerator](generators/watsonxgenerator.mdx) | Enables text generation with IBM Watsonx models. | ✅ |
+| [WatsonxChatGenerator](generators/watsonxchatgenerator.mdx) | Enables chat completions with IBM Watsonx models. | ✅ |
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/aimllapichatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/aimllapichatgenerator.mdx
new file mode 100644
index 0000000000..34bd0f39ad
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/aimllapichatgenerator.mdx
@@ -0,0 +1,296 @@
+---
+title: "AIMLAPIChatGenerator"
+id: aimllapichatgenerator
+slug: "/aimllapichatgenerator"
+description: "AIMLAPIChatGenerator enables chat completion using AI models through the AIMLAPI."
+---
+
+# AIMLAPIChatGenerator
+
+AIMLAPIChatGenerator enables chat completion using AI models through the AIMLAPI.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The AIMLAPI API key. Can be set with `AIMLAPI_API_KEY` env var. |
+| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [AIMLAPI](/reference/integrations-aimlapi) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/aimlapi | +| **Package name** | `aimlapi-haystack` | + +
+
+## Overview
+
+`AIMLAPIChatGenerator` provides access to AI models through the AIMLAPI, a unified API gateway for models from various providers. You can use different models within a single pipeline with a consistent interface. The default model is `openai/gpt-5-chat-latest`.
+
+AIMLAPI uses a single API key for all providers, which allows you to switch between or combine different models without managing multiple credentials.
+
+For a complete list of available models, check the [AIMLAPI documentation](https://docs.aimlapi.com/).
+
+The component needs a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+You can pass any chat completion parameters valid for the underlying model directly to `AIMLAPIChatGenerator` using the `generation_kwargs` parameter, both at initialization and to the `run()` method.
+
+### Authentication
+
+`AIMLAPIChatGenerator` needs an AIMLAPI API key to work. You can set this key in:
+
+- The `api_key` init parameter using [Secret API](../../concepts/secret-management.mdx)
+- The `AIMLAPI_API_KEY` environment variable (recommended)
+
+### Structured Output
+
+`AIMLAPIChatGenerator` supports structured output generation for compatible models, allowing you to receive responses in a predictable format. You can use Pydantic models or JSON schemas to define the structure of the output through the `response_format` parameter in `generation_kwargs`.
+
+This is useful when you need to extract structured data from text or generate responses that match a specific format.
+
+```python
+from pydantic import BaseModel
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.aimlapi import AIMLAPIChatGenerator
+
+class CityInfo(BaseModel):
+ city_name: str
+ country: str
+ population: int
+ famous_for: str
+
+client = AIMLAPIChatGenerator(
+ model="openai/gpt-4o-2024-08-06",
+ generation_kwargs={"response_format": CityInfo}
+)
+
+response = client.run(messages=[
+ ChatMessage.from_user(
+ "Berlin is the capital and largest city of Germany with a population of "
+ "approximately 3.7 million. It's famous for its history, culture, and nightlife."
+ )
+])
+print(response["replies"][0].text)
+
+>> {"city_name":"Berlin","country":"Germany","population":3700000,
+>> "famous_for":"history, culture, and nightlife"}
+```
+
+:::info[Model Compatibility]
+Structured output support depends on the underlying model. OpenAI models starting from `gpt-4o-2024-08-06` support Pydantic models and JSON schemas. For details on which models support this feature, refer to the respective model provider's documentation.
+:::
+
+### Tool Support
+
+`AIMLAPIChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.aimlapi import AIMLAPIChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = AIMLAPIChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+`AIMLAPIChatGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+You can stream output as it's generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+# Configure the generator with a streaming callback
+component = AIMLAPIChatGenerator(streaming_callback=print_streaming_chunk)
+
+# Pass a list of messages
+from haystack.dataclasses import ChatMessage
+
+component.run([ChatMessage.from_user("Your question here")])
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+We recommend to give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+## Usage
+
+Install the `aimlapi-haystack` package to use the `AIMLAPIChatGenerator`:
+
+```shell
+pip install aimlapi-haystack
+```
+
+### On its own
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.aimlapi import AIMLAPIChatGenerator
+
+client = AIMLAPIChatGenerator(model="openai/gpt-5-chat-latest", streaming_callback=print_streaming_chunk)
+
+response = client.run([ChatMessage.from_user("What's Natural Language Processing? Be brief.")])
+
+>> Natural Language Processing (NLP) is a field of artificial intelligence that
+>> focuses on the interaction between computers and humans through natural language.
+>> It involves enabling machines to understand, interpret, and generate human
+>> language in a meaningful way, facilitating tasks such as language translation,
+>> sentiment analysis, and text summarization.
+
+print(response)
+
+>> {'replies': [ChatMessage(_role=`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [AIMLAPI](/reference/integrations-aimlapi) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/aimlapi | +| **Package name** | `aimlapi-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The model to use
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) instances | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) is a fully managed service that makes high-performing foundation models from leading AI startups and Amazon available through a unified API. You can choose from various foundation models to find the one best suited for your use case.
+
+`AmazonBedrockChatGenerator` enables chat completion using chat models from Amazon, Anthropic, Cohere, Meta, Mistral, and more with a single component.
+
+## Overview
+
+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 Generator in Haystack.
+:::
+
+To use this component for text generation, initialize an AmazonBedrockGenerator with the model name, the AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) should be set as environment variables, be configured as described above or passed as [Secret](../../concepts/secret-management.mdx) arguments. Note, make sure the region you set supports Amazon Bedrock.
+
+### Tool Support
+
+`AmazonBedrockChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = AmazonBedrockChatGenerator(
+ model="anthropic.claude-3-5-sonnet-20240620-v1:0",
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+### Prompt Caching
+
+`AmazonBedrockChatGenerator` supports prompt caching, to reduce inference response latency and input token costs.
+
+Prompt caching on Bedrock is available for [selected models](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html).
+It allows you to define cache points within a request, as long as the input meets a model-specific minimum token threshold.
+
+Each request can contain up to four cache points.
+
+#### Caching messages
+
+This generator allows you to control cache points at the `ChatMessage` level via the `meta` field.
+
+For example, to cache a long user message to be reused across multiple requests:
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.amazon_bedrock import (
+ AmazonBedrockChatGenerator,
+)
+
+msg = ChatMessage.from_user(
+ "long message...",
+ meta={"cachePoint": {"type": "default", "ttl": "5m"}},
+)
+
+generator = AmazonBedrockChatGenerator(
+ model="anthropic.claude-sonnet-4-5-20250929-v1:0",
+)
+
+result = generator.run(messages=[msg])
+```
+
+If the cache point is successfully written, the number of cached input tokens is available at:
+```python
+result["replies"][0].meta["usage"]["cache_write_input_tokens"]
+```
+
+#### Caching tools
+
+You can also cache tool definitions using the `tools_cachepoint_config` initialization parameter.
+When provided, all tools sent to the model are cached, if they exceed the minimum token threshold and the selected
+model supports prompt caching.
+
+```python
+from haystack_integrations.components.generators.amazon_bedrock import (
+ AmazonBedrockChatGenerator,
+)
+
+# define or load your tools
+
+generator = AmazonBedrockChatGenerator(
+ model="anthropic.claude-sonnet-4-5-20250929-v1:0",
+ tools=my_tools,
+ tools_cachepoint_config={"type": "default", "ttl": "5m"},
+)
+
+# send a request to the Language Model
+```
+
+For more details on how prompt caching works in Amazon Bedrock, see the [official documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html).
+
+## Usage
+
+To start using Amazon Bedrock with Haystack, install the `amazon-bedrock-haystack` package:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.amazon_bedrock import (
+ AmazonBedrockChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+
+generator = AmazonBedrockChatGenerator(model="meta.llama2-70b-chat-v1")
+messages = [
+ ChatMessage.from_system(
+ "You are a helpful assistant that answers question in Spanish only",
+ ),
+ ChatMessage.from_user("What's Natural Language Processing? Be brief."),
+]
+
+response = generator.run(messages)
+print(response)
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.amazon_bedrock import (
+ AmazonBedrockChatGenerator,
+)
+
+llm = AmazonBedrockChatGenerator(model="anthropic.claude-3-5-sonnet-20240620-v1:0")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(
+ content_parts=["What does the image show? Max 5 words.", image],
+)
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw mat.
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.amazon_bedrock import (
+ AmazonBedrockChatGenerator,
+)
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", AmazonBedrockChatGenerator(model="meta.llama2-70b-chat-v1"))
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system(
+ "You are an assistant giving out valuable information to language learners.",
+)
+messages = [
+ system_message,
+ ChatMessage.from_user("What's the official language of {{ country }}?"),
+]
+
+res = pipe.run(
+ data={
+ "prompt_builder": {
+ "template_variables": {"country": country},
+ "template": messages,
+ },
+ },
+)
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/amazonbedrockgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/amazonbedrockgenerator.mdx
new file mode 100644
index 0000000000..7c945f7b4d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/amazonbedrockgenerator.mdx
@@ -0,0 +1,121 @@
+---
+title: "AmazonBedrockGenerator"
+id: amazonbedrockgenerator
+slug: "/amazonbedrockgenerator"
+description: "This component enables text generation using models through Amazon Bedrock service."
+---
+
+# AmazonBedrockGenerator
+
+This component enables text generation using models through Amazon Bedrock service.
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) instances | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The model to use
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `prompt`: The instructions for the Generator | +| **Output variables** | `replies`: A list of strings with all the replies generated by the model | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) is a fully managed service that makes high-performing foundation models from leading AI startups and Amazon available through a unified API. You can choose from various foundation models to find the one best suited for your use case.
+
+`AmazonBedrockGenerator` enables text generation using models from AI21 Labs, Anthropic, Cohere, Meta, Stability AI, and Amazon with a single component.
+
+The models that we currently support are Anthropic's Claude, AI21 Labs' Jurassic-2, Stability AI's Stable Diffusion, Cohere's Command and Embed, Meta's Llama 2, and the Amazon Titan language and embeddings models.
+
+## Overview
+
+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 Generator in Haystack.
+:::
+
+To use this component for text generation, initialize an AmazonBedrockGenerator with the model name, the AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) should be set as environment variables, be configured as described above or passed as [Secret](../../concepts/secret-management.mdx) arguments. Note, make sure the region you set supports Amazon Bedrock.
+
+To start using Amazon Bedrock with Haystack, install the `amazon-bedrock-haystack` package:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.amazon_bedrock import (
+ AmazonBedrockGenerator,
+)
+
+aws_access_key_id = "..."
+aws_secret_access_key = "..."
+aws_region_name = "eu-central-1"
+
+generator = AmazonBedrockGenerator(model="anthropic.claude-v2")
+result = generator.run("Who is the best American actor?")
+for reply in result["replies"]:
+ print(reply)
+
+## >>> 'There is no definitive "best" American actor, as acting skill and talent a# re subjective. However, some of the most acclaimed and influential American act# ors include Tom Hanks, Daniel Day-Lewis, Denzel Washington, Meryl Streep, Rober# t De Niro, Al Pacino, Marlon Brando, Jack Nicholson, Leonardo DiCaprio and John# ny Depp. Choosing a single "best" actor comes down to personal preference.'
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders import PromptBuilder
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack import Pipeline
+
+from haystack_integrations.components.generators.amazon_bedrock import (
+ AmazonBedrockGenerator,
+)
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: What's the official language of {{ country }}?
+"""
+
+aws_access_key_id = "..."
+aws_secret_access_key = "..."
+aws_region_name = "eu-central-1"
+generator = AmazonBedrockGenerator(model="anthropic.claude-v2")
+docstore = InMemoryDocumentStore()
+
+pipe = Pipeline()
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("generator", generator)
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "generator")
+
+pipe.run({"retriever": {"query": "France"}, "prompt_builder": {"country": "France"}})
+
+## {'generator': {'replies': ['Based on the context provided, the official language of France is French.']}}
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/anthropicchatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/anthropicchatgenerator.mdx
new file mode 100644
index 0000000000..935a44f57f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/anthropicchatgenerator.mdx
@@ -0,0 +1,212 @@
+---
+title: "AnthropicChatGenerator"
+id: anthropicchatgenerator
+slug: "/anthropicchatgenerator"
+description: "This component enables chat completions using Anthropic large language models (LLMs)."
+---
+
+# AnthropicChatGenerator
+
+This component enables chat completions using Anthropic large language models (LLMs).
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `prompt`: The instructions for the Generator | +| **Output variables** | `replies`: A list of strings with all the replies generated by the model | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | +| **Package name** | `amazon-bedrock-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An Anthropic API key. Can be set with `ANTHROPIC_API_KEY` env var. |
+| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | +| **Package name** | `anthropic-haystack` | + +
+
+## Overview
+
+This integration supports Anthropic `chat` models such as `claude-3-5-sonnet-20240620`,`claude-3-opus-20240229`, `claude-3-haiku-20240307`, and similar. Check out the most recent full list in [Anthropic documentation](https://docs.anthropic.com/en/docs/about-claude/models).
+
+### Parameters
+
+`AnthropicChatGenerator` needs an Anthropic API key to work. You can provide this key in:
+
+- The `ANTHROPIC_API_KEY` environment variable (recommended)
+- The `api_key` init parameter and Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`
+
+Set your preferred Anthropic model with the `model` parameter when initializing the component.
+
+`AnthropicChatGenerator` requires a prompt to generate text, but you can pass any text generation parameters available in the Anthropic [Messaging API](https://docs.anthropic.com/en/api/messages) method directly to this component using the `generation_kwargs` parameter, both at initialization and when running the component. For more details on the parameters supported by the Anthropic API, see the [Anthropic documentation](https://docs.anthropic.com).
+
+Finally, the component needs a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+Only text input modality is supported at this time.
+
+### Tool Support
+
+`AnthropicChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = AnthropicChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+You can stream output as it’s generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+## Configure any `Generator` or `ChatGenerator` with a streaming callback
+component = SomeGeneratorOrChatGenerator(streaming_callback=print_streaming_chunk)
+
+## If this is a `ChatGenerator`, pass a list of messages:
+## from haystack.dataclasses import ChatMessage
+## component.run([ChatMessage.from_user("Your question here")])
+
+## If this is a (non-chat) `Generator`, pass a prompt:
+## component.run({"prompt": "Your prompt here"})
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+### Prompt caching
+
+Prompt caching is a feature for Anthropic LLMs that stores large text inputs for reuse. It allows you to send a large text block once and then refer to it in later requests without resending the entire text.
+This feature is particularly useful for coding assistants that need full codebase context and for processing large documents. It can help reduce costs and improve response times.
+
+Here's an example of an instance of `AnthropicChatGenerator` being initialized with prompt caching and tagging a message to be cached:
+
+```python python
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generation_kwargs = {"extra_headers": {"anthropic-beta": "prompt-caching-2024-07-31"}}
+
+claude_llm = AnthropicChatGenerator(
+ api_key=Secret.from_env_var("ANTHROPIC_API_KEY"), generation_kwargs=generation_kwargs
+)
+
+system_message = ChatMessage.from_system("Replace with some long text documents, code or instructions")
+system_message.meta["cache_control"] = {"type": "ephemeral"}
+
+messages = [system_message, ChatMessage.from_user("A query about the long text for example")]
+result = claude_llm.run(messages)
+
+## and now invoke again with
+
+messages = [system_message, ChatMessage.from_user("Another query about the long text etc")]
+result = claude_llm.run(messages)
+
+## and so on, either invoking component directly or in the pipeline
+```
+
+For more details, refer to Anthropic's [documentation](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) and integration [examples](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic/example).
+
+## Usage
+
+Install the`anthropic-haystack` package to use the `AnthropicChatGenerator`:
+
+```shell
+pip install anthropic-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = AnthropicChatGenerator()
+message = ChatMessage.from_user("What's Natural Language Processing? Be brief.")
+print(generator.run([message]))
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+
+llm = AnthropicChatGenerator()
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(
+ content_parts=["What does the image show? Max 5 words.", image],
+)
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+### In a pipeline
+
+You can also use `AnthropicChatGenerator`with the Anthropic chat models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+from haystack.utils import Secret
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component(
+ "llm",
+ AnthropicChatGenerator(Secret.from_env_var("ANTHROPIC_API_KEY")),
+)
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system(
+ "You are an assistant giving out valuable information to language learners.",
+)
+messages = [
+ system_message,
+ ChatMessage.from_user("What's the official language of {{ country }}?"),
+]
+
+res = pipe.run(
+ data={
+ "prompt_builder": {
+ "template_variables": {"country": country},
+ "template": messages,
+ },
+ },
+)
+print(res)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Advanced Prompt Customization for Anthropic](https://haystack.deepset.ai/cookbook/prompt_customization_for_anthropic)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/anthropicgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/anthropicgenerator.mdx
new file mode 100644
index 0000000000..f21aefe82c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/anthropicgenerator.mdx
@@ -0,0 +1,89 @@
+---
+title: "AnthropicGenerator"
+id: anthropicgenerator
+slug: "/anthropicgenerator"
+description: "This component enables text completions using Anthropic large language models (LLMs)."
+---
+
+# AnthropicGenerator
+
+This component enables text completions using Anthropic large language models (LLMs).
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | +| **Package name** | `anthropic-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [PromptBuilder](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An Anthropic API key. Can be set with `ANTHROPIC_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | +| **Package name** | `anthropic-haystack` | + +
+
+## Overview
+
+This integration supports Anthropic models such as `claude-3-5-sonnet-20240620`,`claude-3-opus-20240229`, `claude-3-haiku-20240307`, and similar. Although these LLMs are called chat models, the main prompt interface works with the string prompts. Check out the most recent full list in the [Anthropic documentation](https://docs.anthropic.com/en/docs/about-claude/models).
+
+### Parameters
+
+`AnthropicGenerator` needs an Anthropic API key to work. You can provide this key in:
+
+- The `ANTHROPIC_API_KEY` environment variable (recommended)
+- The `api_key` init parameter and Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`
+
+Set your preferred Anthropic model in the `model` parameter when initializing the component.
+
+`AnthropicGenerator` requires a prompt to generate text, but you can pass any text generation parameters available in the Anthropic [Messaging API](https://docs.anthropic.com/en/api/messages) method directly to this component using the `generation_kwargs` parameter, both at initialization and to `run()` method. For more details on the parameters supported by the Anthropic API, see [Anthropic documentation](https://docs.anthropic.com).
+
+Finally, the component run method requires a single string prompt to generate text.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Install the `anthropic-haystack` package to use the `AnthropicGenerator`:
+
+```shell
+pip install anthropic-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicGenerator
+
+generator = AnthropicGenerator()
+print(generator.run("What's Natural Language Processing? Be brief."))
+```
+
+### In a pipeline
+
+You can also use `AnthropicGenerator` with the Anthropic models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import PromptBuilder
+from haystack_integrations.components.generators.anthropic import AnthropicGenerator
+from haystack.utils import Secret
+
+template = """
+You are an assistant giving out valuable information to language learners.
+Answer this question, be brief.
+
+Question: {{ query }}?
+"""
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", PromptBuilder(template))
+pipe.add_component("llm", AnthropicGenerator(Secret.from_env_var("ANTHROPIC_API_KEY")))
+pipe.connect("prompt_builder", "llm")
+
+query = "What language is spoke in Germany?"
+res = pipe.run(data={"prompt_builder": {"query": {query}}})
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/anthropicvertexchatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/anthropicvertexchatgenerator.mdx
new file mode 100644
index 0000000000..3f74fa7475
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/anthropicvertexchatgenerator.mdx
@@ -0,0 +1,188 @@
+---
+title: "AnthropicVertexChatGenerator"
+id: anthropicvertexchatgenerator
+slug: "/anthropicvertexchatgenerator"
+description: "This component enables chat completions using AnthropicVertex API."
+---
+
+# AnthropicVertexChatGenerator
+
+This component enables chat completions using AnthropicVertex API.
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | +| **Package name** | `anthropic-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `region`: The region where the Anthropic model is deployed
`project_id`: GCP project ID where the Anthropic model is deployed | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and others | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | +| **Package name** | `anthropic-haystack` | + +
+
+## Overview
+
+`AnthropicVertexChatGenerator` enables text generation using state-of-the-art Claude 3 LLMs using the Anthropic Vertex AI API.
+It supports `Claude 3.5 Sonnet`, `Claude 3 Opus`, `Claude 3 Sonnet`, and `Claude 3 Haiku` models, that are accessible through the Vertex AI API endpoint. For more details about the models, refer to [Anthropic Vertex AI documentation](https://docs.anthropic.com/en/api/claude-on-vertex-ai).
+
+### Parameters
+
+To use the `AnthropicVertexChatGenerator`, ensure you have a GCP project with Vertex AI enabled. You need to specify your GCP `project_id` and `region`.
+
+You can provide these keys in the following ways:
+
+- The `REGION` and `PROJECT_ID` environment variables (recommended)
+- The `region` and `project_id` init parameters
+
+Before making requests, you may need to authenticate with GCP using `gcloud auth login`.
+
+Set your preferred supported Anthropic model with the `model` parameter when initializing the component. Additionally, ensure that the desired Anthropic model is activated in the Vertex AI Model Garden.
+
+`AnthropicVertexChatGenerator` requires a prompt to generate text, but you can pass any text generation parameters available in the Anthropic [Messaging API](https://docs.anthropic.com/en/api/messages) method directly to this component using the `generation_kwargs` parameter, both at initialization and when running the component. For more details on the parameters supported by the Anthropic API, see the [Anthropic documentation](https://docs.anthropic.com/).
+
+Finally, the component needs a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+Only text input modality is supported at this time.
+
+### Streaming
+
+You can stream output as it’s generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+## Configure any `Generator` or `ChatGenerator` with a streaming callback
+component = SomeGeneratorOrChatGenerator(streaming_callback=print_streaming_chunk)
+
+## If this is a `ChatGenerator`, pass a list of messages:
+## from haystack.dataclasses import ChatMessage
+## component.run([ChatMessage.from_user("Your question here")])
+
+## If this is a (non-chat) `Generator`, pass a prompt:
+## component.run({"prompt": "Your prompt here"})
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+### Prompt Caching
+
+Prompt caching is a feature for Anthropic LLMs that stores large text inputs for reuse. It allows you to send a large text block once and then refer to it in later requests without resending the entire text.
+
+This feature is particularly useful for coding assistants that need full codebase context and for processing large documents. It can help reduce costs and improve response times.
+
+Here's an example of an instance of `AnthropicVertexChatGenerator` being initialized with prompt caching and tagging a message to be cached:
+
+```python
+from haystack_integrations.components.generators.anthropic import (
+ AnthropicVertexChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+
+generation_kwargs = {"extra_headers": {"anthropic-beta": "prompt-caching-2024-07-31"}}
+
+claude_llm = AnthropicVertexChatGenerator(
+ region="your_region",
+ project_id="test_id",
+ generation_kwargs=generation_kwargs,
+)
+
+system_message = ChatMessage.from_system(
+ "Replace with some long text documents, code or instructions",
+)
+system_message.meta["cache_control"] = {"type": "ephemeral"}
+
+messages = [
+ system_message,
+ ChatMessage.from_user("A query about the long text for example"),
+]
+result = claude_llm.run(messages)
+
+## and now invoke again with
+
+messages = [
+ system_message,
+ ChatMessage.from_user("Another query about the long text etc"),
+]
+result = claude_llm.run(messages)
+
+## and so on, either invoking component directly or in the pipeline
+```
+
+For more details, refer to Anthropic's [documentation](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) and integration [examples](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic/example).
+
+## Usage
+
+Install the`anthropic-haystack` package to use the `AnthropicVertexChatGenerator`:
+
+```shell
+pip install anthropic-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.anthropic import (
+ AnthropicVertexChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+client = AnthropicVertexChatGenerator(
+ model="claude-3-sonnet@20240229",
+ project_id="your-project-id",
+ region="us-central1",
+)
+
+response = client.run(messages)
+print(response)
+```
+
+### In a pipeline
+
+You can also use `AnthropicVertexChatGenerator`with the Anthropic chat models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.anthropic import (
+ AnthropicVertexChatGenerator,
+)
+from haystack.utils import Secret
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component(
+ "llm",
+ AnthropicVertexChatGenerator(project_id="test_id", region="us-central1"),
+)
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system(
+ "You are an assistant giving out valuable information to language learners.",
+)
+messages = [
+ system_message,
+ ChatMessage.from_user("What's the official language of {{ country }}?"),
+]
+
+res = pipe.run(
+ data={
+ "prompt_builder": {
+ "template_variables": {"country": country},
+ "template": messages,
+ },
+ },
+)
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/azureopenaichatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/azureopenaichatgenerator.mdx
new file mode 100644
index 0000000000..8bac571159
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/azureopenaichatgenerator.mdx
@@ -0,0 +1,212 @@
+---
+title: "AzureOpenAIChatGenerator"
+id: azureopenaichatgenerator
+slug: "/azureopenaichatgenerator"
+description: "This component enables chat completion using OpenAI’s large language models (LLMs) through Azure services."
+---
+
+# AzureOpenAIChatGenerator
+
+This component enables chat completion using OpenAI’s large language models (LLMs) through Azure services.
+
+`project_id`: GCP project ID where the Anthropic model is deployed | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and others | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | +| **Package name** | `anthropic-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Azure OpenAI API key. Can be set with `AZURE_OPENAI_API_KEY` env var.
`azure_ad_token`: Microsoft Entra ID token. Can be set with `AZURE_OPENAI_AD_TOKEN` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of alternative replies of the LLM to the input chat | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/azure.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`AzureOpenAIChatGenerator` supports OpenAI models deployed through Azure services. To see the list of supported models, head over to Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?source=recommendations). The default model used with the component is `gpt-4o-mini`.
+
+To work with Azure components, you will need an Azure OpenAI API key, as well as an Azure OpenAI Endpoint. You can learn more about them in Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
+
+The component uses `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_AD_TOKEN` environment variables by default. Otherwise, you can pass `api_key` and `azure_ad_token` at initialization:
+
+```python
+client = AzureOpenAIChatGenerator(
+ azure_endpoint="`azure_ad_token`: Microsoft Entra ID token. Can be set with `AZURE_OPENAI_AD_TOKEN` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of alternative replies of the LLM to the input chat | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/azure.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Azure OpenAI API key. Can be set with `AZURE_OPENAI_API_KEY` env var.
`azure_ad_token`: Microsoft Entra ID token. Can be set with `AZURE_OPENAI_AD_TOKEN` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/azure.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`AzureOpenAIGenerator` supports OpenAI models deployed through Azure services. To see the list of supported models, head over to Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?source=recommendations). The default model used with the component is `gpt-4o-mini`.
+
+To work with Azure components, you will need an Azure OpenAI API key, as well as an Azure OpenAI Endpoint. You can learn more about them in Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
+
+The component uses `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_AD_TOKEN` environment variables by default. Otherwise, you can pass `api_key` and `azure_ad_token` at initialization:
+
+```python
+client = AzureOpenAIGenerator(
+ azure_endpoint="`azure_ad_token`: Microsoft Entra ID token. Can be set with `AZURE_OPENAI_AD_TOKEN` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/azure.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Azure OpenAI API key. Can be set with `AZURE_OPENAI_API_KEY` env var or a callable for Azure AD token.
`azure_endpoint`: The endpoint of the deployed model. Can be set with `AZURE_OPENAI_ENDPOINT` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects containing the generated responses | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/azure_responses.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`AzureOpenAIResponsesChatGenerator` uses OpenAI's Responses API through Azure OpenAI services. It supports gpt-5 and o-series models (reasoning models like o1, o3-mini) deployed on Azure. The default model is `gpt-5-mini`.
+
+The Responses API is designed for reasoning-capable models and supports features like reasoning summaries, multi-turn conversations with previous response IDs, and structured outputs. This component provides access to these capabilities through Azure's infrastructure.
+
+The component requires a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`), and optional metadata. See the [usage](#usage) section for examples.
+
+You can pass any parameters valid for the OpenAI Responses API directly to `AzureOpenAIResponsesChatGenerator` using the `generation_kwargs` parameter, both at initialization and to the `run()` method. For more details on the supported parameters, refer to the [Azure OpenAI documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
+
+You can specify a model for this component through the `azure_deployment` init parameter, which should match your Azure deployment name.
+
+### Authentication
+
+To work with Azure components, you need an Azure OpenAI API key and an Azure OpenAI endpoint. You can learn more about them in the [Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
+
+The component uses `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_ENDPOINT` environment variables by default. Otherwise, you can pass these at initialization using a [`Secret`](../../concepts/secret-management.mdx):
+
+```python
+from haystack.components.generators.chat import AzureOpenAIResponsesChatGenerator
+from haystack.utils import Secret
+
+client = AzureOpenAIResponsesChatGenerator(
+ azure_endpoint="https://your-resource.azure.openai.com/",
+ api_key=Secret.from_token("`azure_endpoint`: The endpoint of the deployed model. Can be set with `AZURE_OPENAI_ENDPOINT` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects containing the generated responses | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/azure_responses.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.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** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | +| **Package name** | `cohere-haystack` | + +
+
+This integration supports Cohere `chat` models such as `command`,`command-r` and `comman-r-plus`. Check out the most recent full list in [Cohere documentation](https://docs.cohere.com/reference/chat).
+
+## Overview
+
+`CohereChatGenerator` needs a Cohere API key to work. You can set this key in:
+
+- The `api_key` init parameter using [Secret API](../../concepts/secret-management.mdx)
+- The `COHERE_API_KEY` environment variable (recommended)
+
+Then, the component needs a prompt to operate, but you can pass any text generation parameters valid for the `Co.chat` method directly to this component using the `generation_kwargs` parameter, both at initialization and to `run()` method. For more details on the parameters supported by the Cohere API, refer to the [Cohere documentation](https://docs.cohere.com/reference/chat).
+
+Finally, the component needs a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+### Tool Support
+
+`CohereChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.cohere import CohereChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = CohereChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+You need to install `cohere-haystack` package to use the `CohereChatGenerator`:
+
+```shell
+pip install cohere-haystack
+```
+
+#### On its own
+
+```python
+from haystack_integrations.components.generators.cohere import CohereChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = CohereChatGenerator()
+message = ChatMessage.from_user("What's Natural Language Processing? Be brief.")
+print(generator.run([message]))
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.cohere import CohereChatGenerator
+
+# Use a multimodal model like Command A Vision
+llm = CohereChatGenerator(model="command-a-vision-07-2025")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(
+ content_parts=["What does the image show? Max 5 words.", image],
+)
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+#### In a Pipeline
+
+You can also use `CohereChatGenerator` to use cohere chat models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.cohere import CohereChatGenerator
+from haystack.utils import Secret
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", CohereChatGenerator())
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system(
+ "You are an assistant giving out valuable information to language learners.",
+)
+messages = [
+ system_message,
+ ChatMessage.from_user("What's the official language of {{ country }}?"),
+]
+
+res = pipe.run(
+ data={
+ "prompt_builder": {
+ "template_variables": {"country": country},
+ "template": messages,
+ },
+ },
+)
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/coheregenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/coheregenerator.mdx
new file mode 100644
index 0000000000..7de9648866
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/coheregenerator.mdx
@@ -0,0 +1,122 @@
+---
+title: "CohereGenerator"
+id: coheregenerator
+slug: "/coheregenerator"
+description: "`CohereGenerator` enables text generation using Cohere's large language models (LLMs)."
+---
+
+# CohereGenerator
+
+`CohereGenerator` enables text generation using Cohere's large language models (LLMs).
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | +| **Package name** | `cohere-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.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** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | +| **Package name** | `cohere-haystack` | + +
+
+ This integration supports Cohere models such as `command`, `command-r` and `comman-r-plus`. Check out the most recent full list in [Cohere documentation](https://docs.cohere.com/reference/chat).
+
+## Overview
+
+`CohereGenerator` needs a Cohere API key to work. You can write this key in:
+
+- The `api_key` init parameter using [Secret API](../../concepts/secret-management.mdx)
+- The `COHERE_API_KEY` environment variable (recommended)
+
+Then, the component needs a prompt to operate, but you can pass any text generation parameters directly to this component using the `generation_kwargs` parameter at initialization. For more details on the parameters supported by the Cohere API, refer to the [Cohere documentation](https://docs.cohere.com/reference/chat).
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+You need to install `cohere-haystack` package to use the `CohereGenerator`:
+
+```shell
+pip install cohere-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.cohere import CohereGenerator
+
+client = CohereGenerator()
+response = client.run("Briefly explain what NLP is in one sentence.")
+print(response)
+
+>>> {'replies': ["Natural Language Processing (NLP) is a subfield of artificial intelligence and computational linguistics that focuses on the interaction between computers and human languages..."],
+ 'meta': [{'finish_reason': 'COMPLETE'}]}
+```
+
+With streaming:
+
+```python
+from haystack_integrations.components.generators.cohere import CohereGenerator
+
+client = CohereGenerator(streaming_callback=lambda chunk: print(chunk.content, end="", flush=True))
+response = client.run("Briefly explain what NLP is in one sentence.")
+print(response)
+
+>>> Natural Language Processing (NLP) is the study of natural language and how it can be used to solve problems through computational methods, enabling machines to understand, interpret, and generate human language.
+
+>>>{'replies': [' Natural Language Processing (NLP) is the study of natural language and how it can be used to solve problems through computational methods, enabling machines to understand, interpret, and generate human language.'], 'meta': [{'index': 0, 'finish_reason': 'COMPLETE'}]}
+
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack import Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.generators.cohere import CohereGenerator
+from haystack import Document
+
+docstore = InMemoryDocumentStore()
+docstore.write_documents(
+ [
+ Document(content="Rome is the capital of Italy"),
+ Document(content="Paris is the capital of France"),
+ ],
+)
+
+query = "What is the capital of France?"
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: {{ query }}?
+"""
+pipe = Pipeline()
+
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("llm", CohereGenerator())
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "llm")
+
+res = pipe.run({"prompt_builder": {"query": query}, "retriever": {"query": query}})
+
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/cometapichatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/cometapichatgenerator.mdx
new file mode 100644
index 0000000000..38a4af273a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/cometapichatgenerator.mdx
@@ -0,0 +1,307 @@
+---
+title: "CometAPIChatGenerator"
+id: cometapichatgenerator
+slug: "/cometapichatgenerator"
+description: "CometAPIChatGenerator enables chat completion using AI models through the Comet API."
+---
+
+# CometAPIChatGenerator
+
+CometAPIChatGenerator enables chat completion using AI models through the Comet API.
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | +| **Package name** | `cohere-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Comet API key. Can be set with `COMET_API_KEY` env var. |
+| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Comet API](/reference/integrations-cometapi) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cometapi | +| **Package name** | `cometapi-haystack` | + +
+
+## Overview
+
+`CometAPIChatGenerator` provides access to over 500 AI models through the Comet API, a unified API gateway for models from providers like OpenAI, Anthropic, Google, Meta, Mistral, and many more. You can use different models from different providers within a single pipeline with a consistent interface.
+
+Comet API uses a single API key for all providers, which allows you to switch between or combine different models without managing multiple credentials.
+
+The range of models supported by Comet API include:
+
+- OpenAI models: `gpt-4o`, `gpt-4o-mini` (default), `gpt-4-turbo`, and more
+- Anthropic models: `claude-3-5-sonnet`, `claude-3-opus`, and more
+- Google models: `gemini-1.5-pro`, `gemini-1.5-flash`, and more
+- Meta models: `llama-3.3-70b`, `llama-3.1-405b`, and more
+- Mistral models: `mistral-large-latest`, `mistral-small`, and more
+
+For a complete list of available models, check the [Comet API documentation](https://apidoc.cometapi.com/).
+
+The component needs a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+You can pass any chat completion parameters valid for the underlying model directly to `CometAPIChatGenerator` using the `generation_kwargs` parameter, both at initialization and to the `run()` method.
+
+### Authentication
+
+`CometAPIChatGenerator` needs a Comet API key to work. You can set this key in:
+
+- The `api_key` init parameter using [Secret API](../../concepts/secret-management.mdx)
+- The `COMET_API_KEY` environment variable (recommended)
+
+### Structured Output
+
+`CometAPIChatGenerator` supports structured output generation for compatible models, allowing you to receive responses in a predictable format. You can use Pydantic models or JSON schemas to define the structure of the output through the `response_format` parameter in `generation_kwargs`.
+
+This is useful when you need to extract structured data from text or generate responses that match a specific format.
+
+```python
+from pydantic import BaseModel
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.cometapi import CometAPIChatGenerator
+
+class CityInfo(BaseModel):
+ city_name: str
+ country: str
+ population: int
+ famous_for: str
+
+client = CometAPIChatGenerator(
+ model="gpt-4o-2024-08-06",
+ generation_kwargs={"response_format": CityInfo}
+)
+
+response = client.run(messages=[
+ ChatMessage.from_user(
+ "Berlin is the capital and largest city of Germany with a population of "
+ "approximately 3.7 million. It's famous for its history, culture, and nightlife."
+ )
+])
+print(response["replies"][0].text)
+
+>> {"city_name":"Berlin","country":"Germany","population":3700000,
+>> "famous_for":"history, culture, and nightlife"}
+```
+
+:::info[Model Compatibility]
+Structured output support depends on the underlying model. OpenAI models starting from `gpt-4o-2024-08-06` support Pydantic models and JSON schemas. For details on which models support this feature, refer to the respective model provider's documentation.
+:::
+
+### Tool Support
+
+`CometAPIChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.cometapi import CometAPIChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = CometAPIChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+`CometAPIChatGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+You can stream output as it's generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+# Configure the generator with a streaming callback
+component = CometAPIChatGenerator(streaming_callback=print_streaming_chunk)
+
+# Pass a list of messages
+from haystack.dataclasses import ChatMessage
+
+component.run([ChatMessage.from_user("Your question here")])
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+We recommend to give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+## Usage
+
+Install the `cometapi-haystack` package to use the `CometAPIChatGenerator`:
+
+```shell
+pip install cometapi-haystack
+```
+
+### On its own
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.cometapi import CometAPIChatGenerator
+
+client = CometAPIChatGenerator(model="gpt-4o-mini", streaming_callback=print_streaming_chunk)
+
+response = client.run([ChatMessage.from_user("What's Natural Language Processing? Be brief.")])
+
+>> Natural Language Processing (NLP) is a field of artificial intelligence that
+>> focuses on the interaction between computers and humans through natural language.
+>> It involves enabling machines to understand, interpret, and generate human
+>> language in a meaningful way, facilitating tasks such as language translation,
+>> sentiment analysis, and text summarization.
+
+print(response)
+
+>> {'replies': [ChatMessage(_role=`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Comet API](/reference/integrations-cometapi) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cometapi | +| **Package name** | `cometapi-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx), flexible |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the model |
+| **Output variables** | `images`: A list of generated images
`revised_prompt`: A string containing the prompt that was used to generate the image, if there was any revision to the prompt made by OpenAI | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/openai_dalle.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+The `DALLEImageGenerator` component generates images using OpenAI's DALL-E model.
+
+By default, the component uses `dall-e-3` model, standard picture quality, and 1024x1024 resolution. You can change these parameters using `model` (during component initialization), `quality`, and `size` (during component initialization or run) parameters.
+
+`DALLEImageGenerator` needs an OpenAI key to work. It uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```
+image_generator = DALLEImageGenerator(api_key=Secret.from_token("`revised_prompt`: A string containing the prompt that was used to generate the image, if there was any revision to the prompt made by OpenAI | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/openai_dalle.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `chat_generators`: A non-empty list of Chat Generator components to try in order |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: Generated ChatMessage instances from the first successful generator
`meta`: Execution metadata including successful generator details | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/fallback.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`FallbackChatGenerator` is a wrapper component that tries multiple Chat Generators sequentially until one succeeds. If a Generator fails, the component tries the next one in the list. This handles provider outages, rate limits, and other transient failures.
+
+The component forwards all parameters to the underlying Chat Generators and returns the first successful result. When a Generator raises any exception, the component tries the next Generator. This includes timeout errors, rate limit errors (429), authentication errors (401), context length errors (400), server errors (500+), and any other exception.
+
+The component returns execution metadata including which Generator succeeded, how many attempts were made, and which Generators failed. All parameters (`messages`, `generation_kwargs`, `tools`, `streaming_callback`) are forwarded to the underlying Generators.
+
+Timeout enforcement is delegated to the underlying Chat Generators. To control latency, configure your Chat Generators with a `timeout` parameter. Chat Generators like OpenAI, Anthropic, and Cohere support timeout parameters that raise exceptions when exceeded.
+
+### Monitoring and Telemetry
+
+The `meta` dictionary in the output contains useful information for monitoring:
+
+```python
+from haystack.components.generators.chat import (
+ FallbackChatGenerator,
+ OpenAIChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+
+## Set up generators
+primary = OpenAIChatGenerator(model="gpt-4o")
+backup = OpenAIChatGenerator(model="gpt-4o-mini")
+generator = FallbackChatGenerator(chat_generators=[primary, backup])
+
+## Run and inspect metadata
+result = generator.run(messages=[ChatMessage.from_user("Hello")])
+
+meta = result["meta"]
+print(
+ f"Successful generator index: {meta['successful_chat_generator_index']}",
+) # 0 for first, 1 for second, etc.
+print(
+ f"Successful generator class: {meta['successful_chat_generator_class']}",
+) # e.g., "OpenAIChatGenerator"
+print(
+ f"Total attempts made: {meta['total_attempts']}",
+) # How many Generators were tried
+print(
+ f"Failed generators: {meta['failed_chat_generators']}",
+) # List of failed Generator names
+```
+
+You can use this metadata to:
+
+- Track which Generators are being used most frequently
+- Monitor failure rates for each Generator
+- Set up alerts when fallbacks occur
+- Adjust Generator ordering based on success rates
+
+### Streaming
+
+`FallbackChatGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) through the `streaming_callback` parameter. The callback is passed directly to the underlying Generators.
+
+## Usage
+
+### On its own
+
+Basic usage with fallback from a primary to a backup model:
+
+```python
+from haystack.components.generators.chat import FallbackChatGenerator, OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+## Create primary and backup generators
+primary = OpenAIChatGenerator(model="gpt-4o", timeout=30)
+backup = OpenAIChatGenerator(model="gpt-4o-mini", timeout=30)
+
+## Wrap them in a FallbackChatGenerator
+generator = FallbackChatGenerator(chat_generators=[primary, backup])
+
+## Use it like any other Chat Generator
+messages = [ChatMessage.from_user("What's Natural Language Processing? Be brief.")]
+result = generator.run(messages=messages)
+
+print(result["replies"][0].text)
+print(f"Successful generator: {result['meta']['successful_chat_generator_class']}")
+print(f"Total attempts: {result['meta']['total_attempts']}")
+
+>> Natural Language Processing (NLP) is a field of artificial intelligence that
+>> focuses on the interaction between computers and humans through natural language...
+>> Successful generator: OpenAIChatGenerator
+>> Total attempts: 1
+```
+
+With multiple providers:
+
+```python
+from haystack.components.generators.chat import (
+ FallbackChatGenerator,
+ OpenAIChatGenerator,
+ AzureOpenAIChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+## Create generators from different providers
+openai_gen = OpenAIChatGenerator(
+ model="gpt-4o-mini",
+ api_key=Secret.from_env_var("OPENAI_API_KEY"),
+ timeout=30,
+)
+
+azure_gen = AzureOpenAIChatGenerator(
+ azure_endpoint="`meta`: Execution metadata including successful generator details | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/fallback.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Google AI Studio API key. Can be set with `GOOGLE_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of alternative replies of the model to the input chat |
+| **API reference** | [Google AI](/reference/integrations-google-ai) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_ai |
+| **Package name** | `google-ai-haystack` |
+
+
+
+`GoogleAIGeminiChatGenerator` supports `gemini-2.5-pro-exp-03-25`, `gemini-2.0-flash`, `gemini-1.5-pro`, and `gemini-1.5-flash` models.
+
+For available models, see https://ai.google.dev/gemini-api/docs/models/gemini.
+
+### Parameters Overview
+
+`GoogleAIGeminiChatGenerator` uses a Google Studio API key for authentication. You can write this key in an `api_key` parameter or as a `GOOGLE_API_KEY` environment variable (recommended).
+
+To get an API key, visit the [Google AI Studio](https://aistudio.google.com/) website.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+To begin working with `GoogleAIGeminiChatGenerator`, install the `google-ai-haystack` package:
+
+```shell
+pip install google-ai-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import os
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.google_ai import GoogleAIGeminiChatGenerator
+
+os.environ["GOOGLE_API_KEY"] = "
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Google AI Studio API key. Can be set with `GOOGLE_API_KEY` env var. |
+| **Mandatory run variables** | `parts`: A variadic list containing a mix of images, audio, video, and text to prompt Gemini |
+| **Output variables** | `replies`: A list of strings or dictionaries with all the replies generated by the model |
+| **API reference** | [Google AI](/reference/integrations-google-ai) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_ai |
+| **Package name** | `google-ai-haystack` |
+
+
+
+`GoogleAIGeminiGenerator` supports `gemini-2.5-pro-exp-03-25`, `gemini-2.0-flash`, `gemini-1.5-pro`, and `gemini-1.5-flash` models.
+
+For available models, see https://ai.google.dev/gemini-api/docs/models/gemini.
+
+### Parameters Overview
+
+`GoogleAIGeminiGenerator` uses a Google AI Studio API key for authentication. You can write this key in an `api_key` parameter or as a `GOOGLE_API_KEY` environment variable (recommended).
+
+To get an API key, visit the [Google AI Studio](https://ai.google.dev/gemini-api/docs/api-key) website.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Start by installing the `google-ai-haystack` package to use the `GoogleAIGeminiGenerator`:
+
+```shell
+pip install google-ai-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import os
+from haystack_integrations.components.generators.google_ai import GoogleAIGeminiGenerator
+
+os.environ["GOOGLE_API_KEY"] = "
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Google API key. Can be set with `GOOGLE_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of alternative replies of the model to the input chat |
+| **API reference** | [Google GenAI](/reference/integrations-google-genai) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai |
+| **Package name** | `google-genai-haystack` |
+
+
+
+## Overview
+
+`GoogleGenAIChatGenerator` supports Gemini generative models, such as
+`gemini-3.1-flash-lite-preview`, `gemini-3.1-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-flash`, `gemini-2.5-pro`, and `gemini-2.5-flash-lite`.
+
+### Tool Support
+
+`GoogleGenAIChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = GoogleGenAIChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+### Authentication
+
+Google Gen AI is compatible with both the Gemini Developer API and the Vertex AI API.
+
+To use this component with the Gemini Developer API and get an API key, visit [Google AI Studio](https://aistudio.google.com/).
+To use this component with the Vertex AI API, visit [Google Cloud > Vertex AI](https://cloud.google.com/vertex-ai).
+
+The component uses a `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` static method:
+
+```python
+embedder = GoogleGenAITextEmbedder(api_key=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_type`: The type of Hugging Face API to use
`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of replies of the LLM to the input chat | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/hugging_face_api.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`HuggingFaceAPIChatGenerator` can be used to generate chat completions using different Hugging Face APIs:
+
+- [Serverless Inference API (Inference Providers)](https://huggingface.co/docs/inference-providers) - free tier available
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
+
+This component's main input is a list of `ChatMessage` objects. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata. For more information, check out our [`ChatMessage` docs](../../concepts/data-classes/chatmessage.mdx).
+
+:::info
+This component is designed for chat completion, so it expects a list of messages, not a single string. If you want to use Hugging Face APIs for simple text generation (such as translation or summarization tasks) or don't want to use the `ChatMessage` object, use [`HuggingFaceAPIGenerator`](huggingfaceapigenerator.mdx) instead.
+:::
+
+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.
+The token is needed:
+
+- If you use the Serverless Inference API, or
+- If you use the Inference Endpoints.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+### On its own
+
+#### Using Serverless Inference API (Inference Providers) - Free Tier Available
+
+This API allows you to quickly experiment with many models hosted on the Hugging Face Hub, offloading the inference to Hugging Face servers. It's rate-limited and not meant for production.
+
+To use this API, you need a [free Hugging Face token](https://huggingface.co/settings/tokens).
+The Generator expects the `model` in `api_params`. It's also recommended to specify a `provider` for better performance and reliability.
+
+```python
+from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack.utils.hf import HFGenerationAPIType
+
+messages = [
+ ChatMessage.from_system("\\nYou are a helpful, respectful and honest assistant"),
+ ChatMessage.from_user("What's Natural Language Processing?"),
+]
+
+## the api_type can be expressed using the HFGenerationAPIType enum or as a string
+api_type = HFGenerationAPIType.SERVERLESS_INFERENCE_API
+api_type = "serverless_inference_api" # this is equivalent to the above
+
+generator = HuggingFaceAPIChatGenerator(
+ api_type=api_type,
+ api_params={"model": "Qwen/Qwen2.5-7B-Instruct", "provider": "together"},
+ token=Secret.from_env_var("HF_API_TOKEN"),
+)
+
+result = generator.run(messages)
+print(result)
+```
+
+#### Using Paid Inference Endpoints
+
+In this case, a private instance of the model is deployed by Hugging Face, and you typically pay per hour.
+
+To understand how to spin up an Inference Endpoint, visit [Hugging Face documentation](https://huggingface.co/inference-endpoints/dedicated).
+
+Additionally, in this case, you need to provide your Hugging Face token.
+The Generator expects the `url` of your endpoint in `api_params`.
+
+```python
+from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+messages = [
+ ChatMessage.from_system("\\nYou are a helpful, respectful and honest assistant"),
+ ChatMessage.from_user("What's Natural Language Processing?"),
+]
+
+generator = HuggingFaceAPIChatGenerator(
+ api_type="inference_endpoints",
+ api_params={"url": "`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of replies of the LLM to the input chat | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/hugging_face_api.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_type`: The type of Hugging Face API to use
`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and others | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/hugging_face_api.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`HuggingFaceAPIGenerator` can be used to generate text using different Hugging Face APIs:
+
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
+
+:::note[Important Note]
+
+As of July 2025, the Hugging Face Inference API no longer offers generative models through the `text_generation` endpoint. Generative models are now only available through providers supporting the `chat_completion` endpoint. As a result, this component might no longer work with the Hugging Face Inference API.
+
+Use the [`HuggingFaceAPIChatGenerator`](huggingfaceapichatgenerator.mdx) component instead, which supports the `chat_completion` endpoint and works with the free Serverless Inference API.
+:::
+
+:::info
+This component is designed for text generation, not for chat. If you want to use these LLMs for chat, use [`HuggingFaceAPIChatGenerator`](huggingfaceapichatgenerator.mdx) instead.
+:::
+
+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.
+The token is needed when you use the Inference Endpoints.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+### On its own
+
+#### Using Paid Inference Endpoints
+
+In this case, a private instance of the model is deployed by Hugging Face, and you typically pay per hour.
+
+To understand how to spin up an Inference Endpoint, visit [Hugging Face documentation](https://huggingface.co/inference-endpoints/dedicated).
+
+Additionally, in this case, you need to provide your Hugging Face token.
+The Generator expects the `url` of your endpoint in `api_params`.
+
+```python
+from haystack.components.generators import HuggingFaceAPIGenerator
+from haystack.utils import Secret
+
+generator = HuggingFaceAPIGenerator(
+ api_type="inference_endpoints",
+ api_params={"url": "`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and others | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/hugging_face_api.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.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** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM |
+| **API reference** | [Generators](/reference/generators-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/hugging_face_local.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+Keep in mind that if LLMs run locally, you may need a powerful machine to run them. This depends strongly on the model you select and its parameter count.
+
+:::info
+This component is designed for chat completion, not for text generation. If you want to use Hugging Face LLMs for text generation, use [`HuggingFaceLocalGenerator`](huggingfacelocalgenerator.mdx) instead.
+:::
+
+For remote file authorization, this component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with `token`:
+
+```python
+local_generator = HuggingFaceLocalChatGenerator(
+ token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.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** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM |
+| **API reference** | [Generators](/reference/generators-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/hugging_face_local.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+Keep in mind that if LLMs run locally, you may need a powerful machine to run them. This depends strongly on the model you select and its parameter count.
+
+:::info[Looking for chat completion?]
+
+This component is designed for text generation, not for chat. If you want to use Hugging Face LLMs for chat, consider using [`HuggingFaceLocalChatGenerator`](huggingfacelocalchatgenerator.mdx) instead.
+:::
+
+For remote files authorization, this component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with `token`:
+
+```python
+local_generator = HuggingFaceLocalGenerator(token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The path of the model to use |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) instances representing the input messages |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) instances with all the replies generated by the LLM |
+| **API reference** | [Llama.cpp](/reference/integrations-llama-cpp) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/llama_cpp |
+| **Package name** | `llama-cpp-haystack` |
+
+
+
+## Overview
+
+[Llama.cpp](https://github.com/ggml-org/llama.cpp) is a library written in C/C++ for efficient inference of Large Language Models. It leverages the efficient quantized GGUF format, dramatically reducing memory requirements and accelerating inference. This means it is possible to run LLMs efficiently on standard machines (even without GPUs).
+
+`Llama.cpp` uses the quantized binary file of the LLM in GGUF format, which can be downloaded from [Hugging Face](https://huggingface.co/models?library=gguf). `LlamaCppChatGenerator` supports models running on `Llama.cpp` by taking the path to the locally saved GGUF file as `model` parameter at initialization.
+
+### Tool Support
+
+`LlamaCppChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = LlamaCppChatGenerator(
+ model="/path/to/model.gguf",
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+## Installation
+
+Install the `llama-cpp-haystack` package to use this integration:
+
+```shell
+pip install llama-cpp-haystack
+```
+
+### Using a different compute backend
+
+The default installation behavior is to build `llama.cpp` for CPU on Linux and Windows and use Metal on MacOS. To use other compute backends:
+
+1. Follow instructions on the [llama.cpp installation page](https://github.com/abetlen/llama-cpp-python#installation) to install [llama-cpp-python](https://github.com/abetlen/llama-cpp-python) for your preferred compute backend.
+2. Install [llama-cpp-haystack](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/llama_cpp) using the command above.
+
+For example, to use `llama-cpp-haystack` with the **cuBLAS backend**, you have to run the following commands:
+
+```shell
+export GGML_CUDA=1
+CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python
+pip install llama-cpp-haystack
+```
+
+## Usage
+
+1. Download the GGUF version of the desired LLM. The GGUF versions of popular models can be downloaded from [Hugging Face](https://huggingface.co/models?library=gguf).
+2. Initialize `LlamaCppChatGenerator` with the path to the GGUF file and specify the required model and text generation parameters:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+
+generator = LlamaCppChatGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ model_kwargs={"n_gpu_layers": -1},
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+generator.warm_up()
+messages = [ChatMessage.from_user("Who is the best American actor?")]
+result = generator.run(messages)
+```
+
+### Passing additional model parameters
+
+The `model`, `n_ctx`, `n_batch` arguments have been exposed for convenience and can be directly passed to the Generator during initialization as keyword arguments. Note that `model` translates to `llama.cpp`'s `model_path` parameter.
+
+The `model_kwargs` parameter can pass additional arguments when initializing the model. In case of duplication, these parameters override the `model`, `n_ctx`, and `n_batch` initialization parameters.
+
+See [Llama.cpp's LLM documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.__init__) for more information on the available model arguments.
+
+**Note**: Llama.cpp automatically extracts the `chat_template` from the model metadata for applying formatting to ChatMessages. You can override the `chat_template` used by passing in a custom `chat_handler` or `chat_format` as a model parameter.
+
+For example, to offload the model to GPU during initialization:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = LlamaCppChatGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ model_kwargs={"n_gpu_layers": -1},
+)
+messages = [ChatMessage.from_user("Who is the best American actor?")]
+result = generator.run(messages, generation_kwargs={"max_tokens": 128})
+generated_reply = result["replies"][0].text
+print(generated_reply)
+```
+
+### Passing text generation parameters
+
+The `generation_kwargs` parameter can pass additional generation arguments like `max_tokens`, `temperature`, `top_k`, `top_p`, and others to the model during inference.
+
+See [Llama.cpp's Chat Completion API documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion) for more information on the available generation arguments.
+
+**Note**: JSON mode, Function Calling, and Tools are all supported as `generation_kwargs`. Please see the [llama-cpp-python GitHub README](https://github.com/abetlen/llama-cpp-python?tab=readme-ov-file#json-and-json-schema-mode) for more information on how to use them.
+
+For example, to set the `max_tokens` and `temperature`:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = LlamaCppChatGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+messages = [ChatMessage.from_user("Who is the best American actor?")]
+result = generator.run(messages)
+```
+
+### With multimodal (image + text) inputs
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+
+# Initialize with multimodal support
+llm = LlamaCppChatGenerator(
+ model="llava-v1.5-7b-q4_0.gguf",
+ chat_handler_name="Llava15ChatHandler", # Use llava-1-5 handler
+ model_clip_path="mmproj-model-f16.gguf", # CLIP model
+ n_ctx=4096, # Larger context for image processing
+)
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(
+ content_parts=["What does the image show? Max 5 words.", image],
+)
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+The `generation_kwargs` can also be passed to the `run` method of the generator directly:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = LlamaCppChatGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+)
+messages = [ChatMessage.from_user("Who is the best American actor?")]
+result = generator.run(
+ messages,
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+```
+
+### In a pipeline
+
+We use the `LlamaCppChatGenerator` in a Retrieval Augmented Generation pipeline on the [Simple Wikipedia](https://huggingface.co/datasets/pszemraj/simple_wikipedia) Dataset from Hugging Face and generate answers using the [OpenChat-3.5](https://huggingface.co/openchat/openchat-3.5-1210) LLM.
+
+Load the dataset:
+
+```python
+## Install HuggingFace Datasets using "pip install datasets"
+from datasets import load_dataset
+from haystack import Document, Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.embedders import (
+ SentenceTransformersDocumentEmbedder,
+ SentenceTransformersTextEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.dataclasses import ChatMessage
+
+## Import LlamaCppChatGenerator
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+
+## Load first 100 rows of the Simple Wikipedia Dataset from HuggingFace
+dataset = load_dataset("pszemraj/simple_wikipedia", split="validation[:100]")
+
+docs = [
+ Document(
+ content=doc["text"],
+ meta={
+ "title": doc["title"],
+ "url": doc["url"],
+ },
+ )
+ for doc in dataset
+]
+```
+
+Index the documents to the `InMemoryDocumentStore` using the `SentenceTransformersDocumentEmbedder` and `DocumentWriter`:
+
+```python
+doc_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+## Install sentence transformers using "pip install sentence-transformers"
+doc_embedder = SentenceTransformersDocumentEmbedder(
+ model="sentence-transformers/all-MiniLM-L6-v2",
+)
+
+## Indexing Pipeline
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(instance=doc_embedder, name="DocEmbedder")
+indexing_pipeline.add_component(
+ instance=DocumentWriter(document_store=doc_store),
+ name="DocWriter",
+)
+indexing_pipeline.connect("DocEmbedder", "DocWriter")
+
+indexing_pipeline.run({"DocEmbedder": {"documents": docs}})
+```
+
+Create the RAG pipeline and add the `LlamaCppChatGenerator` to it:
+
+```python
+system_message = ChatMessage.from_system(
+ """
+ Answer the question using the provided context.
+ Context:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+ """,
+)
+user_message = ChatMessage.from_user("Question: {{question}}")
+assistent_message = ChatMessage.from_assistant("Answer: ")
+
+chat_template = [system_message, user_message, assistent_message]
+
+rag_pipeline = Pipeline()
+
+text_embedder = SentenceTransformersTextEmbedder(
+ model="sentence-transformers/all-MiniLM-L6-v2",
+)
+
+## Load the LLM using LlamaCppChatGenerator
+model_path = "openchat-3.5-1210.Q3_K_S.gguf"
+generator = LlamaCppChatGenerator(model=model_path, n_ctx=4096, n_batch=128)
+
+rag_pipeline.add_component(
+ instance=text_embedder,
+ name="text_embedder",
+)
+rag_pipeline.add_component(
+ instance=InMemoryEmbeddingRetriever(document_store=doc_store, top_k=3),
+ name="retriever",
+)
+rag_pipeline.add_component(
+ instance=ChatPromptBuilder(template=chat_template),
+ name="prompt_builder",
+)
+rag_pipeline.add_component(instance=generator, name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+
+rag_pipeline.connect("text_embedder", "retriever")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+rag_pipeline.connect("llm", "answer_builder")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+```
+
+Run the pipeline:
+
+```python
+question = "Which year did the Joker movie release?"
+result = rag_pipeline.run(
+ {
+ "text_embedder": {"text": question},
+ "prompt_builder": {"question": question},
+ "llm": {"generation_kwargs": {"max_tokens": 128, "temperature": 0.1}},
+ "answer_builder": {"query": question},
+ },
+)
+
+generated_answer = result["answer_builder"]["answers"][0]
+print(generated_answer.data)
+## The Joker movie was released on October 4, 2019.
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/llamacppgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/llamacppgenerator.mdx
new file mode 100644
index 0000000000..e1216b76df
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/llamacppgenerator.mdx
@@ -0,0 +1,258 @@
+---
+title: "LlamaCppGenerator"
+id: llamacppgenerator
+slug: "/llamacppgenerator"
+description: "`LlamaCppGenerator` provides an interface to generate text using an LLM running on Llama.cpp."
+---
+
+# LlamaCppGenerator
+
+`LlamaCppGenerator` provides an interface to generate text using an LLM running on Llama.cpp.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The path of the model to use |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [Llama.cpp](/reference/integrations-llama-cpp) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/llama_cpp | +| **Package name** | `llama-cpp-haystack` | + +
+
+## Overview
+
+[Llama.cpp](https://github.com/ggml-org/llama.cpp) is a library written in C/C++ for efficient inference of Large Language Models. It leverages the efficient quantized GGUF format, dramatically reducing memory requirements and accelerating inference. This means it is possible to run LLMs efficiently on standard machines (even without GPUs).
+
+`Llama.cpp` uses the quantized binary file of the LLM in GGUF format that can be downloaded from [Hugging Face](https://huggingface.co/models?library=gguf). `LlamaCppGenerator` supports models running on `Llama.cpp` by taking the path to the locally saved GGUF file as `model` parameter at initialization.
+
+## Installation
+
+Install the `llama-cpp-haystack` package:
+
+```bash
+pip install llama-cpp-haystack
+```
+
+### Using a different compute backend
+
+The default installation behavior is to build `llama.cpp` for CPU on Linux and Windows and use Metal on MacOS. To use other compute backends:
+
+1. Follow instructions on the [llama.cpp installation page](https://github.com/abetlen/llama-cpp-python#installation) to install [llama-cpp-python](https://github.com/abetlen/llama-cpp-python) for your preferred compute backend.
+2. Install [llama-cpp-haystack](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/llama_cpp) using the command above.
+
+For example, to use `llama-cpp-haystack` with the **cuBLAS backend**, you have to run the following commands:
+
+```bash
+export GGML_CUDA=1
+CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python
+pip install llama-cpp-haystack
+```
+
+## Usage
+
+1. You need to download the GGUF version of the desired LLM. The GGUF versions of popular models can be downloaded from [Hugging Face](https://huggingface.co/models?library=gguf).
+2. Initialize a `LlamaCppGenerator` with the path to the GGUF file and also specify the required model and text generation parameters:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+
+generator = LlamaCppGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ model_kwargs={"n_gpu_layers": -1},
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+generator.warm_up()
+prompt = f"Who is the best American actor?"
+result = generator.run(prompt)
+```
+
+### Passing additional model parameters
+
+The `model`, `n_ctx`, `n_batch` arguments have been exposed for convenience and can be directly passed to the Generator during initialization as keyword arguments. Note that `model` translates to `llama.cpp`'s `model_path` parameter.
+
+The `model_kwargs` parameter can pass additional arguments when initializing the model. In case of duplication, these parameters override the `model`, `n_ctx`, and `n_batch` initialization parameters.
+
+See [Llama.cpp's LLM documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.__init__) for more information on the available model arguments.
+
+For example, to offload the model to GPU during initialization:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+
+generator = LlamaCppGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ model_kwargs={"n_gpu_layers": -1},
+)
+prompt = f"Who is the best American actor?"
+result = generator.run(prompt, generation_kwargs={"max_tokens": 128})
+generated_text = result["replies"][0]
+print(generated_text)
+```
+
+### Passing text generation parameters
+
+The `generation_kwargs` parameter can pass additional generation arguments like `max_tokens`, `temperature`, `top_k`, `top_p`, and others to the model during inference.
+
+See [Llama.cpp's Completion API documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_completion) for more information on the available generation arguments.
+
+For example, to set the `max_tokens` and `temperature`:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+
+generator = LlamaCppGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+prompt = f"Who is the best American actor?"
+result = generator.run(prompt)
+```
+
+The `generation_kwargs` can also be passed to the `run` method of the generator directly:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+
+generator = LlamaCppGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+)
+prompt = f"Who is the best American actor?"
+result = generator.run(
+ prompt,
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+```
+
+### Using in a Pipeline
+
+We use the `LlamaCppGenerator` in a Retrieval Augmented Generation pipeline on the [Simple Wikipedia](https://huggingface.co/datasets/pszemraj/simple_wikipedia) Dataset from HuggingFace and generate answers using the [OpenChat-3.5](https://huggingface.co/openchat/openchat-3.5-1210) LLM.
+
+Load the dataset:
+
+```python
+## Install HuggingFace Datasets using "pip install datasets"
+from datasets import load_dataset
+from haystack import Document, Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.embedders import (
+ SentenceTransformersDocumentEmbedder,
+ SentenceTransformersTextEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+## Import LlamaCppGenerator
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+
+## Load first 100 rows of the Simple Wikipedia Dataset from HuggingFace
+dataset = load_dataset("pszemraj/simple_wikipedia", split="validation[:100]")
+
+docs = [
+ Document(
+ content=doc["text"],
+ meta={
+ "title": doc["title"],
+ "url": doc["url"],
+ },
+ )
+ for doc in dataset
+]
+```
+
+Index the documents to the `InMemoryDocumentStore` using the `SentenceTransformersDocumentEmbedder` and `DocumentWriter`:
+
+```python
+doc_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+doc_embedder = SentenceTransformersDocumentEmbedder(
+ model="sentence-transformers/all-MiniLM-L6-v2",
+)
+
+## Indexing Pipeline
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(instance=doc_embedder, name="DocEmbedder")
+indexing_pipeline.add_component(
+ instance=DocumentWriter(document_store=doc_store),
+ name="DocWriter",
+)
+indexing_pipeline.connect(connect_from="DocEmbedder", connect_to="DocWriter")
+
+indexing_pipeline.run({"DocEmbedder": {"documents": docs}})
+```
+
+Create the Retrieval Augmented Generation (RAG) pipeline and add the `LlamaCppGenerator` to it:
+
+```python
+## Prompt Template for the https://huggingface.co/openchat/openchat-3.5-1210 LLM
+prompt_template = """GPT4 Correct User: Answer the question using the provided context.
+Question: {{question}}
+Context:
+{% for doc in documents %}
+ {{ doc.content }}
+{% endfor %}
+<|end_of_turn|>
+GPT4 Correct Assistant:
+"""
+
+rag_pipeline = Pipeline()
+
+text_embedder = SentenceTransformersTextEmbedder(
+ model="sentence-transformers/all-MiniLM-L6-v2",
+)
+
+## Load the LLM using LlamaCppGenerator
+model_path = "openchat-3.5-1210.Q3_K_S.gguf"
+generator = LlamaCppGenerator(model=model_path, n_ctx=4096, n_batch=128)
+
+rag_pipeline.add_component(
+ instance=text_embedder,
+ name="text_embedder",
+)
+rag_pipeline.add_component(
+ instance=InMemoryEmbeddingRetriever(document_store=doc_store, top_k=3),
+ name="retriever",
+)
+rag_pipeline.add_component(
+ instance=PromptBuilder(template=prompt_template),
+ name="prompt_builder",
+)
+rag_pipeline.add_component(instance=generator, name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+
+rag_pipeline.connect("text_embedder", "retriever")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+rag_pipeline.connect("llm.replies", "answer_builder.replies")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+```
+
+Run the pipeline:
+
+```python
+question = "Which year did the Joker movie release?"
+result = rag_pipeline.run(
+ {
+ "text_embedder": {"text": question},
+ "prompt_builder": {"question": question},
+ "llm": {"generation_kwargs": {"max_tokens": 128, "temperature": 0.1}},
+ "answer_builder": {"query": question},
+ },
+)
+
+generated_answer = result["answer_builder"]["answers"][0]
+print(generated_answer.data)
+## The Joker movie was released on October 4, 2019.
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/llamastackchatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/llamastackchatgenerator.mdx
new file mode 100644
index 0000000000..fb9fea7897
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/llamastackchatgenerator.mdx
@@ -0,0 +1,151 @@
+---
+title: "LlamaStackChatGenerator"
+id: llamastackchatgenerator
+slug: "/llamastackchatgenerator"
+description: "This component enables chat completions using any model made available by inference providers on a Llama Stack server."
+---
+
+# LlamaStackChatGenerator
+
+This component enables chat completions using any model made available by inference providers on a Llama Stack server.
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [Llama.cpp](/reference/integrations-llama-cpp) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/llama_cpp | +| **Package name** | `llama-cpp-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The name of the model to use for chat completion.
This depends on the inference provider used for the Llama Stack Server. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of alternative replies of the model to the input chat | +| **API reference** | [Llama Stack](/reference/integrations-llama-stack) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/llama_stack | +| **Package name** | `llama-stack-haystack` | + +
+
+## Overview
+
+[Llama Stack](https://llama-stack.readthedocs.io/en/latest/index.html) provides building blocks and unified APIs to streamline the development of AI applications across various environments.
+
+The `LlamaStackChatGenerator` enables you to access any LLMs exposed by inference providers hosted on a Llama Stack server. It abstracts away the underlying provider details, allowing you to reuse the same client-side code regardless of the inference backend. For a list of supported providers and configuration options, refer to the [Llama Stack documentation](https://llama-stack.readthedocs.io/en/latest/providers/inference/index.html).
+
+This component uses the same `ChatMessage` format as other Haystack Chat Generators for structured input and output. For more information, see the [ChatMessage documentation](../../concepts/data-classes/chatmessage.mdx).
+
+### Tool Support
+
+`LlamaStackChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.llama_stack import LlamaStackChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = LlamaStackChatGenerator(
+ model="ollama/llama3.2:3b",
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+## Initialization
+
+To use this integration, you must have:
+
+- A running instance of a Llama Stack server (local or remote)
+- A valid model name supported by your selected inference provider
+
+Then initialize the `LlamaStackChatGenerator` by specifying the `model` name or ID. The value depends on the inference provider running on your server.
+
+**Examples:**
+
+- For Ollama: `model="ollama/llama3.2:3b"`
+- For vLLM: `model="meta-llama/Llama-3.2-3B"`
+
+**Note:** Switching the inference provider only requires updating the model name.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+To start using this integration, install the package with:
+
+```shell
+pip install llama-stack-haystack
+```
+
+### On its own
+
+```python
+import os
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.llama_stack import (
+ LlamaStackChatGenerator,
+)
+
+client = LlamaStackChatGenerator(model="ollama/llama3.2:3b")
+response = client.run([ChatMessage.from_user("What are Agentic Pipelines? Be brief.")])
+print(response["replies"])
+```
+
+#### With Streaming
+
+```python
+import os
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.llama_stack import (
+ LlamaStackChatGenerator,
+)
+from haystack.components.generators.utils import print_streaming_chunk
+
+client = LlamaStackChatGenerator(
+ model="ollama/llama3.2:3b",
+ streaming_callback=print_streaming_chunk,
+)
+response = client.run([ChatMessage.from_user("What are Agentic Pipelines? Be brief.")])
+print(response["replies"])
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.llama_stack import (
+ LlamaStackChatGenerator,
+)
+
+prompt_builder = ChatPromptBuilder()
+llm = LlamaStackChatGenerator(model="ollama/llama3.2:3b")
+
+pipe = Pipeline()
+pipe.add_component("builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("builder.prompt", "llm.messages")
+
+messages = [
+ ChatMessage.from_system("Give brief answers."),
+ ChatMessage.from_user("Tell me about {{city}}"),
+]
+
+response = pipe.run(
+ data={"builder": {"template": messages, "template_variables": {"city": "Berlin"}}},
+)
+print(response)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/metallamachatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/metallamachatgenerator.mdx
new file mode 100644
index 0000000000..bc3822bab0
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/metallamachatgenerator.mdx
@@ -0,0 +1,207 @@
+---
+title: "MetaLlamaChatGenerator"
+id: metallamachatgenerator
+slug: "/metallamachatgenerator"
+description: "This component enables chat completion with any model hosted available with Meta Llama API."
+---
+
+# MetaLlamaChatGenerator
+
+This component enables chat completion with any model hosted available with Meta Llama API.
+
+This depends on the inference provider used for the Llama Stack Server. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of alternative replies of the model to the input chat | +| **API reference** | [Llama Stack](/reference/integrations-llama-stack) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/llama_stack | +| **Package name** | `llama-stack-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Meta Llama API key. Can be set with `LLAMA_API_KEY` env variable or passed to `init()` method. |
+| **Mandatory run variables** | `messages`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **API reference** | [Meta Llama API](/reference/integrations-meta-llama) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/meta_llama |
+| **Package name** | `meta-llama-haystack` |
+
+
+
+## Overview
+
+The `MetaLlamaChatGenerator` enables you to use multiple Meta Llama models by making chat completion calls to the Meta [Llama API](https://llama.developer.meta.com/?utm_source=partner-haystack&utm_medium=website). The default model is `Llama-4-Scout-17B-16E-Instruct-FP8`.
+
+Currently available models are:
+
+
+
+| | | | | |
+| --- | --- | --- | --- | --- |
+| Model ID | Input context length | Output context length | Input Modalities | Output Modalities |
+| `Llama-4-Scout-17B-16E-Instruct-FP8` | 128k | 4028 | Text, Image | Text |
+| `Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | Text, Image | Text |
+| `Llama-3.3-70B-Instruct` | 128k | 4028 | Text | Text |
+| `Llama-3.3-8B-Instruct` | 128k | 4028 | Text | Text |
+
+
+This component uses the same `ChatMessage` format as other Haystack Chat Generators for structured input and output. For more information, see the [ChatMessage documentation](../../concepts/data-classes/chatmessage.mdx).
+
+### Tool Support
+
+`MetaLlamaChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.meta_llama import MetaLlamaChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = MetaLlamaChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Initialization
+
+To use this integration, you must have a Meta Llama API key. You can provide it with the `LLAMA_API_KEY` environment variable or by using a [Secret](../../concepts/secret-management.mdx).
+
+Then, install the `meta-llama-haystack` integration:
+
+```shell
+pip install meta-llama-haystack
+```
+
+### Streaming
+
+`MetaLlamaChatGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM, allowing tokens to be emitted as they are generated. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.meta_llama import (
+ MetaLlamaChatGenerator,
+)
+
+llm = MetaLlamaChatGenerator()
+response = llm.run([ChatMessage.from_user("What are Agentic Pipelines? Be brief.")])
+print(response["replies"][0].text)
+```
+
+With streaming and model routing:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.meta_llama import (
+ MetaLlamaChatGenerator,
+)
+
+llm = MetaLlamaChatGenerator(
+ model="Llama-3.3-8B-Instruct",
+ streaming_callback=lambda chunk: print(chunk.content, end="", flush=True),
+)
+
+response = llm.run([ChatMessage.from_user("What are Agentic Pipelines? Be brief.")])
+
+## check the model used for the response
+print("\n\n Model used: ", response["replies"][0].meta["model"])
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.meta_llama import (
+ MetaLlamaChatGenerator,
+)
+
+llm = MetaLlamaChatGenerator(model="Llama-4-Scout-17B-16E-Instruct-FP8")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(
+ content_parts=["What does the image show? Max 5 words.", image],
+)
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+### In a pipeline
+
+```python
+## To run this example, you will need to set a `LLAMA_API_KEY` environment variable.
+
+from haystack import Document, Pipeline
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.utils import Secret
+
+from haystack_integrations.components.generators.meta_llama import (
+ MetaLlamaChatGenerator,
+)
+
+## Write documents to InMemoryDocumentStore
+document_store = InMemoryDocumentStore()
+document_store.write_documents(
+ [
+ Document(content="My name is Jean and I live in Paris."),
+ Document(content="My name is Mark and I live in Berlin."),
+ Document(content="My name is Giorgio and I live in Rome."),
+ ],
+)
+
+## Build a RAG pipeline
+prompt_template = [
+ ChatMessage.from_user(
+ "Given these documents, answer the question.\n"
+ "Documents:\n{% for doc in documents %}{{ doc.content }}{% endfor %}\n"
+ "Question: {{question}}\n"
+ "Answer:",
+ ),
+]
+
+## Define required variables explicitly
+prompt_builder = ChatPromptBuilder(
+ template=prompt_template,
+ required_variables={"question", "documents"},
+)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+llm = MetaLlamaChatGenerator(
+ api_key=Secret.from_env_var("LLAMA_API_KEY"),
+ streaming_callback=print_streaming_chunk,
+)
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm.messages")
+
+## Ask a question
+question = "Who lives in Paris?"
+rag_pipeline.run(
+ {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ },
+)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/mistralchatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/mistralchatgenerator.mdx
new file mode 100644
index 0000000000..2fe30287b1
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/mistralchatgenerator.mdx
@@ -0,0 +1,177 @@
+---
+title: "MistralChatGenerator"
+id: mistralchatgenerator
+slug: "/mistralchatgenerator"
+description: "This component enables chat completion using Mistral’s text generation models."
+---
+
+# MistralChatGenerator
+
+This component enables chat completion using Mistral’s text generation models.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Mistral API key. Can be set with `MISTRAL_API_KEY` env var. |
+| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | +| **Package name** | `mistral-haystack` | + +
+
+## Overview
+
+This integration supports Mistral’s models provided through the generative endpoint. For a full list of available models, check out the [Mistral documentation](https://docs.mistral.ai/platform/endpoints/#generative-endpoints).
+
+`MistralChatGenerator` needs a Mistral API key to work. You can write this key in:
+
+- The `api_key` init parameter using [Secret API](../../concepts/secret-management.mdx)
+- The `MISTRAL_API_KEY` environment variable (recommended)
+
+Currently, available models are:
+
+- `mistral-tiny` (default)
+- `mistral-small`
+- `mistral-medium`(soon to be deprecated)
+- `mistral-large-latest`
+- `codestral-latest`
+
+This component needs a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+Refer to the [Mistral API documentation](https://docs.mistral.ai/api/#operation/createChatCompletion) for more details on the parameters supported by the Mistral API, which you can provide with `generation_kwargs` when running the component.
+
+### Tool Support
+
+`MistralChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = MistralChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Install the `mistral-haystack` package to use the `MistralChatGenerator`:
+
+```shell
+pip install mistral-haystack
+```
+
+#### On its own
+
+```python
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+generator = MistralChatGenerator(
+ api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+ streaming_callback=print_streaming_chunk,
+)
+message = ChatMessage.from_user("What's Natural Language Processing? Be brief.")
+print(generator.run([message]))
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+
+llm = MistralChatGenerator(model="pixtral-12b-2409")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(
+ content_parts=["What does the image show? Max 5 words.", image],
+)
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+#### In a Pipeline
+
+Below is an example RAG Pipeline where we answer questions based on the URL contents. We add the contents of the URL into our `messages` in the `ChatPromptBuilder` and generate an answer with the `MistralChatGenerator`.
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.components.fetchers import LinkContentFetcher
+from haystack.components.converters import HTMLToDocument
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+
+fetcher = LinkContentFetcher()
+converter = HTMLToDocument()
+prompt_builder = ChatPromptBuilder(variables=["documents"])
+llm = MistralChatGenerator(
+ streaming_callback=print_streaming_chunk,
+ model="mistral-small",
+)
+
+message_template = """Answer the following question based on the contents of the article: {{query}}\n
+ Article: {{documents[0].content}} \n
+ """
+messages = [ChatMessage.from_user(message_template)]
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(name="fetcher", instance=fetcher)
+rag_pipeline.add_component(name="converter", instance=converter)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+
+rag_pipeline.connect("fetcher.streams", "converter.sources")
+rag_pipeline.connect("converter.documents", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder.prompt", "llm.messages")
+
+question = "What are the capabilities of Mixtral?"
+
+result = rag_pipeline.run(
+ {
+ "fetcher": {"urls": ["https://mistral.ai/news/mixtral-of-experts"]},
+ "prompt_builder": {
+ "template_variables": {"query": question},
+ "template": messages,
+ },
+ "llm": {"generation_kwargs": {"max_tokens": 165}},
+ },
+)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Web QA with Mixtral-8x7B-Instruct-v0.1](https://haystack.deepset.ai/cookbook/mixtral-8x7b-for-web-qa)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/nvidiachatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/nvidiachatgenerator.mdx
new file mode 100644
index 0000000000..b5e4de7419
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/nvidiachatgenerator.mdx
@@ -0,0 +1,164 @@
+---
+title: "NvidiaChatGenerator"
+id: nvidiachatgenerator
+slug: "/nvidiachatgenerator"
+description: "This Generator enables chat completion using NVIDIA-hosted models."
+---
+
+# NvidiaChatGenerator
+
+This Generator enables chat completion using NVIDIA-hosted models.
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | +| **Package name** | `mistral-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: API key for the NVIDIA NIM. Can be set with `NVIDIA_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **API reference** | [NVIDIA API](https://build.nvidia.com/models) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia |
+| **Package name** | `nvidia-haystack` |
+
+
+
+## Overview
+
+`NvidiaChatGenerator` enables chat completions using NVIDIA generative models via the NVIDIA API. It is compatible with the [ChatMessage](../../concepts/data-classes/chatmessage.mdx) format for both input and output, ensuring seamless integration in chat-based pipelines.
+
+You can use LLMs self-hosted with NVIDIA NIM or models hosted on the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover). The default model for this component is `meta/llama-3.1-8b-instruct`.
+
+To use this integration, you must have an NVIDIA API key. You can provide it with the `NVIDIA_API_KEY` environment variable or by using a [Secret](../../concepts/secret-management.mdx).
+
+### Tool support
+
+`NvidiaChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = NvidiaChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, refer to the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+This generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+## Usage
+
+To start using `NvidiaChatGenerator`, install the `nvidia-haystack` package:
+
+```shell
+pip install nvidia-haystack
+```
+
+You can use `NvidiaChatGenerator` with all the LLMs available in the [NVIDIA API Catalog](https://docs.api.nvidia.com/nim/reference) or with a model deployed using NVIDIA NIM. For more information, refer to the [NVIDIA NIM for LLMs Playbook](https://developer.nvidia.com/docs/nemo-microservices/inference/playbooks/nmi_playbook.html).
+
+### On its own
+
+To use LLMs from the NVIDIA API Catalog, specify the `api_url` if needed (the default is `https://integrate.api.nvidia.com/v1`) and your API key. You can get your API key from the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover).
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+
+generator = NvidiaChatGenerator(
+ model="meta/llama-3.1-8b-instruct",
+ api_key=Secret.from_env_var("NVIDIA_API_KEY"),
+)
+
+messages = [ChatMessage.from_user("What's Natural Language Processing? Be brief.")]
+result = generator.run(messages)
+print(result["replies"])
+print(result["meta"])
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack.utils import Secret
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+
+llm = NvidiaChatGenerator(
+ model="meta/llama-3.2-11b-vision-instruct",
+ api_key=Secret.from_env_var("NVIDIA_API_KEY"),
+)
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(
+ content_parts=[
+ "What does the image show? Max 5 words.",
+ image,
+ ],
+)
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+# Red apple on straw.
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component(
+ "llm",
+ NvidiaChatGenerator(
+ model="meta/llama-3.1-8b-instruct",
+ api_key=Secret.from_env_var("NVIDIA_API_KEY"),
+ ),
+)
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system(
+ "You are an assistant giving out valuable information to language learners.",
+)
+messages = [
+ system_message,
+ ChatMessage.from_user("What's the official language of {{ country }}?"),
+]
+
+res = pipe.run(
+ data={
+ "prompt_builder": {
+ "template_variables": {"country": country},
+ "template": messages,
+ },
+ },
+)
+print(res)
+```
+
+## Related
+
+- Cookbook: [Haystack RAG Pipeline with Self-Deployed AI models using NVIDIA NIMs](https://haystack.deepset.ai/cookbook/rag-with-nims)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/nvidiagenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/nvidiagenerator.mdx
new file mode 100644
index 0000000000..2db25c183e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/nvidiagenerator.mdx
@@ -0,0 +1,148 @@
+---
+title: "NvidiaGenerator"
+id: nvidiagenerator
+slug: "/nvidiagenerator"
+description: "This Generator enables text generation using NVIDIA-hosted models."
+---
+
+# NvidiaGenerator
+
+This Generator enables text generation using NVIDIA-hosted models.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: API key for the NVIDIA NIM. Can be set with `NVIDIA_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [NVIDIA](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | +| **Package name** | `nvidia-haystack` | + +
+
+## Overview
+
+`NvidiaGenerator` provides an interface for generating text using LLMs self-hosted with NVIDIA NIM or models hosted on the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover).
+
+## Usage
+
+To start using `NvidiaGenerator`, install the `nvidia-haystack` package:
+
+```shell
+pip install nvidia-haystack
+```
+
+You can use `NvidiaGenerator` with all the LLMs available in the [NVIDIA API Catalog](https://docs.api.nvidia.com/nim/reference) or with a model deployed using NVIDIA NIM. For more information, refer to the [NVIDIA NIM for LLMs Playbook](https://developer.nvidia.com/docs/nemo-microservices/inference/playbooks/nmi_playbook.html).
+
+### On its own
+
+To use LLMs from the NVIDIA API Catalog, specify the `api_url` and your API key. You can get your API key from the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover).
+
+`NvidiaGenerator` uses the `NVIDIA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with the `api_key` parameter:
+
+```python
+from haystack.utils.auth import Secret
+from haystack_integrations.components.generators.nvidia import NvidiaGenerator
+
+generator = NvidiaGenerator(
+ model="meta/llama-3.1-70b-instruct",
+ api_url="https://integrate.api.nvidia.com/v1",
+ api_key=Secret.from_token("`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [NVIDIA](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | +| **Package name** | `nvidia-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of LLM’s alternative replies |
+| **API reference** | [Ollama](/reference/integrations-ollama) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama |
+| **Package name** | `ollama-haystack` |
+
+
+
+## Overview
+
+[Ollama](https://github.com/jmorganca/ollama) is a project focused on running LLMs locally. Internally, it uses the quantized GGUF format by default. This means it is possible to run LLMs on standard machines (even without GPUs) without having to handle complex installation procedures.
+
+`OllamaChatGenerator` supports models running on Ollama, such as `llama2` and `mixtral`. Find the full list of supported models [here](https://ollama.ai/library).
+
+`OllamaChatGenerator` needs a `model` name and a `url` to work. By default, it uses `"orca-mini"` model and `"http://localhost:11434"` url.
+
+The way to operate with `OllamaChatGenerator` is by using `ChatMessage` objects. [ChatMessage](../../concepts/data-classes/chatmessage.mdx) is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata. See the [usage](#usage) section for an example.
+
+### Tool Support
+
+`OllamaChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.ollama import OllamaChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = OllamaChatGenerator(
+ model="llama2",
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+You can stream output as it’s generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+## Configure any `Generator` or `ChatGenerator` with a streaming callback
+component = SomeGeneratorOrChatGenerator(streaming_callback=print_streaming_chunk)
+
+## If this is a `ChatGenerator`, pass a list of messages:
+## from haystack.dataclasses import ChatMessage
+## component.run([ChatMessage.from_user("Your question here")])
+
+## If this is a (non-chat) `Generator`, pass a prompt:
+## component.run({"prompt": "Your prompt here"})
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+### Streaming with Tools
+
+You can combine streaming with tool calling. Pass both `tools` and `streaming_callback`; when the model decides to invoke a tool, the streamed chunks carry tool-call deltas instead of text tokens, and the final reconstructed `ChatMessage` exposes the resolved `tool_calls` list on `replies[0]`.
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.dataclasses.streaming_chunk import StreamingChunk
+from haystack.tools import create_tool_from_function
+from haystack_integrations.components.generators.ollama import OllamaChatGenerator
+
+
+def get_weather(city: str) -> str:
+ """Get current weather for a city."""
+ return f"Sunny, 22°C in {city}"
+
+
+def callback(chunk: StreamingChunk) -> None:
+ if chunk.tool_calls:
+ print(f"[tool delta] {chunk.tool_calls}")
+ elif chunk.content:
+ print(chunk.content, end="", flush=True)
+
+
+generator = OllamaChatGenerator(
+ model="llama3.1:8b",
+ generation_kwargs={"temperature": 0.0},
+ tools=[create_tool_from_function(get_weather)],
+ streaming_callback=callback,
+)
+
+response = generator.run(
+ messages=[ChatMessage.from_user(
+ "What's the weather in Berlin? Use the get_weather tool."
+ )]
+)
+
+# Final reconstructed message: tool_calls populated, text is None
+assistant_message = response["replies"][0]
+print(assistant_message.tool_calls)
+# -> [ToolCall(tool_name='get_weather', arguments={'city': 'Berlin'}, ...)]
+```
+
+You can use the built-in `print_streaming_chunk` callback (which handles both text tokens and tool events) instead of writing your own.
+
+## Usage
+
+1. You need a running instance of Ollama. The installation instructions are [in the Ollama GitHub repository](https://github.com/jmorganca/ollama).
+ A fast way to run Ollama is using Docker:
+
+```bash
+docker run -d -p 11434:11434 --name ollama ollama/ollama:latest
+```
+
+2. You need to download or pull the desired LLM. The model library is available on the [Ollama website](https://ollama.ai/library).
+ If you are using Docker, you can, for example, pull the Zephyr model:
+
+```bash
+docker exec ollama ollama pull zephyr
+```
+
+If you already installed Ollama in your system, you can execute:
+
+```bash
+ollama pull zephyr
+```
+
+:::tip[Choose a specific version of a model]
+
+You can also specify a tag to choose a specific (quantized) version of your model. The available tags are shown in the model card of the Ollama models library. This is an [example](https://ollama.ai/library/zephyr/tags) for Zephyr.
+In this case, simply run
+
+```shell
+# ollama pull model:tag
+ollama pull zephyr:7b-alpha-q3_K_S
+```
+:::
+
+3. You also need to install the `ollama-haystack` package:
+
+```bash
+pip install ollama-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.ollama import OllamaChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = OllamaChatGenerator(model="zephyr",
+ url = "http://localhost:11434",
+ generation_kwargs={
+ "num_predict": 100,
+ "temperature": 0.9,
+ })
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
+ChatMessage.from_user("What's Natural Language Processing?")]
+
+print(generator.run(messages=messages))
+>> {
+ "replies": [
+ ChatMessage(
+ _role=
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | +| **Package name** | `ollama-haystack` | + +
+
+## Overview
+
+`OllamaGenerator` provides an interface to generate text using an LLM running on Ollama.
+
+`OllamaGenerator` needs a `model` name and a `url` to work. By default, it uses `"orca-mini"` model and `"http://localhost:11434"` url.
+
+[Ollama](https://github.com/jmorganca/ollama) is a project focused on running LLMs locally. Internally, it uses the quantized GGUF format by default. This means it is possible to run LLMs on standard machines (even without GPUs) without having to go through complex installation procedures.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+1. You need a running instance of Ollama. You can find the installation instructions [here](https://github.com/jmorganca/ollama).
+ A fast way to run Ollama is using Docker:
+
+```shell
+docker run -d -p 11434:11434 --name ollama ollama/ollama:latest
+```
+
+2. You need to download or pull the desired LLM. The model library is available on the [Ollama website](https://ollama.ai/library).
+ If you are using Docker, you can, for example, pull the Zephyr model:
+
+```shell
+docker exec ollama ollama pull zephyr
+```
+
+If you have already installed Ollama in your system, you can execute:
+
+```shell
+ollama pull zephyr
+```
+
+:::tip[Choose a specific version of a model]
+
+You can also specify a tag to choose a specific (quantized) version of your model. The available tags are shown in the model card of the Ollama models library. This is an [example](https://ollama.ai/library/zephyr/tags) for Zephyr.
+In this case, simply run
+
+```shell
+# ollama pull model:tag
+ollama pull zephyr:7b-alpha-q3_K_S
+```
+:::
+
+3. You also need to install the `ollama-haystack` package:
+
+```shell
+pip install ollama-haystack
+```
+
+### On its own
+
+Here's how the `OllamaGenerator` would work just on its own:
+
+```python
+from haystack_integrations.components.generators.ollama import OllamaGenerator
+
+generator = OllamaGenerator(
+ model="zephyr",
+ url="http://localhost:11434",
+ generation_kwargs={
+ "num_predict": 100,
+ "temperature": 0.9,
+ },
+)
+
+print(generator.run("Who is the best American actor?"))
+
+## {'replies': ['I do not have the ability to form opinions or preferences.
+## However, some of the most acclaimed american actors in recent years include
+## denzel washington, tom hanks, leonardo dicaprio, matthew mcconaughey...'],
+## 'meta': [{'model': 'zephyr', ...}]}
+```
+
+### In a Pipeline
+
+```python
+from haystack_integrations.components.generators.ollama import OllamaGenerator
+
+from haystack import Pipeline, Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: {{ query }}?
+"""
+
+docstore = InMemoryDocumentStore()
+docstore.write_documents(
+ [
+ Document(content="I really like summer"),
+ Document(content="My favorite sport is soccer"),
+ Document(content="I don't like reading sci-fi books"),
+ Document(content="I don't like crowded places"),
+ ],
+)
+
+generator = OllamaGenerator(
+ model="zephyr",
+ url="http://localhost:11434",
+ generation_kwargs={
+ "num_predict": 100,
+ "temperature": 0.9,
+ },
+)
+
+pipe = Pipeline()
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("llm", generator)
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "llm")
+
+result = pipe.run({"prompt_builder": {"query": query}, "retriever": {"query": query}})
+
+print(result)
+
+## {'llm': {'replies': ['Based on the provided context, it seems that you enjoy
+## soccer and summer. Unfortunately, there is no direct information given about
+## what else you enjoy...'],
+## 'meta': [{'model': 'zephyr', ...]}}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/openaichatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/openaichatgenerator.mdx
new file mode 100644
index 0000000000..340c8fda7c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/openaichatgenerator.mdx
@@ -0,0 +1,275 @@
+---
+title: "OpenAIChatGenerator"
+id: openaichatgenerator
+slug: "/openaichatgenerator"
+description: "`OpenAIChatGenerator` enables chat completion using OpenAI’s large language models (LLMs)."
+---
+
+# OpenAIChatGenerator
+
+`OpenAIChatGenerator` enables chat completion using OpenAI's large language models (LLMs).
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | +| **Package name** | `ollama-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of alternative replies of the LLM to the input chat |
+| **API reference** | [Generators](/reference/generators-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/openai.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`OpenAIChatGenerator` supports OpenAI models starting from gpt-3.5-turbo and later (gpt-4, gpt-4-turbo, and so on).
+
+`OpenAIChatGenerator` needs an OpenAI key to work. It uses an ` OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+generator = OpenAIChatGenerator(model="gpt-4o-mini")
+```
+
+Then, the component needs a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata. See the [usage](#usage) section for an example.
+
+You can pass any chat completion parameters valid for the `openai.ChatCompletion.create` method directly to `OpenAIChatGenerator` using the `generation_kwargs` parameter, both at initialization and to `run()` method. For more details on the parameters supported by the OpenAI API, refer to the [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
+
+`OpenAIChatGenerator` can support custom deployments of your OpenAI models through the `api_base_url` init parameter.
+
+### Structured Output
+
+`OpenAIChatGenerator` supports structured output generation, allowing you to receive responses in a predictable format. You can use Pydantic models or JSON schemas to define the structure of the output through the `response_format` parameter in `generation_kwargs`.
+
+This is useful when you need to extract structured data from text or generate responses that match a specific format.
+
+```python
+from pydantic import BaseModel
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+class NobelPrizeInfo(BaseModel):
+ recipient_name: str
+ award_year: int
+ category: str
+ achievement_description: str
+ nationality: str
+
+client = OpenAIChatGenerator(
+ model="gpt-4o-2024-08-06",
+ generation_kwargs={"response_format": NobelPrizeInfo}
+)
+
+response = client.run(messages=[
+ ChatMessage.from_user(
+ "In 2021, American scientist David Julius received the Nobel Prize in"
+ " Physiology or Medicine for his groundbreaking discoveries on how the human body"
+ " senses temperature and touch."
+ )
+])
+print(response["replies"][0].text)
+
+>> {"recipient_name":"David Julius","award_year":2021,"category":"Physiology or Medicine",
+>> "achievement_description":"David Julius was awarded for his transformative findings
+>> regarding the molecular mechanisms underlying the human body's sense of temperature
+>> and touch. Through innovative experiments, he identified specific receptors responsible
+>> for detecting heat and mechanical stimuli, ranging from gentle touch to pain-inducing
+>> pressure.","nationality":"American"}
+```
+
+:::info[Model Compatibility and Limitations]
+
+- Pydantic models and JSON schemas are supported for latest models starting from `gpt-4o-2024-08-06`.
+- Older models only support basic JSON mode through `{"type": "json_object"}`. For details, see [OpenAI JSON mode documentation](https://platform.openai.com/docs/guides/structured-outputs#json-mode).
+- Streaming limitation: When using streaming with structured outputs, you must provide a JSON schema instead of a Pydantic model for `response_format`.
+- For complete information, check the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+:::
+
+### Streaming
+
+You can stream output as it’s generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+## Configure any `Generator` or `ChatGenerator` with a streaming callback
+component = SomeGeneratorOrChatGenerator(streaming_callback=print_streaming_chunk)
+
+## If this is a `ChatGenerator`, pass a list of messages:
+## from haystack.dataclasses import ChatMessage
+## component.run([ChatMessage.from_user("Your question here")])
+
+## If this is a (non-chat) `Generator`, pass a prompt:
+## component.run({"prompt": "Your prompt here"})
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+## Usage
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+client = OpenAIChatGenerator()
+response = client.run(
+ [ChatMessage.from_user("What's Natural Language Processing? Be brief.")]
+)
+print(response)
+
+>> {'replies': [ChatMessage(_role=
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/openai.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`OpenAIGenerator` supports OpenAI models starting from gpt-3.5-turbo and later (gpt-4, gpt-4-turbo, and so on).
+
+`OpenAIGenerator` needs an OpenAI key to work. It uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```
+generator = OpenAIGenerator(api_key=Secret.from_token("`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/openai.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects containing the generated responses |
+| **API reference** | [Generators](/reference/generators-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/openai_responses.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`OpenAIResponsesChatGenerator` uses OpenAI's Responses API to generate chat completions. It supports gpt-4 and o-series models (reasoning models like o1, o3-mini). The default model is `gpt-5-mini`.
+
+The Responses API is designed for reasoning-capable models and supports features like reasoning summaries, multi-turn conversations with previous response IDs, and structured outputs.
+
+The component requires a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`), and optional metadata. See the [usage](#usage) section for examples.
+
+You can pass any parameters valid for the OpenAI Responses API directly to `OpenAIResponsesChatGenerator` using the `generation_kwargs` parameter, both at initialization and to the `run()` method. For more details on the parameters supported by the OpenAI API, refer to the [OpenAI Responses API documentation](https://platform.openai.com/docs/api-reference/responses).
+
+`OpenAIResponsesChatGenerator` can support custom deployments of your OpenAI models through the `api_base_url` init parameter.
+
+### Authentication
+
+`OpenAIResponsesChatGenerator` needs an OpenAI key to work. It uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key` using a [`Secret`](../../concepts/secret-management.mdx):
+
+```python
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.utils import Secret
+
+generator = OpenAIResponsesChatGenerator(api_key=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An OpenRouter API key. Can be set with `OPENROUTER_API_KEY` env variable or passed to `init()` method. |
+| **Mandatory run variables** | `messages`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **API reference** | [OpenRouter](/reference/integrations-openrouter) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/openrouter |
+| **Package name** | `openrouter-haystack` |
+
+
+
+## Overview
+
+The `OpenRouterChatGenerator` enables you to use models from multiple providers (such as `openai/gpt-4o`, `anthropic/claude-3.5-sonnet`, and others) by making chat completion calls to the [OpenRouter API](https://openrouter.ai/docs/quickstart).
+
+This generator also supports OpenRouter-specific features such as:
+
+- Provider routing and model fallback that are configurable with the `generation_kwargs` parameter during initialization or runtime.
+- Custom HTTP headers that can be supplied using the `extra_headers` parameter.
+
+This component uses the same `ChatMessage` format as other Haystack Chat Generators for structured input and output. For more information, see the [ChatMessage documentation](../../concepts/data-classes/chatmessage.mdx).
+
+### Tool Support
+
+`OpenRouterChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = OpenRouterChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Initialization
+
+To use this integration, you must have an active OpenRouter subscription with sufficient credits and an API key. You can provide it with the `OPENROUTER_API_KEY` environment variable or by using a [Secret](../../concepts/secret-management.mdx).
+
+Then, install the `openrouter-haystack` integration:
+
+```shell
+pip install openrouter-haystack
+```
+
+### Streaming
+
+`OpenRouterChatGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM, allowing tokens to be emitted as they are generated. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.openrouter import (
+ OpenRouterChatGenerator,
+)
+
+client = OpenRouterChatGenerator()
+response = client.run([ChatMessage.from_user("What are Agentic Pipelines? Be brief.")])
+print(response["replies"][0].text)
+```
+
+With streaming and model routing:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.openrouter import (
+ OpenRouterChatGenerator,
+)
+
+client = OpenRouterChatGenerator(
+ model="openrouter/auto",
+ streaming_callback=lambda chunk: print(chunk.content, end="", flush=True),
+)
+
+response = client.run([ChatMessage.from_user("What are Agentic Pipelines? Be brief.")])
+
+## check the model used for the response
+print("\n\n Model used: ", response["replies"][0].meta["model"])
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.openrouter import (
+ OpenRouterChatGenerator,
+)
+
+llm = OpenRouterChatGenerator(model="anthropic/claude-3-5-sonnet")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(
+ content_parts=["What does the image show? Max 5 words.", image],
+)
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.openrouter import (
+ OpenRouterChatGenerator,
+)
+
+prompt_builder = ChatPromptBuilder()
+llm = OpenRouterChatGenerator(model="openai/gpt-4o-mini")
+
+pipe = Pipeline()
+pipe.add_component("builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("builder.prompt", "llm.messages")
+
+messages = [
+ ChatMessage.from_system("Give brief answers."),
+ ChatMessage.from_user("Tell me about {{city}}"),
+]
+
+response = pipe.run(
+ data={"builder": {"template": messages, "template_variables": {"city": "Berlin"}}},
+)
+print(response)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/sagemakergenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/sagemakergenerator.mdx
new file mode 100644
index 0000000000..4aab3d548a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/sagemakergenerator.mdx
@@ -0,0 +1,108 @@
+---
+title: "SagemakerGenerator"
+id: sagemakergenerator
+slug: "/sagemakergenerator"
+description: "This component enables text generation using LLMs deployed on Amazon Sagemaker."
+---
+
+# SagemakerGenerator
+
+This component enables text generation using LLMs deployed on Amazon Sagemaker.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The model to use
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Amazon Sagemaker](/reference/integrations-amazon-sagemaker) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_sagemaker | +| **Package name** | `amazon-sagemaker-haystack` | + +
+
+`SagemakerGenerator` allows you to make use of models deployed on [AWS SageMaker](https://docs.aws.amazon.com/sagemaker/latest/dg/whatis.html).
+
+## Parameters Overview
+
+`SagemakerGenerator` needs AWS credentials to work. Set the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.
+
+You also need to specify your Sagemaker endpoint at initialization time for the component to work. Pass the endpoint name to the `model` parameter like this:
+
+```python
+generator = SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-instruct-bf16")
+```
+
+Additionally, you can pass any text generation parameters valid for your specific model directly to `SagemakerGenerator` using the `generation_kwargs` parameter, both at initialization and to `run()` method.
+
+If your model also needs custom attributes, pass those as a dictionary at initialization time by setting the `aws_custom_attributes` parameter.
+
+One notable family of models that needs these custom parameters is Llama2, which needs to be initialized with `{"accept_eula": True}` :
+
+```python
+generator = SagemakerGenerator(
+ model="jumpstart-dft-meta-textgenerationneuron-llama-2-7b",
+ aws_custom_attributes={"accept_eula": True},
+)
+```
+
+## Usage
+
+You need to install `amazon-sagemaker-haystack` package to use the `SagemakerGenerator`:
+
+```shell
+pip install amazon-sagemaker-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.amazon_sagemaker import SagemakerGenerator
+
+client = SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-instruct-bf16")
+response = client.run("Briefly explain what NLP is in one sentence.")
+print(response)
+
+>>> {'replies': ["Natural Language Processing (NLP) is a subfield of artificial intelligence and computational linguistics that focuses on the interaction between computers and human languages..."],
+ 'metadata': [{}]}
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack_integrations.components.generators.amazon_sagemaker import (
+ SagemakerGenerator,
+)
+from haystack import Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders import PromptBuilder
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: What's the official language of {{ country }}?
+"""
+pipe = Pipeline()
+
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component(
+ "llm",
+ SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-instruct-bf16"),
+)
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "llm")
+
+pipe.run({"prompt_builder": {"country": "France"}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/stackitchatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/stackitchatgenerator.mdx
new file mode 100644
index 0000000000..744dbd58f3
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/stackitchatgenerator.mdx
@@ -0,0 +1,120 @@
+---
+title: "STACKITChatGenerator"
+id: stackitchatgenerator
+slug: "/stackitchatgenerator"
+description: "This component enables chat completions using the STACKIT API."
+---
+
+# STACKITChatGenerator
+
+This component enables chat completions using the STACKIT API.
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Amazon Sagemaker](/reference/integrations-amazon-sagemaker) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_sagemaker | +| **Package name** | `amazon-sagemaker-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The model used through the STACKIT API |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply (such as token count, finish reason, and so on) | +| **API reference** | [STACKIT](/reference/integrations-stackit) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit | +| **Package name** | `stackit-haystack` | + +
+
+## Overview
+
+`STACKITChatGenerator` enables text generation models served by STACKIT through their API.
+
+### Parameters
+
+To use the `STACKITChatGenerator`, ensure you have set a `STACKIT_API_KEY` as an environment variable. Alternatively, provide the API key as another environment variable or a token by setting
+`api_key` and using Haystack’s [secret management](../../concepts/secret-management.mdx).
+
+Set your preferred supported model with the `model` parameter when initializing the component. See the full list of all supported models on the [STACKIT website](https://docs.stackit.cloud/stackit/en/models-licenses-319914532.html).
+
+Optionally, you can change the default `api_base_url`, which is `"https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1"`.
+
+You can pass any text generation parameters valid for the STACKIT Chat Completion API directly to this component with the `generation_kwargs` parameter in the init or run methods.
+
+The component needs a list of `ChatMessage` objects to run. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata. Find out more about it [ChatMessage documentation](../../concepts/data-classes/chatmessage.mdx).
+
+### Streaming
+
+This ChatGenerator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly into the output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Install the `stackit-haystack` package to use the `STACKITChatGenerator`:
+
+```shell
+pip install stackit-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.stackit import STACKITChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = STACKITChatGenerator(model="neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8")
+
+result = generator.run([ChatMessage.from_user("Tell me a joke.")])
+print(result)
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.stackit import STACKITChatGenerator
+
+llm = STACKITChatGenerator(model="meta-llama/Llama-3.2-11B-Vision-Instruct")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(
+ content_parts=["What does the image show? Max 5 words.", image],
+)
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+### In a pipeline
+
+You can also use `STACKITChatGenerator` in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.components.generators.stackit import STACKITChatGenerator
+
+prompt_builder = ChatPromptBuilder()
+llm = STACKITChatGenerator(model="neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8")
+
+messages = [ChatMessage.from_user("Question: {{question}} \\n")]
+
+pipeline = Pipeline()
+pipeline.add_component("prompt_builder", prompt_builder)
+pipeline.add_component("llm", llm)
+
+pipeline.connect("prompt_builder.prompt", "llm.messages")
+
+result = pipeline.run(
+ {
+ "prompt_builder": {
+ "template_variables": {"question": "Tell me a joke."},
+ "template": messages,
+ },
+ },
+)
+
+print(result)
+```
+
+For an example of streaming in a pipeline, refer to the examples in the STACKIT integration [repository](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit/examples) and on its dedicated [integration page](https://haystack.deepset.ai/integrations/stackit).
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/togetheraichatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/togetheraichatgenerator.mdx
new file mode 100644
index 0000000000..b5ecfa92a4
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/togetheraichatgenerator.mdx
@@ -0,0 +1,143 @@
+---
+title: "TogetherAIChatGenerator"
+id: togetheraichatgenerator
+slug: "/togetheraichatgenerator"
+description: "This component enables chat completion using models hosted on Together AI."
+---
+
+# TogetherAIChatGenerator
+
+This component enables chat completion using models hosted on Together AI.
+
+`meta`: A list of dictionaries with the metadata associated with each reply (such as token count, finish reason, and so on) | +| **API reference** | [STACKIT](/reference/integrations-stackit) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit | +| **Package name** | `stackit-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Together API key. Can be set with `TOGETHER_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **API reference** | [TogetherAI](/reference/integrations-togetherai) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/togetherai |
+| **Package name** | `togetherai-haystack` |
+
+
+
+## Overview
+
+`TogetherAIChatGenerator` supports models hosted on [Together AI](https://docs.together.ai/intro), such as `meta-llama/Llama-3.3-70B-Instruct-Turbo`. For the full list of supported models, see [Together AI documentation](https://docs.together.ai/docs/chat-models).
+
+This component needs a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+You can pass any text generation parameters valid for the Together AI chat completion API directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs` parameter in `run` method. For more details on the parameters supported by the Together AI API, see [Together AI API documentation](https://docs.together.ai/reference/chat-completions-1).
+
+To use this integration, you need to have an active TogetherAI subscription with sufficient credits and an API key. You can provide it with:
+
+- The `TOGETHER_API_KEY` environment variable (recommended)
+- The `api_key` init parameter and Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`
+
+By default, the component uses Together AI's OpenAI-compatible base URL `https://api.together.xyz/v1`, which you can override with `api_base_url` if needed.
+
+### Tool Support
+
+`TogetherAIChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.togetherai import TogetherAIChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = TogetherAIChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+`TogetherAIChatGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM, allowing tokens to be emitted as they are generated. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+## Usage
+
+Install the `togetherai-haystack` package to use the `TogetherAIChatGenerator`:
+
+```shell
+pip install togetherai-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.togetherai import (
+ TogetherAIChatGenerator,
+)
+
+client = TogetherAIChatGenerator()
+response = client.run([ChatMessage.from_user("What are Agentic Pipelines? Be brief.")])
+print(response["replies"][0].text)
+```
+
+With streaming:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.togetherai import (
+ TogetherAIChatGenerator,
+)
+
+client = TogetherAIChatGenerator(
+ model="meta-llama/Llama-3.3-70B-Instruct-Turbo",
+ streaming_callback=lambda chunk: print(chunk.content, end="", flush=True),
+)
+
+response = client.run([ChatMessage.from_user("What are Agentic Pipelines? Be brief.")])
+
+# check the model used for the response
+print("\n\nModel used:", response["replies"][0].meta.get("model"))
+```
+
+### In a Pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.togetherai import (
+ TogetherAIChatGenerator,
+)
+
+prompt_builder = ChatPromptBuilder()
+llm = TogetherAIChatGenerator(model="meta-llama/Llama-3.3-70B-Instruct-Turbo")
+
+pipe = Pipeline()
+pipe.add_component("builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("builder.prompt", "llm.messages")
+
+messages = [
+ ChatMessage.from_system("Give brief answers."),
+ ChatMessage.from_user("Tell me about {{city}}"),
+]
+
+response = pipe.run(
+ data={"builder": {"template": messages, "template_variables": {"city": "Berlin"}}},
+)
+print(response)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/togetheraigenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/togetheraigenerator.mdx
new file mode 100644
index 0000000000..34a2328aee
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/togetheraigenerator.mdx
@@ -0,0 +1,149 @@
+---
+title: "TogetherAIGenerator"
+id: togetheraigenerator
+slug: "/togetheraigenerator"
+description: "This component enables text generation using models hosted on Together AI."
+---
+
+# TogetherAIGenerator
+
+This component enables text generation using models hosted on Together AI.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Together API key. Can be set with `TOGETHER_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [TogetherAI](/reference/integrations-togetherai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/togetherai | +| **Package name** | `togetherai-haystack` | + +
+
+## Overview
+
+`TogetherAIGenerator` supports models hosted on [Together AI](https://docs.together.ai/intro), such as `meta-llama/Llama-3.3-70B-Instruct-Turbo`. For the full list of supported models, see [Together AI documentation](https://docs.together.ai/docs/chat-models).
+
+This component needs a prompt string to operate. You can pass any text generation parameters valid for the Together AI chat completion API directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs` parameter in `run` method. For more details on the parameters supported by the Together AI API, see [Together AI API documentation](https://docs.together.ai/reference/chat-completions-1).
+
+You can also provide an optional `system_prompt` to set context or instructions for text generation. If not provided, the system prompt is omitted, and the default system prompt of the model is used.
+
+To use this integration, you need to have an active TogetherAI subscription with sufficient credits and an API key. You can provide it with:
+
+- The `TOGETHER_API_KEY` environment variable (recommended)
+- The `api_key` init parameter and Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`
+
+By default, the component uses Together AI's OpenAI-compatible base URL `https://api.together.xyz/v1`, which you can override with `api_base_url` if needed.
+
+### Streaming
+
+`TogetherAIGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM, allowing tokens to be emitted as they are generated. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+:::info
+This component is designed for text generation, not for chat. If you want to use Together AI LLMs for chat, use [`TogetherAIChatGenerator`](togetheraichatgenerator.mdx) instead.
+:::
+
+## Usage
+
+Install the `togetherai-haystack` package to use the `TogetherAIGenerator`:
+
+```shell
+pip install togetherai-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.togetherai import TogetherAIGenerator
+
+client = TogetherAIGenerator(model="meta-llama/Llama-3.3-70B-Instruct-Turbo")
+response = client.run("What's Natural Language Processing? Be brief.")
+print(response)
+
+>> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence
+>> that focuses on enabling computers to understand, interpret, and generate human language
+>> in a way that is meaningful and useful.'],
+>> 'meta': [{'model': 'meta-llama/Llama-3.3-70B-Instruct-Turbo', 'index': 0,
+>> 'finish_reason': 'stop', 'usage': {'prompt_tokens': 15, 'completion_tokens': 36,
+>> 'total_tokens': 51}}]}
+```
+
+With streaming:
+
+```python
+from haystack_integrations.components.generators.togetherai import TogetherAIGenerator
+
+client = TogetherAIGenerator(
+ model="meta-llama/Llama-3.3-70B-Instruct-Turbo",
+ streaming_callback=lambda chunk: print(chunk.content, end="", flush=True),
+)
+
+response = client.run("What's Natural Language Processing? Be brief.")
+print(response)
+```
+
+With system prompt:
+
+```python
+from haystack_integrations.components.generators.togetherai import TogetherAIGenerator
+
+client = TogetherAIGenerator(
+ model="meta-llama/Llama-3.3-70B-Instruct-Turbo",
+ system_prompt="You are a helpful assistant that provides concise answers.",
+)
+
+response = client.run("What's Natural Language Processing?")
+print(response["replies"][0])
+```
+
+### In a Pipeline
+
+```python
+from haystack import Pipeline, Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.generators.togetherai import TogetherAIGenerator
+
+docstore = InMemoryDocumentStore()
+docstore.write_documents([
+ Document(content="Rome is the capital of Italy"),
+ Document(content="Paris is the capital of France")
+])
+
+query = "What is the capital of France?"
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: {{ query }}?
+"""
+
+pipe = Pipeline()
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("llm", TogetherAIGenerator(model="meta-llama/Llama-3.3-70B-Instruct-Turbo"))
+
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "llm")
+
+result = pipe.run({
+ "prompt_builder": {"query": query},
+ "retriever": {"query": query}
+})
+
+print(result)
+
+>> {'llm': {'replies': ['The capital of France is Paris.'],
+>> 'meta': [{'model': 'meta-llama/Llama-3.3-70B-Instruct-Turbo', ...}]}}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaicodegenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaicodegenerator.mdx
new file mode 100644
index 0000000000..8cc641d877
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaicodegenerator.mdx
@@ -0,0 +1,100 @@
+---
+title: "VertexAICodeGenerator"
+id: vertexaicodegenerator
+slug: "/vertexaicodegenerator"
+description: "This component enables code generation using Google Vertex AI generative model."
+---
+
+# VertexAICodeGenerator
+
+This component enables code generation using Google Vertex AI generative model.
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [TogetherAI](/reference/integrations-togetherai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/togetherai | +| **Package name** | `togetherai-haystack` | + +
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `prefix`: A string of code before the current point
`suffix`: An optional string of code after the current point | +| **Output variables** | `replies`: Code generated by the model | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | +| **Package name** | `google-vertex-haystack` | + +
+
+`VertexAICodeGenerator` supports `code-bison`, `code-bison-32k`, and `code-gecko`.
+
+### Parameters Overview
+
+`VertexAICodeGenerator` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+You need to install `google-vertex-haystack` package first to use the `VertexAIImageCaptioner`:
+
+```shell
+pip install google-vertex-haystack
+```
+
+Basic usage:
+
+````python
+from haystack_integrations.components.generators.google_vertex import VertexAICodeGenerator
+
+generator = VertexAICodeGenerator()
+
+result = generator.run(prefix="def to_json(data):")
+
+for answer in result["replies"]:
+ print(answer)
+
+>>> ```python
+>>> import json
+>>>
+>>> def to_json(data):
+>>> """Converts a Python object to a JSON string.
+>>>
+>>> Args:
+>>> data: The Python object to convert.
+>>>
+>>> Returns:
+>>> A JSON string representing the Python object.
+>>> """
+>>>
+>>> return json.dumps(data)
+>>> ```
+````
+
+You can also set other parameters like the number of output tokens, temperature, stop sequences, and the number of candidates.
+
+Let’s try a different model:
+
+```python
+from haystack_integrations.components.generators.google_vertex import VertexAICodeGenerator
+
+generator = VertexAICodeGenerator(
+ model="code-gecko",
+ temperature=0.8,
+ candidate_count=3
+)
+
+result = generator.run(prefix="def convert_temperature(degrees):")
+
+for answer in result["replies"]:
+ print(answer)
+
+>>>
+>>> return degrees * (9/5) + 32
+
+>>>
+>>> return round(degrees * (9.0 / 5.0) + 32, 1)
+
+>>>
+>>> return 5 * (degrees - 32) /9
+>>>
+>>> def convert_temperature_back(degrees):
+>>> return 9 * (degrees / 5) + 32
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaigeminichatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaigeminichatgenerator.mdx
new file mode 100644
index 0000000000..35395dfaa6
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaigeminichatgenerator.mdx
@@ -0,0 +1,178 @@
+---
+title: "VertexAIGeminiChatGenerator"
+id: vertexaigeminichatgenerator
+slug: "/vertexaigeminichatgenerator"
+description: "`VertexAIGeminiChatGenerator` enables chat completion using Google Gemini models."
+---
+
+# VertexAIGeminiChatGenerator
+
+`VertexAIGeminiChatGenerator` enables chat completion using Google Gemini models.
+
+:::warning[Deprecation Notice]
+
+This integration uses the deprecated google-generativeai SDK, which will lose support after August 2025.
+
+We recommend switching to the new [GoogleGenAIChatGenerator](googlegenaichatgenerator.mdx) integration instead.
+:::
+
+`suffix`: An optional string of code after the current point | +| **Output variables** | `replies`: Code generated by the model | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | +| **Package name** | `google-vertex-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of alternative replies of the model to the input chat |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+| **Package name** | `google-vertex-haystack` |
+
+
+
+`VertexAIGeminiGenerator` supports `gemini-1.5-pro` and `gemini-1.5-flash`/ `gemini-2.0-flash` models. Note that [Google recommends upgrading](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions) from `gemini-1.5-pro` to `gemini-2.0-flash`.
+
+For available models, see https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models.
+
+:::info
+To explore the full capabilities of Gemini check out this [article](https://haystack.deepset.ai/blog/gemini-models-with-google-vertex-for-haystack) and the related [🧑🍳 Cookbook](https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/vertexai-gemini-examples.ipynb).
+:::
+
+### Parameters Overview
+
+`VertexAIGeminiChatGenerator` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+You need to install the `google-vertex-haystack` package to use the `VertexAIGeminiChatGenerator`:
+
+```shell
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiChatGenerator
+
+gemini_chat = VertexAIGeminiChatGenerator()
+
+messages = [ChatMessage.from_user("Tell me the name of a movie")]
+res = gemini_chat.run(messages)
+
+print(res["replies"][0].text)
+>>> The Shawshank Redemption
+
+messages += [res["replies"][0], ChatMessage.from_user("Who's the main actor?")]
+res = gemini_chat.run(messages)
+
+print(res["replies"][0].text)
+>>> Tim Robbins
+```
+
+When chatting with Gemini Pro, you can also easily use function calls. First, define the function locally and convert into a [Tool](../../tools/tool.mdx):
+
+```python
+from typing import Annotated
+from haystack.tools import create_tool_from_function
+
+
+## example function to get the current weather
+def get_current_weather(
+ location: Annotated[
+ str,
+ "The city for which to get the weather, e.g. 'San Francisco'",
+ ] = "Munich",
+ unit: Annotated[str, "The unit for the temperature, e.g. 'celsius'"] = "celsius",
+) -> str:
+ return f"The weather in {location} is sunny. The temperature is 20 {unit}."
+
+
+tool = create_tool_from_function(get_current_weather)
+```
+
+Create a new instance of `VertexAIGeminiChatGenerator` to set the tools and a [ToolInvoker](../tools/toolinvoker.mdx) to invoke the tools.:
+
+```python
+from haystack_integrations.components.generators.google_vertex import (
+ VertexAIGeminiChatGenerator,
+)
+from haystack.components.tools import ToolInvoker
+
+gemini_chat = VertexAIGeminiChatGenerator(model="gemini-2.0-flash-exp", tools=[tool])
+
+tool_invoker = ToolInvoker(tools=[tool])
+```
+
+And then ask our question:
+
+```python
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What is the temperature in celsius in Berlin?")]
+res = gemini_chat.run(messages=messages)
+
+print(res["replies"][0].tool_calls)
+>>> [ToolCall(tool_name='get_current_weather',
+>>> arguments={'unit': 'celsius', 'location': 'Berlin'}, id=None)]
+
+tool_messages = tool_invoker.run(messages=replies)["tool_messages"]
+messages = user_message + replies + tool_messages
+
+messages += res["replies"][0] + [ChatMessage.from_function(content=weather, name="get_current_weather")]
+
+final_replies = gemini_chat.run(messages=messages)["replies"]
+print(final_replies[0].text)
+>>> The temperature in Berlin is 20 degrees Celsius.
+```
+
+### In a pipeline
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiChatGenerator
+
+## no parameter init, we don't use any runtime template variables
+prompt_builder = ChatPromptBuilder()
+gemini_chat = VertexAIGeminiChatGenerator()
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("gemini", gemini)
+pipe.connect("prompt_builder.prompt", "gemini.messages")
+
+location = "Rome"
+messages = [ChatMessage.from_user("Tell me briefly about {{location}} history")]
+res = pipe.run(data={"prompt_builder": {"template_variables":{"location": location}, "template": messages}})
+
+print(res)
+
+>>> - **753 B.C.:** Traditional date of the founding of Rome by Romulus and Remus.
+>>> - **509 B.C.:** Establishment of the Roman Republic, replacing the Etruscan monarchy.
+>>> - **492-264 B.C.:** Series of wars against neighboring tribes, resulting in the expansion of the Roman Republic's territory.
+>>> - **264-146 B.C.:** Three Punic Wars against Carthage, resulting in the destruction of Carthage and the Roman Republic becoming the dominant power in the Mediterranean.
+>>> - **133-73 B.C.:** Series of civil wars and slave revolts, leading to the rise of Julius Caesar.
+>>> - **49 B.C.:** Julius Caesar crosses the Rubicon River, starting the Roman Civil War.
+>>> - **44 B.C.:** Julius Caesar is assassinated, leading to the Second Triumvirate of Octavian, Mark Antony, and Lepidus.
+>>> - **31 B.C.:** Battle of Actium, where Octavian defeats Mark Antony and Cleopatra, becoming the sole ruler of Rome.
+>>> - **27 B.C.:** The Roman Republic is transformed into the Roman Empire, with Octavian becoming the first Roman emperor, known as Augustus.
+>>> - **1st century A.D.:** The Roman Empire reaches its greatest extent, stretching from Britain to Egypt.
+>>> - **3rd century A.D.:** The Roman Empire begins to decline, facing internal instability, invasions by Germanic tribes, and the rise of Christianity.
+>>> - **476 A.D.:** The last Western Roman emperor, Romulus Augustulus, is overthrown by the Germanic leader Odoacer, marking the end of the Roman Empire in the West.
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Function Calling and Multimodal QA with Gemini](https://haystack.deepset.ai/cookbook/vertexai-gemini-examples)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaigeminigenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaigeminigenerator.mdx
new file mode 100644
index 0000000000..d0587452dc
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaigeminigenerator.mdx
@@ -0,0 +1,160 @@
+---
+title: "VertexAIGeminiGenerator"
+id: vertexaigeminigenerator
+slug: "/vertexaigeminigenerator"
+description: "`VertexAIGeminiGenerator` enables text generation using Google Gemini models."
+---
+
+# VertexAIGeminiGenerator
+
+`VertexAIGeminiGenerator` enables text generation using Google Gemini models.
+
+:::warning[Deprecation Notice]
+
+This integration uses the deprecated google-generativeai SDK, which will lose support after August 2025.
+
+We recommend switching to the new [GoogleGenAIChatGenerator](googlegenaichatgenerator.mdx) integration instead.
+:::
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory run variables** | `parts`: A variadic list containing a mix of images, audio, video, and text to prompt Gemini |
+| **Output variables** | `replies`: A list of strings or dictionaries with all the replies generated by the model |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+| **Package name** | `google-vertex-haystack` |
+
+
+
+`VertexAIGeminiGenerator` supports `gemini-1.5-pro` and `gemini-1.5-flash`/ `gemini-2.0-flash` models. Note that [Google recommends upgrading](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions) from `gemini-1.5-pro` to `gemini-2.0-flash`.
+
+For details on available models, see https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models.
+
+:::info
+To explore the full capabilities of Gemini check out this [article](https://haystack.deepset.ai/blog/gemini-models-with-google-vertex-for-haystack) and the related [Colab notebook](https://colab.research.google.com/drive/10SdXvH2ATSzqzA3OOmTM8KzD5ZdH_Q6Z?usp=sharing).
+:::
+
+### Parameters Overview
+
+`VertexAIGeminiGenerator` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+You should install `google-vertex-haystack` package to use the `VertexAIGeminiGenerator`:
+
+```shell
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiGenerator
+
+gemini = VertexAIGeminiGenerator()
+result = gemini.run(parts = ["What is the most interesting thing you know?"])
+for answer in result["replies"]:
+ print(answer)
+
+>>> 1. **The Origin of Life:** How and where did life begin? The answers to this question are still shrouded in mystery, but scientists continuously uncover new insights into the remarkable story of our planet's earliest forms of life.
+>>> 2. **The Unseen Universe:** The vast majority of the universe is comprised of matter and energy that we cannot directly observe. Dark matter and dark energy make up over 95% of the universe, yet we still don't fully understand their properties or how they influence the cosmos.
+>>> 3. **Quantum Entanglement:** This eerie phenomenon in quantum mechanics allows two particles to become so intertwined that they share the same fate, regardless of how far apart they are. This has mind-bending implications for our understanding of reality and could potentially lead to advancements in communication and computing.
+>>> 4. **Time Dilation:** Einstein's theory of relativity revealed that time can pass at different rates for different observers. Astronauts traveling at high speeds, for example, experience time dilation relative to people on Earth. This phenomenon could have significant implications for future space travel.
+>>> 5. **The Fermi Paradox:** Despite the vastness of the universe and the abundance of potential life-supporting planets, we have yet to find any concrete evidence of extraterrestrial life. This contradiction between scientific expectations and observational reality is known as the Fermi Paradox and remains one of the most intriguing mysteries in modern science.
+>>> 6. **Biological Evolution:** The idea that life evolves over time through natural selection is one of the most profound and transformative scientific discoveries. It explains the diversity of life on Earth and provides insights into our own origins and the interconnectedness of all living things.
+>>> 7. **Neuroplasticity:** The brain's ability to adapt and change throughout life, known as neuroplasticity, is a remarkable phenomenon that has important implications for learning, memory, and recovery from brain injuries.
+>>> 8. **The Goldilocks Zone:** The concept of the habitable zone, or the Goldilocks zone, refers to the range of distances from a star within which liquid water can exist on a planet's surface. This zone is critical for the potential existence of life as we know it and has been used to guide the search for exoplanets that could support life.
+>>> 9. **String Theory:** This theoretical framework in physics aims to unify all the fundamental forces of nature into a single coherent theory. It suggests that the universe has extra dimensions beyond the familiar three spatial dimensions and time.
+>>> 10. **Consciousness:** The nature of human consciousness and how it arises from the brain's physical processes remain one of the most profound and elusive mysteries in science. Understanding consciousness is crucial for unraveling the complexities of the human mind and our place in the universe.
+```
+
+Advanced usage, multi-modal prompting:
+
+```python
+import requests
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiGenerator
+
+URLS = [
+ "https://raw.githubusercontent.com/silvanocerza/robots/main/robot1.jpg",
+ "https://raw.githubusercontent.com/silvanocerza/robots/main/robot2.jpg",
+ "https://raw.githubusercontent.com/silvanocerza/robots/main/robot3.jpg",
+ "https://raw.githubusercontent.com/silvanocerza/robots/main/robot4.jpg"
+]
+images = [
+ ByteStream(data=requests.get(url).content, mime_type="image/jpeg")
+ for url in URLS
+]
+
+gemini = VertexAIGeminiGenerator()
+result = gemini.run(parts = ["What can you tell me about this robots?", *images])
+for answer in result["replies"]:
+ print(answer)
+>>> The first image is of C-3PO and R2-D2 from the Star Wars franchise. C-3PO is a protocol droid, while R2-D2 is an astromech droid. They are both loyal companions to the heroes of the Star Wars saga.
+>>> The second image is of Maria from the 1927 film Metropolis. Maria is a robot who is created to be the perfect woman. She is beautiful, intelligent, and obedient. However, she is also soulless and lacks any real emotions.
+>>> The third image is of Gort from the 1951 film The Day the Earth Stood Still. Gort is a robot who is sent to Earth to warn humanity about the dangers of nuclear war. He is a powerful and intelligent robot, but he is also compassionate and understanding.
+>>> The fourth image is of Marvin from the 1977 film The Hitchhiker's Guide to the Galaxy. Marvin is a robot who is depressed and pessimistic. He is constantly complaining about everything, but he is also very intelligent and has a dry sense of humor.
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders import PromptBuilder
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.generators.google_vertex import (
+ VertexAIGeminiGenerator,
+)
+
+docstore = InMemoryDocumentStore()
+docstore.write_documents(
+ [
+ Document(content="Rome is the capital of Italy"),
+ Document(content="Paris is the capital of France"),
+ ],
+)
+
+query = "What is the capital of France?"
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: {{ query }}?
+"""
+pipe = Pipeline()
+
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("gemini", VertexAIGeminiGenerator())
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "gemini")
+
+res = pipe.run({"prompt_builder": {"query": query}, "retriever": {"query": query}})
+
+print(res)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Function Calling and Multimodal QA with Gemini](https://haystack.deepset.ai/cookbook/vertexai-gemini-examples)
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaiimagecaptioner.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaiimagecaptioner.mdx
new file mode 100644
index 0000000000..994a1adbd2
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaiimagecaptioner.mdx
@@ -0,0 +1,83 @@
+---
+title: "VertexAIImageCaptioner"
+id: vertexaiimagecaptioner
+slug: "/vertexaiimagecaptioner"
+description: "`VertexAIImageCaptioner` enables text generation using Google Vertex AI `imagetext` generative model."
+---
+
+# VertexAIImageCaptioner
+
+`VertexAIImageCaptioner` enables text generation using Google Vertex AI `imagetext` generative model.
+
+
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `image`: A [`ByteStream`](../../concepts/data-classes.mdx#bytestream) object storing an image |
+| **Output variables** | `captions`: A list of strings generated by the model |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+| **Package name** | `google-vertex-haystack` |
+
+
+
+### Parameters Overview
+
+`VertexAIImageCaptioner` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+You need to install `google-vertex-haystack` package to use the `VertexAIImageCaptioner`:
+
+```shell
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import requests
+
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIImageCaptioner
+
+captioner = VertexAIImageCaptioner()
+
+image = ByteStream(data=requests.get("https://raw.githubusercontent.com/silvanocerza/robots/main/robot1.jpg").content)
+result = captioner.run(image=image)
+
+for caption in result["captions"]:
+ print(caption)
+
+>>> two gold robots are standing next to each other in the desert
+```
+
+You can also set the caption language and the number of results:
+
+```python
+import requests
+
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIImageCaptioner
+
+captioner = VertexAIImageCaptioner(
+ number_of_results=3, # Can't be greater than 3
+ language="it",
+)
+
+image = ByteStream(data=requests.get("https://raw.githubusercontent.com/silvanocerza/robots/main/robot1.jpg").content)
+result = captioner.run(image=image)
+
+for caption in result["captions"]:
+ print(caption)
+
+>>> due robot dorati sono in piedi uno accanto all'altro in un deserto
+>>> un c3p0 e un r2d2 stanno in piedi uno accanto all'altro in un deserto
+>>> due robot dorati sono in piedi uno accanto all'altro
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaiimagegenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaiimagegenerator.mdx
new file mode 100644
index 0000000000..52885c6b6d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaiimagegenerator.mdx
@@ -0,0 +1,81 @@
+---
+title: "VertexAIImageGenerator"
+id: vertexaiimagegenerator
+slug: "/vertexaiimagegenerator"
+description: "This component enables image generation using Google Vertex AI generative model."
+---
+
+# VertexAIImageGenerator
+
+This component enables image generation using Google Vertex AI generative model.
+
+
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the model |
+| **Output variables** | `images`: A list of [`ByteStream`](../../concepts/data-classes.mdx#bytestream) containing images generated by the model |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+| **Package name** | `google-vertex-haystack` |
+
+
+
+`VertexAIImageGenerator` supports the `imagegeneration` model.
+
+### Parameters Overview
+
+`VertexAIImageGenerator` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+You need to install `google-vertex-haystack` package to use the `VertexAIImageGenerator`:
+
+```python
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from pathlib import Path
+
+from haystack_integrations.components.generators.google_vertex import (
+ VertexAIImageGenerator,
+)
+
+generator = VertexAIImageGenerator()
+result = generator.run(prompt="Generate an image of a cute cat")
+result["images"][0].to_file(Path("my_image.png"))
+```
+
+You can also set other parameters like the number of images generated and the guidance scale to change the strength of the prompt.
+
+Let’s also use a negative prompt to omit something from the image:
+
+```python
+from pathlib import Path
+
+from haystack_integrations.components.generators.google_vertex import (
+ VertexAIImageGenerator,
+)
+
+generator = VertexAIImageGenerator(
+ number_of_images=3,
+ guidance_scale=12,
+)
+
+result = generator.run(
+ prompt="Generate an image of a cute cat",
+ negative_prompt="window, chair",
+)
+
+for i, image in enumerate(result["images"]):
+ images.to_file(Path(f"image_{i}.png"))
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaiimageqa.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaiimageqa.mdx
new file mode 100644
index 0000000000..987ec63e80
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaiimageqa.mdx
@@ -0,0 +1,80 @@
+---
+title: "VertexAIImageQA"
+id: vertexaiimageqa
+slug: "/vertexaiimageqa"
+description: "This component enables text generation (image captioning) using Google Vertex AI generative models."
+---
+
+# VertexAIImageQA
+
+This component enables text generation (image captioning) using Google Vertex AI generative models.
+
+
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `image`: A [`ByteStream`](../../concepts/data-classes.mdx#bytestream) containing an image data
`question`: A string of a question about the image | +| **Output variables** | `replies`: A list of strings containing answers generated by the model | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | +| **Package name** | `google-vertex-haystack` | + +
+
+`VertexAIImageQA` supports the `imagetext` model.
+
+### Parameters Overview
+
+`VertexAIImageQA` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+You need to install `google-vertex-haystack` package to use the `VertexAIImageQA`:
+
+```python
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIImageQA
+
+qa = VertexAIImageQA()
+
+image = ByteStream.from_file_path("dog.jpg")
+
+res = qa.run(image=image, question="What color is this dog")
+
+print(res["replies"][0])
+
+>>> white
+```
+
+You can also set the number of answers generated:
+
+```python
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIImageQA
+
+qa = VertexAIImageQA(
+ number_of_results=3,
+)
+image = ByteStream.from_file_path("dog.jpg")
+
+res = qa.run(image=image, question="Tell me something about this dog")
+
+for answer in res["replies"]:
+ print(answer)
+
+>>> pomeranian
+>>> white
+>>> pomeranian puppy
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaitextgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaitextgenerator.mdx
new file mode 100644
index 0000000000..9ad23df684
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vertexaitextgenerator.mdx
@@ -0,0 +1,88 @@
+---
+title: "VertexAITextGenerator"
+id: vertexaitextgenerator
+slug: "/vertexaitextgenerator"
+description: "This component enables text generation using Google Vertex AI generative models."
+---
+
+# VertexAITextGenerator
+
+This component enables text generation using Google Vertex AI generative models.
+
+`question`: A string of a question about the image | +| **Output variables** | `replies`: A list of strings containing answers generated by the model | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | +| **Package name** | `google-vertex-haystack` | + +
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the model |
+| **Output variables** | `replies`: A list of strings containing answers generated by the model
`safety_attributes`: A dictionary containing scores for safety attributes
`citations`: A list of dictionaries containing grounding citations | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | +| **Package name** | `google-vertex-haystack` | + +
+
+`VertexAITextGenerator` supports `text-bison`, `text-unicorn` and `text-bison-32k` models.
+
+### Parameters Overview
+
+`VertexAITextGenerator` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+You need to install `google-vertex-haystack` package to use the `VertexAITextGenerator`:
+
+```python
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+````python
+from haystack_integrations.components.generators.google_vertex import VertexAITextGenerator
+
+generator = VertexAITextGenerator()
+res = generator.run("Tell me a good interview question for a software engineer.")
+
+print(res["replies"][0])
+
+>>> **Question:** You are given a list of integers and a target sum. Find all unique combinations of numbers in the list that add up to the target sum.
+>>>
+>>> **Example:**
+>>>
+>>> ```
+>>> Input: [1, 2, 3, 4, 5], target = 7
+>>> Output: [[1, 2, 4], [3, 4]]
+>>> ```
+>>>
+>>> **Follow-up:** What if the list contains duplicate numbers?
+````
+
+You can also set other parameters like the number of answers generated, temperature to control the randomness, and stop sequences to stop generation. For a full list of possible parameters, see the documentation of [`TextGenerationModel.predict()`](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.language_models.TextGenerationModel#vertexai_language_models_TextGenerationModel_predict).
+
+```python
+from haystack_integrations.components.generators.google_vertex import VertexAITextGenerator
+
+generator = VertexAITextGenerator(
+ candidate_count=3,
+ temperature=0.2,
+ stop_sequences=["example", "Example"],
+)
+res = generator.run("Tell me a good interview question for a software engineer.")
+
+for answer in res["replies"]:
+ print(answer)
+ print("-----")
+
+>>> **Question:** You are given a list of integers, and you need to find the longest increasing subsequence. What is the most efficient algorithm to solve this problem?
+>>> -----
+>>> **Question:** You are given a list of integers and a target sum. Find all unique combinations in the list that sum up to the target sum. The same number can be used multiple times in a combination.
+>>> -----
+>>> **Question:** You are given a list of integers and a target sum. Find all unique combinations of numbers in the list that add up to the target sum.
+>>> -----
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vllmchatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vllmchatgenerator.mdx
new file mode 100644
index 0000000000..ebfb532a93
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/vllmchatgenerator.mdx
@@ -0,0 +1,197 @@
+---
+title: "VLLMChatGenerator"
+id: vllmchatgenerator
+slug: "/vllmchatgenerator"
+description: "This component enables chat completion using models served with vLLM."
+---
+
+# VLLMChatGenerator
+
+This component enables chat completion using models served with [vLLM](https://docs.vllm.ai/).
+
+`safety_attributes`: A dictionary containing scores for safety attributes
`citations`: A list of dictionaries containing grounding citations | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | +| **Package name** | `google-vertex-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The name of the model served by vLLM |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **API reference** | [vLLM](/reference/integrations-vllm) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/vllm |
+| **Package name** | `vllm-haystack` |
+
+
+
+## Overview
+
+[vLLM](https://docs.vllm.ai/) is a high-throughput and memory-efficient inference and serving engine for LLMs. It exposes an OpenAI-compatible HTTP server, which `VLLMChatGenerator` uses to run chat completions.
+
+`VLLMChatGenerator` expects a vLLM server to be running and accessible at the `api_base_url` parameter (by default, `http://localhost:8000/v1`). The component needs a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+You can pass any text generation parameters valid for the vLLM OpenAI-compatible Chat Completion API directly to this component using the `generation_kwargs` parameter in `__init__` or in the `run` method. vLLM-specific parameters not part of the standard OpenAI API (such as `top_k`, `min_tokens`, `repetition_penalty`) can be passed through `generation_kwargs["extra_body"]`. For more details, see the [vLLM documentation](https://docs.vllm.ai/en/stable/serving/openai_compatible_server/).
+
+If the vLLM server was started with `--api-key`, provide the API key through the `VLLM_API_KEY` environment variable or the `api_key` init parameter using Haystack's [Secret](../../concepts/secret-management.mdx) API.
+
+### Tool Support
+
+`VLLMChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+For tool calling to work, the vLLM server must be started with `--enable-auto-tool-choice` and `--tool-call-parser`. The available tool call parsers depend on the model. See the [vLLM tool calling docs](https://docs.vllm.ai/en/stable/features/tool_calling/) for the full list.
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+`VLLMChatGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM, allowing tokens to be emitted as they are generated. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+### Reasoning models
+
+`VLLMChatGenerator` supports reasoning models. To use them, start the vLLM server with the appropriate `--reasoning-parser`. The reasoning content produced by the model is exposed in the `reasoning` field of the returned `ChatMessage`.
+
+## Usage
+
+Install the `vllm-haystack` package to use the `VLLMChatGenerator`:
+
+```shell
+pip install vllm-haystack
+```
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server:
+
+```bash
+vllm serve Qwen/Qwen3-4B-Instruct-2507
+```
+
+For reasoning models, start the server with the appropriate reasoning parser:
+
+```bash
+vllm serve Qwen/Qwen3-0.6B --reasoning-parser qwen3
+```
+
+For tool calling, start the server with `--enable-auto-tool-choice` and `--tool-call-parser`:
+
+```bash
+vllm serve Qwen/Qwen3-0.6B --enable-auto-tool-choice --tool-call-parser hermes
+```
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+generator = VLLMChatGenerator(
+ model="Qwen/Qwen3-4B-Instruct-2507",
+ generation_kwargs={"max_tokens": 512, "temperature": 0.7},
+)
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+response = generator.run(messages=messages)
+print(response["replies"][0].text)
+```
+
+### With vLLM-specific parameters
+
+Pass vLLM-specific parameters through the `generation_kwargs["extra_body"]` dictionary:
+
+```python
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+generator = VLLMChatGenerator(
+ model="Qwen/Qwen3-4B-Instruct-2507",
+ generation_kwargs={
+ "max_tokens": 512,
+ "extra_body": {
+ "top_k": 50,
+ "min_tokens": 10,
+ "repetition_penalty": 1.1,
+ },
+ },
+)
+```
+
+### With tool calling
+
+Start the vLLM server with `--enable-auto-tool-choice` and `--tool-call-parser`, then:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.tools import tool
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+
+@tool
+def weather(city: str) -> str:
+ """Get the weather in a given city."""
+ return f"The weather in {city} is sunny"
+
+
+generator = VLLMChatGenerator(model="Qwen/Qwen3-0.6B", tools=[weather])
+
+messages = [ChatMessage.from_user("What is the weather in Paris?")]
+response = generator.run(messages=messages)
+print(response["replies"][0].tool_calls)
+```
+
+### With reasoning models
+
+Start the vLLM server with `--reasoning-parser`, then:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+generator = VLLMChatGenerator(model="Qwen/Qwen3-0.6B")
+
+messages = [ChatMessage.from_user("Solve step by step: what is 15 * 37?")]
+response = generator.run(messages=messages)
+reply = response["replies"][0]
+if reply.reasoning:
+ print("Reasoning:", reply.reasoning.reasoning_text)
+print("Answer:", reply.text)
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+prompt_builder = ChatPromptBuilder()
+llm = VLLMChatGenerator(model="Qwen/Qwen3-4B-Instruct-2507")
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+messages = [
+ ChatMessage.from_system("Give brief answers."),
+ ChatMessage.from_user("Tell me about {{city}}"),
+]
+
+response = pipe.run(
+ data={
+ "prompt_builder": {
+ "template": messages,
+ "template_variables": {"city": "Berlin"},
+ },
+ },
+)
+print(response)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/watsonxchatgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/watsonxchatgenerator.mdx
new file mode 100644
index 0000000000..a64ac6c038
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/watsonxchatgenerator.mdx
@@ -0,0 +1,135 @@
+---
+title: "WatsonxChatGenerator"
+id: watsonxchatgenerator
+slug: "/watsonxchatgenerator"
+description: "Use this component with IBM watsonx models like `granite-3-2b-instruct` for chat generation."
+---
+
+# WatsonxChatGenerator
+
+Use this component with IBM watsonx models like `granite-3-2b-instruct` for chat generation.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The IBM Cloud API key. Can be set with `WATSONX_API_KEY` env var.
`project_id`: The IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | +| **Package name** | `watsonx-haystack` | + +
+
+This integration supports IBM watsonx.ai foundation models such as `ibm/granite-13b-chat-v2`, `ibm/llama-2-70b-chat`, `ibm/llama-3-70b-instruct`, and similar. These models provide high-quality chat completion capabilities through IBM's cloud platform. Check out the most recent full list in the [IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-ibm.html?context=wx).
+
+## Overview
+
+`WatsonxChatGenerator` needs IBM Cloud credentials to work. You can set these in:
+
+- The `api_key` and `project_id` init parameters using [Secret API](../../concepts/secret-management.mdx)
+- The `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` environment variables (recommended)
+
+Then, the component needs a prompt to operate, but you can pass any text generation parameters valid for the IBM watsonx.ai API directly to this component using the `generation_kwargs` parameter, both at initialization and to `run()` method. For more details on the parameters supported by the IBM watsonx.ai API, refer to the [IBM watsonx.ai documentation](https://cloud.ibm.com/apidocs/watsonx-ai).
+
+Finally, the component needs a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+You need to install `watsonx-haystack` package to use the `WatsonxChatGenerator`:
+
+```shell
+pip install watsonx-haystack
+```
+
+#### On its own
+
+```python
+from haystack_integrations.components.generators.watsonx.chat.chat_generator import (
+ WatsonxChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+generator = WatsonxChatGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+ model="ibm/granite-13b-instruct-v2",
+)
+
+message = ChatMessage.from_user("What's Natural Language Processing? Be brief.")
+print(generator.run([message]))
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.watsonx.chat.chat_generator import (
+ WatsonxChatGenerator,
+)
+
+# Use a multimodal model
+llm = WatsonxChatGenerator(model="meta-llama/llama-3-2-11b-vision-instruct")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(
+ content_parts=["What does the image show? Max 5 words.", image],
+)
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+#### In a Pipeline
+
+You can also use `WatsonxChatGenerator` to use IBM watsonx.ai chat models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.watsonx.chat.chat_generator import (
+ WatsonxChatGenerator,
+)
+from haystack.utils import Secret
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component(
+ "llm",
+ WatsonxChatGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+ model="ibm/granite-13b-instruct-v2",
+ ),
+)
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system(
+ "You are an assistant giving out valuable information to language learners.",
+)
+messages = [
+ system_message,
+ ChatMessage.from_user("What's the official language of {{ country }}?"),
+]
+
+res = pipe.run(
+ data={
+ "prompt_builder": {
+ "template_variables": {"country": country},
+ "template": messages,
+ },
+ },
+)
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/watsonxgenerator.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/watsonxgenerator.mdx
new file mode 100644
index 0000000000..f6690c5fcb
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/generators/watsonxgenerator.mdx
@@ -0,0 +1,108 @@
+---
+title: "WatsonxGenerator"
+id: watsonxgenerator
+slug: "/watsonxgenerator"
+description: "Use this component with IBM watsonx models like `granite-3-2b-instruct` for simple text generation tasks."
+---
+
+# WatsonxGenerator
+
+Use this component with IBM watsonx models like `granite-3-2b-instruct` for simple text generation tasks.
+
+`project_id`: The IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | +| **Package name** | `watsonx-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [PromptBuilder](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An IBM Cloud API key. Can be set with `WATSONX_API_KEY` env var.
`project_id`: An IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | +| **Package name** | `watsonx-haystack` | + +
+
+## Overview
+
+This integration supports IBM watsonx.ai foundation models such as `ibm/granite-13b-chat-v2`, `ibm/llama-2-70b-chat`, `ibm/llama-3-70b-instruct`, and similar. These models provide high-quality text generation capabilities through IBM's cloud platform. Check out the most recent full list in the [IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-ibm.html?context=wx).
+
+### Parameters
+
+`WatsonxGenerator` needs IBM Cloud credentials to work. You can provide these in:
+
+- The `WATSONX_API_KEY` environment variable (recommended)
+- The `WATSONX_PROJECT_ID` environment variable (recommended)
+- The `api_key` and `project_id` init parameters using Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`
+
+Set your preferred IBM watsonx.ai model in the `model` parameter when initializing the component. The default model is `ibm/granite-3-2b-instruct`.
+
+`WatsonxGenerator` requires a prompt to generate text, but you can pass any text generation parameters available in the IBM watsonx.ai API directly to this component using the `generation_kwargs` parameter, both at initialization and to `run()` method. For more details on the parameters supported by the IBM watsonx.ai API, see [IBM watsonx.ai documentation](https://cloud.ibm.com/apidocs/watsonx-ai).
+
+The component also supports system prompts that can be set at initialization or passed during runtime to provide context or instructions for the generation.
+
+Finally, the component run method requires a single string prompt to generate text.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Install the `watsonx-haystack` package to use the `WatsonxGenerator`:
+
+```shell
+pip install watsonx-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.watsonx.generator import (
+ WatsonxGenerator,
+)
+from haystack.utils import Secret
+
+generator = WatsonxGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+
+print(generator.run("What's Natural Language Processing? Be brief."))
+```
+
+### In a pipeline
+
+You can also use `WatsonxGenerator` with the IBM watsonx.ai models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import PromptBuilder
+from haystack_integrations.components.generators.watsonx.generator import (
+ WatsonxGenerator,
+)
+from haystack.utils import Secret
+
+template = """
+You are an assistant giving out valuable information to language learners.
+Answer this question, be brief.
+
+Question: {{ query }}?
+"""
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", PromptBuilder(template))
+pipe.add_component(
+ "llm",
+ WatsonxGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+ ),
+)
+pipe.connect("prompt_builder", "llm")
+
+query = "What language is spoken in Germany?"
+res = pipe.run(data={"prompt_builder": {"query": query}})
+
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners.mdx
new file mode 100644
index 0000000000..0bd093453f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners.mdx
@@ -0,0 +1,15 @@
+---
+title: "Joiners"
+id: joiners
+slug: "/joiners"
+---
+
+# Joiners
+
+| Component | Description |
+| --- | --- |
+| [AnswerJoiner](joiners/answerjoiner.mdx) | Joins multiple answers from different Generators into a single list. |
+| [BranchJoiner](joiners/branchjoiner.mdx) | Joins different branches of a pipeline into a single output. |
+| [DocumentJoiner](joiners/documentjoiner.mdx) | Joins lists of documents. |
+| [ListJoiner](joiners/listjoiner.mdx) | Joins multiple lists into a single flat list. |
+| [StringJoiner](joiners/stringjoiner.mdx) | Joins strings from different components into a list of strings. |
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/answerjoiner.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/answerjoiner.mdx
new file mode 100644
index 0000000000..47e8afa854
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/answerjoiner.mdx
@@ -0,0 +1,72 @@
+---
+title: "AnswerJoiner"
+id: answerjoiner
+slug: "/answerjoiner"
+description: "Merges multiple answers from different Generators into a single list."
+---
+
+# AnswerJoiner
+
+Merges multiple answers from different Generators into a single list.
+
+`project_id`: An IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | +| **Package name** | `watsonx-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In query pipelines, after [Generators](../generators.mdx) and, subsequently, components that return a list of answers such as [`AnswerBuilder`](../builders/answerbuilder.mdx) |
+| **Mandatory run variables** | `answers`: A nested list of answers to be merged, received from the Generator. This input is `variadic`, meaning you can connect a variable number of components to it. |
+| **Output variables** | `answers`: A merged list of answers |
+| **API reference** | [Joiners](/reference/joiners-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/joiners/answer_joiner.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overvew
+
+`AnswerJoiner` joins input lists of [`Answer`](../../concepts/data-classes.mdx#answer) objects from multiple connections and returns them as one list.
+
+You can optionally set the `top_k` parameter, which specifies the maximum number of answers to return. If you don’t set this parameter, the component returns all answers it receives.
+
+## Usage
+
+In this simple example pipeline, the `AnswerJoiner` merges answers from two instances of Generators:
+
+```python
+from haystack.components.builders import AnswerBuilder
+from haystack.components.joiners import AnswerJoiner
+
+from haystack.core.pipeline import Pipeline
+
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+query = "What's Natural Language Processing?"
+messages = [
+ ChatMessage.from_system(
+ "You are a helpful, respectful and honest assistant. Be super concise.",
+ ),
+ ChatMessage.from_user(query),
+]
+
+pipe = Pipeline()
+pipe.add_component("gpt-4o", OpenAIChatGenerator(model="gpt-4o"))
+pipe.add_component("llama", OpenAIChatGenerator())
+pipe.add_component("aba", AnswerBuilder())
+pipe.add_component("abb", AnswerBuilder())
+pipe.add_component("joiner", AnswerJoiner())
+
+pipe.connect("gpt-4o.replies", "aba")
+pipe.connect("llama.replies", "abb")
+pipe.connect("aba.answers", "joiner")
+pipe.connect("abb.answers", "joiner")
+
+results = pipe.run(
+ data={
+ "gpt-4o": {"messages": messages},
+ "llama": {"messages": messages},
+ "aba": {"query": query},
+ "abb": {"query": query},
+ },
+)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/branchjoiner.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/branchjoiner.mdx
new file mode 100644
index 0000000000..955eaa907e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/branchjoiner.mdx
@@ -0,0 +1,222 @@
+---
+title: "BranchJoiner"
+id: branchjoiner
+slug: "/branchjoiner"
+description: "Use this component to join different branches of a pipeline into a single output."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# BranchJoiner
+
+Use this component to join different branches of a pipeline into a single output.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible: Can appear at the beginning of a pipeline or at the start of loops. |
+| **Mandatory init variables** | `type`: The type of data expected from preceding components |
+| **Mandatory run variables** | `**kwargs`: Any input data type defined at the initialization. This input is variadic, meaning you can connect a variable number of components to it. |
+| **Output variables** | `value`: The first value received from the connected components. |
+| **API reference** | [Joiners](/reference/joiners-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/joiners/branch.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`BranchJoiner` joins multiple branches in a pipeline, allowing their outputs to be reconciled into a single branch. This is especially useful in pipelines with multiple branches that need to be unified before moving to the single component that comes next.
+
+`BranchJoiner` receives multiple data connections of the same type from other components and passes the first value it receives to its single output. This makes it essential for closing loops in pipelines or reconciling multiple branches from a decision component.
+
+`BranchJoiner` can handle only one input of one data type, declared in the `__init__` function. It ensures that the data type remains consistent across the pipeline branches. If more than one value is received for the input when `run` is invoked, the component will raise an error:
+
+```python
+from haystack.components.joiners import BranchJoiner
+
+bj = BranchJoiner(int)
+bj.run(value=[3, 4, 5])
+
+>>> ValueError: BranchJoiner expects only one input, but 3 were received.
+
+```
+
+## Usage
+
+### On its own
+
+Although only one input value is allowed at every run, due to its variadic nature `BranchJoiner` still expects a list. As an example:
+
+```python
+from haystack.components.joiners import BranchJoiner
+
+## an example where input and output are strings
+bj = BranchJoiner(str)
+bj.run(value=["hello"])
+>>> {"value" : "hello"}
+
+## an example where input and output are integers
+bj = BranchJoiner(int)
+bj.run(value=[3])
+>>> {"value": 3}
+```
+
+### In a pipeline
+
+#### Enabling loops
+
+Below is an example where `BranchJoiner` is used for closing a loop. In this example, `BranchJoiner` receives a looped-back list of `ChatMessage` objects from the `JsonSchemaValidator` and sends it down to the `OpenAIChatGenerator` for re-generation.
+
+```python
+import json
+
+from haystack import Pipeline
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.joiners import BranchJoiner
+from haystack.components.validators import JsonSchemaValidator
+from haystack.dataclasses import ChatMessage
+
+person_schema = {
+ "type": "object",
+ "properties": {
+ "first_name": {"type": "string", "pattern": "^[A-Z][a-z]+$"},
+ "last_name": {"type": "string", "pattern": "^[A-Z][a-z]+$"},
+ "nationality": {
+ "type": "string",
+ "enum": ["Italian", "Portuguese", "American"],
+ },
+ },
+ "required": ["first_name", "last_name", "nationality"],
+}
+
+## Initialize a pipeline
+pipe = Pipeline()
+
+## Add components to the pipeline
+pipe.add_component("joiner", BranchJoiner(list[ChatMessage]))
+pipe.add_component("fc_llm", OpenAIChatGenerator(model="gpt-4.1-mini"))
+pipe.add_component("validator", JsonSchemaValidator(json_schema=person_schema))
+
+## Connect components
+pipe.connect("joiner", "fc_llm")
+pipe.connect("fc_llm.replies", "validator.messages")
+pipe.connect("validator.validation_error", "joiner")
+
+result = pipe.run(
+ data={
+ "fc_llm": {"generation_kwargs": {"response_format": {"type": "json_object"}}},
+ "joiner": {
+ "value": [ChatMessage.from_user("Create json object from Peter Parker")],
+ },
+ },
+)
+
+print(json.loads(result["validator"]["validated"][0].text))
+
+## Output:
+## {'first_name': 'Peter', 'last_name': 'Parker', 'nationality': 'American', 'name': 'Spider-Man', 'occupation':
+## 'Superhero', 'age': 23, 'location': 'New York City'}
+```
+
+
+
+
+
+#### Reconciling branches
+
+In this example, the `TextLanguageRouter` component directs the query to one of three language-specific Retrievers. The next component would be a `PromptBuilder`, but we cannot connect multiple Retrievers to a single `PromptBuilder` directly. Instead, we connect all the Retrievers to the `BranchJoiner` component. The `BranchJoiner` then takes the output from the Retriever that was actually called and passes it as a single list of documents to the `PromptBuilder`. The `BranchJoiner` ensures that the pipeline can handle multiple languages seamlessly by consolidating different outputs from the Retrievers into a unified connection for further processing.
+
+```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.joiners import BranchJoiner
+from haystack.components.builders import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+from haystack.components.routers import TextLanguageRouter
+
+prompt_template = """
+Answer the question based on the given reviews.
+Reviews:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+Question: {{ query}}
+Answer:
+"""
+
+documents = [
+ Document(
+ content="Super appartement. Juste au dessus de plusieurs bars qui ferment très tard. A savoir à l'avance. (Bouchons d'oreilles fournis !)",
+ ),
+ Document(
+ content="El apartamento estaba genial y muy céntrico, todo a mano. Al lado de la librería Lello y De la Torre de los clérigos. Está situado en una zona de marcha, así que si vais en fin de semana , habrá ruido, aunque a nosotros no nos molestaba para dormir",
+ ),
+ Document(
+ content="The keypad with a code is convenient and the location is convenient. Basically everything else, very noisy, wi-fi didn't work, check-in person didn't explain anything about facilities, shower head was broken, there's no cleaning and everything else one may need is charged.",
+ ),
+ Document(
+ content="It is very central and appartement has a nice appearance (even though a lot IKEA stuff), *W A R N I N G** the appartement presents itself as a elegant and as a place to relax, very wrong place to relax - you cannot sleep in this appartement, even the beds are vibrating from the bass of the clubs in the same building - you get ear plugs from the hotel.",
+ ),
+ Document(
+ content="Céntrico. Muy cómodo para moverse y ver Oporto. Edificio con terraza propia en la última planta. Todo reformado y nuevo. The staff brings a great breakfast every morning to the apartment. Solo que se puede escuchar algo de ruido de la street a primeras horas de la noche. Es un zona de ocio nocturno. Pero respetan los horarios.",
+ ),
+]
+
+en_document_store = InMemoryDocumentStore()
+fr_document_store = InMemoryDocumentStore()
+es_document_store = InMemoryDocumentStore()
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(
+ instance=TextLanguageRouter(["en", "fr", "es"]),
+ name="router",
+)
+rag_pipeline.add_component(
+ instance=InMemoryBM25Retriever(document_store=en_document_store),
+ name="en_retriever",
+)
+rag_pipeline.add_component(
+ instance=InMemoryBM25Retriever(document_store=fr_document_store),
+ name="fr_retriever",
+)
+rag_pipeline.add_component(
+ instance=InMemoryBM25Retriever(document_store=es_document_store),
+ name="es_retriever",
+)
+rag_pipeline.add_component(instance=BranchJoiner(type_=list[Document]), name="joiner")
+rag_pipeline.add_component(
+ instance=PromptBuilder(template=prompt_template),
+ name="prompt_builder",
+)
+rag_pipeline.add_component(instance=OpenAIGenerator(), name="llm")
+
+rag_pipeline.connect("router.en", "en_retriever.query")
+rag_pipeline.connect("router.fr", "fr_retriever.query")
+rag_pipeline.connect("router.es", "es_retriever.query")
+rag_pipeline.connect("en_retriever", "joiner")
+rag_pipeline.connect("fr_retriever", "joiner")
+rag_pipeline.connect("es_retriever", "joiner")
+rag_pipeline.connect("joiner", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+en_question = "Does this apartment has a noise problem?"
+
+result = rag_pipeline.run(
+ {"router": {"text": en_question}, "prompt_builder": {"query": en_question}},
+)
+
+print(result["llm"]["replies"][0])
+```
+
+Expand to see the pipeline graph
+
+
+
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/documentjoiner.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/documentjoiner.mdx
new file mode 100644
index 0000000000..b2fcf6af58
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/documentjoiner.mdx
@@ -0,0 +1,192 @@
+---
+title: "DocumentJoiner"
+id: documentjoiner
+slug: "/documentjoiner"
+description: "Use this component in hybrid retrieval pipelines or indexing pipelines with multiple file converters to join lists of documents."
+---
+
+# DocumentJoiner
+
+Use this component in hybrid retrieval pipelines or indexing pipelines with multiple file converters to join lists of documents.
+
+Expand to see the pipeline graph
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing and query pipelines, after components that return a list of documents such as multiple [Retrievers](../retrievers.mdx) or multiple [Converters](../converters.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents. This input is `variadic`, meaning you can connect a variable number of components to it. |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Joiners](/reference/joiners-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/joiners/document_joiner.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`DocumentJoiner` joins input lists of documents from multiple connections and outputs them as one list. You can choose how you want the lists to be joined by specifying the `join_mode`. There are three options available:
+
+- `concatenate` - Combines document from multiple components, discarding any duplicates. documents get their scores from the last component in the pipeline that assigns scores. This mode doesn’t influence document scores.
+- `merge` - Merges the scores of duplicate documents coming from multiple components. You can also assign a weight to the scores to influence how they’re merged and set the top_k limit to specify how many documents you want `DocumentJoiner` to return.
+- `reciprocal_rank_fusion`- Combines documents into a single list based on their ranking received from multiple components. It then calculates a new score based on the ranks of documents in the input lists. If the same Document appears in more than one list (was returned by multiple components), it gets a higher score.
+- `distribution_based_rank_fusion` – Combines rankings from multiple sources into a single, unified ranking. It analyzes how scores are spread out and normalizes them, ensuring that each component's scoring method is taken into account. This normalization helps to balance the influence of each component, resulting in a more robust and fair combined ranking. If a document appears in multiple lists, its final score is adjusted based on the distribution of scores from all lists.
+
+## Usage
+
+### On its own
+
+Below is an example where we are using the `DocumentJoiner` to merge two lists of documents. We run the `DocumentJoiner` and provide the documents. It returns a list of documents ranked by combined scores. By default, equal weight is given to each Retriever score. You could also use custom weights by setting the weights parameter to a list of floats with one weight per input component.
+
+```python
+from haystack import Document
+from haystack.components.joiners.document_joiner import DocumentJoiner
+
+docs_1 = [
+ Document(content="Paris is the capital of France.", score=0.5),
+ Document(content="Berlin is the capital of Germany.", score=0.4),
+]
+docs_2 = [
+ Document(content="Paris is the capital of France.", score=0.6),
+ Document(content="Rome is the capital of Italy.", score=0.5),
+]
+
+joiner = DocumentJoiner(join_mode="merge")
+
+joiner.run(documents=[docs_1, docs_2])
+
+## {'documents': [Document(id=0f5beda04153dbfc462c8b31f8536749e43654709ecf0cfe22c6d009c9912214, content: 'Paris is the capital of France.', score: 0.55), Document(id=424beed8b549a359239ab000f33ca3b1ddb0f30a988bbef2a46597b9c27e42f2, content: 'Rome is the capital of Italy.', score: 0.25), Document(id=312b465e77e25c11512ee76ae699ce2eb201f34c8c51384003bb367e24fb6cf8, content: 'Berlin is the capital of Germany.', score: 0.2)]}
+```
+
+### In a pipeline
+
+#### Hybrid Retrieval
+
+Below is an example of a hybrid retrieval pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`) and embedding search (using `InMemoryEmbeddingRetriever`). It then uses the `DocumentJoiner` with its default join mode to concatenate the retrieved documents into one list. The Document Store must contain documents with embeddings, otherwise the `InMemoryEmbeddingRetriever` will not return any documents.
+
+```python
+from haystack.components.joiners.document_joiner import DocumentJoiner
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import (
+ InMemoryBM25Retriever,
+ InMemoryEmbeddingRetriever,
+)
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(
+ instance=InMemoryBM25Retriever(document_store=document_store),
+ name="bm25_retriever",
+)
+p.add_component(
+ instance=SentenceTransformersTextEmbedder(
+ model="sentence-transformers/all-MiniLM-L6-v2",
+ ),
+ name="text_embedder",
+)
+p.add_component(
+ instance=InMemoryEmbeddingRetriever(document_store=document_store),
+ name="embedding_retriever",
+)
+p.add_component(instance=DocumentJoiner(), name="joiner")
+p.connect("bm25_retriever", "joiner")
+p.connect("embedding_retriever", "joiner")
+p.connect("text_embedder", "embedding_retriever")
+query = "What is the capital of France?"
+p.run(data={"bm25_retriever": {"query": query}, "text_embedder": {"text": query}})
+```
+
+#### Indexing
+
+Here's an example of an indexing pipeline that uses `DocumentJoiner` to compile all files into a single list of documents that can be fed through the rest of the indexing pipeline as one.
+
+```python
+from haystack.components.writers import DocumentWriter
+from haystack.components.converters import (
+ MarkdownToDocument,
+ PyPDFToDocument,
+ TextFileToDocument,
+)
+from haystack.components.preprocessors import DocumentSplitter, DocumentCleaner
+from haystack.components.routers import FileTypeRouter
+from haystack.components.joiners import DocumentJoiner
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from pathlib import Path
+
+document_store = InMemoryDocumentStore()
+file_type_router = FileTypeRouter(
+ mime_types=["text/plain", "application/pdf", "text/markdown"],
+)
+text_file_converter = TextFileToDocument()
+markdown_converter = MarkdownToDocument()
+pdf_converter = PyPDFToDocument()
+document_joiner = DocumentJoiner()
+
+document_cleaner = DocumentCleaner()
+document_splitter = DocumentSplitter(
+ split_by="word",
+ split_length=150,
+ split_overlap=50,
+)
+
+document_embedder = SentenceTransformersDocumentEmbedder(
+ model="sentence-transformers/all-MiniLM-L6-v2",
+)
+document_writer = DocumentWriter(document_store)
+
+preprocessing_pipeline = Pipeline()
+preprocessing_pipeline.add_component(instance=file_type_router, name="file_type_router")
+preprocessing_pipeline.add_component(
+ instance=text_file_converter,
+ name="text_file_converter",
+)
+preprocessing_pipeline.add_component(
+ instance=markdown_converter,
+ name="markdown_converter",
+)
+preprocessing_pipeline.add_component(instance=pdf_converter, name="pypdf_converter")
+preprocessing_pipeline.add_component(instance=document_joiner, name="document_joiner")
+preprocessing_pipeline.add_component(instance=document_cleaner, name="document_cleaner")
+preprocessing_pipeline.add_component(
+ instance=document_splitter,
+ name="document_splitter",
+)
+preprocessing_pipeline.add_component(
+ instance=document_embedder,
+ name="document_embedder",
+)
+preprocessing_pipeline.add_component(instance=document_writer, name="document_writer")
+
+preprocessing_pipeline.connect(
+ "file_type_router.text/plain",
+ "text_file_converter.sources",
+)
+preprocessing_pipeline.connect(
+ "file_type_router.application/pdf",
+ "pypdf_converter.sources",
+)
+preprocessing_pipeline.connect(
+ "file_type_router.text/markdown",
+ "markdown_converter.sources",
+)
+preprocessing_pipeline.connect("text_file_converter", "document_joiner")
+preprocessing_pipeline.connect("pypdf_converter", "document_joiner")
+preprocessing_pipeline.connect("markdown_converter", "document_joiner")
+preprocessing_pipeline.connect("document_joiner", "document_cleaner")
+preprocessing_pipeline.connect("document_cleaner", "document_splitter")
+preprocessing_pipeline.connect("document_splitter", "document_embedder")
+preprocessing_pipeline.connect("document_embedder", "document_writer")
+
+preprocessing_pipeline.run(
+ {"file_type_router": {"sources": list(Path(output_dir).glob("**/*"))}},
+)
+```
+
++ +## Additional References + +:notebook: Tutorial: [Preprocessing Different File Types](https://haystack.deepset.ai/tutorials/30_file_type_preprocessing_index_pipeline) diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/listjoiner.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/listjoiner.mdx new file mode 100644 index 0000000000..c556c22bb8 --- /dev/null +++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/listjoiner.mdx @@ -0,0 +1,101 @@ +--- +title: "ListJoiner" +id: listjoiner +slug: "/listjoiner" +description: "A component that joins multiple lists into a single flat list." +--- + +# ListJoiner + +A component that joins multiple lists into a single flat list. + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing and query pipelines, after components that return lists of documents such as multiple [Retrievers](../retrievers.mdx) or multiple [Converters](../converters.mdx) |
+| **Mandatory run variables** | `values`: The dictionary of lists to be joined |
+| **Output variables** | `values`: A dictionary with a `values` key containing the joined list |
+| **API reference** | [Joiners](/reference/joiners-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/joiners/list_joiner.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `ListJoiner` component combines multiple lists into one list. It is useful for combining multiple lists from different pipeline components, merging LLM responses, handling multi-step data processing, and gathering data from different sources into one list.
+
+The items stay in order based on when each input list was processed in a pipeline.
+
+You can optionally specify a `list_type_` parameter to set the expected type of the lists being joined (for example, `List[ChatMessage]`). If not set, `ListJoiner` will accept lists containing mixed data types.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.joiners import ListJoiner
+
+list1 = ["Hello", "world"]
+list2 = ["This", "is", "Haystack"]
+list3 = ["ListJoiner", "Example"]
+
+joiner = ListJoiner()
+
+result = joiner.run(values=[list1, list2, list3])
+
+print(result["values"])
+```
+
+### In a pipeline
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+from haystack.components.joiners import ListJoiner
+from typing import List
+
+user_message = [
+ ChatMessage.from_user("Give a brief answer the following question: {{query}}"),
+]
+
+feedback_prompt = """
+ You are given a question and an answer.
+ Your task is to provide a score and a brief feedback on the answer.
+ Question: {{query}}
+ Answer: {{response}}
+ """
+feedback_message = [ChatMessage.from_system(feedback_prompt)]
+
+prompt_builder = ChatPromptBuilder(template=user_message)
+feedback_prompt_builder = ChatPromptBuilder(template=feedback_message)
+llm = OpenAIChatGenerator(model="gpt-4o-mini")
+feedback_llm = OpenAIChatGenerator(model="gpt-4o-mini")
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.add_component("feedback_prompt_builder", feedback_prompt_builder)
+pipe.add_component("feedback_llm", feedback_llm)
+pipe.add_component("list_joiner", ListJoiner(List[ChatMessage]))
+
+pipe.connect("prompt_builder.prompt", "llm.messages")
+pipe.connect("prompt_builder.prompt", "list_joiner")
+pipe.connect("llm.replies", "list_joiner")
+pipe.connect("llm.replies", "feedback_prompt_builder.response")
+pipe.connect("feedback_prompt_builder.prompt", "feedback_llm.messages")
+pipe.connect("feedback_llm.replies", "list_joiner")
+
+query = "What is nuclear physics?"
+ans = pipe.run(
+ data={
+ "prompt_builder": {"template_variables": {"query": query}},
+ "feedback_prompt_builder": {"template_variables": {"query": query}},
+ },
+)
+
+print(ans["list_joiner"]["values"])
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/stringjoiner.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/stringjoiner.mdx
new file mode 100644
index 0000000000..440fee8aa6
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/joiners/stringjoiner.mdx
@@ -0,0 +1,55 @@
+---
+title: "StringJoiner"
+id: stringjoiner
+slug: "/stringjoiner"
+description: "Component to join strings from different components into a list of strings."
+---
+
+# StringJoiner
+
+Component to join strings from different components into a list of strings.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After at least two other components to join their strings |
+| **Mandatory run variables** | `strings`: Multiple strings from connected components. |
+| **Output variables** | `strings`: A list of merged strings |
+| **API reference** | [Joiners](/reference/joiners-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/joiners/string_joiner.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `StringJoiner` component collects multiple string outputs from various pipeline components and combines them into a single list. This is useful when you need to merge several strings from different parts of a pipeline into a unified output.
+
+## Usage
+
+```python
+from haystack.components.joiners import StringJoiner
+from haystack.components.builders import PromptBuilder
+from haystack.core.pipeline import Pipeline
+
+string_1 = "What's Natural Language Processing?"
+string_2 = "What is life?"
+
+pipeline = Pipeline()
+pipeline.add_component("prompt_builder_1", PromptBuilder("Builder 1: {{query}}"))
+pipeline.add_component("prompt_builder_2", PromptBuilder("Builder 2: {{query}}"))
+pipeline.add_component("string_joiner", StringJoiner())
+
+pipeline.connect("prompt_builder_1.prompt", "string_joiner.strings")
+pipeline.connect("prompt_builder_2.prompt", "string_joiner.strings")
+
+result = pipeline.run(
+ data={
+ "prompt_builder_1": {"query": string_1},
+ "prompt_builder_2": {"query": string_2},
+ },
+)
+
+print(result)
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors.mdx
new file mode 100644
index 0000000000..4da2019dff
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors.mdx
@@ -0,0 +1,29 @@
+---
+title: "PreProcessors"
+id: preprocessors
+slug: "/preprocessors"
+description: "Use the PreProcessors to prepare your data normalize white spaces, remove headers and footers, clean empty lines in your Documents, or split them into smaller pieces. PreProcessors are useful in an indexing pipeline to prepare your files for search."
+---
+
+# PreProcessors
+
+Use the PreProcessors to prepare your data normalize white spaces, remove headers and footers, clean empty lines in your Documents, or split them into smaller pieces. PreProcessors are useful in an indexing pipeline to prepare your files for search.
+
+| PreProcessor | Description |
+| --- | --- |
+| [ChineseDocumentSplitter](preprocessors/chinesedocumentsplitter.mdx) | Divides Chinese text documents into smaller chunks using advanced Chinese language processing capabilities, using HanLP for accurate Chinese word segmentation and sentence tokenization. |
+| [ChonkieRecursiveDocumentSplitter](preprocessors/chonkierecursivedocumentsplitter.mdx) | Splits documents recursively using a hierarchy of rules via Chonkie's `RecursiveChunker`, applying progressively finer splits until all chunks satisfy the size constraints. |
+| [ChonkieSemanticDocumentSplitter](preprocessors/chonkiesemanticdocumentsplitter.mdx) | Splits documents at semantic topic boundaries using embedding similarity via Chonkie's `SemanticChunker`, keeping related sentences together. |
+| [ChonkieSentenceDocumentSplitter](preprocessors/chonkiesentencedocumentsplitter.mdx) | Splits documents into chunks that respect sentence boundaries via Chonkie's `SentenceChunker`, avoiding mid-sentence cuts. |
+| [ChonkieTokenDocumentSplitter](preprocessors/chonkietokendocumentsplitter.mdx) | Splits documents into fixed-size token-based chunks via Chonkie's `TokenChunker`, supporting multiple tokenizers. |
+| [CSVDocumentCleaner](preprocessors/csvdocumentcleaner.mdx) | Cleans CSV documents by removing empty rows and columns while preserving specific ignored rows and columns. |
+| [CSVDocumentSplitter](preprocessors/csvdocumentsplitter.mdx) | Divides CSV documents into smaller sub-tables based on empty rows and columns. |
+| [DocumentCleaner](preprocessors/documentcleaner.mdx) | Removes extra whitespaces, empty lines, specified substrings, regexes, page headers, and footers from documents. |
+| [DocumentPreprocessor](preprocessors/documentpreprocessor.mdx) | Divides a list of text documents into a list of shorter text documents and then makes them more readable by cleaning. |
+| [DocumentSplitter](preprocessors/documentsplitter.mdx) | Splits a list of text documents into a list of text documents with shorter texts. |
+| [HierarchicalDocumentSplitter](preprocessors/hierarchicaldocumentsplitter.mdx) | Creates a multi-level document structure based on parent-children relationships between text segments. |
+| [MarkdownHeaderSplitter](preprocessors/markdownheadersplitter.mdx) | Splits documents at ATX-style Markdown headers (#), with optional secondary splitting. Preserves header hierarchy as metadata. |
+| [PresidioDocumentCleaner](preprocessors/presidiodocumentcleaner.mdx) | Replaces PII in Document text with entity type placeholders using Microsoft Presidio. |
+| [PresidioTextCleaner](preprocessors/presidiotextcleaner.mdx) | Replaces PII in plain strings — useful for sanitizing user queries before they reach an LLM. |
+| [RecursiveSplitter](preprocessors/recursivesplitter.mdx) | Splits text into smaller chunks, it does so by recursively applying a list of separators to the text, applied in the order they are provided. | +| [TextCleaner](preprocessors/textcleaner.mdx) | Removes regexes, punctuation, and numbers, as well as converts text to lowercase. Useful to clean up text data before evaluation. | diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chinesedocumentsplitter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chinesedocumentsplitter.mdx new file mode 100644 index 0000000000..d00504c569 --- /dev/null +++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chinesedocumentsplitter.mdx @@ -0,0 +1,190 @@ +--- +title: "ChineseDocumentSplitter" +id: chinesedocumentsplitter +slug: "/chinesedocumentsplitter" +description: "`ChineseDocumentSplitter` divides Chinese text documents into smaller chunks using advanced Chinese language processing capabilities. It leverages HanLP for accurate Chinese word segmentation and sentence tokenization, making it ideal for processing Chinese text that requires linguistic awareness." +--- + +# ChineseDocumentSplitter + +`ChineseDocumentSplitter` divides Chinese text documents into smaller chunks using advanced Chinese language processing capabilities. It leverages HanLP for accurate Chinese word segmentation and sentence tokenization, making it ideal for processing Chinese text that requires linguistic awareness. + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) and [DocumentCleaner](documentcleaner.mdx), before [Classifiers](../classifiers.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents with Chinese text content |
+| **Output variables** | `documents`: A list of documents, each containing a chunk of the original Chinese text |
+| **API reference** | [HanLP](/reference/integrations-hanlp) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/hanlp |
+| **Package name** | `hanlp-haystack` |
+
+
+
+## Overview
+
+`ChineseDocumentSplitter` is a specialized document splitter designed specifically for Chinese text processing. Unlike English text where words are separated by spaces, Chinese text is written continuously without spaces between words.
+
+This component leverages HanLP (Han Language Processing) to provide accurate Chinese word segmentation and sentence tokenization. It supports two granularity levels:
+
+- **Coarse granularity**: Provides broader word segmentation suitable for most general use cases. Uses `COARSE_ELECTRA_SMALL_ZH` model for general-purpose segmentation.
+- **Fine granularity**: Offers more detailed word segmentation for specialized applications. Uses `FINE_ELECTRA_SMALL_ZH` model for detailed segmentation.
+
+The splitter can divide documents by various units:
+
+- `word`: Splits by Chinese words (multi-character tokens)
+- `sentence`: Splits by sentences using HanLP sentence tokenizer
+- `passage`: Splits by double line breaks ("\\n\\n")
+- `page`: Splits by form feed characters ("\\f")
+- `line`: Splits by single line breaks ("\\n")
+- `period`: Splits by periods (".")
+- `function`: Uses a custom splitting function
+
+Each extracted chunk retains metadata from the original document and includes additional fields:
+
+- `source_id`: The ID of the original document
+- `page_number`: The page number the chunk belongs to
+- `split_id`: The sequential ID of the split within the document
+- `split_idx_start`: The starting index of the chunk in the original document
+
+When `respect_sentence_boundary=True` is set, the component uses HanLP's sentence tokenizer (`UD_CTB_EOS_MUL`) to ensure that splits occur only between complete sentences, preserving the semantic integrity of the text.
+
+## Usage
+
+### On its own
+
+You can use `ChineseDocumentSplitter` outside of a pipeline to process Chinese documents directly:
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter
+
+## Initialize the splitter with word-based splitting
+splitter = ChineseDocumentSplitter(
+ split_by="word",
+ split_length=10,
+ split_overlap=3,
+ granularity="coarse",
+)
+
+## Create a Chinese document
+doc = Document(
+ content="这是第一句话，这是第二句话，这是第三句话。这是第四句话，这是第五句话，这是第六句话！",
+)
+
+## Split the document
+result = splitter.run(documents=[doc])
+print(result["documents"]) # List of split documents
+```
+
+### With sentence boundary respect
+
+When splitting by words, you can ensure that sentence boundaries are respected:
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter
+
+doc = Document(
+ content="这是第一句话，这是第二句话，这是第三句话。"
+ "这是第四句话，这是第五句话，这是第六句话！"
+ "这是第七句话，这是第八句话，这是第九句话？",
+)
+
+splitter = ChineseDocumentSplitter(
+ split_by="word",
+ split_length=10,
+ split_overlap=3,
+ respect_sentence_boundary=True,
+ granularity="coarse",
+)
+result = splitter.run(documents=[doc])
+
+## Each chunk will end with a complete sentence
+for doc in result["documents"]:
+ print(f"Chunk: {doc.content}")
+ print(f"Ends with sentence: {doc.content.endswith(('。', '！', '？'))}")
+```
+
+### With fine granularity
+
+For more detailed word segmentation:
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter
+
+doc = Document(content="人工智能技术正在快速发展，改变着我们的生活方式。")
+
+splitter = ChineseDocumentSplitter(
+ split_by="word",
+ split_length=5,
+ split_overlap=0,
+ granularity="fine", # More detailed segmentation
+)
+result = splitter.run(documents=[doc])
+print(result["documents"])
+```
+
+### With custom splitting function
+
+You can also use a custom function for splitting:
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter
+
+
+def custom_split(text: str) -> list[str]:
+ """Custom splitting function that splits by commas"""
+ return text.split("，")
+
+
+doc = Document(content="第一段，第二段，第三段，第四段")
+
+splitter = ChineseDocumentSplitter(split_by="function", splitting_function=custom_split)
+splitter.warm_up()
+result = splitter.run(documents=[doc])
+print(result["documents"])
+```
+
+### In a pipeline
+
+Here's how you can integrate `ChineseDocumentSplitter` into a Haystack indexing pipeline:
+
+```python
+from haystack import Pipeline, Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.txt import TextFileToDocument
+from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.writers import DocumentWriter
+
+## Initialize components
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=TextFileToDocument(), name="text_file_converter")
+p.add_component(instance=DocumentCleaner(), name="cleaner")
+p.add_component(
+ instance=ChineseDocumentSplitter(
+ split_by="word",
+ split_length=100,
+ split_overlap=20,
+ respect_sentence_boundary=True,
+ granularity="coarse",
+ ),
+ name="chinese_splitter",
+)
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+
+## Connect components
+p.connect("text_file_converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "chinese_splitter.documents")
+p.connect("chinese_splitter.documents", "writer.documents")
+
+## Run pipeline with Chinese text files
+p.run({"text_file_converter": {"sources": ["path/to/your/chinese/files.txt"]}})
+```
+
+This pipeline processes Chinese text files by converting them to documents, cleaning the text, splitting them into linguistically-aware chunks using Chinese word segmentation, and storing the results in the Document Store for further retrieval and processing.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkierecursivedocumentsplitter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkierecursivedocumentsplitter.mdx
new file mode 100644
index 0000000000..32aa20cd59
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkierecursivedocumentsplitter.mdx
@@ -0,0 +1,129 @@
+---
+title: "ChonkieRecursiveDocumentSplitter"
+id: chonkierecursivedocumentsplitter
+slug: "/chonkierecursivedocumentsplitter"
+description: "Use `ChonkieRecursiveDocumentSplitter` to split documents recursively using a hierarchy of rules, powered by the Chonkie library."
+---
+
+# ChonkieRecursiveDocumentSplitter
+
+`ChonkieRecursiveDocumentSplitter` splits documents using a hierarchy of splitting rules via [Chonkie](https://docs.chonkie.ai/)'s `RecursiveChunker`.
+It applies progressively finer-grained splits until all chunks satisfy the configured size constraints, making it effective for structured text like Markdown or code.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx), before [Embedders](../embedders.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Chonkie](/reference/integrations-chonkie) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chonkie |
+
+
+
+## Overview
+
+`ChonkieRecursiveDocumentSplitter` wraps Chonkie's `RecursiveChunker` to split documents by applying splitting rules level by level.
+If a chunk produced at one level still exceeds `chunk_size`, the next level's rules are applied to it.
+This continues recursively until all chunks are within the size limit.
+
+You can customize the splitting behavior by providing `RecursiveRules` from Chonkie.
+See the [Chonkie documentation](https://docs.chonkie.ai/) for details on defining custom rules.
+
+Each output document includes the original document's metadata plus:
+- `source_id`: ID of the original document
+- `page_number`: Page number of the chunk within the original document
+- `split_id`: Index of the chunk within the document
+- `split_idx_start` / `split_idx_end`: Character offsets of the chunk in the original text
+- `token_count`: Number of tokens in the chunk
+
+## Installation
+
+```bash
+pip install chonkie-haystack
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `tokenizer` | `"character"` | Tokenizer to use. Common options: `"character"`, `"gpt2"`, `"cl100k_base"`. See [Chonkie docs](https://docs.chonkie.ai/) for all options. |
+| `chunk_size` | `2048` | Maximum number of tokens per chunk. |
+| `min_characters_per_chunk` | `24` | Minimum number of characters a chunk must contain. |
+| `rules` | `None` | Custom `RecursiveRules` defining the splitting hierarchy. If `None`, Chonkie's default rules are used. |
+| `skip_empty_documents` | `True` | Whether to skip documents with empty content. |
+| `page_break_character` | `"\f"` | Character used to detect page breaks when tracking page numbers. |
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.chonkie import (
+ ChonkieRecursiveDocumentSplitter,
+)
+
+chunker = ChonkieRecursiveDocumentSplitter(chunk_size=512)
+documents = [
+ Document(
+ content="# Introduction\n\nHaystack is a framework.\n\n## Features\n\nIt supports RAG pipelines.",
+ ),
+]
+result = chunker.run(documents=documents)
+print(result["documents"])
+```
+
+### With custom rules
+
+```python
+from chonkie.types.recursive import RecursiveLevel, RecursiveRules
+from haystack import Document
+from haystack_integrations.components.preprocessors.chonkie import (
+ ChonkieRecursiveDocumentSplitter,
+)
+
+rules = RecursiveRules(
+ levels=[
+ RecursiveLevel(delimiters=["\n\n"]),
+ RecursiveLevel(delimiters=["\n"]),
+ RecursiveLevel(delimiters=[". ", "! ", "? "]),
+ ],
+)
+
+chunker = ChonkieRecursiveDocumentSplitter(chunk_size=256, rules=rules)
+documents = [Document(content="First paragraph.\n\nSecond paragraph with more detail.")]
+result = chunker.run(documents=documents)
+print(result["documents"])
+```
+
+### In a pipeline
+
+```python
+from pathlib import Path
+
+from haystack import Pipeline
+from haystack.components.converters import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.preprocessors.chonkie import (
+ ChonkieRecursiveDocumentSplitter,
+)
+
+document_store = InMemoryDocumentStore()
+
+p = Pipeline()
+p.add_component("converter", TextFileToDocument())
+p.add_component("cleaner", DocumentCleaner())
+p.add_component("splitter", ChonkieRecursiveDocumentSplitter(chunk_size=512))
+p.add_component("writer", DocumentWriter(document_store=document_store))
+
+p.connect("converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+files = list(Path("path/to/your/files").glob("*.md"))
+p.run({"converter": {"sources": files}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkiesemanticdocumentsplitter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkiesemanticdocumentsplitter.mdx
new file mode 100644
index 0000000000..b736c4ede7
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkiesemanticdocumentsplitter.mdx
@@ -0,0 +1,119 @@
+---
+title: "ChonkieSemanticDocumentSplitter"
+id: chonkiesemanticdocumentsplitter
+slug: "/chonkiesemanticdocumentsplitter"
+description: "Use `ChonkieSemanticDocumentSplitter` to split documents at semantic topic boundaries using embedding similarity, powered by the Chonkie library."
+---
+
+# ChonkieSemanticDocumentSplitter
+
+`ChonkieSemanticDocumentSplitter` splits documents at semantically meaningful boundaries using [Chonkie](https://docs.chonkie.ai/)'s `SemanticChunker`.
+Rather than splitting by a fixed token count, it uses an embedding model to detect topic shifts and keeps related sentences together.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx), before [Embedders](../embedders.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Chonkie](/reference/integrations-chonkie) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chonkie |
+
+
+
+## Overview
+
+`ChonkieSemanticDocumentSplitter` wraps Chonkie's `SemanticChunker` to produce context-aware chunks by grouping sentences with similar semantic content.
+It computes embeddings for sentences and uses cosine similarity to find natural topic boundaries.
+
+The embedding model is loaded lazily — `warm_up()` is called automatically the first time `run()` is invoked, whether inside a pipeline or standalone.
+
+Each output document includes the original document's metadata plus:
+- `source_id`: ID of the original document
+- `page_number`: Page number of the chunk within the original document
+- `split_id`: Index of the chunk within the document
+- `split_idx_start` / `split_idx_end`: Character offsets of the chunk in the original text
+- `token_count`: Number of tokens in the chunk
+
+## Installation
+
+```bash
+pip install chonkie-haystack
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `embedding_model` | `"minishlab/potion-base-32M"` | The embedding model used to compute sentence similarity. See [Chonkie docs](https://docs.chonkie.ai/) for supported models. |
+| `threshold` | `0.8` | Cosine similarity threshold below which a sentence boundary becomes a split point. |
+| `chunk_size` | `2048` | Maximum number of tokens per chunk (based on the embedding model's tokenizer). |
+| `similarity_window` | `3` | Number of surrounding sentences to include when computing similarity. |
+| `min_sentences_per_chunk` | `1` | Minimum number of sentences that must be included in each chunk. |
+| `min_characters_per_sentence` | `24` | Minimum number of characters for a sentence to be considered valid. |
+| `delim` | `None` | Custom sentence delimiters. If `None`, Chonkie's default delimiters are used. |
+| `include_delim` | `"prev"` | Whether to attach the delimiter to the previous (`"prev"`) or next (`"next"`) chunk. |
+| `skip_window` | `0` | Number of sentences to skip when computing similarity scores. |
+| `filter_window` | `5` | Window size for the Savitzky-Golay smoothing filter applied to similarity scores. |
+| `filter_polyorder` | `3` | Polynomial order for the Savitzky-Golay filter. |
+| `filter_tolerance` | `0.2` | Tolerance used when filtering similarity scores. |
+| `skip_empty_documents` | `True` | Whether to skip documents with empty content. |
+| `page_break_character` | `"\f"` | Character used to detect page breaks when tracking page numbers. |
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.chonkie import (
+ ChonkieSemanticDocumentSplitter,
+)
+
+chunker = ChonkieSemanticDocumentSplitter(chunk_size=512, threshold=0.5)
+
+documents = [
+ Document(
+ content="Haystack is an open-source framework for LLM applications. "
+ "It makes building RAG pipelines easy. "
+ "The Eiffel Tower is located in Paris. "
+ "Paris is the capital of France.",
+ ),
+]
+result = chunker.run(documents=documents)
+print(result["documents"])
+```
+
+### In a pipeline
+
+```python
+from pathlib import Path
+
+from haystack import Pipeline
+from haystack.components.converters import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.preprocessors.chonkie import (
+ ChonkieSemanticDocumentSplitter,
+)
+
+document_store = InMemoryDocumentStore()
+
+p = Pipeline()
+p.add_component("converter", TextFileToDocument())
+p.add_component("cleaner", DocumentCleaner())
+p.add_component(
+ "splitter",
+ ChonkieSemanticDocumentSplitter(chunk_size=512, threshold=0.5),
+)
+p.add_component("writer", DocumentWriter(document_store=document_store))
+
+p.connect("converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+files = list(Path("path/to/your/files").glob("*.txt"))
+p.run({"converter": {"sources": files}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkiesentencedocumentsplitter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkiesentencedocumentsplitter.mdx
new file mode 100644
index 0000000000..c13d1355bc
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkiesentencedocumentsplitter.mdx
@@ -0,0 +1,113 @@
+---
+title: "ChonkieSentenceDocumentSplitter"
+id: chonkiesentencedocumentsplitter
+slug: "/chonkiesentencedocumentsplitter"
+description: "Use `ChonkieSentenceDocumentSplitter` to split documents into sentence-aware chunks using the Chonkie library."
+---
+
+# ChonkieSentenceDocumentSplitter
+
+`ChonkieSentenceDocumentSplitter` splits documents into chunks that respect sentence boundaries using [Chonkie](https://docs.chonkie.ai/)'s `SentenceChunker`.
+Unlike pure token splitting, it avoids cutting mid-sentence, producing more coherent chunks.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) and [`DocumentCleaner`](documentcleaner.mdx), before [Embedders](../embedders.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Chonkie](/reference/integrations-chonkie) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chonkie |
+
+
+
+## Overview
+
+`ChonkieSentenceDocumentSplitter` wraps Chonkie's `SentenceChunker` to split each input document into chunks whose boundaries align with sentence endings.
+The chunker groups sentences together until the chunk size limit is reached.
+
+Each output document includes the original document's metadata plus:
+- `source_id`: ID of the original document
+- `page_number`: Page number of the chunk within the original document
+- `split_id`: Index of the chunk within the document
+- `split_idx_start` / `split_idx_end`: Character offsets of the chunk in the original text
+- `token_count`: Number of tokens in the chunk
+
+## Installation
+
+```bash
+pip install chonkie-haystack
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `tokenizer` | `"character"` | Tokenizer to use. Common options: `"character"`, `"gpt2"`, `"cl100k_base"`. See [Chonkie docs](https://docs.chonkie.ai/) for all options. |
+| `chunk_size` | `2048` | Maximum number of tokens per chunk. |
+| `chunk_overlap` | `0` | Number of overlapping tokens between consecutive chunks. |
+| `min_sentences_per_chunk` | `1` | Minimum number of sentences that must be included in each chunk. |
+| `min_characters_per_sentence` | `12` | Minimum number of characters for a sentence to be considered valid. |
+| `approximate` | `False` | Whether to use approximate chunking for faster processing. |
+| `delim` | `None` | Custom sentence delimiters. If `None`, Chonkie's default delimiters are used. |
+| `include_delim` | `"prev"` | Whether to attach the delimiter to the previous (`"prev"`) or next (`"next"`) chunk. |
+| `skip_empty_documents` | `True` | Whether to skip documents with empty content. |
+| `page_break_character` | `"\f"` | Character used to detect page breaks when tracking page numbers. |
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.chonkie import (
+ ChonkieSentenceDocumentSplitter,
+)
+
+chunker = ChonkieSentenceDocumentSplitter(
+ tokenizer="gpt2",
+ chunk_size=512,
+ chunk_overlap=0,
+)
+documents = [
+ Document(
+ content="Haystack is an open-source framework. It helps you build LLM applications.",
+ ),
+]
+result = chunker.run(documents=documents)
+print(result["documents"])
+```
+
+### In a pipeline
+
+```python
+from pathlib import Path
+
+from haystack import Pipeline
+from haystack.components.converters import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.preprocessors.chonkie import (
+ ChonkieSentenceDocumentSplitter,
+)
+
+document_store = InMemoryDocumentStore()
+
+p = Pipeline()
+p.add_component("converter", TextFileToDocument())
+p.add_component("cleaner", DocumentCleaner())
+p.add_component(
+ "splitter",
+ ChonkieSentenceDocumentSplitter(tokenizer="gpt2", chunk_size=512),
+)
+p.add_component("writer", DocumentWriter(document_store=document_store))
+
+p.connect("converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+files = list(Path("path/to/your/files").glob("*.txt"))
+p.run({"converter": {"sources": files}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkietokendocumentsplitter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkietokendocumentsplitter.mdx
new file mode 100644
index 0000000000..656710268f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/chonkietokendocumentsplitter.mdx
@@ -0,0 +1,108 @@
+---
+title: "ChonkieTokenDocumentSplitter"
+id: chonkietokendocumentsplitter
+slug: "/chonkietokendocumentsplitter"
+description: "Use `ChonkieTokenDocumentSplitter` to split documents into token-based chunks using the Chonkie library."
+---
+
+# ChonkieTokenDocumentSplitter
+
+`ChonkieTokenDocumentSplitter` splits documents into fixed-size token-based chunks using [Chonkie](https://docs.chonkie.ai/)'s `TokenChunker`.
+It supports multiple tokenizers and is well-suited for splitting long documents before indexing.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) and [`DocumentCleaner`](documentcleaner.mdx), before [Embedders](../embedders.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Chonkie](/reference/integrations-chonkie) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chonkie |
+
+
+
+## Overview
+
+`ChonkieTokenDocumentSplitter` wraps Chonkie's `TokenChunker` to split each input document into smaller chunks based on token count.
+You can configure the tokenizer, chunk size, and overlap between chunks.
+
+Each output document includes the original document's metadata plus:
+- `source_id`: ID of the original document
+- `page_number`: Page number of the chunk within the original document
+- `split_id`: Index of the chunk within the document
+- `split_idx_start` / `split_idx_end`: Character offsets of the chunk in the original text
+- `token_count`: Number of tokens in the chunk
+
+## Installation
+
+```bash
+pip install chonkie-haystack
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `tokenizer` | `"character"` | Tokenizer to use. Common options: `"character"`, `"gpt2"`, `"cl100k_base"`. See [Chonkie docs](https://docs.chonkie.ai/) for all options. |
+| `chunk_size` | `2048` | Maximum number of tokens per chunk. |
+| `chunk_overlap` | `0` | Number of overlapping tokens between consecutive chunks. |
+| `skip_empty_documents` | `True` | Whether to skip documents with empty content. |
+| `page_break_character` | `"\f"` | Character used to detect page breaks when tracking page numbers. |
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.chonkie import (
+ ChonkieTokenDocumentSplitter,
+)
+
+chunker = ChonkieTokenDocumentSplitter(
+ tokenizer="gpt2",
+ chunk_size=512,
+ chunk_overlap=50,
+)
+documents = [
+ Document(
+ content="Haystack is an open-source framework for building LLM applications.",
+ ),
+]
+result = chunker.run(documents=documents)
+print(result["documents"])
+```
+
+### In a pipeline
+
+```python
+from pathlib import Path
+
+from haystack import Pipeline
+from haystack.components.converters import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.preprocessors.chonkie import (
+ ChonkieTokenDocumentSplitter,
+)
+
+document_store = InMemoryDocumentStore()
+
+p = Pipeline()
+p.add_component("converter", TextFileToDocument())
+p.add_component("cleaner", DocumentCleaner())
+p.add_component(
+ "splitter",
+ ChonkieTokenDocumentSplitter(tokenizer="gpt2", chunk_size=512),
+)
+p.add_component("writer", DocumentWriter(document_store=document_store))
+
+p.connect("converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+files = list(Path("path/to/your/files").glob("*.txt"))
+p.run({"converter": {"sources": files}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/csvdocumentcleaner.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/csvdocumentcleaner.mdx
new file mode 100644
index 0000000000..95add1767b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/csvdocumentcleaner.mdx
@@ -0,0 +1,90 @@
+---
+title: "CSVDocumentCleaner"
+id: csvdocumentcleaner
+slug: "/csvdocumentcleaner"
+description: "Use `CSVDocumentCleaner` to clean CSV documents by removing empty rows and columns while preserving specific ignored rows and columns. It processes CSV content stored in documents and helps standardize data for further analysis."
+---
+
+# CSVDocumentCleaner
+
+Use `CSVDocumentCleaner` to clean CSV documents by removing empty rows and columns while preserving specific ignored rows and columns. It processes CSV content stored in documents and helps standardize data for further analysis.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) , before [Embedders](../embedders.mdx) or [Writers](../writers/documentwriter.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents containing CSV content |
+| **Output variables** | `documents`: A list of cleaned CSV documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/csv_document_cleaner.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`CSVDocumentCleaner` expects a list of `Document` objects as input, each containing CSV-formatted content as text. It cleans the data by removing fully empty rows and columns while allowing users to specify the number of rows and columns to be preserved before cleaning.
+
+### Parameters
+
+- `ignore_rows`: Number of rows to ignore from the top of the CSV table before processing. If any columns are removed, the same columns will be dropped from the ignored rows.
+- `ignore_columns`: Number of columns to ignore from the left of the CSV table before processing. If any rows are removed, the same rows will be dropped from the ignored columns.
+- `remove_empty_rows`: Whether to remove entirely empty rows.
+- `remove_empty_columns`: Whether to remove entirely empty columns.
+- `keep_id`: Whether to retain the original document ID in the output document.
+
+### Cleaning Process
+
+The `CSVDocumentCleaner` algorithm follows these steps:
+
+1. Reads each document's content as a CSV table using pandas.
+2. Retains the specified number of `ignore_rows` from the top and `ignore_columns` from the left.
+3. Drops any rows and columns that are entirely empty (contain only NaN values).
+4. If columns are dropped, they are also removed from ignored rows.
+5. If rows are dropped, they are also removed from ignored columns.
+6. Reattaches the remaining ignored rows and columns to maintain their original positions.
+7. Returns the cleaned CSV content as a new `Document` object.
+
+## Usage
+
+### On its own
+
+You can use `CSVDocumentCleaner` independently to clean up CSV documents:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import CSVDocumentCleaner
+
+cleaner = CSVDocumentCleaner(ignore_rows=1, ignore_columns=0)
+
+documents = [Document(content="""col1,col2,col3\n,,\na,b,c\n,,""")]
+cleaned_docs = cleaner.run(documents=documents)
+```
+
+### In a pipeline
+
+```python
+from pathlib import Path
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import XLSXToDocument
+from haystack.components.preprocessors import CSVDocumentCleaner
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=XLSXToDocument(), name="xlsx_file_converter")
+p.add_component(
+ instance=CSVDocumentCleaner(ignore_rows=1, ignore_columns=1),
+ name="csv_cleaner",
+)
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+
+p.connect("xlsx_file_converter.documents", "csv_cleaner.documents")
+p.connect("csv_cleaner.documents", "writer.documents")
+
+p.run({"xlsx_file_converter": {"sources": [Path("your_xlsx_file.xlsx")]}})
+```
+
+This ensures that CSV documents are properly cleaned before further processing or storage.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/csvdocumentsplitter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/csvdocumentsplitter.mdx
new file mode 100644
index 0000000000..15adee0ade
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/csvdocumentsplitter.mdx
@@ -0,0 +1,118 @@
+---
+title: "CSVDocumentSplitter"
+id: csvdocumentsplitter
+slug: "/csvdocumentsplitter"
+description: "`CSVDocumentSplitter` divides CSV documents into smaller sub-tables based on split arguments. This is useful for handling structured data that contains multiple tables, improving data processing efficiency and retrieval."
+---
+
+# CSVDocumentSplitter
+
+`CSVDocumentSplitter` divides CSV documents into smaller sub-tables based on split arguments. This is useful for handling structured data that contains multiple tables, improving data processing efficiency and retrieval.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) , before [CSVDocumentCleaner](csvdocumentcleaner.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents with CSV-formatted content |
+| **Output variables** | `documents`: A list of documents, each containing a sub-table extracted from the original CSV file |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/csv_document_splitter.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`CSVDocumentSplitter` expects a list of documents containing CSV-formatted content and returns a list of new `Document` objects, each representing a sub-table extracted from the original document.
+
+There are two modes of operation for the splitter:
+
+1. `threshold` (Default): Identifies empty rows or columns exceeding a given threshold and splits the document accordingly.
+2. `row-wise`: Splits each row into a separate document, treating each as an independent sub-table.
+
+The splitting process follows these rules:
+
+1. **Row-Based Splitting**: If `row_split_threshold` is set, consecutive empty rows equalling or exceeding this threshold trigger a split.
+2. **Column-Based Splitting**: If `column_split_threshold` is set, consecutive empty columns equalling or exceeding this threshold trigger a split.
+3. **Recursive Splitting**: If both thresholds are provided, `CSVDocumentSplitter` first splits by rows and then by columns. If more empty rows are detected, the splitting process is called again. This ensures that sub-tables are fully separated.
+
+Each extracted sub-table retains metadata from the original document and includes additional fields:
+
+- `source_id`: The ID of the original document
+- `row_idx_start`: The starting row index of the sub-table in the original document
+- `col_idx_start`: The starting column index of the sub-table in the original document
+- `split_id`: The sequential ID of the split within the document
+
+This component is especially useful for document processing pipelines that require structured data to be extracted and stored efficiently.
+
+### Supported Document Stores
+
+`CSVDocumentSplitter` is compatible with the following Document Stores:
+
+- [AstraDocumentStore](../../document-stores/astradocumentstore.mdx)
+- [ChromaDocumentStore](../../document-stores/chromadocumentstore.mdx)
+- [ElasticsearchDocumentStore](../../document-stores/elasticsearch-document-store.mdx)
+- [OpenSearchDocumentStore](../../document-stores/opensearch-document-store.mdx)
+- [PgvectorDocumentStore](../../document-stores/pgvectordocumentstore.mdx)
+- [PineconeDocumentStore](../../document-stores/pinecone-document-store.mdx)
+- [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx)
+- [WeaviateDocumentStore](../../document-stores/weaviatedocumentstore.mdx)
+- [MilvusDocumentStore](https://haystack.deepset.ai/integrations/milvus-document-store)
+- [Neo4jDocumentStore](https://haystack.deepset.ai/integrations/neo4j-document-store)
+
+## Usage
+
+### On its own
+
+You can use `CSVDocumentSplitter` outside of a pipeline to process CSV documents directly:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import CSVDocumentSplitter
+
+splitter = CSVDocumentSplitter(row_split_threshold=1, column_split_threshold=1)
+
+doc = Document(
+ content="""ID,LeftVal,,,RightVal,Extra
+1,Hello,,,World,Joined
+2,StillLeft,,,StillRight,Bridge
+,,,,,
+A,B,,,C,D
+E,F,,,G,H
+""",
+)
+split_result = splitter.run([doc])
+print(split_result["documents"]) # List of split tables as Documents
+```
+
+### In a pipeline
+
+Here's how you can integrate `CSVDocumentSplitter` into a Haystack indexing pipeline:
+
+```python
+from haystack import Pipeline, Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.csv import CSVToDocument
+from haystack.components.preprocessors import CSVDocumentSplitter
+from haystack.components.preprocessors import CSVDocumentCleaner
+from haystack.components.writers import DocumentWriter
+
+## Initialize components
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=CSVToDocument(), name="csv_file_converter")
+p.add_component(instance=CSVDocumentSplitter(), name="splitter")
+p.add_component(instance=CSVDocumentCleaner(), name="cleaner")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+
+## Connect components
+p.connect("csv_file_converter.documents", "splitter.documents")
+p.connect("splitter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "writer.documents")
+
+## Run pipeline
+p.run({"csv_file_converter": {"sources": ["path/to/your/file.csv"]}})
+```
+
+This pipeline extracts CSV content, splits it into structured sub-tables, cleans the CSV documents by removing empty rows and columns, and stores the resulting documents in the Document Store for further retrieval and processing.
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/documentcleaner.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/documentcleaner.mdx
new file mode 100644
index 0000000000..03d87f5d98
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/documentcleaner.mdx
@@ -0,0 +1,152 @@
+---
+title: "DocumentCleaner"
+id: documentcleaner
+slug: "/documentcleaner"
+description: "Use `DocumentCleaner` to make text documents more readable. It removes extra whitespaces, empty lines, specified substrings, regexes, page headers, and footers in this particular order. This is useful for preparing the documents for further processing by LLMs."
+---
+
+# DocumentCleaner
+
+Use `DocumentCleaner` to make text documents more readable. It removes extra whitespaces, empty lines, specified substrings, regexes, page headers, and footers in this particular order. This is useful for preparing the documents for further processing by LLMs.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) , after [`DocumentSplitter`](documentsplitter.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/document_cleaner.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`DocumentCleaner` expects a list of documents as input and returns a list of documents with cleaned texts. Selectable cleaning steps for each input document are to `remove_empty_lines`, `remove_extra_whitespaces` and to `remove_repeated_substrings`. These three parameters are booleans that can be set when the component is initialized.
+
+- `unicode_normalization` normalizes Unicode characters to a standard form. The parameter can be set to NFC, NFKC, NFD, or NFKD.
+- `ascii_only` removes accents from characters and replaces them with their closest ASCII equivalents.
+- `remove_empty_lines` removes empty lines from the document.
+- `remove_extra_whitespaces` removes extra whitespaces from the document.
+- `remove_repeated_substrings` removes repeated substrings (headers/footers) from pages in the document. Pages in the text need to be separated by form feed character "\\f", which is supported by [`TextFileToDocument`](../converters/textfiletodocument.mdx), [`AzureOCRDocumentConverter`](../converters/azureocrdocumentconverter.mdx), [`MistralOCRDocumentConverter`](../converters/mistralocrdocumentconverter.mdx), and [`PaddleOCRVLDocumentConverter`](../converters/paddleocrvldocumentconverter.mdx).
+
+:::note
+`remove_extra_whitespaces` and `remove_empty_lines` work best on plain-text content. If your converter returns Markdown, such as [`AzureDocumentIntelligenceConverter`](../converters/azuredocumentintelligenceconverter.mdx), [`MarkItDownConverter`](../converters/markitdownconverter.mdx), [`MistralOCRDocumentConverter`](../converters/mistralocrdocumentconverter.mdx), or [`PaddleOCRVLDocumentConverter`](../converters/paddleocrvldocumentconverter.mdx), disable those options to preserve headings, tables, lists, and image tags.
+:::
+
+In addition, you can specify a list of strings that should be removed from all documents as part of the cleaning with the parameter `remove_substring`. You can also specify a regular expression with the parameter `remove_regex` and any matches will be removed.
+
+The cleaning steps are executed in the following order:
+
+1. unicode_normalization
+2. ascii_only
+3. remove_extra_whitespaces
+4. remove_empty_lines
+5. remove_substrings
+6. remove_regex
+7. remove_repeated_substrings
+
+## Usage
+
+### On its own
+
+You can use it outside of a pipeline to clean up your documents:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentCleaner
+
+doc = Document(content="This is a document to clean\n\n\nsubstring to remove")
+
+cleaner = DocumentCleaner(remove_substrings=["substring to remove"])
+result = cleaner.run(documents=[doc])
+
+assert result["documents"][0].content == "This is a document to clean "
+```
+
+### In a pipeline
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=TextFileToDocument(), name="text_file_converter")
+p.add_component(instance=DocumentCleaner(), name="cleaner")
+p.add_component(
+ instance=DocumentSplitter(split_by="sentence", split_length=1),
+ name="splitter",
+)
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+p.connect("text_file_converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+p.run({"text_file_converter": {"sources": your_files}})
+```
+
+### In YAML
+```yaml
+components:
+ cleaner:
+ init_parameters:
+ ascii_only: false
+ keep_id: false
+ remove_empty_lines: true
+ remove_extra_whitespaces: true
+ remove_regex: null
+ remove_repeated_substrings: false
+ remove_substrings: null
+ replace_regexes: null
+ strip_whitespaces: false
+ unicode_normalization: null
+ type: haystack.components.preprocessors.document_cleaner.DocumentCleaner
+ splitter:
+ init_parameters:
+ extend_abbreviations: true
+ language: en
+ respect_sentence_boundary: false
+ skip_empty_documents: true
+ split_by: sentence
+ split_length: 1
+ split_overlap: 0
+ split_threshold: 0
+ use_split_rules: true
+ type: haystack.components.preprocessors.document_splitter.DocumentSplitter
+ text_file_converter:
+ init_parameters:
+ encoding: utf-8
+ store_full_path: false
+ type: haystack.components.converters.txt.TextFileToDocument
+ writer:
+ init_parameters:
+ document_store:
+ init_parameters:
+ bm25_algorithm: BM25L
+ bm25_parameters: {}
+ bm25_tokenization_regex: (?u)\\b\\w+\\b
+ embedding_similarity_function: dot_product
+ index: 64e4f9ab-87fb-47fd-b390-dabcfda61447
+ return_embedding: true
+ type: haystack.document_stores.in_memory.document_store.InMemoryDocumentStore
+ policy: NONE
+ type: haystack.components.writers.document_writer.DocumentWriter
+connection_type_validation: true
+connections:
+- receiver: cleaner.documents
+ sender: text_file_converter.documents
+- receiver: splitter.documents
+ sender: cleaner.documents
+- receiver: writer.documents
+ sender: splitter.documents
+max_runs_per_component: 100
+metadata: {}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/documentpreprocessor.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/documentpreprocessor.mdx
new file mode 100644
index 0000000000..4067a56656
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/documentpreprocessor.mdx
@@ -0,0 +1,80 @@
+---
+title: "DocumentPreprocessor"
+id: documentpreprocessor
+slug: "/documentpreprocessor"
+description: "Divides a list of text documents into a list of shorter text documents and then makes them more readable by cleaning."
+---
+
+# DocumentPreprocessor
+
+Divides a list of text documents into a list of shorter text documents and then makes them more readable by cleaning.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of split and cleaned documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/document_preprocessor.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`DocumentPreprocessor` first splits and then cleans documents.
+
+It is a SuperComponent that combines a `DocumentSplitter` and a `DocumentCleaner` into a single component.
+
+### Parameters
+
+The `DocumentPreprocessor` exposes all initialization parameters of the underlying `DocumentSplitter` and `DocumentCleaner`, and they are all optional. A detailed description of their parameters is in the respective documentation pages:
+
+- [DocumentSplitter](documentsplitter.mdx)
+- [DocumentCleaner](documentcleaner.mdx)
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentPreprocessor
+
+doc = Document(content="I love pizza!")
+preprocessor = DocumentPreprocessor()
+
+result = preprocessor.run(documents=[doc])
+print(result["documents"])
+```
+
+### In a pipeline
+
+You can use the `DocumentPreprocessor` in your indexing pipeline. The example below requires installing additional dependencies for the `MultiFileConverter`:
+
+```shell
+pip install pypdf markdown-it-py mdit_plain trafilatura python-pptx python-docx jq openpyxl tabulate pandas
+```
+
+```python
+from haystack import Pipeline
+from haystack.components.converters import MultiFileConverter
+from haystack.components.preprocessors import DocumentPreprocessor
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", MultiFileConverter())
+pipeline.add_component("preprocessor", DocumentPreprocessor())
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "preprocessor")
+pipeline.connect("preprocessor", "writer")
+
+result = pipeline.run(data={"sources": ["test.txt", "test.pdf"]})
+print(result)
+## {'writer': {'documents_written': 3}}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/documentsplitter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/documentsplitter.mdx
new file mode 100644
index 0000000000..0d13575815
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/documentsplitter.mdx
@@ -0,0 +1,159 @@
+---
+title: "DocumentSplitter"
+id: documentsplitter
+slug: "/documentsplitter"
+description: "`DocumentSplitter` divides a list of text documents into a list of shorter text documents. This is useful for long texts that otherwise wouldn't fit into the maximum text length of language models and can also speed up question answering."
+---
+
+# DocumentSplitter
+
+`DocumentSplitter` divides a list of text documents into a list of shorter text documents. This is useful for long texts that otherwise wouldn't fit into the maximum text length of language models and can also speed up question answering.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) and [`DocumentCleaner`](documentcleaner.mdx) , before [Classifiers](../classifiers.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/document_splitter.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+`DocumentSplitter` expects a list of documents as input and returns a list of documents with split texts. It splits each input document by `split_by` after `split_length` units with an overlap of `split_overlap` units. These additional parameters can be set when the component is initialized:
+
+- `split_by` can be `"word"`, `"sentence"`, `"passage"` (paragraph), `"page"`, `"line"` or `"function"`.
+- `split_length` is an integer indicating the chunk size, which is the number of words, sentences, or passages.
+- `split_overlap` is an integer indicating the number of overlapping words, sentences, or passages between chunks.
+- `split_threshold` is an integer indicating the minimum number of words, sentences, or passages that the document fragment should have. If the fragment is below the threshold, it will be attached to the previous one.
+
+A field `"source_id"` is added to each document's `meta` data to keep track of the original document that was split. Another meta field `"page_number"` is added to each document to keep track of the page it belonged to in the original document. Other metadata are copied from the original document.
+
+The DocumentSplitter is compatible with the following DocumentStores:
+
+- [AstraDocumentStore](../../document-stores/astradocumentstore.mdx)
+- [ChromaDocumentStore](../../document-stores/chromadocumentstore.mdx) – limited support, overlapping information is not stored.
+- [ElasticsearchDocumentStore](../../document-stores/elasticsearch-document-store.mdx)
+- [OpenSearchDocumentStore](../../document-stores/opensearch-document-store.mdx)
+- [PgvectorDocumentStore](../../document-stores/pgvectordocumentstore.mdx)
+- [PineconeDocumentStore](../../document-stores/pinecone-document-store.mdx) – limited support, overlapping information is not stored.
+- [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx)
+- [WeaviateDocumentStore](../../document-stores/weaviatedocumentstore.mdx)
+- [MilvusDocumentStore](https://haystack.deepset.ai/integrations/milvus-document-store)
+- [Neo4jDocumentStore](https://haystack.deepset.ai/integrations/neo4j-document-store)
+
+## Usage
+
+### On its own
+
+You can use this component outside of a pipeline to shorten your documents like this:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentSplitter
+
+doc = Document(
+ content="Moonlight shimmered softly, wolves howled nearby, night enveloped everything.",
+)
+
+splitter = DocumentSplitter(split_by="word", split_length=3, split_overlap=0)
+result = splitter.run(documents=[doc])
+```
+
+### In a pipeline
+
+Here's how you can use `DocumentSplitter` in an indexing pipeline:
+
+```python
+from pathlib import Path
+
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.txt import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=TextFileToDocument(), name="text_file_converter")
+p.add_component(instance=DocumentCleaner(), name="cleaner")
+p.add_component(
+ instance=DocumentSplitter(split_by="sentence", split_length=1),
+ name="splitter",
+)
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+p.connect("text_file_converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+path = "path/to/your/files"
+files = list(Path(path).glob("*.md"))
+p.run({"text_file_converter": {"sources": files}})
+```
+
+### In YAML
+
+This is the YAML representation of the indexing pipeline shown above. It reads text files, cleans the text, splits it into individual sentences, and writes them to an in-memory document store.
+
+```yaml
+components:
+ cleaner:
+ init_parameters:
+ ascii_only: false
+ keep_id: false
+ remove_empty_lines: true
+ remove_extra_whitespaces: true
+ remove_regex: null
+ remove_repeated_substrings: false
+ remove_substrings: null
+ replace_regexes: null
+ strip_whitespaces: false
+ unicode_normalization: null
+ type: haystack.components.preprocessors.document_cleaner.DocumentCleaner
+ splitter:
+ init_parameters:
+ extend_abbreviations: true
+ language: en
+ respect_sentence_boundary: false
+ skip_empty_documents: true
+ split_by: sentence
+ split_length: 1
+ split_overlap: 0
+ split_threshold: 0
+ use_split_rules: true
+ type: haystack.components.preprocessors.document_splitter.DocumentSplitter
+ text_file_converter:
+ init_parameters:
+ encoding: utf-8
+ store_full_path: false
+ type: haystack.components.converters.txt.TextFileToDocument
+ writer:
+ init_parameters:
+ document_store:
+ init_parameters:
+ bm25_algorithm: BM25L
+ bm25_parameters: {}
+ bm25_tokenization_regex: (?u)\\b\\w+\\b
+ embedding_similarity_function: dot_product
+ index: 64e4f9ab-87fb-47fd-b390-dabcfda61447
+ return_embedding: true
+ type: haystack.document_stores.in_memory.document_store.InMemoryDocumentStore
+ policy: NONE
+ type: haystack.components.writers.document_writer.DocumentWriter
+connection_type_validation: true
+connections:
+- receiver: cleaner.documents
+ sender: text_file_converter.documents
+- receiver: splitter.documents
+ sender: cleaner.documents
+- receiver: writer.documents
+ sender: splitter.documents
+max_runs_per_component: 100
+metadata: {}
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/embeddingbaseddocumentsplitter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/embeddingbaseddocumentsplitter.mdx
new file mode 100644
index 0000000000..e80ce7c52e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/embeddingbaseddocumentsplitter.mdx
@@ -0,0 +1,98 @@
+---
+title: "EmbeddingBasedDocumentSplitter"
+id: embeddingbaseddocumentsplitter
+slug: "/embeddingbaseddocumentsplitter"
+description: "Use this component to split documents based on embedding similarity using cosine distances between sequential sentence groups."
+---
+
+# EmbeddingBasedDocumentSplitter
+
+Use this component to split documents based on embedding similarity using cosine distances between sequential sentence groups.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) and [`DocumentCleaner`](documentcleaner.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents to split each into smaller documents based on embedding similarity. |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/embedding_based_document_splitter.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+This component splits documents based on embedding similarity using cosine distances between sequential sentence groups.
+
+It first splits text into sentences, optionally groups them, calculates embeddings for each group, and then uses cosine
+distance between sequential embeddings to determine split points. Any distance above the specified percentile is treated
+as a break point. The component also tracks page numbers based on form feed characters (`\f`) in the original document.
+
+This component is inspired by [5 Levels of Text Splitting](https://github.com/FullStackRetrieval-com/RetrievalTutorials/blob/main/tutorials/LevelsOfTextSplitting/5_Levels_Of_Text_Splitting.ipynb) by Greg Kamradt.
+
+## Usage
+
+### On its own
+
+```python
+
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+from haystack.components.preprocessors import EmbeddingBasedDocumentSplitter
+
+# Create a document with content that has a clear topic shift
+doc = Document(
+ content="This is a first sentence. This is a second sentence. This is a third sentence. "
+ "Completely different topic. The same completely different topic.",
+)
+
+# Initialize the embedder to calculate semantic similarities
+embedder = SentenceTransformersDocumentEmbedder()
+
+# Configure the splitter with parameters that control splitting behavior
+splitter = EmbeddingBasedDocumentSplitter(
+ document_embedder=embedder,
+ sentences_per_group=2, # Group 2 sentences before calculating embeddings
+ percentile=0.95, # Split when cosine distance exceeds 95th percentile
+ min_length=50, # Merge splits shorter than 50 characters
+ max_length=1000, # Further split chunks longer than 1000 characters
+)
+result = splitter.run(documents=[doc])
+
+# The result contains a list of Document objects, each representing a semantic chunk
+# Each split document includes metadata: source_id, split_id, and page_number
+print(f"Original document split into {len(result['documents'])} chunks")
+for i, split_doc in enumerate(result["documents"]):
+ print(f"Chunk {i}: {split_doc.content[:50]}...")
+```
+
+### In a pipeline
+
+```python
+from pathlib import Path
+
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.txt import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import EmbeddingBasedDocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+Pipeline = Pipeline()
+Pipeline.add_component(instance=TextFileToDocument(), name="text_file_converter")
+Pipeline.add_component(instance=DocumentCleaner(), name="cleaner")
+Pipeline.add_component(instance=EmbeddingBasedDocumentSplitter(document_embedder=embedder, sentences_per_group=2, percentile=0.95, min_length=50,max_length=1000)
+Pipeline.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+Pipeline.connect("text_file_converter.documents", "cleaner.documents")
+Pipeline.connect("cleaner.documents", "splitter.documents")
+Pipeline.connect("splitter.documents", "writer.documents")
+
+path = "path/to/your/files"
+files = list(Path(path).glob("*.md"))
+Pipeline.run({"text_file_converter": {"sources": files}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/hierarchicaldocumentsplitter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/hierarchicaldocumentsplitter.mdx
new file mode 100644
index 0000000000..f47722064b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/hierarchicaldocumentsplitter.mdx
@@ -0,0 +1,98 @@
+---
+title: "HierarchicalDocumentSplitter"
+id: hierarchicaldocumentsplitter
+slug: "/hierarchicaldocumentsplitter"
+description: "Use this component to create a multi-level document structure based on parent-children relationships between text segments."
+---
+
+# HierarchicalDocumentSplitter
+
+Use this component to create a multi-level document structure based on parent-children relationships between text segments.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) and [`DocumentCleaner`](documentcleaner.mdx) |
+| **Mandatory init variables** | `block_sizes`: Set of block sizes to split the document into. The blocks are split in descending order. |
+| **Mandatory run variables** | `documents`: A list of documents to split into hierarchical blocks |
+| **Output variables** | `documents`: A list of hierarchical documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | [https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/hierarchical_document_splitter.py](https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/hierarchical_document_splitter.py#L12) |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `HierarchicalDocumentSplitter` divides documents into blocks of different sizes, creating a tree-like structure.
+
+A block is one of the chunks of text that the splitter produces. It is similar to cutting a long piece of text into smaller pieces: each piece is a block. Blocks form a tree structure where your full document is the root block, and as you split it into smaller and smaller pieces you get child-blocks and leaf-blocks, down to whatever smallest size specified.
+
+The [`AutoMergingRetriever`](../retrievers/automergingretriever.mdx) component then leverages this hierarchical structure to improve document retrieval.
+
+To initialize the component, you need to specify the `block_size`, which is the “maximum length” of each of the blocks, measured in the specific unit (see `split_by` parameter). Pass a set of sizes (for example, `{20, 5}`), and it will:
+
+- First, split the document into blocks of up to 20 units each (the “parent” blocks).
+- Then, it will split each of those into blocks of up to 5 units each (the “child” blocks).
+
+This descending order of sizes builds the hierarchy.
+
+These additional parameters can be set when the component is initialized:
+
+- `split_by` can be `"word"` (default), `"sentence"`, `"passage"`, `"page"`.
+- `split_overlap` is an integer indicating the number of overlapping words, sentences, or passages between chunks, 0 being the default.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import HierarchicalDocumentSplitter
+
+doc = Document(content="This is a simple test document")
+splitter = HierarchicalDocumentSplitter(block_sizes={3, 2}, split_overlap=0, split_by="word")
+splitter.run([doc])
+
+>> {'documents': [Document(id=3f7..., content: 'This is a simple test document', meta: {'block_size': 0, 'parent_id': None, 'children_ids': ['5ff..', '8dc..'], 'level': 0}),
+>> Document(id=5ff.., content: 'This is a ', meta: {'block_size': 3, 'parent_id': '3f7..', 'children_ids': ['f19..', '52c..'], 'level': 1, 'source_id': '3f7..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+>> Document(id=8dc.., content: 'simple test document', meta: {'block_size': 3, 'parent_id': '3f7..', 'children_ids': ['39d..', 'e23..'], 'level': 1, 'source_id': '3f7..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 10}),
+>> Document(id=f19.., content: 'This is ', meta: {'block_size': 2, 'parent_id': '5ff..', 'children_ids': [], 'level': 2, 'source_id': '5ff..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+>> Document(id=52c.., content: 'a ', meta: {'block_size': 2, 'parent_id': '5ff..', 'children_ids': [], 'level': 2, 'source_id': '5ff..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 8}),
+>> Document(id=39d.., content: 'simple test ', meta: {'block_size': 2, 'parent_id': '8dc..', 'children_ids': [], 'level': 2, 'source_id': '8dc..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+>> Document(id=e23.., content: 'document', meta: {'block_size': 2, 'parent_id': '8dc..', 'children_ids': [], 'level': 2, 'source_id': '8dc..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 12})]}
+```
+
+### In a pipeline
+
+This Haystack pipeline processes `.md` files by converting them to documents, cleaning the text, splitting it into sentence-based chunks, and storing the results in an In-Memory Document Store.
+
+```python
+from pathlib import Path
+
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.txt import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import HierarchicalDocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+Pipeline = Pipeline()
+Pipeline.add_component(instance=TextFileToDocument(), name="text_file_converter")
+Pipeline.add_component(instance=DocumentCleaner(), name="cleaner")
+Pipeline.add_component(instance=HierarchicalDocumentSplitter(
+ block_sizes={10, 6, 3}, split_overlap=0, split_by="sentence", name="splitter"
+)
+Pipeline.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+Pipeline.connect("text_file_converter.documents", "cleaner.documents")
+Pipeline.connect("cleaner.documents", "splitter.documents")
+Pipeline.connect("splitter.documents", "writer.documents")
+
+path = "path/to/your/files"
+files = list(Path(path).glob("*.md"))
+Pipeline.run({"text_file_converter": {"sources": files}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/markdownheadersplitter.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/markdownheadersplitter.mdx
new file mode 100644
index 0000000000..bef00d32f4
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/markdownheadersplitter.mdx
@@ -0,0 +1,123 @@
+---
+title: "MarkdownHeaderSplitter"
+id: markdownheadersplitter
+slug: "/markdownheadersplitter"
+description: "Split documents at ATX-style Markdown headers (#), with optional secondary splitting. Preserves header hierarchy as metadata."
+---
+
+# MarkdownHeaderSplitter
+
+Split documents at ATX-style Markdown headers (`#`, `##`, and so on), with optional secondary splitting. Header hierarchy is preserved as metadata on each chunk.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) and [`DocumentCleaner`](documentcleaner.mdx) |
+| **Mandatory run variables** | `documents`: A list of text documents to split. |
+| **Output variables** | `documents`: A list of documents split at headers (and optionally by secondary split). |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | [https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/markdown_header_splitter.py](https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/markdown_header_splitter.py) |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+The `MarkdownHeaderSplitter` processes text documents by:
+
+- Splitting them into chunks at ATX-style Markdown headers (`#`, `##`, …, `######`), preserving header hierarchy as metadata.
+- Optionally applying a secondary split (by word, passage, period, or line) to each chunk using Haystack's [`DocumentSplitter`](documentsplitter.mdx).
+- Preserving and propagating metadata such as parent headers, page numbers, and split IDs.
+
+Only ATX-style headers are recognized (e.g. `# Title`). Setext-style headers (`Underline with ===`) aren't supported.
+
+Parameters you can set when initializing the component:
+
+- `page_break_character`: Character used to identify page breaks. Defaults to form feed `\f`.
+- `keep_headers`: If `True`, headers remain in the chunk content. If `False`, headers are moved to metadata only. Defaults to `True`.
+- `secondary_split`: Optional secondary split after header splitting. Options: `None`, `"word"`, `"passage"`, `"period"`, `"line"`. Defaults to `None`.
+- `split_length`: Maximum number of units per split when using secondary splitting. Defaults to `200`.
+- `split_overlap`: Number of overlapping units between splits when using secondary splitting. Defaults to `0`.
+- `split_threshold`: Minimum number of units per split when using secondary splitting. Defaults to `0`.
+- `skip_empty_documents`: Whether to skip documents with empty content. Defaults to `True`.
+
+Each output document's metadata includes:
+
+- `source_id`: ID of the original document.
+- `page_number`: Page number. Updated when `page_break_character` is found.
+- `split_id`: Index of the chunk within its parent.
+- `header`: The header text for this chunk.
+- `parent_headers`: List of parent header texts in hierarchy order.
+
+The component only works with text documents. Documents with `None` or non-string content raise a `ValueError`.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import MarkdownHeaderSplitter
+
+text = (
+ "# Introduction\n"
+ "This is the intro section.\n"
+ "## Getting Started\n"
+ "Here is how to start.\n"
+ "## Advanced\n"
+ "Advanced content here."
+)
+doc = Document(content=text)
+splitter = MarkdownHeaderSplitter(keep_headers=True)
+result = splitter.run(documents=[doc])
+
+# result["documents"] contains one document per header section,
+# with meta["header"], meta["parent_headers"], meta["source_id"], and so on
+```
+
+### With secondary splitting
+
+When sections are long, you can add a secondary split, for example by word, so each chunk stays within a maximum size:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import MarkdownHeaderSplitter
+
+text = "# Section\n" + "Some long body text. " * 50
+doc = Document(content=text)
+splitter = MarkdownHeaderSplitter(
+ keep_headers=True,
+ secondary_split="word",
+ split_length=20,
+ split_overlap=2,
+)
+result = splitter.run(documents=[doc])
+```
+
+### In a pipeline
+
+This pipeline converts Markdown files to documents, cleans them, splits by headers, and writes to an in-memory document store:
+
+```python
+from pathlib import Path
+
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.txt import TextFileToDocument
+from haystack.components.preprocessors import MarkdownHeaderSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+p = Pipeline()
+p.add_component("text_file_converter", TextFileToDocument())
+p.add_component("splitter", MarkdownHeaderSplitter(keep_headers=True))
+p.add_component("writer", DocumentWriter(document_store=document_store))
+p.connect("text_file_converter.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+path = "path/to/your/files"
+files = list(Path(path).glob("*.md"))
+p.run({"text_file_converter": {"sources": files}})
+```
diff --git a/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/presidiodocumentcleaner.mdx b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/presidiodocumentcleaner.mdx
new file mode 100644
index 0000000000..15b01837f9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.29-unstable/pipeline-components/preprocessors/presidiodocumentcleaner.mdx
@@ -0,0 +1,147 @@
+---
+title: "PresidioDocumentCleaner"
+id: presidiodocumentcleaner
+slug: "/presidiodocumentcleaner"
+description: "Use `PresidioDocumentCleaner` to replace PII in Document text with entity type placeholders, powered by Microsoft Presidio."
+---
+
+# PresidioDocumentCleaner
+
+`PresidioDocumentCleaner` replaces personally identifiable information (PII) in the text content of Documents with entity type placeholders such as `
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In an indexing pipeline, before writing Documents to a Document Store |
+| **Mandatory run variables** | `documents`: A list of Document objects |
+| **Output variables** | `documents`: A list of Document objects with PII replaced |
+| **API reference** | [Presidio](/reference/integrations-presidio) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/presidio |
+| **Package name** | `presidio-haystack` |
+
+
+
+## Overview
+
+[Microsoft Presidio](https://microsoft.github.io/presidio/) is an open-source framework for PII detection and anonymization. `PresidioDocumentCleaner` uses Presidio's Analyzer and Anonymizer engines to scan document text and replace detected entities with type placeholders such as `