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.
+ Defaults to `"*"`, which marks every variable found in the prompt as required.
+ Pass an explicit list to only require a subset of the variables; any variable not listed becomes
+ optional and is replaced with an empty string in the rendered prompt when missing.
+ Set to `None` to mark every variable as 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 `template` 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 required by default.
+To make any subset of variables optional, set `required_variables` to an explicit list of the variables that
+should remain required. Optional variables are 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 ChatGenerator.
+
+```python
+from haystack import Pipeline, Document
+from haystack.utils import Secret
+from haystack.components.generators.chat import OpenAIChatGenerator
+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=OpenAIChatGenerator(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 = "*",
+ 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 required by default.
+- **required_variables** (list\[str\] | Literal['\*'] | None) – List variables that must be provided as input to PromptBuilder.
+ Defaults to `"*"`, which marks every variable found in the prompt as required.
+ Pass an explicit list to only require a subset of the variables; any variable not listed becomes
+ optional and is replaced with an empty string in the rendered prompt when missing.
+ Set to `None` to mark every variable as 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-3.2-unstable/haystack-api/cachings_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/cachings_api.md
new file mode 100644
index 00000000000..b89485d03fe
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/cachings_api.md
@@ -0,0 +1,130 @@
+---
+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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/converters_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/converters_api.md
new file mode 100644
index 00000000000..18b2cc0cc7a
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/converters_api.md
@@ -0,0 +1,1699 @@
+---
+title: "Converters"
+id: converters-api
+description: "Various converters to transform data from one format to another."
+slug: "/converters-api"
+---
+
+
+## csv
+
+### CSVToDocument
+
+Converts CSV files to Documents.
+
+By default, it uses UTF-8 encoding (`utf-8-sig`, which also strips a byte order mark if
+present) 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-sig",
+ 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.
+
+### 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 = ["test/test_files/pdf/react_paper.pdf", "test/test_files/images/haystack-logo.png"]
+file_contents = converter.run(sources=sources)["file_contents"]
+
+print(file_contents)
+# >> [FileContent(base64_data='...', mime_type='application/pdf', filename='react_paper.pdf', extra={}),
+# >> FileContent(base64_data='...', mime_type='image/png', filename='haystack-logo.png', 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,
+ encoding: str = "utf-8",
+) -> 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.
+- **encoding** (str) – The default encoding to use when converting HTML files. If the encoding is specified in the metadata of a
+ source ByteStream, it overrides this value.
+
+#### 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="test/test_files",
+ detail="high",
+ size=(800, 600)
+)
+
+documents = [
+ Document(content="Optional description of apple.jpg", meta={"file_path": "images/apple.jpg"}),
+ Document(
+ content="Optional description of sample_pdf_1.pdf",
+ meta={"file_path": "pdf/sample_pdf_1.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': 'images/apple.jpg'}
+# ),
+# ImageContent(
+# base64_image='/9j/4A...', mime_type='image/jpeg', detail='high',
+# meta={'file_path': 'pdf/sample_pdf_1.pdf', 'page_number': 1})
+# )]
+```
+
+#### __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 and are guaranteed to stay within it. If None,
+ file paths are treated as absolute paths with no containment check.
+ Security: this component reads the file referenced by `file_path_meta_field` from the host filesystem. If
+ document metadata may be influenced by untrusted input, set `root_path` to a dedicated data directory so
+ that path-traversal payloads (e.g. absolute paths or `../`) are rejected instead of read.
+- **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 the order of the input documents. A document that is
+ missing the required metadata keys, has an invalid file path, or has an unsupported MIME type gets
+ None in its position and a logged warning with the reason.
+
+## 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 `LLMDocumentContentExtractor` or the
+`SentenceTransformersDocumentImageEmbedder` (available in the `sentence-transformers-haystack` integration).
+
+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,
+ encoding: str = "utf-8-sig",
+ *,
+ extract_frontmatter: 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.
+- **encoding** (str) – The default encoding to use when converting Markdown files. If the encoding is specified in the metadata
+ of a source ByteStream, it overrides this value.
+- **extract_frontmatter** (bool) – If True, YAML frontmatter at the beginning of the Markdown file is
+ removed from the document content and added to the document metadata.
+
+#### 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.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-sig", 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.
+
+## 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,
+ link_format: str | LinkFormat = LinkFormat.NONE,
+) -> 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.
+- **link_format** (str | LinkFormat) – The format used for the hyperlinks found in the PDF link annotations.
+ The links of a page are appended at the end of that page's text, one per line. PDF link annotations
+ carry no anchor text, so the address is used as the link text as well. Can be either:
+ `LinkFormat.MARKDOWN` or `"markdown"` to get `[address](address)`,
+ `LinkFormat.PLAIN` or `"plain"` to get `address (address)`,
+ `LinkFormat.NONE` or `"none"` to get text without links.
+
+#### 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]) -> PDFMinerToDocument
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary with serialized data.
+
+**Returns:**
+
+- PDFMinerToDocument – Deserialized component.
+
+#### 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,
+ link_format: str | LinkFormat = LinkFormat.NONE
+) -> 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.
+- **link_format** (str | LinkFormat) – The format used for the hyperlinks found in the PDF link annotations.
+ The links of a page are appended at the end of that page's text, one per line. PDF link annotations
+ carry no anchor text, so the address is used as the link text as well. Can be either:
+ `LinkFormat.MARKDOWN` or `"markdown"` to get `[address](address)`,
+ `LinkFormat.PLAIN` or `"plain"` to get `address (address)`,
+ `LinkFormat.NONE` or `"none"` to get text without links.
+
+#### 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.
+
+## txt
+
+### TextFileToDocument
+
+Converts text files to documents your pipeline can query.
+
+By default, it uses UTF-8 encoding (`utf-8-sig`, which also strips a byte order mark if
+present) 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-sig', 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-3.2-unstable/haystack-api/data_classes_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/data_classes_api.md
new file mode 100644
index 00000000000..16bd5cf034c
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/data_classes_api.md
@@ -0,0 +1,1282 @@
+---
+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.
+
+### 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.
+- **inputs_format** (str | None) – Which format `inputs` are stored in. `"internal"` means each input records the component
+ that sent it, in the order it arrived, as in `{component: {socket: [{"sender": ..., "value": ...}]}}`.
+ `None` marks snapshots taken before Haystack recorded the sender, which hold one flattened value per socket,
+ `{component: {socket: value}}`, and can only be resumed on a component's first visit.
+
+#### 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** (Breakpoint) – The breakpoint that triggered the snapshot.
+- **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.
+
+The `_meta` field of ChatMessage is removed because it is not supported 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 the `meta` field. Defaults to `True` to be backward-compatible with Haystack 1.x.
+ Meta keys that clash with document field names are kept in a nested `meta` dictionary.
+
+#### 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.
+
+## skill_info
+
+### SkillInfo
+
+Lightweight metadata describing a skill.
+
+This is what a `SkillStore` returns when listing its skills, keeping the catalog cheap; the full skill
+content (the instructions body and bundled files) is fetched on demand.
+
+**Parameters:**
+
+- **name** (str) – The skill's name, used to look it up.
+- **description** (str) – A short description of when to use the skill. Shown to the agent up front.
+
+## 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.
+
+In an async context (`requires_async=True`), a sync callback is accepted but emits a warning: it will run inline on
+the event loop and may block it. In a sync context (`requires_async=False`), an async callback is rejected because
+there is no way to await it.
+
+**Parameters:**
+
+- **init_callback** (StreamingCallbackT | None) – The initial callback.
+- **runtime_callback** (StreamingCallbackT | None) – The runtime callback.
+- **requires_async** (bool) – Whether the selected callback will be invoked from an async context.
+
+**Returns:**
+
+- StreamingCallbackT | None – The selected callback.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/document_stores_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/document_stores_api.md
new file mode 100644
index 00000000000..ced0521d0a2
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/document_stores_api.md
@@ -0,0 +1,625 @@
+---
+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,
+ shared: bool = True,
+ async_executor: ThreadPoolExecutor | None = None,
+ return_embedding: bool = True,
+ *,
+ strict_datetime_comparison: bool = False
+) -> 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.
+ When `shared` is True, instances using the same index share the same documents.
+- **shared** (bool) – Whether the documents live in process-global storage shared across instances using the same
+ index (True, the default), or are kept instance-local and freed when this instance is garbage collected
+ (False). Shared storage persists for the lifetime of the process, so prefer `shared=False` for stores
+ that are created frequently (for example per request) to avoid unbounded memory growth.
+- **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.
+- **strict_datetime_comparison** (bool) – If `True`, timezone-naive and timezone-aware datetimes never match each other in filters.
+ If `False` (the default), the timezone from the aware datetime is copied to the naive one before
+ comparing.
+
+#### 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.
+
+JSON-serializable metadata values, including nested lists and dictionaries, are supported.
+
+**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,
+ from_: int = 0,
+ size: int = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Returns unique values for a metadata field, optionally filtered by a search term, with pagination.
+
+JSON-serializable metadata values, including nested lists and dictionaries, are supported.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name. Can include or omit the "meta." prefix.
+- **search_term** (str | None) – Optional search term to filter values, matched as a case-insensitive substring
+ against the metadata field's value.
+- **from\_** (int) – The offset to start returning values from (for pagination).
+- **size** (int) – The maximum number of unique values to return.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple of (paginated 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.
+
+JSON-serializable metadata values, including nested lists and dictionaries, are supported.
+
+**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,
+ from_: int = 0,
+ size: int = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Returns unique values for a metadata field, optionally filtered by a search term, with pagination.
+
+JSON-serializable metadata values, including nested lists and dictionaries, are supported.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name. Can include or omit the "meta." prefix.
+- **search_term** (str | None) – Optional search term to filter values, matched as a case-insensitive substring
+ against the metadata field's value.
+- **from\_** (int) – The offset to start returning values from (for pagination).
+- **size** (int) – The maximum number of unique values to return.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple of (paginated 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-3.2-unstable/haystack-api/document_writers_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/document_writers_api.md
new file mode 100644
index 00000000000..2010bd408f7
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/document_writers_api.md
@@ -0,0 +1,145 @@
+---
+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`.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/embedders_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/embedders_api.md
new file mode 100644
index 00000000000..f2dcee126ee
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/embedders_api.md
@@ -0,0 +1,929 @@
+---
+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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the synchronous AzureOpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Initializes the asynchronous AzureOpenAI client on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Releases the synchronous AzureOpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Releases the asynchronous AzureOpenAI 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]) -> 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).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the synchronous Azure OpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Initializes the asynchronous Azure OpenAI client on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Releases the synchronous Azure OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Releases the asynchronous Azure OpenAI 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.
+
+## mock_document_embedder
+
+### MockDocumentEmbedder
+
+A Document Embedder that returns deterministic embeddings without calling any API.
+
+It is a drop-in replacement for real Document Embedders (such as `OpenAIDocumentEmbedder`) in tests, smoke tests,
+and quick prototypes. It implements the same interface (`run`, `run_async`, serialization) but never contacts an
+external service, so it is fully deterministic and free to run.
+
+The embedding is selected based on how the component is configured:
+
+- **Deterministic (default)**: with no configuration, each document's embedding is derived from a hash of its
+ (prepared) text. The same text always yields the same embedding, and different texts yield different
+ embeddings, so the mock works in retrieval pipelines and is reproducible across runs and processes.
+- **Fixed embedding**: pass an `embedding` vector. The same vector is assigned to every document.
+- **Dynamic embedding**: pass an `embedding_fn` callable that receives the (prepared) text of a document and
+ returns the embedding. This is useful when the embedding should depend on the input in a custom way.
+
+Like real Document Embedders, the metadata fields listed in `meta_fields_to_embed` are concatenated with the
+document content before embedding, so the deterministic embedding reflects the embedded metadata.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.embedders import MockDocumentEmbedder
+
+embedder = MockDocumentEmbedder(dimension=8)
+result = embedder.run([Document(content="I love pizza!")])
+print(result["documents"][0].embedding) # a deterministic list of 8 floats
+```
+
+#### __init__
+
+```python
+__init__(
+ embedding: list[float] | None = None,
+ *,
+ embedding_fn: EmbeddingFn | None = None,
+ dimension: int = 768,
+ model: str = "mock-model",
+ meta: dict[str, Any] | None = None,
+ prefix: str = "",
+ suffix: str = "",
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ progress_bar: bool = False
+) -> None
+```
+
+Creates an instance of MockDocumentEmbedder.
+
+**Parameters:**
+
+- **embedding** (list\[float\] | None) – An optional fixed embedding assigned to every document. Mutually exclusive with
+ `embedding_fn`. If neither is provided, a deterministic embedding is derived from each document's text.
+- **embedding_fn** (EmbeddingFn | None) – An optional callable that receives the prepared text of a document and returns the
+ embedding as a list of floats. Mutually exclusive with `embedding`. To support serialization, pass a
+ named function (lambdas and nested functions cannot be serialized).
+- **dimension** (int) – The number of dimensions of the deterministic embedding. Ignored when `embedding` or
+ `embedding_fn` is provided, since their length is determined by the value or callable.
+- **model** (str) – The model name reported in the metadata. Purely cosmetic; no model is loaded.
+- **meta** (dict\[str, Any\] | None) – Additional metadata merged into the output `meta`.
+- **prefix** (str) – A string to add at the beginning of each text before embedding.
+- **suffix** (str) – A string to add at the end of each text before embedding.
+- **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.
+- **progress_bar** (bool) – Accepted for interface compatibility with real Document Embedders and ignored.
+
+**Raises:**
+
+- ValueError – If both `embedding` and `embedding_fn` are provided, if `dimension` is not positive, or
+ if `embedding` is an empty list.
+- TypeError – If `embedding` is not a sequence of numbers.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MockDocumentEmbedder
+```
+
+Deserialize the component from a dictionary.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+No-op warm up, provided for interface compatibility with real Embedders.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, Any]
+```
+
+Return the input documents with deterministic embeddings added, without calling any API.
+
+**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`: Metadata about the (mock) model.
+
+**Raises:**
+
+- TypeError – If `documents` is not a list of `Document` objects.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, Any]
+```
+
+Asynchronously return the input documents with deterministic embeddings added, without calling any API.
+
+**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`: Metadata about the (mock) model.
+
+**Raises:**
+
+- TypeError – If `documents` is not a list of `Document` objects.
+
+## mock_text_embedder
+
+### MockTextEmbedder
+
+A Text Embedder that returns deterministic embeddings without calling any API.
+
+It is a drop-in replacement for real Text Embedders (such as `OpenAITextEmbedder`) in tests, smoke tests, and
+quick prototypes. It implements the same interface (`run`, `run_async`, serialization) but never contacts an
+external service, so it is fully deterministic and free to run.
+
+The embedding is selected based on how the component is configured:
+
+- **Deterministic (default)**: with no configuration, the embedding is derived from a hash of the input text.
+ The same text always yields the same embedding, and different texts yield different embeddings, so the mock
+ works in retrieval pipelines and is reproducible across runs and processes.
+- **Fixed embedding**: pass an `embedding` vector. The same vector is returned for every input.
+- **Dynamic embedding**: pass an `embedding_fn` callable that receives the (prepared) text and returns the
+ embedding. This is useful when the embedding should depend on the input in a custom way.
+
+### Usage example
+
+```python
+from haystack.components.embedders import MockTextEmbedder
+
+embedder = MockTextEmbedder(dimension=8)
+result = embedder.run("I love pizza!")
+print(result["embedding"]) # a deterministic list of 8 floats
+```
+
+#### __init__
+
+```python
+__init__(
+ embedding: list[float] | None = None,
+ *,
+ embedding_fn: EmbeddingFn | None = None,
+ dimension: int = 768,
+ model: str = "mock-model",
+ meta: dict[str, Any] | None = None,
+ prefix: str = "",
+ suffix: str = ""
+) -> None
+```
+
+Creates an instance of MockTextEmbedder.
+
+**Parameters:**
+
+- **embedding** (list\[float\] | None) – An optional fixed embedding returned for every input. Mutually exclusive with
+ `embedding_fn`. If neither is provided, a deterministic embedding is derived from the input text.
+- **embedding_fn** (EmbeddingFn | None) – An optional callable that receives the prepared text (after `prefix`/`suffix` are
+ applied) and returns the embedding as a list of floats. Mutually exclusive with `embedding`. To support
+ serialization, pass a named function (lambdas and nested functions cannot be serialized).
+- **dimension** (int) – The number of dimensions of the deterministic embedding. Ignored when `embedding` or
+ `embedding_fn` is provided, since their length is determined by the value or callable.
+- **model** (str) – The model name reported in the metadata. Purely cosmetic; no model is loaded.
+- **meta** (dict\[str, Any\] | None) – Additional metadata merged into the output `meta`.
+- **prefix** (str) – A string to add at the beginning of the text before embedding.
+- **suffix** (str) – A string to add at the end of the text before embedding.
+
+**Raises:**
+
+- ValueError – If both `embedding` and `embedding_fn` are provided, if `dimension` is not positive, or
+ if `embedding` is an empty list.
+- TypeError – If `embedding` is not a sequence of numbers.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MockTextEmbedder
+```
+
+Deserialize the component from a dictionary.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+No-op warm up, provided for interface compatibility with real Embedders.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Return a deterministic embedding for the input text without calling any API.
+
+**Parameters:**
+
+- **text** (str) – The text to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+- `meta`: Metadata about the (mock) model.
+
+**Raises:**
+
+- TypeError – If `text` is not a string.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, Any]
+```
+
+Asynchronously return a deterministic embedding for the input text without calling any API.
+
+**Parameters:**
+
+- **text** (str) – The text to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+- `meta`: Metadata about the (mock) model.
+
+**Raises:**
+
+- TypeError – If `text` is not a string.
+
+## 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the synchronous OpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Initializes the asynchronous OpenAI client on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Releases the synchronous OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Releases the asynchronous OpenAI 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]) -> 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).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the synchronous OpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Initializes the asynchronous OpenAI client on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Releases the synchronous OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Releases the asynchronous OpenAI 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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/evaluation_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/evaluation_api.md
new file mode 100644
index 00000000000..1c0f6446941
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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-3.2-unstable/haystack-api/evaluators_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/evaluators_api.md
new file mode 100644
index 00000000000..fc0811fef54
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/evaluators_api.md
@@ -0,0 +1,1193 @@
+---
+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,
+# 'status': 'evaluated'
+# },
+# {
+# '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,
+# 'status': 'evaluated'
+# },
+# {
+# 'relevant_statements': [],
+# 'score': 0.0,
+# 'status': 'evaluated'
+# }]
+```
+
+#### __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.
+ - `individual_scores`: A list of context relevance scores for each input question.
+ - `results`: A list of dictionaries with `relevant_statements`, `score`, and `status` for each input
+ context. `status` is `evaluated` for valid results and `error` for failed evaluations.
+
+#### run_async
+
+```python
+run_async(**inputs: Any) -> dict[str, Any]
+```
+
+Run the LLM evaluator asynchronously.
+
+**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.
+ - `individual_scores`: A list of context relevance scores for each input question.
+ - `results`: A list of dictionaries with `relevant_statements`, `score`, and `status` for each input
+ context. `status` is `evaluated` for valid results and `error` for failed evaluations.
+
+#### 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
+```
+
+#### __init__
+
+```python
+__init__(document_comparison_field: str = 'content') -> None
+```
+
+Create a DocumentNDCGEvaluator 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 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 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.
+
+Ground truth documents whose comparison value cannot be determined (e.g. missing meta key)
+are excluded, since they can never be matched in `calculate_dcg` either. Documents that share
+a comparison value are collapsed to a single relevant item, mirroring `calculate_dcg`, which
+credits each relevant value at most once. Including duplicates or unmatchable documents here
+would inflate the IDCG and make it impossible for NDCG to reach 1.0 for a perfect retrieval.
+
+**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,
+# 'status': 'evaluated'}]
+```
+
+#### __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`, `statement_scores`, `score`, and `status` for
+ each input answer. `status` is `evaluated` for valid results and `error` for failed evaluations.
+
+#### run_async
+
+```python
+run_async(**inputs: Any) -> dict[str, Any]
+```
+
+Run the LLM evaluator asynchronously.
+
+**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`, `statement_scores`, `score`, and `status` for
+ each input answer. `status` is `evaluated` for valid results and `error` for failed evaluations.
+
+#### 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 underlying chat generator.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the underlying chat generator on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the underlying chat generator's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the underlying chat generator's async resources.
+
+#### 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.
+
+#### run_async
+
+```python
+run_async(**inputs: Any) -> dict[str, Any]
+```
+
+Run the LLM evaluator asynchronously
+
+**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:**
+
+- TypeError – If the chat generator does not support async execution.
+- 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-3.2-unstable/haystack-api/extractors_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/extractors_api.md
new file mode 100644
index 00000000000..24e59073343
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/extractors_api.md
@@ -0,0 +1,592 @@
+---
+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 and are guaranteed to stay within it. If None,
+ file paths are treated as absolute paths with no containment check.
+ Security: this component reads the file referenced by `file_path_meta_field` from the host filesystem. If
+ document metadata may be influenced by untrusted input, set `root_path` to a dedicated data directory so
+ that path-traversal payloads (e.g. absolute paths or `../`) are rejected instead of read.
+- **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 underlying chat generator.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the underlying chat generator on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the underlying chat generator's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the underlying chat generator's async resources.
+
+#### 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).
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Asynchronously run extraction on image-based documents. One LLM call per document.
+
+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. LLM calls are made concurrently, bounded by `max_workers`.
+If the chat generator only implements a synchronous `run` method, it is executed in a thread to avoid
+blocking the event loop.
+
+**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 must have exactly one variable, called
+`document`, that points 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. It must contain exactly one variable, called `document`,
+ which points to a single document in the list of documents. For example, to access the content of the
+ document, use `{{ document.content }}` in the prompt.
+- **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 underlying chat generator and splitter.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the underlying chat generator and splitter on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the underlying chat generator's and splitter's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the underlying chat generator's and splitter's async resources.
+
+#### 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.
+
+## 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-3.2-unstable/haystack-api/fetchers_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/fetchers_api.md
new file mode 100644
index 00000000000..0f8e23e6bac
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/fetchers_api.md
@@ -0,0 +1,155 @@
+---
+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.
+- **request_headers** (dict\[str, str\] | None) – Additional headers to send with every request. These take precedence over the
+ component's default headers but not over the rotating `User-Agent`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the synchronous httpx client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Initializes the asynchronous httpx client on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Releases the synchronous httpx client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Releases the asynchronous httpx client.
+
+#### 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-3.2-unstable/haystack-api/generators_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/generators_api.md
new file mode 100644
index 00000000000..3e0947094bd
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/generators_api.md
@@ -0,0 +1,1709 @@
+---
+title: "Generators"
+id: generators-api
+description: "Enables text generation using LLMs."
+slug: "/generators-api"
+---
+
+
+## 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 | Secret | None) – The endpoint of the deployed model, for example `"https://example-resource.azure.openai.com/"`.
+ Can also be a [Secret](https://docs.haystack.deepset.ai/docs/secret-management), for example
+ `Secret.from_env_var("AZURE_OPENAI_ENDPOINT")`, to resolve the value from an environment variable at
+ runtime. This is useful to switch endpoints between environments (e.g. dev and prod) without changing the
+ serialized pipeline.
+- **api_version** (str | Secret | None) – The version of the API to use. Defaults to 2024-12-01-preview.
+ Can also be a [Secret](https://docs.haystack.deepset.ai/docs/secret-management), for example
+ `Secret.from_env_var("AZURE_OPENAI_API_VERSION")`, to resolve the value from an environment variable at
+ runtime.
+- **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 tools and initialize the synchronous Azure OpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the tools and initialize the asynchronous Azure OpenAI client on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Releases the synchronous Azure OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Releases the asynchronous Azure OpenAI 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]) -> 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 | list[dict] | 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 | list\[dict\] | 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.
+
+#### 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.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up all underlying chat generators on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the underlying chat generators' resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the underlying chat generators' async resources.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage] | str,
+ 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\] | str) – 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] | str,
+ 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\] | str) – 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/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
+
+llm = LLM(
+ chat_generator=OpenAIChatGenerator(),
+ system_prompt="You are a helpful translation assistant.",
+ user_prompt="Summarize the following document: {{ document }}",
+ 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 | None = None,
+ 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. Can be a plain string template or a Jinja2 message template.
+- **user_prompt** (str | None) – User prompt for the LLM. This prompt is appended to the messages provided at
+ runtime. Can be a plain string template or a Jinja2 message template. If it contains template variables
+ (e.g., `{{ variable_name }}`), they become inputs to the component. If omitted or if there are no
+ template variables, `messages` must be provided at runtime instead.
+- **required_variables** (list\[str\] | Literal['\*']) – Variables that must be provided as input to `user_prompt` or `system_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 `"*"`.
+ Only relevant when `user_prompt` or `system_prompt` contains template variables.
+- **streaming_callback** (StreamingCallbackT | None) – A callback that will be invoked when a response is streamed from the LLM.
+
+**Raises:**
+
+- ValueError – If user_prompt contains template variables but 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(
+ *,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ **kwargs: Any
+) -> dict[str, Any]
+```
+
+Process messages and generate a response from the language model.
+
+**Parameters:**
+
+- **messages** – Optional list of ChatMessage objects to prepend to the conversation. Whether this is
+ required or optional depends on the `user_prompt` configuration: if `user_prompt` has no template
+ variables, `messages` must be provided. Passed via `**kwargs`.
+- **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 chat generator. These are merged per key
+ with the `generation_kwargs` passed at the chat generator's initialization: keys provided here take
+ precedence, keys set only at initialization are kept.
+- **kwargs** (Any) – Additional keyword arguments. These are used to fill template variables in `user_prompt` or
+ `system_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.
+- "token_usage": Token usage from the LLM call (e.g. prompt_tokens, completion_tokens). Empty if the
+ chat generator did not return usage data.
+
+#### run_async
+
+```python
+run_async(
+ *,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ **kwargs: Any
+) -> dict[str, Any]
+```
+
+Asynchronously process messages and generate a response from the language model.
+
+**Parameters:**
+
+- **messages** – Optional list of ChatMessage objects to prepend to the conversation. Whether this is
+ required or optional depends on the `user_prompt` configuration: if `user_prompt` has no template
+ variables, `messages` must be provided. Passed via `**kwargs`.
+- **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 chat generator. These are merged per key
+ with the `generation_kwargs` passed at the chat generator's initialization: keys provided here take
+ precedence, keys set only at initialization are kept.
+- **kwargs** (Any) – Additional keyword arguments. These are used to fill template variables in `user_prompt` or
+ `system_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.
+- "token_usage": Token usage from the LLM call (e.g. prompt_tokens, completion_tokens). Empty if the
+ chat generator did not return usage data.
+
+## chat/mock
+
+### MockChatGenerator
+
+A Chat Generator that returns predefined responses without calling any API.
+
+It is a drop-in replacement for real Chat Generators (such as `OpenAIChatGenerator`) in tests, smoke tests, and
+quick prototypes. It implements the same interface (`run`, `run_async`, streaming, serialization) but never
+contacts an external service, so it is fully deterministic and free to run.
+
+The response is selected based on how the component is configured:
+
+- **Fixed response**: pass a single string or `ChatMessage`. The same reply is returned on every call.
+ Any `ChatMessage` passed as a response must have the `assistant` role.
+- **Cycling responses**: pass a list of strings and/or `ChatMessage` objects. Each call returns the next item,
+ wrapping around to the start once the list is exhausted. This is useful to drive multi-step flows such as
+ Agents, where the first call returns a tool call and a later call returns the final answer.
+- **Dynamic response**: pass a `response_fn` callable that receives the input messages and returns the reply.
+ This is useful when the reply should depend on the input, for example to echo back part of the prompt. If the
+ callable accepts a second positional argument, it also receives the `tools` passed to `run` (a `ToolsType` or
+ `None`), so the reply can depend on the runtime tool schema — handy for exercising Agents whose tool set varies.
+- **Echo (default)**: with no configuration, the component echoes back the text of the last message that has
+ text content. This makes it usable out of the box for quick prototyping.
+
+Pass `ChatMessage` objects (rather than plain strings) to return tool calls or reasoning content, which is handy
+for exercising tool-calling pipelines without a real model.
+
+### Usage example
+
+```python
+from haystack.components.generators.chat import MockChatGenerator
+from haystack.dataclasses import ChatMessage, ToolCall
+
+# Fixed response
+generator = MockChatGenerator(responses="Hello, this is a mock response.")
+result = generator.run([ChatMessage.from_user("Hi!")])
+print(result["replies"][0].text) # "Hello, this is a mock response."
+
+# Cycling responses to drive an Agent-like loop
+generator = MockChatGenerator(
+ responses=[
+ ChatMessage.from_assistant(tool_calls=[ToolCall(tool_name="search", arguments={"query": "Haystack"})]),
+ "Here is the final answer.",
+ ]
+)
+
+# Dynamic, tool-aware response: build a tool call from the tools passed to run()
+def call_first_tool(messages, tools):
+ if not tools:
+ return "No tools available."
+ return ChatMessage.from_assistant(
+ tool_calls=[ToolCall(tool_name=tools[0].name, arguments={})]
+ )
+
+generator = MockChatGenerator(response_fn=call_first_tool)
+```
+
+#### __init__
+
+```python
+__init__(
+ responses: str | ChatMessage | Sequence[str | ChatMessage] | None = None,
+ *,
+ response_fn: ResponseFn | None = None,
+ model: str = "mock-model",
+ meta: dict[str, Any] | None = None,
+ streaming_callback: StreamingCallbackT | None = None
+) -> None
+```
+
+Creates an instance of MockChatGenerator.
+
+**Parameters:**
+
+- **responses** (str | ChatMessage | Sequence\[str | ChatMessage\] | None) – The predefined response(s) to return. Accepts a single string or `ChatMessage` (returned on
+ every call), or a non-empty list of strings and/or `ChatMessage` objects that are returned in order,
+ cycling back to the start once exhausted. Strings are wrapped into assistant `ChatMessage` objects, and any
+ `ChatMessage` passed must have the `assistant` role. Mutually exclusive with `response_fn`. If neither is
+ provided, the component echoes the last message with text content.
+- **response_fn** (ResponseFn | None) – An optional callable that returns the reply as a string or an assistant `ChatMessage`. It
+ receives the input messages; if it accepts a second positional argument, it also receives the `tools`
+ passed to `run` (a `ToolsType` or `None`), letting the reply depend on the runtime tool schema. Use this
+ for input-dependent responses. Mutually exclusive with `responses`. To support serialization, pass a named
+ function (lambdas and nested functions cannot be serialized).
+- **model** (str) – The model name reported in the response metadata. Purely cosmetic; no model is loaded.
+- **meta** (dict\[str, Any\] | None) – Additional metadata merged into the `meta` of every returned `ChatMessage`. A per-response
+ `ChatMessage`'s own metadata takes precedence over this value.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callback invoked with `StreamingChunk` objects reconstructed from the
+ predefined response. It lets the mock exercise streaming code paths without a real model.
+
+**Raises:**
+
+- ValueError – If both `responses` and `response_fn` are provided, if `responses` is an empty list, or if
+ a `ChatMessage` response does not have the `assistant` role.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MockChatGenerator
+```
+
+Deserialize the component from a dictionary.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+No-op warm up, provided for interface compatibility with real Chat Generators.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage] | str,
+ 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]]
+```
+
+Return a predefined reply for the given messages without calling any API.
+
+The signature mirrors `OpenAIChatGenerator.run` so the mock can be used as a positional drop-in replacement.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | str) – The conversation history as a list of `ChatMessage` instances or a single string.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callback invoked with reconstructed `StreamingChunk` objects. Overrides
+ the callback set at initialization.
+- **generation_kwargs** (dict\[str, Any\] | None) – Accepted for interface compatibility and ignored.
+- **tools** (ToolsType | None) – Passed to a tool-aware `response_fn` (one that accepts a second positional argument); otherwise
+ accepted for interface compatibility and ignored.
+- **tools_strict** (bool | None) – Accepted for interface compatibility and ignored.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with a single key `replies` containing the predefined reply as a list of one
+ `ChatMessage` (empty in echo mode when there is no message to echo).
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage] | str,
+ 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 return a predefined reply for the given messages without calling any API.
+
+The signature mirrors `OpenAIChatGenerator.run_async` so the mock can be used as a positional drop-in
+replacement.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | str) – The conversation history as a list of `ChatMessage` instances or a single string.
+- **streaming_callback** (StreamingCallbackT | None) – An optional callback invoked with reconstructed `StreamingChunk` objects. Overrides
+ the callback set at initialization.
+- **generation_kwargs** (dict\[str, Any\] | None) – Accepted for interface compatibility and ignored.
+- **tools** (ToolsType | None) – Passed to a tool-aware `response_fn` (one that accepts a second positional argument); otherwise
+ accepted for interface compatibility and ignored.
+- **tools_strict** (bool | None) – Accepted for interface compatibility and ignored.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with a single key `replies` containing the predefined reply as a list of one
+ `ChatMessage` (empty in echo mode when there is no message to echo).
+
+## 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 tools and initialize the synchronous OpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the tools and initialize the asynchronous OpenAI client on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Releases the synchronous OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Releases the asynchronous OpenAI 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]) -> 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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages. If a string is provided, it is converted
+ to a list containing a ChatMessage with user role.
+- **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 are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set
+ only at initialization are kept.
+ 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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages. If a string is provided, it is converted
+ to a list containing a ChatMessage with user role.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream. Async callbacks are
+ preferred; a sync callback is accepted but will run synchronously on the event loop and may block it.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set
+ only at initialization are kept.
+ 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.
+ - `mode`: The reasoning mode. Can be `standard`, or `pro`. Supported since GPT-5.6.
+ 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).
+- `include`: Specify additional output data to include in the model response. Supported values are:
+ - web_search_call.action.sources: Include the sources of the web search tool call.
+ - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool
+ call items.
+ - computer_call_output.output.image_url: Include image urls from the computer call output.
+ - file_search_call.results: Include the search results of the file search tool call.
+ - message.input_image.image_url: Include image urls from the input message.
+ - message.output_text.logprobs: Include logprobs with assistant messages.
+ - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item
+ outputs. This enables reasoning items to be used in multi-turn conversations when using the
+ Responses API statelessly (like when the store parameter is set to false, or when an organization
+ is enrolled in the zero data retention program).
+- **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 tools and initialize the synchronous OpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the tools and initialize the asynchronous OpenAI client on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Releases the synchronous OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Releases the asynchronous OpenAI 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]) -> 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] | str,
+ *,
+ 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\] | str) – 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 are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set
+ only at initialization are kept.
+ 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] | str,
+ *,
+ 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\] | str) – 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. Async callbacks are
+ preferred; a sync callback is accepted but will run synchronously on the event loop and may block it.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set
+ only at initialization are kept.
+ 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.
+
+## openai_image_generator
+
+### OpenAIImageGenerator
+
+Generates images using OpenAI's image generation models such as `gpt-image-2`.
+
+For details on OpenAI API parameters, see
+[OpenAI documentation](https://developers.openai.com/api/reference/resources/images/methods/generate).
+
+### Usage example
+
+```python
+from haystack.components.generators import OpenAIImageGenerator
+image_generator = OpenAIImageGenerator()
+response = image_generator.run("Show me a picture of a black cat.")
+print(response)
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str = "gpt-image-2",
+ quality: Literal["auto", "high", "medium", "low"] = "auto",
+ size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"] = "1024x1024",
+ response_format: Literal["b64_json"] = "b64_json",
+ 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 OpenAIImageGenerator. Unless specified otherwise in `model`, uses OpenAI's gpt-image-2.
+
+**Parameters:**
+
+- **model** (str) – The model to use for image generation. Model names can be found in the
+ [OpenAI documentation](https://developers.openai.com/api/docs/models/all).
+- **quality** (Literal['auto', 'high', 'medium', 'low']) – The quality of the generated image. Can be "auto", "high", "medium", or "low".
+- **size** (Literal['1024x1024', '1024x1536', '1536x1024', 'auto']) – The size of the generated images. One of 1024x1024, 1024x1536, 1536x1024, or "auto".
+ `gpt-image-2` also supports arbitrary sizes. You can find more information about supported sizes in
+ the [OpenAI documentation](https://developers.openai.com/api/reference/resources/images/methods/generate).
+- **response_format** (Literal['b64_json']) – This parameter is ignored and only kept for backward compatibility.
+- **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
+```
+
+Initializes the synchronous OpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Initializes the asynchronous OpenAI client on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Releases the synchronous OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Releases the asynchronous OpenAI client.
+
+#### run
+
+```python
+run(
+ prompt: str,
+ size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"] | None = None,
+ quality: Literal["auto", "high", "medium", "low"] | None = None,
+ response_format: Literal["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['1024x1024', '1024x1536', '1536x1024', 'auto'] | None) – If provided, overrides the size provided during initialization.
+- **quality** (Literal['auto', 'high', 'medium', 'low'] | None) – If provided, overrides the quality provided during initialization.
+- **response_format** (Literal['b64_json'] | None) – This parameter is ignored and only kept for backward compatibility.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the generated list of images as base64 encoded JSON strings and the revised prompt.
+ The revised prompt is the prompt that was used to generate the image, if there was any revision
+ to the prompt made by OpenAI.
+
+#### run_async
+
+```python
+run_async(
+ prompt: str,
+ size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"] | None = None,
+ quality: Literal["auto", "high", "medium", "low"] | None = None,
+ response_format: Literal["b64_json"] | None = None,
+) -> dict[str, Any]
+```
+
+Asynchronously invokes the image generation inference based on the provided prompt 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:**
+
+- **prompt** (str) – The prompt to generate the image.
+- **size** (Literal['1024x1024', '1024x1536', '1536x1024', 'auto'] | None) – If provided, overrides the size provided during initialization.
+- **quality** (Literal['auto', 'high', 'medium', 'low'] | None) – If provided, overrides the quality provided during initialization.
+- **response_format** (Literal['b64_json'] | None) – This parameter is ignored and only kept for backward compatibility.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary containing the generated list of images as base64 encoded JSON strings and the revised prompt.
+ 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]) -> OpenAIImageGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- OpenAIImageGenerator – 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-3.2-unstable/haystack-api/hooks_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/hooks_api.md
new file mode 100644
index 00000000000..0b643024302
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/hooks_api.md
@@ -0,0 +1,1837 @@
+---
+title: "Hooks"
+id: hooks-api
+description: "Hooks that run at points in the Agent's run loop and influence it by mutating State, including built-in context compaction, tool result offloading, and Human-in-the-Loop tool confirmation."
+slug: "/hooks-api"
+---
+
+
+## budget/hooks
+
+### TokenBudgetHook
+
+Stop an Agent run when its token usage reaches a configured budget.
+
+The hook runs at the `before_llm` hook point and checks the cumulative token usage recorded in the Agent state.
+When the budget is reached, the run ends before the next LLM call with the exit reason `"token_budget_exceeded"`.
+
+Only calls made by the Agent's chat generator contribute to `token_usage`; calls made by tools or other hooks are
+not included.
+
+
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.hooks.budget import TokenBudgetHook
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(),
+ tools=[web_search],
+ hooks={"before_llm": [TokenBudgetHook(max_total_tokens=100_000)]},
+)
+
+result = agent.run(messages=[...])
+```
+
+#### __init__
+
+```python
+__init__(*, max_total_tokens: int, add_final_message: bool = False) -> None
+```
+
+Create a token budget hook.
+
+**Parameters:**
+
+- **max_total_tokens** (int) – Maximum cumulative token usage before the Agent is stopped.
+- **add_final_message** (bool) – Whether to append an assistant message explaining why the Agent stopped.
+
+**Raises:**
+
+- ValueError – If `max_total_tokens` is less than 1.
+
+#### run
+
+```python
+run(state: State) -> None
+```
+
+Stop the Agent if its cumulative token usage has reached the budget.
+
+**Parameters:**
+
+- **state** (State) – Agent state containing the cumulative token usage.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this hook to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized representation of the hook.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TokenBudgetHook
+```
+
+Create a hook from its serialized representation.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Serialized hook data.
+
+**Returns:**
+
+- TokenBudgetHook – The deserialized hook.
+
+## compaction/hooks
+
+### CompactionHook
+
+Compacts an Agent's conversation once it fills too much of the model's context window.
+
+This `before_llm` Agent hook estimates the size of the conversation before each chat-generator call and, once it
+reaches `compact_at` of the window, hands it to a `Compactor` to bring back down to `compact_to`. Register it on an
+`Agent` under the `before_llm` hook point:
+
+
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor
+
+hook = CompactionHook(
+ compactor=SlidingWindowCompactor(),
+ context_window=400_000,
+ compact_at=0.7,
+ compact_to=0.4,
+)
+agent = Agent(
+ chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
+ tools=[web_search],
+ hooks={"before_llm": [hook]},
+ max_agent_steps=50,
+)
+```
+
+Size is measured by anchoring on the `context_tokens` state key - the chat generator's own count of the request it
+was sent plus its reply, which already covers the system prompt, the tool schemas, and the provider's chat-template
+overhead - and counting only the messages appended since that call. The estimate is therefore exact for the bulk of
+the conversation and approximate only for its most recent messages.
+
+Compaction is lossy by nature, so the Agent works from a shorter record of the run afterwards. What survives is up
+to the compactor.
+
+#### __init__
+
+```python
+__init__(
+ compactor: Compactor,
+ *,
+ context_window: int,
+ compact_at: float = 0.7,
+ compact_to: float = 0.4,
+ token_counter: TokenCounter | None = None
+) -> None
+```
+
+Initialize the hook with a compactor and the window it has to fit in.
+
+**Parameters:**
+
+- **compactor** (Compactor) – The `Compactor` that rewrites the conversation.
+- **context_window** (int) – The model's context window in tokens. Everything else is a fraction of this, so moving to
+ a different model means changing only this number.
+- **compact_at** (float) – The fraction of the window at which compaction starts. Leave room above it for the reply and
+ the tool results it triggers, which land on top of what was measured.
+- **compact_to** (float) – The fraction of the window compaction aims to bring the conversation down to. Lower means
+ compacting less often but losing more each time.
+- **token_counter** (TokenCounter | None) – The `TokenCounter` used to size the messages the chat generator has not reported on yet.
+ Defaults to `ApproximateTokenCounter`, which needs no extra dependency.
+
+**Raises:**
+
+- ValueError – If `context_window` is not positive, or the fractions are not
+ `0 < compact_to < compact_at <= 1`.
+
+#### run
+
+```python
+run(state: State) -> None
+```
+
+Compact `state.data["messages"]` if the conversation fills too much of the window.
+
+**Parameters:**
+
+- **state** (State) – The Agent's live `State`. Read to decide whether to compact, and rewritten in place when the
+ compactor returns a compacted conversation.
+
+**Returns:**
+
+- None – None. The hook mutates `state` in place.
+
+#### run_async
+
+```python
+run_async(state: State) -> None
+```
+
+Asynchronously compact `state.data["messages"]` if the conversation fills too much of the window.
+
+**Parameters:**
+
+- **state** (State) – The Agent's live `State`. Read to decide whether to compact, and rewritten in place when the
+ compactor returns a compacted conversation.
+
+**Returns:**
+
+- None – None. The hook mutates `state` in place.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the token counter and the compactor, which may hold resources such as a Chat Generator.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the token counter and the compactor on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the compactor's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the compactor's async resources.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the hook, including its compactor and token counter.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the hook.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CompactionHook
+```
+
+Deserialize the hook, reconstructing its compactor and token counter.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – A dictionary representation produced by `to_dict`.
+
+**Returns:**
+
+- CompactionHook – The deserialized `CompactionHook`.
+
+## compaction/sliding_window
+
+### SlidingWindowCompactor
+
+Bases: Compactor
+
+Keeps the Agent's instructions, current task, and as much complete recent conversation as the target allows.
+
+Leading system messages and the latest user message are protected. Historical turns are kept in full when they fit,
+and the current task's history is kept in complete Agent steps, where a step is an assistant message together
+with all immediately following tool results.
+
+An `omission_note` is left where the removed messages used to sit: directly after the leading system messages when
+only historical turns were removed, and directly after the latest user message when the current task's own steps
+were removed. Only one note is ever present, since a later compaction folds an earlier note into its replacement.
+
+
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor
+
+hook = CompactionHook(
+ compactor=SlidingWindowCompactor(), context_window=400_000, compact_at=0.7, compact_to=0.4
+)
+agent = Agent(
+ chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
+ tools=[web_search],
+ hooks={"before_llm": [hook]},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ min_keep_steps: int = 1,
+ omission_note: str | None = _DEFAULT_OMISSION_NOTE
+) -> None
+```
+
+Initialize the compactor.
+
+**Parameters:**
+
+- **min_keep_steps** (int) – The fewest complete recent Agent steps to keep even when they exceed the target. A step
+ is an assistant message and all immediately following tool results. `0` allows all completed steps to be
+ removed when none fit.
+- **omission_note** (str | None) – The user message left in place of what was removed, or None to remove the messages
+ silently. Include `{num_removed}` to have the number of removed messages substituted in.
+
+**Raises:**
+
+- ValueError – If `min_keep_steps` is negative.
+
+#### compact
+
+```python
+compact(
+ messages: list[ChatMessage], target_tokens: int, token_counter: TokenCounter
+) -> list[ChatMessage] | None
+```
+
+Drop older history while preserving the task anchor and a complete recent conversation window.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The conversation to compact, oldest to newest.
+- **target_tokens** (int) – The size the kept conversation should come in under.
+- **token_counter** (TokenCounter) – The `TokenCounter` to measure messages with.
+
+**Returns:**
+
+- list\[ChatMessage\] | None – The conversation that survived, with an omission note if configured standing where the removed
+ messages used to sit; or None when there is nothing to remove but an earlier note.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the compactor.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the compactor.
+
+## compaction/summarization
+
+### SummarizationCompactor
+
+Bases: Compactor
+
+A compactor that progressively summarizes a conversation until it fits a target token budget.
+
+In typical Agent use, the `CompactionHook` supplies the target (aka `target_tokens`) to `compact`. It derives it
+from the hook's `context_window` and `compact_to` settings after accounting for non-message overhead.
+
+The conversation is read as two regions. History runs from the end of the leading system messages up to the latest
+real user message; the current task runs from that user message to the end. Compaction always summarizes history
+before it summarizes the current task. Within history it summarizes complete turns before combining standalone
+historical summaries; within the current task it summarizes eligible Agent steps before combining current-task
+summaries.
+
+Each round of summarization happens in one of four tiers, in this order:
+
+1. `historical_turns`: Starting with the oldest, as few complete historical turns as needed to reach the target are
+ summarized.
+1. `historical_summaries`: Next if no complete historical turns remain, as few of the oldest historical summaries
+ as needed to reach the target are combined.
+1. `current_task_steps`: Third the fewest oldest steps of the current task are summarized to reach the target,
+ but always keeping the `min_keep_steps` newest.
+1. `current_task_summaries`: Last if no steps of the current task can be given up because of `min_keep_steps`, as
+ few of its oldest summaries as needed to reach the target are combined.
+
+Each summary is marked as belonging to this compaction strategy under the `context_compaction` key in its `meta`,
+alongside `summarized_messages`, the number of messages it replaced.
+
+The SummarizationCompactor has a floor it cannot go below: the leading system messages, one combined historical
+summary, the latest user message, one combined current-task summary, and the `min_keep_steps` newest steps. Once a
+conversation is reduced to that, `compact` returns None however small the target is, because there is nothing left
+that may be given up.
+
+
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.hooks.compaction import CompactionHook, SummarizationCompactor
+
+summary_generator = OpenAIResponsesChatGenerator(model="gpt-5.4-nano")
+hook = CompactionHook(
+ compactor=SummarizationCompactor(chat_generator=summary_generator),
+ context_window=400_000,
+ compact_at=0.7,
+ compact_to=0.4,
+)
+agent = Agent(chat_generator=agent_generator, tools=[web_search], hooks={"before_llm": [hook]})
+```
+
+#### __init__
+
+```python
+__init__(
+ chat_generator: ChatGenerator,
+ *,
+ min_keep_steps: int = 1,
+ approximate_summary_tokens: int = 1024,
+ summary_instruction: str = _DEFAULT_SUMMARY_INSTRUCTION,
+ raise_on_failure: bool = False
+) -> None
+```
+
+Initialize the compactor.
+
+**Parameters:**
+
+- **chat_generator** (ChatGenerator) – The Chat Generator used to write summaries.
+- **min_keep_steps** (int) – The fewest complete recent Agent steps to keep, even when they exceed the target.
+- **approximate_summary_tokens** (int) – About how long you expect a summary to come out. This is an estimate used
+ for planning, not a limit imposed on the model. The compactor uses it to work out how much of the
+ conversation to summarize. A higher value causes the compactor to summarize more of the conversation per
+ round, so the result is likelier to land under the target, at the cost of giving up more of the
+ conversation. A lower value summarizes less per round and keeps more, but may leave the result above the
+ target.
+- **summary_instruction** (str) – The prompt instructions for how to summarize a portion of the conversation.
+ The default instructions ask for a summary with fixed sections covering the objective, decisions and
+ constraints, completed work, exact identifiers, and unresolved work.
+- **raise_on_failure** (bool) – Whether to raise an exception if the chat generator fails or returns a summary that
+ does not shrink the conversation. By default the failure is logged and any successful partial compaction
+ is returned.
+
+**Raises:**
+
+- ValueError – If `min_keep_steps` is negative or `approximate_summary_tokens` is not positive.
+
+#### compact
+
+```python
+compact(
+ messages: list[ChatMessage], target_tokens: int, token_counter: TokenCounter
+) -> list[ChatMessage] | None
+```
+
+Return a progressively summarized conversation, or None when no useful reduction is possible.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The conversation to compact, ordered oldest to newest.
+- **target_tokens** (int) – The token budget the compacted messages should aim to fit.
+- **token_counter** (TokenCounter) – The counter used both to plan compaction and verify generated summaries.
+
+**Returns:**
+
+- list\[ChatMessage\] | None – A smaller replacement conversation, or None when nothing was reduced.
+
+#### compact_async
+
+```python
+compact_async(
+ messages: list[ChatMessage], target_tokens: int, token_counter: TokenCounter
+) -> list[ChatMessage] | None
+```
+
+Asynchronously return a progressively summarized conversation.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The conversation to compact, ordered oldest to newest.
+- **target_tokens** (int) – The token budget the compacted messages should aim to fit.
+- **token_counter** (TokenCounter) – The counter used both to plan compaction and verify generated summaries.
+
+**Returns:**
+
+- list\[ChatMessage\] | None – A smaller replacement conversation, or None when nothing was reduced.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Chat Generator that writes summaries.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the Chat Generator on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the Chat Generator's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the Chat Generator's resources.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the compactor and its Chat Generator.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SummarizationCompactor
+```
+
+Deserialize the compactor and reconstruct its Chat Generator.
+
+## compaction/tool_result_pruning
+
+### ToolResultPruningCompactor
+
+Bases: Compactor
+
+Replaces the content of older tool results with a short placeholder, keeping the conversation's shape intact.
+
+Tool output usually dominates a long Agent run, and most of it stops being useful once the model has acted on it.
+This compactor rewrites those results in place rather than removing messages, so every tool call keeps its matching
+result and the model can see what it ran and re-run it if needed.
+
+
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.hooks.compaction import CompactionHook, ToolResultPruningCompactor
+
+hook = CompactionHook(
+ compactor=ToolResultPruningCompactor(min_keep_steps=1),
+ context_window=400_000,
+ compact_at=0.7,
+ compact_to=0.4,
+)
+agent = Agent(
+ chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
+ tools=[web_search],
+ hooks={"before_llm": [hook]},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ min_keep_steps: int = 1,
+ min_tokens: int = 200,
+ placeholder: str = _DEFAULT_PLACEHOLDER,
+ skip_meta_keys: tuple[str, ...] = ("tool_result_offloaded",)
+) -> None
+```
+
+Initialize the compactor with the rules deciding which results it prunes.
+
+**Parameters:**
+
+- **min_keep_steps** (int) – The minimum number of recent tool-calling Agent steps whose results remain untouched,
+ even when they exceed the target. Must be at least 1, which ensures the current result batch remains intact
+ until the model has acted on it.
+- **min_tokens** (int) – Only prune tool-result messages that use more than this many tokens. Small results cost
+ little and are often the ones worth keeping.
+- **placeholder** (str) – The text left in place of a pruned result, replacing the built-in one. May contain
+ `{tool_name}`, which is filled in with the name of the tool that produced the result.
+- **skip_meta_keys** (tuple\[str, ...\]) – Results whose `meta` contains any of these keys are left alone. The default covers
+ results that a `ToolResultOffloadHook` already replaced with a reference to stored content: pruning one of
+ those would destroy the reference the model needs to read it back.
+
+**Raises:**
+
+- ValueError – If `min_keep_steps` is less than 1 or `min_tokens` is negative.
+
+#### compact
+
+```python
+compact(
+ messages: list[ChatMessage], target_tokens: int, token_counter: TokenCounter
+) -> list[ChatMessage] | None
+```
+
+Replace the content of prunable tool results with a placeholder.
+
+Results are considered oldest first and pruning stops as soon as the conversation reaches `target_tokens`.
+This keeps as much original output as possible. Results from the most recent `min_keep_steps` tool-calling
+Agent steps are never considered, even when the target cannot otherwise be reached. After measuring the initial
+conversation, the running total is updated with per-result token deltas to avoid repeatedly counting the full
+context.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The conversation to compact, oldest to newest.
+- **target_tokens** (int) – The size the compacted conversation should come in under.
+- **token_counter** (TokenCounter) – The `TokenCounter` used to measure the conversation before and after each replacement.
+
+**Returns:**
+
+- list\[ChatMessage\] | None – The conversation with older tool results replaced, or None when no result was prunable.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the compactor.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the compactor.
+
+## compaction/types/protocol
+
+### Compactor
+
+Bases: Protocol
+
+Rewrites an Agent's conversation into a shorter one that carries the same working context.
+
+A compactor is the *how* of context compaction; deciding *when* to compact is the caller's job, which
+`CompactionHook` does by comparing the context size against a fraction of the model's window. Strategies
+differ widely in cost and fidelity, from dropping the oldest messages outright to condensing them with an LLM.
+
+Implementations must honor three rules:
+
+1. **Return `None` unless the conversation actually gets smaller.** Callers apply whatever else is returned, so
+ judging whether compacting was worthwhile is the compactor's job.
+1. **Return a new list; leave `messages` as it is.** The caller owns that list and writes the returned one back.
+1. **Keep tool calls and their results together.** Do not retain a tool result after removing the assistant message
+ that contains its originating call, or retain a tool call without all of its results. Chat-completion APIs reject
+ these incomplete tool-call exchanges.
+
+`target_tokens` is a goal, not a guarantee: a compactor that cannot reach it should get as close as it can rather
+than strip the conversation past what the Agent needs to keep working.
+
+Implement `to_dict` so the compactor's settings survive serialization. The default `from_dict` passes them straight
+back to the constructor, which is enough for plain values; override it when `to_dict` emitted something that has to
+be rebuilt first, such as a `Secret` or a nested component.
+
+#### compact
+
+```python
+compact(
+ messages: list[ChatMessage], target_tokens: int, token_counter: TokenCounter
+) -> list[ChatMessage] | None
+```
+
+Return a shorter replacement for `messages`, or None to leave it unchanged.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The conversation to compact, oldest to newest.
+- **target_tokens** (int) – The size the compacted conversation should come in under.
+- **token_counter** (TokenCounter) – The `TokenCounter` to measure messages with. The same one the caller sized the context
+ with, so a compactor's measurements are consistent with the decision to compact.
+
+**Returns:**
+
+- list\[ChatMessage\] | None – The replacement conversation, or None when this compactor has nothing to change.
+
+#### compact_async
+
+```python
+compact_async(
+ messages: list[ChatMessage], target_tokens: int, token_counter: TokenCounter
+) -> list[ChatMessage] | None
+```
+
+Asynchronously return a shorter replacement for `messages`, or None to leave it unchanged.
+
+The default implementation calls `compact` directly. Override it when compaction does I/O, so the event loop is
+not blocked.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The conversation to compact, oldest to newest.
+- **target_tokens** (int) – The size the compacted conversation should come in under.
+- **token_counter** (TokenCounter) – The `TokenCounter` to measure messages with. The same one the caller sized the context
+ with, so a compactor's measurements are consistent with the decision to compact.
+
+**Returns:**
+
+- list\[ChatMessage\] | None – The replacement conversation, or None when this compactor has nothing to change.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the compactor to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Compactor
+```
+
+Deserialize the compactor from a dictionary.
+
+## from_function
+
+### FunctionHook
+
+Wraps a function (or a sync/async pair) into a serializable `Hook`.
+
+Produced by the `@hook` decorator for the single-function case. To give a hook both an optimized sync and async
+path, construct it directly with both `function` and `async_function` set.
+
+#### __init__
+
+```python
+__init__(
+ function: Callable[[State], None] | None = None,
+ async_function: Callable[[State], Awaitable[None]] | None = None,
+) -> None
+```
+
+Initialize the hook with a synchronous function, an async function, or both.
+
+**Parameters:**
+
+- **function** (Callable\\[[State\], None\] | None) – The synchronous function invoked by `run`. Must be a regular function — coroutine functions
+ should be passed to `async_function` instead. Either `function` or `async_function` (or both) must be set.
+- **async_function** (Callable\\[[State\], Awaitable[None]\] | None) – Optional coroutine function awaited by `run_async`. When only `async_function` is set,
+ `run` raises a `RuntimeError`. When only `function` is set, `run_async` calls `function`.
+
+**Raises:**
+
+- ValueError – If neither is set, if `function` is a coroutine function, if `async_function` is not, or
+ if a provided function does not declare a `State`-typed parameter.
+
+#### run
+
+```python
+run(state: State) -> None
+```
+
+Run the synchronous function against the live `State`.
+
+**Parameters:**
+
+- **state** (State) – The Agent's live `State`, mutated in place by the wrapped function.
+
+**Raises:**
+
+- RuntimeError – If the hook only has an `async_function`; use the Agent's async run methods instead.
+
+#### run_async
+
+```python
+run_async(state: State) -> None
+```
+
+Await the async function if set, otherwise call the synchronous function.
+
+**Parameters:**
+
+- **state** (State) – The Agent's live `State`, mutated in place by the wrapped function.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the hook, storing each wrapped function as an importable reference.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the hook's type and the import paths of its sync/async functions.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FunctionHook
+```
+
+Deserialize the hook, resolving each function from its importable reference.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The serialized hook dictionary produced by `to_dict`.
+
+**Returns:**
+
+- FunctionHook – The reconstructed `FunctionHook`.
+
+### hook
+
+```python
+hook(function: Callable[[State], None | Awaitable[None]]) -> FunctionHook
+```
+
+Wrap a function into a `Hook` the Agent can invoke during its run loop.
+
+The decorated function receives the Agent's `State` and influences the run by mutating it in place. A coroutine
+function is wrapped as the hook's async path; a regular function as its sync path. To give a single hook both
+paths, construct a `FunctionHook` directly with both `function` and `async_function`.
+
+### Usage example
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.hooks import hook
+from haystack.components.agents.state import State
+from haystack.dataclasses import ChatMessage
+from haystack.tools import tool
+
+@tool
+def weather_tool(city: str) -> str:
+ '''Get the current weather for a given city.'''
+ return f"The weather in {city} is sunny."
+
+@tool
+def save(content: str) -> str:
+ '''Save content to durable storage.'''
+ return "Saved."
+
+@hook
+def require_save(state: State) -> None:
+ if state.get("tool_call_counts", {}).get("save", 0) == 0:
+ state.set("messages", [ChatMessage.from_system("You must call `save` before finishing.")])
+ state.set("continue_run", True)
+
+agent = Agent(chat_generator=OpenAIChatGenerator(), tools=[weather_tool, save], hooks={"on_exit": [require_save]})
+```
+
+**Parameters:**
+
+- **function** (Callable\\[[State\], None | Awaitable[None]\]) – A callable taking the Agent's `State` and returning `None` (sync or async).
+
+**Returns:**
+
+- FunctionHook – A `FunctionHook` wrapping the function.
+
+## human_in_the_loop/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.
+
+## human_in_the_loop/hooks
+
+### ConfirmationHook
+
+A `before_tool` Agent hook that applies Human-in-the-Loop confirmation strategies to pending tool calls.
+
+Register it on an `Agent` to confirm, modify, or reject tool calls before they run:
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.tools import tool
+from haystack.hooks.human_in_the_loop import (
+ AlwaysAskPolicy,
+ BlockingConfirmationStrategy,
+ ConfirmationHook,
+ NeverAskPolicy,
+ RichConsoleUI,
+ SimpleConsoleUI,
+)
+
+@tool
+def delete_file(path: str) -> str:
+ '''Delete the file at the given path.'''
+ return f"Deleted {path}."
+
+hook = ConfirmationHook(
+ confirmation_strategies={
+ "delete_file": BlockingConfirmationStrategy(
+ confirmation_policy=NeverAskPolicy(), confirmation_ui=SimpleConsoleUI()
+ )
+ }
+)
+agent = Agent(chat_generator=OpenAIChatGenerator(), tools=[delete_file], hooks={"before_tool": [hook]})
+```
+
+A key may be a single tool name, a tuple of tool names sharing one strategy, or the wildcard `"*"` which applies
+to any tool without a more specific entry. More specific keys win, so you can set a default for all tools and
+override individual ones:
+
+```python
+hook = ConfirmationHook(
+ confirmation_strategies={
+ "delete_file": BlockingConfirmationStrategy(
+ confirmation_policy=AlwaysAskPolicy(), confirmation_ui=RichConsoleUI()
+ ),
+ "*": BlockingConfirmationStrategy(
+ confirmation_policy=NeverAskPolicy(), confirmation_ui=SimpleConsoleUI()
+ ),
+ }
+)
+```
+
+Request-scoped resources for the strategies (e.g. a WebSocket or queue) are passed per run via the Agent's
+`hook_context` argument (`agent.run(messages=[...], hook_context={...})`) and read by the hook with
+`state.data.get("hook_context")`.
+
+This hook only makes sense at the `before_tool` hook point, where the pending tool calls exist (between the model
+requesting tools and those tools running); the Agent enforces this and raises if it is registered elsewhere. Use a
+single ConfirmationHook with one entry per tool (or per tuple of tools) in `confirmation_strategies` rather than
+registering several hooks.
+
+#### __init__
+
+```python
+__init__(
+ confirmation_strategies: dict[str | tuple[str, ...], ConfirmationStrategy],
+) -> None
+```
+
+Initialize the hook with its per-tool confirmation strategies.
+
+**Parameters:**
+
+- **confirmation_strategies** (dict\[str | tuple\[str, ...\], ConfirmationStrategy\]) – Mapping of tool name (or a tuple of tool names) to its `ConfirmationStrategy`.
+ The wildcard key `"*"` applies to any tool without a more specific entry.
+
+#### run
+
+```python
+run(state: State) -> None
+```
+
+Confirm the pending tool calls, rewriting the `messages` in `state` to reflect modifications and rejections.
+
+**Parameters:**
+
+- **state** (State) – The Agent's live `State`. Reads the available tools (`state.data.get("tools")`) and the per-run
+ context (`state.data.get("hook_context")`), and the pending tool calls from the last message; writes the
+ updated conversation back to `messages`. Reads go through `state.data` rather than `state.get`, which
+ deep-copies and would break non-copyable resources (e.g. a WebSocket or client) in `hook_context`.
+
+#### run_async
+
+```python
+run_async(state: State) -> None
+```
+
+Async version of `run`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the hook, including its confirmation strategies (tuple keys become JSON-array strings).
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ConfirmationHook
+```
+
+Deserialize the hook, reconstructing its confirmation strategies.
+
+## human_in_the_loop/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.
+
+## human_in_the_loop/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.
+
+## human_in_the_loop/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.
+
+## protocol
+
+### Hook
+
+Bases: Protocol
+
+A callable the Agent invokes at a point in its run loop, receiving the live `State`.
+
+A hook influences the run only by mutating `State` in place. At least `messages` (the conversation),
+`step_count`, `token_usage` and `tool_call_counts` are available; any additional keys defined in the Agent's
+`state_schema` are available too. The same hook object can be registered under multiple hook points.
+
+Implement this protocol directly for stateful hooks (e.g. one wrapping a component), or use the `@hook` decorator to
+wrap a plain `(State) -> None` function.
+
+A hook may additionally define `async def run_async(self, state: State) -> None` for true async behavior; when
+absent, the Agent calls `run` during async runs. It is left off this protocol on purpose so sync-only hooks
+don't have to implement it.
+
+A hook may also implement the optional lifecycle methods `warm_up` / `warm_up_async` and `close` / `close_async`.
+The Agent calls them from its own `warm_up` / `warm_up_async` and `close` / `close_async`, so a hook can defer
+opening clients or reading credentials until warm-up and release them on close. Because warm-up runs before every
+Agent run, hooks should avoid repeating expensive initialization, for example by returning early if a client has
+already been initialized.
+
+#### run
+
+```python
+run(state: State) -> None
+```
+
+Run the hook against the live `State`, mutating it in place.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the hook to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Hook
+```
+
+Deserialize the hook from a dictionary.
+
+## tool_result_offloading/hooks
+
+### ToolResultOffloadHook
+
+Offload tool results to a `ToolResultStore`, replacing them in the conversation with a compact pointer.
+
+This `after_tool` Agent hook writes the full result to the store so the next LLM call sees a reference instead of
+the full result. Register it on an `Agent` under the `after_tool` hook point. Which tools offload, and under what
+condition, is controlled per tool by `offload_strategies`:
+
+
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.hooks.tool_result_offloading import (
+ AlwaysOffload,
+ FileSystemToolResultStore,
+ NeverOffload,
+ OffloadOverChars,
+ ToolResultOffloadHook,
+)
+
+hook = ToolResultOffloadHook(
+ store=FileSystemToolResultStore(root="tool_results"),
+ offload_strategies={
+ "web_search": AlwaysOffload(), # force offload
+ "get_time": NeverOffload(), # opt out
+ ("read_file", "list_dir"): OffloadOverChars(4000), # tuple key: shared policy
+ "*": OffloadOverChars(8000), # wildcard default for any unlisted tool
+ },
+)
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[web_search, get_time, read_file, list_dir],
+ hooks={"after_tool": [hook]},
+)
+```
+
+A key may be a single tool name, a tuple of tool names sharing one policy, or the wildcard `"*"` which applies to
+any tool without a more specific entry. More specific keys win. A tool with no matching key (and no `"*"`) is not
+offloaded.
+
+Only successful tool output is offloaded; error results are always left in context. Each part of a result is
+written to its own store entry and the pointer says where each one went. Image and file content is only offloaded
+to a store that sets `supports_binary_content`; with a text-only store the result stays in context and a warning
+is logged. Each result is offloaded at most once, even though the hook runs on every tool step.
+
+The hook keeps no mutable state, so a single instance can be shared across concurrent runs. The constructor
+`store`, however, is shared by every run that does not override it — fine for single-user or local use, but in a
+multi-user server give each run its own isolated store (a per-session directory or sandbox) via `hook_context`
+under the key `RESULT_STORE_CONTEXT_KEY`
+(`agent.run(messages=[...], hook_context={RESULT_STORE_CONTEXT_KEY: per_request_store})`); it overrides the
+constructor store for that run. Isolating the store per run keeps concurrent users from colliding on store keys or
+reading each other's offloaded results — important especially when a bash/read tool is scoped to the store.
+
+#### __init__
+
+```python
+__init__(
+ store: ToolResultStore,
+ offload_strategies: dict[str | tuple[str, ...], OffloadPolicy],
+ *,
+ preview_chars: int = 200
+) -> None
+```
+
+Initialize the hook with a store and per-tool offload strategies.
+
+**Parameters:**
+
+- **store** (ToolResultStore) – Where offloaded results are written. Can be overridden per run via `hook_context`.
+- **offload_strategies** (dict\[str | tuple\[str, ...\], OffloadPolicy\]) – Mapping of tool name (or a tuple of tool names, or the wildcard `"*"`) to the
+ `OffloadPolicy` that decides whether that tool's results are offloaded.
+- **preview_chars** (int) – Number of leading characters of each offloaded text to include in the pointer left in
+ the conversation, so the model knows roughly what was offloaded. Image and file blocks are described by
+ their MIME type and size instead.
+
+#### run
+
+```python
+run(state: State) -> None
+```
+
+Offload the freshly produced tool results in `state.data["messages"]` according to `offload_strategies`.
+
+Considers only the trailing block of tool-result messages (the current step's results); earlier history is
+left untouched. Offloads each of those messages its policy opts in for, and writes the rewritten conversation
+back to `messages` only if at least one message changed.
+
+Results are written to the store this run resolves to: a per-run store passed in `state`'s `hook_context`
+under `RESULT_STORE_CONTEXT_KEY` if present, otherwise the store the hook was constructed with. Supply the
+per-run store when calling the Agent, e.g.
+`agent.run(messages=[...], hook_context={RESULT_STORE_CONTEXT_KEY: per_request_store})`. In a multi-user
+server, pass an isolated store per run this way so concurrent users write to separate locations and never
+read each other's results.
+
+The hook keeps no mutable state, so a single instance is safe to share across concurrent runs; isolation
+comes entirely from giving each run its own store via `hook_context`.
+
+**Parameters:**
+
+- **state** (State) – The Agent's live `State`. Reads the per-run store from `hook_context` and rewrites the offloaded
+ tool-result messages back into `messages`.
+
+**Returns:**
+
+- None – None. The hook mutates `state` in place.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the hook, including its store and per-tool offload strategies.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the hook.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ToolResultOffloadHook
+```
+
+Deserialize the hook, reconstructing its store and offload strategies.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – A dictionary representation produced by `to_dict`.
+
+**Returns:**
+
+- ToolResultOffloadHook – The deserialized `ToolResultOffloadHook`.
+
+## tool_result_offloading/policies
+
+### AlwaysOffload
+
+Bases: OffloadPolicy
+
+Offload every result of the tool it is assigned to.
+
+#### should_offload
+
+```python
+should_offload(tool_name: str, result: str, state: State) -> bool
+```
+
+Decide whether to offload the given tool result.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool that produced the result (unused; this policy always offloads).
+- **result** (str) – The tool result string (unused; this policy always offloads).
+- **state** (State) – The Agent's live `State` (unused; this policy always offloads).
+
+**Returns:**
+
+- bool – Always True.
+
+### NeverOffload
+
+Bases: OffloadPolicy
+
+Never offload; keep the tool's full result in context. Use to opt a tool out of a wildcard default.
+
+#### should_offload
+
+```python
+should_offload(tool_name: str, result: str, state: State) -> bool
+```
+
+Decide whether to offload the given tool result.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool that produced the result (unused; this policy never offloads).
+- **result** (str) – The tool result string (unused; this policy never offloads).
+- **state** (State) – The Agent's live `State` (unused; this policy never offloads).
+
+**Returns:**
+
+- bool – Always False.
+
+### OffloadOverChars
+
+Bases: OffloadPolicy
+
+Offload a result only when its string length exceeds `threshold` characters.
+
+#### __init__
+
+```python
+__init__(threshold: int) -> None
+```
+
+Initialize the policy with its character threshold.
+
+**Parameters:**
+
+- **threshold** (int) – Offload the result when its length in characters is strictly greater than this value.
+
+#### should_offload
+
+```python
+should_offload(tool_name: str, result: str, state: State) -> bool
+```
+
+Decide whether to offload the given tool result based on its length.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool that produced the result (unused; only length is considered).
+- **result** (str) – The tool result string whose length is compared against the threshold.
+- **state** (State) – The Agent's live `State` (unused; only length is considered).
+
+**Returns:**
+
+- bool – True when `result` is longer than `threshold` characters, otherwise False.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the policy, including its threshold.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the policy.
+
+## tool_result_offloading/stores
+
+### FileSystemToolResultStore
+
+Bases: ToolResultStore
+
+A `ToolResultStore` that writes offloaded tool results to files under a root directory on the local file system.
+
+```python
+from haystack.hooks.tool_result_offloading import FileSystemToolResultStore
+
+store = FileSystemToolResultStore(root="tool_results")
+reference = store.write(key="search_1.txt", content="...")
+store.read(reference)
+```
+
+Binary content is supported too: `write` takes bytes (an offloaded image or file) and `read` returns them
+unchanged.
+
+#### __init__
+
+```python
+__init__(root: str | Path) -> None
+```
+
+Initialize the store with the root directory results are written under.
+
+**Parameters:**
+
+- **root** (str | Path) – Directory under which result files are written. Created on first write if it does not exist.
+
+#### write
+
+```python
+write(*, key: str, content: str | bytes) -> str
+```
+
+Write `content` to `str) – Relative file name for the result within the store root.
+- **content** (str | bytes) – The tool result to persist, as text or as raw bytes.
+
+**Returns:**
+
+- str – The absolute path the content was written to, as a string, for use with `read`.
+
+**Raises:**
+
+- ValueError – If `key` resolves to a location outside the store root.
+
+#### read
+
+```python
+read(reference: str) -> str | bytes
+```
+
+Read back the content previously written to `reference`.
+
+A file whose bytes are valid UTF-8 is returned as a string, so text results round trip unchanged; anything
+else (an offloaded image or file) is returned as raw bytes.
+
+The resolved reference must stay within the store root: it is a store-scoped reference returned by `write`,
+to be passed back unchanged, not an arbitrary filesystem path callers can build themselves.
+
+**Parameters:**
+
+- **reference** (str) – A store reference returned by `write`.
+
+**Returns:**
+
+- str | bytes – The stored content, as text when it decodes as UTF-8 and as bytes otherwise.
+
+**Raises:**
+
+- ValueError – If `reference` resolves to a location outside the store root.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the store, storing its root directory as a string.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the store.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FileSystemToolResultStore
+```
+
+Deserialize the store from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – A dictionary representation produced by `to_dict`.
+
+**Returns:**
+
+- FileSystemToolResultStore – The deserialized `FileSystemToolResultStore`.
+
+## tool_result_offloading/types/protocol
+
+### ToolResultStore
+
+Bases: Protocol
+
+A place a `ToolResultOffloadHook` writes offloaded tool results to, and reads them back from.
+
+Implementations decide where and how the content lives (local disk, an isolated sandbox filesystem, object
+storage, ...). `write` returns a reference string that the Agent puts in the conversation in place of the full
+result; `read` resolves that reference back to the original content. Only the store interprets a reference -
+callers pass it back to `read` unchanged.
+
+A store that sets `supports_binary_content` takes bytes in `write` and gives them back from `read`. One that
+leaves it False is only ever given text, and image and file results stay in the conversation instead.
+
+Implement both `to_dict` and `from_dict` to make a custom store serializable; the default implementations below
+cover stores whose constructor takes no arguments.
+
+#### write
+
+```python
+write(*, key: str, content: str | bytes) -> str
+```
+
+Persist `content` under `key` and return a reference to it.
+
+**Parameters:**
+
+- **key** (str) – A stable, per-result identifier the hook derives from the tool call (e.g. a file name). It carries
+ an extension matching the content, so a store that maps keys to files can use it as-is.
+- **content** (str | bytes) – The tool result to persist. Text arrives as a string. Image and file content arrives as the
+ decoded bytes of its base64 payload, and only when the store sets `supports_binary_content` to True - a
+ text-only store may narrow this parameter to `str`.
+
+**Returns:**
+
+- str – A reference string (e.g. a path or URI) that `read` can later resolve.
+
+#### read
+
+```python
+read(reference: str) -> str | bytes
+```
+
+Return the content previously stored under `reference`.
+
+**Parameters:**
+
+- **reference** (str) – A reference string returned by `write`.
+
+**Returns:**
+
+- str | bytes – The stored content: a string for content written as text, bytes for binary content such as an
+ offloaded image or file. A store that does not support binary content only ever returns a string.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the store to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ToolResultStore
+```
+
+Deserialize the store from a dictionary.
+
+### OffloadPolicy
+
+Bases: Protocol
+
+Decides, per tool result, whether the `ToolResultOffloadHook` offloads it to the store or leaves it in context.
+
+A `ToolResultOffloadHook` maps tool names to policies, so different tools can offload under different conditions
+(always, never, or a custom rule such as a size threshold).
+
+Implement both `to_dict` and `from_dict` to make a custom policy serializable; the default implementations below
+cover policies whose constructor takes no arguments.
+
+#### should_offload
+
+```python
+should_offload(tool_name: str, result: str, state: State) -> bool
+```
+
+Return whether the given tool result should be offloaded.
+
+**Parameters:**
+
+- **tool_name** (str) – The name of the tool that produced the result.
+- **result** (str) – The tool result as a string (the content that would otherwise stay in the conversation). For a
+ result carrying image or file blocks, this is the text and base64 payloads of all its blocks joined
+ together, so its length reflects the context the result actually occupies.
+- **state** (State) – The Agent's live `State`, for policies that decide based on run context.
+
+**Returns:**
+
+- bool – True to offload the result to the store, False to leave it in context.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the policy to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OffloadPolicy
+```
+
+Deserialize the policy from a dictionary.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/image_converters_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/image_converters_api.md
new file mode 100644
index 00000000000..5b20a86b703
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/image_converters_api.md
@@ -0,0 +1,356 @@
+---
+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="test/test_files",
+ detail="high",
+ size=(800, 600)
+)
+
+documents = [
+ Document(content="Optional description of apple.jpg", meta={"file_path": "images/apple.jpg"}),
+ Document(
+ content="Optional description of sample_pdf_1.pdf",
+ meta={"file_path": "pdf/sample_pdf_1.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': 'images/apple.jpg'}
+# ),
+# ImageContent(
+# base64_image='/9j/4A...', mime_type='image/jpeg', detail='high',
+# meta={'file_path': 'pdf/sample_pdf_1.pdf', 'page_number': 1})
+# )]
+```
+
+#### __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 and are guaranteed to stay within it. If None,
+ file paths are treated as absolute paths with no containment check.
+ Security: this component reads the file referenced by `file_path_meta_field` from the host filesystem. If
+ document metadata may be influenced by untrusted input, set `root_path` to a dedicated data directory so
+ that path-traversal payloads (e.g. absolute paths or `../`) are rejected instead of read.
+- **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 the order of the input documents. A document that is
+ missing the required metadata keys, has an invalid file path, or has an unsupported MIME type gets
+ None in its position and a logged warning with the reason.
+
+## 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 `LLMDocumentContentExtractor` or the
+`SentenceTransformersDocumentImageEmbedder` (available in the `sentence-transformers-haystack` integration).
+
+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-3.2-unstable/haystack-api/joiners_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/joiners_api.md
new file mode 100644
index 00000000000..955c14eacba
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/joiners_api.md
@@ -0,0 +1,591 @@
+---
+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. Must be `None` or greater than 0.
+- **sort_by_score** (bool) – If `True`, sorts the answers by score in descending order.
+ If an answer has no score, it is handled as if its score is -infinity.
+
+**Raises:**
+
+- ValueError – If `top_k` is not `None` and is less than or equal to 0.
+
+#### 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.
+
+If the instance was created with `sort_by_score=True`, the merged Answers are sorted by
+score in descending order before `top_k` is applied; Answers without a score are handled
+as if their score were -infinity. Otherwise, the input order is preserved.
+
+**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.
+ A value of 0 returns no answers. Must not be negative.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `answers`: Merged list of Answers, sorted by score if `sort_by_score` was set to
+ `True` on the instance, otherwise in input order
+
+**Raises:**
+
+- ValueError – If `top_k` is negative.
+
+#### 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 OpenAITextEmbedder, OpenAIDocumentEmbedder
+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 = OpenAIDocumentEmbedder()
+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=OpenAITextEmbedder(),
+ 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", "embedding_retriever.query_embedding")
+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.
+ Each weight must be a non-negative number.
+- **top_k** (int | None) – The maximum number of documents to return. Must be `None` or greater than 0.
+- **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.
+
+**Raises:**
+
+- ValueError – If `top_k` is not `None` and is less than or equal to 0,
+ or if any value in `weights` is negative.
+
+#### 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.
+ A value of 0 returns no documents. Must not be negative.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: Merged list of Documents
+
+**Raises:**
+
+- ValueError – If `top_k` is negative.
+
+#### 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": {"query": query},
+ "feedback_prompt_builder": {"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-3.2-unstable/haystack-api/pipeline_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/pipeline_api.md
new file mode 100644
index 00000000000..cdf31b06e9f
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/pipeline_api.md
@@ -0,0 +1,501 @@
+---
+title: "Pipeline"
+id: pipeline-api
+description: "Arranges components and integrations in flow."
+slug: "/pipeline-api"
+---
+
+
+## pipeline
+
+### PipelineStreamHandle
+
+Handle returned by `Pipeline.stream()`.
+
+Async-iterable over `StreamingChunk`s produced by streaming components in the pipeline. After iteration ends,
+`result` holds the final pipeline output dict.
+
+By default, iteration cleans up automatically: if the consumer abandons iteration, the underlying pipeline task is
+cancelled. `aclose()` is also available for explicit cleanup.
+
+#### result
+
+```python
+result: dict[str, Any]
+```
+
+Final pipeline output dict, available only after a successful, complete run.
+
+Raises a `RuntimeError` if the pipeline has not finished or was cancelled. If the pipeline failed, re-raises the
+original exception.
+
+#### aclose
+
+```python
+aclose() -> None
+```
+
+Cancel the underlying pipeline task.
+
+Bounded by `_CLEANUP_TIMEOUT_SECONDS` so that components cannot block cleanup indefinitely.
+
+### Pipeline
+
+Bases: PipelineBase
+
+Orchestration engine that runs components according to the execution graph.
+
+Supports both a synchronous run path (`run`) and an asynchronous run path
+(`run_async`, `run_async_generator`, `stream`).
+
+#### run
+
+```python
+run(
+ data: dict[str, Any],
+ include_outputs_from: set[str] | None = None,
+ *,
+ break_point: Breakpoint | None = None,
+ pipeline_snapshot: PipelineSnapshot | None = None,
+ snapshot_callback: SnapshotCallback | None = None
+) -> dict[str, Any]
+```
+
+Runs the Pipeline with given input data.
+
+`run` executes synchronously and blocks the calling thread until the run completes. In an async context,
+use `run_async` instead.
+
+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 | None) – A breakpoint that pauses execution before the specified component runs by raising a
+ `BreakpointException` carrying a `PipelineSnapshot` of the current pipeline state.
+- **pipeline_snapshot** (PipelineSnapshot | None) – A snapshot of a previously interrupted pipeline execution to resume from. Can be combined with
+ `break_point` to step through a pipeline: resume from the snapshot and pause again at the next
+ breakpoint. The `break_point` must target a different component or visit count than the one the
+ snapshot was created at, otherwise it would trigger again before any progress is made.
+- **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.
+
+#### run_async_generator
+
+```python
+run_async_generator(
+ data: dict[str, Any],
+ include_outputs_from: set[str] | None = None,
+ concurrency_limit: int = 4,
+) -> AsyncGenerator[dict[str, Any], None]
+```
+
+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 Pipeline
+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 = 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")
+
+# 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:**
+
+- AsyncGenerator\[dict\[str, Any\], None\] – An async iterator containing partial (and final) outputs.
+
+**Raises:**
+
+- ValueError – If invalid inputs are provided to the pipeline, or if `concurrency_limit` is less than 1.
+- 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 import Pipeline
+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 = 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")
+
+# 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, or if `concurrency_limit` is less than 1.
+- 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.
+
+#### stream
+
+```python
+stream(
+ data: dict[str, Any],
+ *,
+ streaming_components: list[str] | None = None,
+ include_outputs_from: set[str] | None = None,
+ concurrency_limit: int = 4,
+ cancel_on_abandon: bool = True
+) -> PipelineStreamHandle
+```
+
+Run the pipeline and return a handle that streams `StreamingChunk`s as they arrive.
+
+Iterate the handle with `async for` to consume chunks; after iteration ends, `handle.result` holds the final
+pipeline output dict (same as `run_async`). By default, if iteration is abandoned, the underlying pipeline task
+is cancelled automatically. Pass `cancel_on_abandon=False` to instead let the pipeline run to completion.
+
+For every async-capable component that exposes a `streaming_callback` input socket, a forwarder is injected at
+runtime that pushes chunks onto the handle's queue. If a `streaming_callback` is provided at component init or
+at runtime (inside `data`, e.g. `data={"llm": {"streaming_callback": cb}}`), it is also invoked for each chunk.
+Async callbacks are preferred; a sync callback is accepted but will run synchronously on the event loop and
+may block it.
+
+Usage:
+
+```python
+import asyncio
+
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack import Pipeline
+from haystack.dataclasses import ChatMessage
+
+pipe = Pipeline()
+pipe.add_component(
+ "prompt_builder",
+ ChatPromptBuilder(template=[ChatMessage.from_user("Tell me about {{topic}}")]),
+)
+pipe.add_component("llm", OpenAIChatGenerator())
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+async def main():
+ handle = pipe.stream(data={"prompt_builder": {"topic": "Italy"}})
+ async for chunk in handle:
+ print(chunk.content, end="", flush=True)
+ return handle.result
+
+result = asyncio.run(main())
+print(result["llm"]["replies"])
+```
+
+**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,
+}
+```
+
+- **streaming_components** (list\[str\] | None) – Names of components to stream from. If `None` (default), every streaming-capable
+ component is forwarded. If a list, only the listed components are forwarded; unknown names or names of
+ components that do not support streaming raise `ValueError`.
+- **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.
+- **cancel_on_abandon** (bool) – If `True` (default), the underlying pipeline task is cancelled when iteration is
+ abandoned. If `False`, the pipeline runs to completion even when the consumer stops reading.
+
+**Returns:**
+
+- PipelineStreamHandle – A `PipelineStreamHandle` that is async-iterable over `StreamingChunk`s. After iteration ends,
+ `handle.result` holds the final pipeline output dict (same shape as `run_async`).
+
+**Raises:**
+
+- ValueError – If `streaming_components` contains unknown component names or components that do not support streaming,
+ or if invalid inputs are provided to the pipeline, or if `concurrency_limit` is less than 1.
+- PipelineRuntimeError – Surfaced during iteration. 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 – Surfaced during iteration. If a Component reaches the maximum number of times it can be run in this
+ Pipeline.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/preprocessors_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/preprocessors_api.md
new file mode 100644
index 00000000000..473584ba568
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/preprocessors_api.md
@@ -0,0 +1,1079 @@
+---
+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,
+ min_content_length: int = 0,
+) -> 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.
+- **min_content_length** (int) – Minimum length of the cleaned document content after stripping leading and trailing
+ whitespace. Documents shorter than this value are dropped. A value of `0` keeps all documents.
+
+#### 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",
+ "token",
+ ] = "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,
+ tokenizer_encoding: str = "o200k_base",
+ 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', 'token']) – The unit of splitting: "function", "page", "passage", "period", "word", "line",
+ "sentence", or "token".
+- **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.
+- **tokenizer_encoding** (str) – The tiktoken encoding to use when `split_by="token"`. Defaults to
+ `"o200k_base"` (current OpenAI models). Only used when `split_by="token"`.
+
+**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",
+ "token",
+ ] = "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,
+ tokenizer_encoding: str = "o200k_base"
+) -> None
+```
+
+Initialize DocumentSplitter.
+
+**Parameters:**
+
+- **split_by** (Literal['function', 'page', 'passage', 'period', 'word', 'line', 'sentence', 'token']) – 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
+- `token` for splitting by token count using tiktoken (requires `pip install tiktoken`)
+- **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.
+- **tokenizer_encoding** (str) – The tiktoken encoding to use when `split_by="token"`. Defaults to
+ `"o200k_base"` (current OpenAI models). Only used when `split_by="token"`.
+ Special-token strings in document content are encoded as ordinary text.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the DocumentSplitter by loading the sentence tokenizer or tiktoken encoder.
+
+#### 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 OpenAIDocumentEmbedder
+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 = OpenAIDocumentEmbedder()
+
+# 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 and the document embedder.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the component on the serving event loop.
+
+Initializes the sentence splitter and warms up the document embedder using its async warm-up path when
+available, falling back to the synchronous one otherwise.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the document embedder's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the document embedder's async resources.
+
+#### 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 `split_idx_start` with the character offset of the chunk in the original document.
+ - 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 `split_idx_start` with the character offset of the chunk in the original document.
+ - 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.
+
+**Raises:**
+
+- ValueError – If `block_sizes` is empty, if `split_overlap` is negative, or if `split_overlap` is
+ greater than or equal to the smallest value in `block_sizes`.
+
+#### 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=15, 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: {'source_id': '...', 'parent_id': '...', 'split_id': 0, 'split_idx_start': 0, '_split_overlap': None, 'page_number': 1})
+# Document(id=..., content: 'AI, in its broadest sense, is intelligence exhibited by machines, particularly computer systems.\n', meta: {'source_id': '...', 'parent_id': '...', 'split_id': 1, 'split_idx_start': 45, '_split_overlap': None, 'page_number': 1})
+# Document(id=..., content: 'AI technology is widely used throughout industry, government, and science.', meta: {'source_id': '...', 'parent_id': '...', 'split_id': 2, 'split_idx_start': 142, '_split_overlap': None, 'page_number': 1})
+# Document(id=..., content: ' Some high-profile applications include advanced web search engines; recommendation systems; interac...', meta: {'source_id': '...', 'parent_id': '...', 'split_id': 3, 'split_idx_start': 216, '_split_overlap': None, 'page_number': 1})
+# Document(id=..., content: 'vehicles; generative and creative tools; and superhuman play and analysis in strategy games.', meta: {'source_id': '...', 'parent_id': '...', 'split_id': 4, 'split_idx_start': 350, '_split_overlap': None, 'page_number': 1})
+# ]
+```
+
+#### __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 overlapping units (words, characters, or tokens, per
+ `split_unit`) 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).
+ Special-token strings in document content are encoded as ordinary text.
+- **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.
+
+#### 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(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.
+
+#### 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(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-3.2-unstable/haystack-api/query_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/query_api.md
new file mode 100644
index 00000000000..f7c68ce1647
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/query_api.md
@@ -0,0 +1,183 @@
+---
+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. Must be a positive integer.
+
+**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).
+
+#### run_async
+
+```python
+run_async(query: str, n_expansions: int | None = None) -> dict[str, list[str]]
+```
+
+Asynchronously expand the input query into multiple semantically similar queries.
+
+The language of the original query is preserved in the expanded queries.
+
+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. If the chat generator only implements a synchronous
+`run` method, it is executed in a thread to avoid blocking the event loop.
+
+**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. Must be a positive integer.
+
+**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 underlying chat generator.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the underlying chat generator on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the underlying chat generator's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the underlying chat generator's async resources.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/rankers_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/rankers_api.md
new file mode 100644
index 00000000000..7d70ff7d20b
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/rankers_api.md
@@ -0,0 +1,514 @@
+---
+title: "Rankers"
+id: rankers-api
+description: "Reorders a set of Documents based on their relevance to the query."
+slug: "/rankers-api"
+---
+
+
+## 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.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the underlying chat generator on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the underlying chat generator's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the underlying chat generator's async resources.
+
+#### 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.
+
+#### run_async
+
+```python
+run_async(
+ query: str, documents: list[Document], top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously rank documents for a query using an LLM.
+
+Before ranking, duplicate documents are removed.
+
+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. If the chat generator only implements a synchronous
+`run` method, it is executed in a thread to avoid blocking the event loop.
+
+**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 'linear_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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/retrievers_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/retrievers_api.md
new file mode 100644
index 00000000000..ab4a9ecd0c4
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/retrievers_api.md
@@ -0,0 +1,1543 @@
+---
+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)
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+## 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+## 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 OpenAIDocumentEmbedder, OpenAITextEmbedder
+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 = OpenAIDocumentEmbedder()
+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 = OpenAITextEmbedder()
+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 OpenAITextEmbedder
+from haystack.components.embedders import OpenAIDocumentEmbedder
+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 = OpenAIDocumentEmbedder()
+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 = OpenAITextEmbedder()
+
+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 in `run` and of concurrent retriever calls in
+ `run_async`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the query embedder and the retriever.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the query embedder and the retriever on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the query embedder's and the retriever's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the query embedder's and the retriever's async resources.
+
+#### 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.
+
+#### run_async
+
+```python
+run_async(
+ queries: list[str], retriever_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents using multiple queries concurrently.
+
+Uses each component's `run_async` method if available, otherwise falls back to running `run`
+in a thread executor. Queries are processed concurrently using asyncio.gather.
+
+**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 in `run` and of concurrent retriever calls in
+ `run_async`. Default is 3.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the retriever.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the retriever on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the retriever's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the retriever's async resources.
+
+#### 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.
+
+#### run_async
+
+```python
+run_async(
+ queries: list[str], retriever_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents using multiple queries concurrently.
+
+Uses the retriever's `run_async` method if available, otherwise falls back to running `run`
+in a thread executor. Queries are processed concurrently using asyncio.gather.
+
+**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 OpenAITextEmbedder, OpenAIDocumentEmbedder
+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 = OpenAIDocumentEmbedder()
+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=OpenAITextEmbedder(),
+ ),
+ },
+ 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_per_retriever: int | None = None,
+ top_k: int | None = None,
+ 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_per_retriever** (int | None) – The maximum number of documents to return per retriever. If set, this will override the `top_k`
+ parameter for each retriever. If None, the `top_k` parameter of retrievers will be used.
+- **top_k** (int | None) – The maximum number of documents to return overall, extracted from the combined results of all
+ retrievers. When set, the results are always merged using reciprocal rank fusion (regardless of
+ `join_mode`) so that the combined list has a consistent global ranking before it is truncated to
+ `top_k`. If None, all results are returned.
+- **max_workers** (int) – The maximum number of threads in `run` and of concurrent retriever calls in `run_async`.
+- **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.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the retrievers on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the retrievers' resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the retrievers' async resources.
+
+#### run
+
+```python
+run(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ top_k_per_retriever: int | 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_per_retriever** (int | None) – The maximum number of documents to return per retriever. When set, this will override the `top_k`
+ parameter for each retriever. If None, the `top_k` parameter set for retrievers will be used.
+ Defaults to the value set at initialization.
+- **top_k** (int | None) – The maximum number of documents to return overall, extracted from the combined results of all
+ retrievers. When set, the results are always merged using reciprocal rank fusion (regardless of
+ `join_mode`) so that the combined list has a consistent global ranking before it is truncated to
+ `top_k`. If None, all results are returned. 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_per_retriever: int | 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_per_retriever** (int | None) – The maximum number of documents to return per retriever. When set, this will override the `top_k`
+ parameter for each retriever. If None, the `top_k` parameter set for retrievers will be used.
+ Defaults to the value set at initialization.
+- **top_k** (int | None) – The maximum number of documents to return overall, extracted from the combined results of all
+ retrievers. When set, the results are always merged using reciprocal rank fusion (regardless of
+ `join_mode`) so that the combined list has a consistent global ranking before it is truncated to
+ `top_k`. If None, all results are returned. 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. It must be greater than 0; values of
+ 0 and negative values are rejected.
+
+**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. It must be greater than 0; values of
+ 0 and negative values are rejected.
+
+**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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+## 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 OpenAITextEmbedder, OpenAIDocumentEmbedder
+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 = OpenAIDocumentEmbedder()
+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 = OpenAITextEmbedder()
+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.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the text embedder and the retriever on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the text embedder's and the retriever's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the text embedder's and the retriever's async resources.
+
+#### 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.
+
+#### run_async
+
+```python
+run_async(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents using a single query asynchronously.
+
+Uses `run_async` on the text embedder and retriever if available, otherwise falls back to
+running `run` in a thread executor.
+
+**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-3.2-unstable/haystack-api/routers_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/routers_api.md
new file mode 100644
index 00000000000..d82cbefc7ee
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/routers_api.md
@@ -0,0 +1,926 @@
+---
+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.
+
+An optional field `output_passthrough` can be set to `True` to treat `output` as a variable name
+instead of a Jinja2 template, passing the variable value directly. This is useful for routing
+complex non-basic types (dataclasses, Pydantic models, etc.) without Jinja2 processing.
+
+### 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'}}
+```
+
+### Passthrough routing for non-basic types
+
+Without `output_passthrough`, the router renders `output` as a Jinja2 template, which converts
+the value to its string representation. Custom types cannot survive that round-trip:
+
+```python
+# Without output_passthrough — the object is silently converted to a string
+routes = [
+ {
+ "condition": "{{True}}",
+ "output": "{{query}}",
+ "output_name": "out",
+ "output_type": ParsedQuery,
+ }
+]
+router = ConditionalRouter(routes)
+result = router.run(query=ParsedQuery(text="hello", intent="search", entities=[]))
+# result["out"] == "ParsedQuery(text='hello', intent='search', entities=[])"
+# ^^^ str, not ParsedQuery — the object was destroyed
+```
+
+Set `output_passthrough: True` to skip Jinja2 entirely and pass the value directly from kwargs:
+
+```python
+from haystack.components.routers import ConditionalRouter
+from dataclasses import dataclass, field
+
+@dataclass
+class ParsedQuery:
+ text: str
+ intent: str # "search" | "chat"
+ entities: list[str] = field(default_factory=list)
+
+routes = [
+ {
+ "condition": "{{query.intent == 'search'}}",
+ "output": "query", # variable name, not a Jinja2 template
+ "output_name": "search_query",
+ "output_type": ParsedQuery,
+ "output_passthrough": True,
+ },
+ {
+ "condition": "{{query.intent == 'chat'}}",
+ "output": "query",
+ "output_name": "chat_query",
+ "output_type": ParsedQuery,
+ "output_passthrough": True,
+ },
+]
+
+router = ConditionalRouter(routes)
+query = ParsedQuery(text="What is Haystack?", intent="search", entities=["Haystack"])
+result = router.run(query=query)
+
+assert isinstance(result["search_query"], ParsedQuery) # type preserved
+assert result["search_query"] is query # same object, no copying
+```
+
+#### __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, or a plain variable name
+ if `output_passthrough` is `True`.
+- `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.
+- `output_passthrough` (optional): If `True`, treats `output` as a plain variable name and
+ passes the value directly from the input kwargs, skipping all Jinja2 processing. Useful
+ for routing complex non-basic types without template transformation.
+ Note: if the variable named in `output` is also listed in `optional_variables`, a missing
+ value at runtime will route `None` downstream rather than raising a `ValueError`.
+- **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 the route output doesn't match the declared type, or if
+ `output_passthrough` is `True` and the variable named in `output` is not found in kwargs.
+
+## 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"]`). `"unclassified"` is reserved.
+- **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, uses the reserved name `"unclassified"`, 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; byte streams use metadata.
+Each entry in `mime_types` is matched against a source's MIME type by exact equality first,
+falling back to regex `fullmatch` if equality misses. So `"image/svg+xml"` routes
+`image/svg+xml` streams correctly via the equality check (without `+` being interpreted as a
+regex quantifier), and patterns like `"audio/.*"` keep matching every audio subtype.
+
+### Usage example
+
+```python
+from haystack.components.routers import FileTypeRouter
+from pathlib import Path
+
+# Exact MIME matching — `+`-containing IANA types like image/svg+xml work correctly
+router = FileTypeRouter(mime_types=["text/plain", "application/pdf", "image/svg+xml"])
+
+# Regex matching — catch every audio subtype
+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"]`).
+ `"unclassified"` and `"failed"` are reserved output names and cannot be used here.
+- **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.
+
+**Raises:**
+
+- ValueError – If `mime_types` is empty, contains an invalid regex, or uses the reserved names
+ `"unclassified"` or `"failed"`.
+
+#### 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_integrations.components.generators.huggingface_api 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. `"chat_generator_text"` and `"unmatched"` are reserved output names and cannot be used here.
+- **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, or if
+ output_names uses the reserved names `"chat_generator_text"` or `"unmatched"`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the underlying chat generator.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the underlying chat generator on the serving event loop.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the underlying chat generator's resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the underlying chat generator's async resources.
+
+#### 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.
+
+#### run_async
+
+```python
+run_async(messages: list[ChatMessage]) -> dict[str, str | list[ChatMessage]]
+```
+
+Asynchronously classify the messages based on LLM output and route them to the appropriate output connection.
+
+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. If the chat generator only implements a synchronous
+`run` method, it is executed in a thread to avoid blocking the event loop.
+
+**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],
+ *,
+ strict_datetime_comparison: bool = False
+) -> 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 (`"unmatched"` is reserved), 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"},
+ ],
+},
+}
+```
+
+- **output_type** (type) – The type of the output produced. Lists of Documents or ByteStreams can be specified.
+- **strict_datetime_comparison** (bool) – If `True`, timezone-naive and timezone-aware datetimes never match each other.
+ If `False` (the default), the timezone from the aware datetime is copied to the naive one before comparing.
+
+**Raises:**
+
+- ValueError – If `rules` contains the reserved output name `"unmatched"` or an invalid filter.
+
+#### 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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/samplers_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/samplers_api.md
new file mode 100644
index 00000000000..d225afc4a66
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/samplers_api.md
@@ -0,0 +1,86 @@
+---
+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) – Minimum number of scored documents to return. If top-p sampling selects fewer documents,
+ documents with the next-highest scores are added. Must be a non-negative integer or None.
+ If greater than the number of scored documents, all scored documents are returned.
+
+**Raises:**
+
+- ValueError – If top_p is not within [0, 1] or min_top_k is not a non-negative integer or None.
+
+#### 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-3.2-unstable/haystack-api/skill_stores_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/skill_stores_api.md
new file mode 100644
index 00000000000..52fef844cf9
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/skill_stores_api.md
@@ -0,0 +1,256 @@
+---
+title: "Skill Stores"
+id: skill-stores-api
+description: "Storage layers that discover skills and serve their content on demand."
+slug: "/skill-stores-api"
+---
+
+
+## file_system/skill_store
+
+### FileSystemSkillStore
+
+SkillStore backed by a directory of skill sub-directories on the local filesystem.
+
+Expected layout:
+
+```
+skills/
+ pdf-forms/
+ SKILL.md # frontmatter (name, description) + markdown instructions
+ reference/forms.md # optional bundled file
+```
+
+The skill catalog is built by reading the frontmatter of each `SKILL.md` on `warm_up`; bodies and bundled files
+are read lazily when the agent calls the corresponding tool.
+
+#### __init__
+
+```python
+__init__(skills_dir: str | Path | Secret) -> None
+```
+
+Initialize the store with the root directory to scan.
+
+No filesystem access happens here; the directory is scanned lazily on first use (see `warm_up`), so the store
+can be constructed cheaply.
+
+**Parameters:**
+
+- **skills_dir** (str | Path | Secret) – Root directory that contains one sub-directory per skill. Can also be a `Secret`
+ (e.g. `Secret.from_env_var("SKILLS_DIR")`) to source the path from an environment variable rather than
+ hard-coding it.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Scan `skills_dir` and build the skill catalog by reading each skill's `SKILL.md` frontmatter.
+
+Only the frontmatter is read here; bodies and bundled files are read lazily when the corresponding method is
+called. Idempotent: repeated calls after the first are no-ops.
+
+**Raises:**
+
+- ValueError – If `skills_dir` does not exist, is not a directory, a skill's frontmatter is missing,
+ malformed, or missing a required field, or two skills share the same name.
+
+#### list_skills
+
+```python
+list_skills() -> dict[str, SkillInfo]
+```
+
+Return all skills discovered on disk, warming up the store first if needed.
+
+**Returns:**
+
+- dict\[str, SkillInfo\] – Mapping of skill name to its metadata.
+
+**Raises:**
+
+- ValueError – If the skills directory is invalid or a skill's frontmatter is malformed.
+
+#### load_skill
+
+```python
+load_skill(name: str) -> tuple[str, list[str]]
+```
+
+Read the named skill's instruction body and the manifest of its bundled files.
+
+**Parameters:**
+
+- **name** (str) – Skill name as returned by `list_skills`.
+
+**Returns:**
+
+- tuple\[str, list\[str\]\] – A tuple of (markdown body of the skill's `SKILL.md` with frontmatter stripped, sorted list of
+ POSIX-style paths relative to the skill directory for any bundled files). The file list is empty when
+ the skill bundles no extras.
+
+**Raises:**
+
+- KeyError – If no skill with `name` exists.
+
+#### read_skill_file
+
+```python
+read_skill_file(name: str, path: str) -> str | ImageContent | FileContent
+```
+
+Read a file bundled with the named skill, preventing path traversal outside the skill directory.
+
+The return type depends on the file: text files are returned as a `str`, image files (PNG, JPEG, ...) as an
+`ImageContent`, and PDFs as a `FileContent`, so a multimodal agent can pass them straight to the model.
+
+**Parameters:**
+
+- **name** (str) – Skill name as returned by `list_skills`.
+- **path** (str) – Path of the file relative to the skill directory (e.g. `"reference/forms.md"`).
+
+**Returns:**
+
+- str | ImageContent | FileContent – The file's text content (`str`), an `ImageContent` for images, or a `FileContent` for PDFs.
+
+**Raises:**
+
+- KeyError – If no skill with `name` exists.
+- PermissionError – If `path` resolves outside the skill's directory (path-traversal attempt). The
+ message lists the readable files so the caller can retry with a valid path.
+- FileNotFoundError – If the file does not exist within the skill. The message lists the readable
+ files so the caller can retry with a valid path.
+- ValueError – If the file is binary but not a supported image or PDF (i.e. not UTF-8 text either).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this store to a dictionary for use with `from_dict`.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary representation of the store.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FileSystemSkillStore
+```
+
+Deserialize a `FileSystemSkillStore` from its dictionary representation.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary representation of the store, as produced by `to_dict`.
+
+**Returns:**
+
+- FileSystemSkillStore – A new `FileSystemSkillStore` instance.
+
+## types/protocol
+
+### SkillStore
+
+Bases: Protocol
+
+Protocol for a skill storage layer.
+
+A `SkillStore` is responsible for discovering available skills and providing their content on demand. Implement
+this protocol to back a `haystack.tools.SkillToolset` with any storage system — a local directory, a database,
+a remote API, or an in-memory fixture.
+
+Skills are identified by their `name`, which must be unique within a store. The `name` is the lookup key for every
+method below; implementations resolve it to their own internal locator (a directory, a row id, an object key, ...).
+
+Implementations may defer all I/O (filesystem reads, database connections, ...) until a method is actually called,
+so a store can be constructed cheaply and only touch its backend on first use.
+
+Skill content is text: instruction bodies and bundled files are returned as strings. Binary assets (images,
+fonts, ...) are not supported.
+
+#### list_skills
+
+```python
+list_skills() -> dict[str, SkillInfo]
+```
+
+Discover and return all available skills.
+
+**Returns:**
+
+- dict\[str, SkillInfo\] – Mapping of skill name to its metadata.
+
+#### load_skill
+
+```python
+load_skill(name: str) -> tuple[str, list[str]]
+```
+
+Return the named skill's instruction body and the manifest of its bundled files.
+
+**Parameters:**
+
+- **name** (str) – Skill name as returned by `list_skills`.
+
+**Returns:**
+
+- tuple\[str, list\[str\]\] – A tuple of (markdown body with frontmatter stripped, sorted list of POSIX-style paths relative
+ to the skill root for any bundled files). The file list is empty when the skill bundles no extras.
+
+**Raises:**
+
+- KeyError – If no skill with `name` exists.
+
+#### read_skill_file
+
+```python
+read_skill_file(name: str, path: str) -> str | ImageContent | FileContent
+```
+
+Read a file bundled with the named skill.
+
+Implementations should return text files as a `str`, image files as an `ImageContent`, and PDFs as a
+`FileContent`, so a multimodal agent can pass binary assets straight to the model.
+
+**Parameters:**
+
+- **name** (str) – Skill name as returned by `list_skills`.
+- **path** (str) – Path of the file relative to the skill root (e.g. `"reference/forms.md"`).
+
+**Returns:**
+
+- str | ImageContent | FileContent – The file's text content (`str`), an `ImageContent` for images, or a `FileContent` for PDFs.
+
+**Raises:**
+
+- KeyError – If no skill with `name` exists.
+- FileNotFoundError – If the file does not exist within the skill.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this store to a dictionary for use with `from_dict`.
+
+Implement both this method and `from_dict` to make your custom store serializable.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SkillStore
+```
+
+Deserialize a store from a dictionary produced by `to_dict`.
+
+Implement both this method and `to_dict` to make your custom store serializable.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary as produced by `to_dict`.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/token_counters_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/token_counters_api.md
new file mode 100644
index 00000000000..6d8e44b0e59
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/token_counters_api.md
@@ -0,0 +1,317 @@
+---
+title: "Token Counters"
+id: token-counters-api
+description: "Estimate how many tokens a conversation occupies, for features that need a size before sending it to a model."
+slug: "/token-counters-api"
+---
+
+
+## approximate_counter
+
+### ApproximateTokenCounter
+
+Bases: TokenCounter
+
+Estimates tokens from text length using a flat ratio of characters to tokens.
+
+## Usage Example:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.token_counters import ApproximateTokenCounter
+
+counter = ApproximateTokenCounter(chars_per_token=4.0)
+messages = [
+ ChatMessage.from_user("Hello, how are you?"),
+ ChatMessage.from_assistant("I'm good, thank you! How can I assist you today?")
+]
+token_count = counter.count(messages)
+print(f"Estimated token count: {token_count}")
+```
+
+#### __init__
+
+```python
+__init__(
+ chars_per_token: float = 4.0,
+ tokens_per_image: int = 85,
+ tokens_per_file: int = 1000,
+) -> None
+```
+
+Initialize the counter.
+
+**Parameters:**
+
+- **chars_per_token** (float) – How many characters to treat as one token.
+- **tokens_per_image** (int) – Tokens to charge per image, which has no text to measure. The default is what
+ OpenAI charges for a small image; raise it if you send large ones.
+- **tokens_per_file** (int) – Tokens to charge per file. A rough stand-in for a short document, since the real
+ cost depends on the page count; raise it if you send long ones.
+
+**Raises:**
+
+- ValueError – If `chars_per_token` is not positive.
+
+#### count
+
+```python
+count(messages: list[ChatMessage], tools: ToolsType | None = None) -> int
+```
+
+Return the estimated number of tokens the given messages occupy.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The messages to measure.
+- **tools** (ToolsType | None) – Tools whose schemas are sent alongside the messages, and so consume tokens too.
+
+**Returns:**
+
+- int – The estimated token count, or `0` when there is nothing to measure.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the counter.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the counter.
+
+## openai_counter
+
+### OpenAITokenCounter
+
+Bases: TokenCounter
+
+Counts tokens with OpenAI's input token counting API.
+
+Unlike local token counters, this counter sends the input to OpenAI's
+`POST /v1/responses/input_tokens` endpoint. The returned count includes the model-specific formatting used for
+messages and tool schemas, as well as supported non-text content such as images and files.
+
+## Usage Example:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.token_counters import OpenAITokenCounter
+
+counter = OpenAITokenCounter("gpt-5-mini")
+messages = [ChatMessage.from_user("Hello, how are you?")]
+token_count = counter.count(messages)
+print(f"Token count: {token_count}")
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ *,
+ 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
+```
+
+Initialize the counter.
+
+**Parameters:**
+
+- **model** (str) – The model whose tokenization should be used.
+- **api_key** (Secret) – The OpenAI API key. You can set it with the `OPENAI_API_KEY` environment variable or pass it
+ explicitly.
+- **api_base_url** (str | None) – An optional base URL for the OpenAI API.
+- **organization** (str | None) – Your OpenAI organization ID.
+- **timeout** (float | None) – Timeout for OpenAI client calls. If unset, uses `OPENAI_TIMEOUT` or 30 seconds.
+- **max_retries** (int | None) – Maximum retries for OpenAI client calls. If unset, uses `OPENAI_MAX_RETRIES` or 5.
+- **http_client_kwargs** (dict\[str, Any\] | None) – Keyword arguments used to configure the underlying HTTPX client.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the OpenAI client.
+
+#### count
+
+```python
+count(messages: list[ChatMessage], tools: ToolsType | None = None) -> int
+```
+
+Return the exact number of input tokens OpenAI will use for the given messages and tools.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The messages to measure.
+- **tools** (ToolsType | None) – Tools whose schemas are sent alongside the messages, and so consume tokens too.
+
+**Returns:**
+
+- int – The token count, or `0` when there is nothing to measure.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the OpenAI client and its underlying HTTP resources.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the counter.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the counter.
+
+## tiktoken_counter
+
+### TiktokenCounter
+
+Bases: TokenCounter
+
+Counts tokens locally with `tiktoken`, OpenAI's byte-pair encoder.
+
+Counting is an estimate, and two limits are worth knowing before relying on it:
+
+- **It is text-only**, so images and files get the flat `tokens_per_image` / `tokens_per_file` estimate rather
+ than a real count.
+- **It is OpenAI's encoder.** Other providers tokenize differently, so expect the count to drift on them.
+
+## Usage Example:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.token_counters import TiktokenCounter
+
+counter = TiktokenCounter(encoding="o200k_base")
+messages = [
+ ChatMessage.from_user("Hello, how are you?"),
+ ChatMessage.from_assistant("I'm good, thank you! How can I assist you today?")
+]
+token_count = counter.count(messages)
+print(f"Token count: {token_count}")
+```
+
+#### __init__
+
+```python
+__init__(
+ encoding: str = "o200k_base",
+ tokens_per_image: int = 85,
+ tokens_per_file: int = 1000,
+) -> None
+```
+
+Initialize the counter.
+
+**Parameters:**
+
+- **encoding** (str) – The `tiktoken` encoding to count with. The default, `o200k_base`, is what current OpenAI
+ models use.
+- **tokens_per_image** (int) – Tokens to charge per image, which the tokenizer cannot measure. The default is what
+ OpenAI charges for a small image; raise it if you send large ones.
+- **tokens_per_file** (int) – Tokens to charge per file. A rough stand-in for a short document, since the real
+ cost depends on the page count; raise it if you send long ones.
+
+**Raises:**
+
+- ImportError – If `tiktoken` is not installed.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Load the encoder, downloading its vocabulary if it is not already cached.
+
+#### count
+
+```python
+count(messages: list[ChatMessage], tools: ToolsType | None = None) -> int
+```
+
+Return the estimated number of tokens used by the given messages.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The messages to measure.
+- **tools** (ToolsType | None) – Tools whose schemas are sent alongside the messages, and so consume tokens too.
+
+**Returns:**
+
+- int – The estimated token count, or `0` when there is nothing to measure.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the counter.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the counter.
+
+## types/protocol
+
+### TokenCounter
+
+Bases: Protocol
+
+Estimates the number tokens used by a list of messages.
+
+Implement `to_dict` so the counter's settings survive serialization. The default `from_dict` passes them straight
+back to the constructor, which is enough for plain values; override it when `to_dict` emitted something that has to
+be rebuilt first, such as a `Secret` or a nested component.
+
+#### count
+
+```python
+count(messages: list[ChatMessage], tools: ToolsType | None = None) -> int
+```
+
+Return the estimated number of tokens in the given messages.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The messages to measure.
+- **tools** (ToolsType | None) – Tools whose schemas are sent alongside the messages, and so consume tokens too. Pass them to have
+ them counted; leave as None to measure the messages alone.
+
+**Returns:**
+
+- int – The estimated token count.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the counter to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TokenCounter
+```
+
+Deserialize the counter from a dictionary.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/tools_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/tools_api.md
new file mode 100644
index 00000000000..a5ddd4f4e6d
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/tools_api.md
@@ -0,0 +1,1497 @@
+---
+title: "Tools"
+id: tools-api
+description: "Unified abstractions to represent tools across the framework."
+slug: "/tools-api"
+---
+
+
+## agent_tool
+
+### agent_result_to_string
+
+```python
+agent_result_to_string(result: dict[str, Any]) -> str
+```
+
+Default `outputs_to_string` handler
+
+### AgentTool
+
+Bases: ComponentTool
+
+A Tool that wraps a Haystack Agent, allowing it to be used as a tool by another Agent.
+
+AgentTool is a building block for multi-agent systems: an Agent specialized in one task becomes a tool that
+other Agents can delegate to. The calling Agent only sees the final reply, so all the steps the wrapped Agent
+takes stay out of its context. Sensible defaults make this work out of the box: the task is delegated as a
+single user message and comes back as text.
+
+To use AgentTool, you first need a Haystack Agent. Below is an example of creating an AgentTool from an Agent
+that searches the web with a SerperDevWebSearch component from the `serperdev-haystack` integration package
+(`pip install serperdev-haystack`).
+
+## Usage Example:
+
+
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import AgentTool, ComponentTool
+from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
+
+researcher = Agent(
+ chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-mini"),
+ system_prompt="You are a research specialist. Investigate the task and report your findings.",
+ tools=[
+ ComponentTool(
+ component=SerperDevWebSearch(
+ top_k=3,
+ ),
+ name="web_search",
+ description="Search the web for current information on any topic",
+ ),
+ ],
+)
+
+research = AgentTool(
+ agent=researcher,
+ name="research",
+ description="Research a question on the web and report the findings",
+)
+
+coordinator = Agent(
+ chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4"),
+ tools=[research],
+ system_prompt="You coordinate specialists. Delegate research questions, then answer the user.",
+)
+
+result = coordinator.run([ChatMessage.from_user("What are the latest developments in the Haystack framework?")])
+print(result["last_message"].text)
+```
+
+#### __init__
+
+```python
+__init__(
+ agent: Agent,
+ *,
+ name: str,
+ description: str,
+ 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 Agent.
+
+**Parameters:**
+
+- **agent** (Agent) – The Haystack Agent to wrap as a tool.
+- **name** (str) – Name of the tool.
+- **description** (str) – Description of the tool. It should tell the calling LLM what the Agent is specialized in
+ and when to delegate to it.
+- **parameters** (dict\[str, Any\] | None) – A JSON schema defining the parameters expected by the Tool.
+ Will fall back to a schema with the task to delegate as a single user message, plus one string parameter
+ for every other mandatory input of the Agent, 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 the text of the Agent's final reply, or the serialized message if
+ the reply has no text. A warning is appended if the Agent stopped because it reached `max_agent_steps`,
+ reached the model's output limit, or had its response stopped by a content filter.
+
+`outputs_to_string` supports two formats:
+
+1. Single output format - use "source", "handler", and/or "raw_result" at the root level:
+
+ ```python
+ {
+ "source": "last_message", "handler": format_reply, "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 `handler`
+ is required, since the Agent returns a dictionary, and it must return a list of
+ `TextContent`/`ImageContent` objects to ensure compatibility with Chat Generators.
+
+1. Multiple output format - map keys to individual configurations:
+
+ ```python
+ {
+ "reply": {"source": "last_message", "handler": format_reply},
+ "steps": {"source": "step_count", "handler": str}
+ }
+ ```
+
+ 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 the calling Agent's state keys to Agent input names.
+ Example: `{"subject": "topic"}` maps state's "subject" to the Agent's "topic" input.
+ Inputs mapped this way are not added to the generated `parameters` schema, since the calling Agent
+ provides them.
+- **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.
+ The keys must be declared in the `state_schema` of the calling Agent.
+ Handlers merge the tool output into the state and are called as `handler(current_value, tool_output)`.
+ If the source is provided only the specified output key is sent to the handler.
+ Example:
+
+```python
+{
+ "notes": {"source": "last_message", "handler": custom_handler}
+}
+```
+
+If the source is omitted the whole tool result is sent to the handler.
+Example:
+
+```python
+{
+ "notes": {"handler": custom_handler}
+}
+```
+
+**Raises:**
+
+- TypeError – If the object passed is not a Haystack Agent instance.
+- ValueError – If `parameters` is provided but does not cover all the mandatory inputs of the Agent.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the AgentTool to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized dictionary representation of AgentTool.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AgentTool
+```
+
+Deserializes the AgentTool from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of AgentTool.
+
+**Returns:**
+
+- AgentTool – The deserialized AgentTool instance.
+
+## 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
+from the `serperdev-haystack` integration package (`pip install serperdev-haystack`).
+
+## Usage Example:
+
+
+
+```python
+from haystack import component
+from haystack.tools import ComponentTool
+from haystack.utils import Secret
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
+
+# 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 an Agent with an OpenAIChatGenerator and the tool
+agent = Agent(chat_generator=OpenAIChatGenerator(), tools=[tool])
+
+message = ChatMessage.from_user("Use the web search tool to find information about Nikola Tesla")
+
+# Run the Agent
+result = agent.run(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. May be either a regular function (assigned to the
+ resulting Tool's `function` field) or a coroutine function defined with `async def` (assigned
+ to `async_function`).
+ 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 import OpenAITextEmbedder, OpenAIDocumentEmbedder
+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 = OpenAIDocumentEmbedder()
+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", OpenAITextEmbedder())
+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,
+ *,
+ 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) – 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 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 SearchableToolset, tool
+
+@tool
+def get_weather(city: Annotated[str, "The city to get the weather for"]) -> str:
+ '''Get the current weather for a city.'''
+ return f"The weather in {city} is 22°C and sunny."
+
+@tool
+def search_web(query: Annotated[str, "The query to search the web for"]) -> str:
+ '''Search the web for a query.'''
+ return f"Top result for '{query}': ..."
+
+@tool
+def convert_currency(
+ amount: Annotated[float, "The amount to convert"],
+ to_currency: Annotated[str, "The currency to convert to, e.g. 'EUR'"],
+) -> str:
+ '''Convert an amount in USD to another currency.'''
+ return f"{amount} USD is {amount * 0.9} {to_currency}"
+
+# search_threshold=2 means a catalog of 2+ tools activates discovery: the agent only sees the
+# `search_tools` tool and must search to load the others (set it higher for larger catalogs).
+toolset = SearchableToolset(catalog=[get_weather, search_web, convert_currency], search_threshold=2)
+
+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?")])
+print(result["last_message"].text)
+```
+
+#### __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) -> None
+```
+
+Adding new tools after initialization is not supported for SearchableToolset.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Prepare the toolset for use.
+
+Warms up the catalog (so lazy toolsets like MCPToolset can connect) and flattens it. Above the passthrough
+threshold, it also indexes the catalog and creates the search_tools bootstrap tool.
+
+This method is idempotent: it only warms up the toolset the first time it is called.
+
+**Raises:**
+
+- ValueError – If the flattened catalog contains tools with duplicate names.
+
+#### get_selectable_tools
+
+```python
+get_selectable_tools() -> list[Tool]
+```
+
+Return the full catalog of tools that can be selected by name.
+
+Iteration only exposes the search tool plus already-discovered tools, but name-based selection can target
+any tool in the catalog, so this returns the entire flattened catalog (warming up first if needed).
+
+**Returns:**
+
+- list\[Tool\] – The flattened catalog of tools.
+
+#### 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.
+
+#### spawn
+
+```python
+spawn(selected_tool_names: set[str] | None = None) -> SearchableToolset
+```
+
+Return an isolated copy for a single run, carrying the given name selection.
+
+The copy shares the read-only catalog and BM25 index but gets fresh discovered tools and name selection,
+plus a bootstrap search tool bound to the copy; the selection scopes both iteration and search. This way
+concurrent runs sharing the same configured SearchableToolset don't share discovered tools or collide on
+the active selection.
+
+**Parameters:**
+
+- **selected_tool_names** (set\[str\] | None) – Optional catalog tool names this run is restricted to. None means no
+ restriction.
+
+**Returns:**
+
+- SearchableToolset – A run-scoped copy of this SearchableToolset.
+
+#### 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.
+
+**Raises:**
+
+- TypeError – If a serialized catalog entry is not a subclass of Tool or Toolset.
+
+## skills/skill_toolset
+
+### SkillToolset
+
+Bases: Toolset
+
+A Toolset that lets an Agent discover and read skills via progressive disclosure.
+
+A skill is a directory (or equivalent storage unit) containing a `SKILL.md` file with YAML frontmatter
+(`name` and `description`) and a markdown body of instructions. Skills may bundle additional files
+(reference docs, examples, templates).
+
+- On `warm_up`, the name and description of every discovered skill are baked into the `load_skill` tool
+ description so the model knows which skills exist without any system prompt injection.
+- `load_skill` returns a skill's full instructions on demand, plus a manifest of its bundled files.
+- `read_skill_file` reads a bundled file on demand.
+
+### 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 SkillToolset
+from haystack.skill_stores.file_system import FileSystemSkillStore
+
+store = FileSystemSkillStore("skills/")
+skills_toolset = SkillToolset(store)
+agent = Agent(chat_generator=OpenAIChatGenerator(), tools=skills_toolset)
+result = agent.run(messages=[ChatMessage.from_user("Fill in this PDF form for me.")])
+```
+
+Expected filesystem layout:
+
+```
+skills/
+ pdf-forms/
+ SKILL.md # frontmatter (name, description) + markdown instructions
+ reference/forms.md
+```
+
+The tool names `load_skill` and `read_skill_file` are fixed, so an `Agent` can use at most one
+`SkillToolset`. To serve skills from multiple sources, back a single toolset with a custom store that
+merges them.
+
+#### __init__
+
+```python
+__init__(store: SkillStore) -> None
+```
+
+Initialize the SkillToolset.
+
+Constructing the toolset does not read any skills. The store is queried for the available skills on
+`warm_up()`, so stores that do I/O (reading a directory, connecting to a database) stay cheap to
+construct.
+
+The `load_skill` and `read_skill_file` tools are created right away, so the toolset can be used as a
+collection (length, membership checks, iteration) immediately.
+
+**Parameters:**
+
+- **store** (SkillStore) – A `haystack.skill_stores.types.SkillStore` instance to back this toolset.
+
+#### skills
+
+```python
+skills: dict[str, SkillInfo]
+```
+
+Mapping of skill name to its metadata. Triggers `warm_up()` on first access if not already warmed up.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Discover the available skills from the store and bake the catalog into the `load_skill` description.
+
+Only the description content is dynamic, so the (static) tools created in `__init__` are reused; this
+refreshes `load_skill`'s description once the catalog is known. Idempotent: repeated calls after the
+first are no-ops.
+
+#### add
+
+```python
+add(tool: Tool) -> None
+```
+
+Adding tools is not supported: a SkillToolset's tools are fixed and defined by its store.
+
+#### 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]) -> SkillToolset
+```
+
+Deserialize a toolset from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary representation of the toolset, as produced by `to_dict`.
+
+**Returns:**
+
+- SkillToolset – A new SkillToolset 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 | None) – The synchronous function invoked by `Tool.invoke`. Must be a regular function — coroutine functions should
+ be passed to `async_function` instead. Either `function` or `async_function` (or both) must be set.
+- **async_function** (Callable | None) – Optional coroutine function awaited by `Tool.invoke_async`. When only `async_function` is set, `invoke` raises
+ a `ToolInvocationError`. When only `function` is set, `invoke_async` falls back to running `function` in a
+ worker thread via `asyncio.to_thread`.
+- **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 neither `function` nor `async_function` is provided, if `function` is a
+ coroutine function, if `async_function` is not a coroutine function, 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 synchronously with the provided keyword arguments.
+
+**Raises:**
+
+- ToolInvocationError – If the Tool has no sync `function`, or if the underlying call
+ raises an exception.
+
+#### invoke_async
+
+```python
+invoke_async(**kwargs: Any) -> Any
+```
+
+Invoke the Tool asynchronously with the provided keyword arguments.
+
+If `async_function` is set, it is awaited directly. Otherwise the sync `function` is dispatched to a worker
+thread via `asyncio.to_thread`, which propagates the current context to the worker.
+
+**Raises:**
+
+- ToolInvocationError – If the underlying call raises an exception.
+
+#### 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 typing import Annotated
+from haystack.tools import tool, Toolset
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+# Create tools with the @tool decorator (the recommended way)
+@tool
+def add(a: Annotated[int, "first number"], b: Annotated[int, "second number"]) -> int:
+ '''Add two numbers.'''
+ return a + b
+
+@tool
+def subtract(a: Annotated[int, "first number"], b: Annotated[int, "second number"]) -> int:
+ '''Subtract b from a.'''
+ return a - b
+
+# Create a toolset with the math tools
+math_toolset = Toolset([add, subtract])
+
+# Use the toolset with an Agent
+agent = Agent(chat_generator=OpenAIChatGenerator(), 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.
+
+ When implementing a custom Toolset subclass for dynamic tool loading:
+
+ - Load the tools in `warm_up()` and assign them to `self.tools`. Since `warm_up()` may be called before
+ every run, make it idempotent by guarding on your own state (e.g. `if self._client is not None: return`).
+ - Override `to_dict()` and `from_dict()` to serialize the endpoint descriptor (URL, server info) rather than
+ the dynamically loaded Tool instances.
+
+ Example:
+
+```python
+from haystack.core.serialization import generate_qualified_class_name
+from haystack.tools import Toolset
+
+class RemoteServiceToolset(Toolset):
+ def __init__(self, endpoint: str) -> None:
+ self.endpoint = endpoint
+ self._client = None
+ super().__init__(tools=[]) # tools are loaded on warm_up()
+
+ def warm_up(self) -> None:
+ if self._client is not None:
+ return
+ self._client = connect(self.endpoint)
+ self.tools = self._client.fetch_tools()
+
+ def to_dict(self):
+ return {
+ "type": generate_qualified_class_name(type(self)),
+ "data": {"endpoint": self.endpoint},
+ }
+
+ @classmethod
+ def from_dict(cls, data):
+ return cls(endpoint=data["data"]["endpoint"])
+```
+
+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 Agent or Haystack
+chat generators.
+
+#### get_selectable_tools
+
+```python
+get_selectable_tools() -> list[Tool]
+```
+
+Return the tools available for name-based selection (e.g. via `Agent.run(tools=["tool_name"])`).
+
+Warms up the Toolset first, so lazily loaded tools are selectable too. Subclasses whose iteration does
+not surface every selectable tool (e.g. SearchableToolset) override this to return the full set.
+
+**Returns:**
+
+- list\[Tool\] – The list of tools available for name-based selection.
+
+#### spawn
+
+```python
+spawn(selected_tool_names: set[str] | None = None) -> Toolset
+```
+
+Return this Toolset, or an isolated copy of it, for a single run.
+
+A plain Toolset has no run-scoped state, so the default implementation returns `self` and ignores the
+selection (the Agent materializes it). Subclasses with run-scoped state (e.g. SearchableToolset) override
+this to return a copy carrying the selection, so concurrent runs sharing the same configured Toolset
+don't corrupt each other.
+
+**Parameters:**
+
+- **selected_tool_names** (set\[str\] | None) – Optional tool names this run is restricted to. None means no restriction.
+
+**Returns:**
+
+- Toolset – This Toolset, or a run-scoped copy of it.
+
+#### 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
+- Loading tools dynamically from an external source and assigning them to `self.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 and load the tools through it:
+
+```python
+class MCPToolset(Toolset):
+ def warm_up(self) -> None:
+ if self.mcp_connection is not None:
+ return
+ self.mcp_connection = establish_connection(self.server_url)
+ self.tools = self.mcp_connection.fetch_tools()
+```
+
+This method may be called multiple times (e.g. before every run): implementations are responsible for
+their own idempotence, guarding on their own state as in the example above. The default implementation delegates
+to the tools' own idempotent `warm_up()`.
+
+#### add
+
+```python
+add(tool: Tool) -> None
+```
+
+Add a new Tool to this Toolset.
+
+**Parameters:**
+
+- **tool** (Tool) – A Tool instance to add
+
+**Raises:**
+
+- ValueError – If adding the tool would result in duplicate tool names
+- TypeError – If the provided object is not a Tool
+
+#### 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-3.2-unstable/haystack-api/utils_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/utils_api.md
new file mode 100644
index 00000000000..17312698da7
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/utils_api.md
@@ -0,0 +1,1120 @@
+---
+title: "Utils"
+id: utils-api
+description: "Utility functions and classes used across the library."
+slug: "/utils-api"
+---
+
+
+## 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.chat import OpenAIChatGenerator
+from haystack.utils import Secret
+
+generator = OpenAIChatGenerator(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 an Azure AD token using the DefaultAzureCredential and the "https://cognitiveservices.azure.com/.default" scope.
+
+## base_serialization
+
+## 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.
+
+Every module path tried during resolution is checked against the
+deserialization allowlist (see `haystack.core.serialization_security`). Callables in modules
+outside the allowlist are rejected with a `DeserializationError` before any import is
+attempted. To allow a third-party module, extend the allowlist via
+`Pipeline.load(..., allowed_modules=[...])`, `allow_deserialization_module(...)`, or the
+`HAYSTACK_DESERIALIZATION_ALLOWLIST` environment variable.
+
+**Parameters:**
+
+- **callable_handle** (str) – The full path of the callable_handle
+
+**Returns:**
+
+- Callable – The callable
+
+**Raises:**
+
+- DeserializationError – If the module path is not on the deserialization allowlist, or 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 usable device in the device map, if any.
+
+Disk devices are skipped because they can only be used as part of a device map and not as a
+single device. If the device map is empty or contains only disk devices, a `ValueError` is
+raised so callers that do `first_device.to_torch()` still get a clear error instead of
+`AttributeError: 'NoneType' object has no attribute 'to_torch'`.
+
+**Returns:**
+
+- Optional\[ComponentDevice\] – The first usable 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
+
+### document_matches_filter
+
+```python
+document_matches_filter(
+ filters: dict[str, Any],
+ document: Document | ByteStream,
+ *,
+ strict_datetime_comparison: bool = False
+) -> 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.
+
+**Parameters:**
+
+- **strict_datetime_comparison** (bool) – If `True`, timezone-naive and timezone-aware datetimes never match each other.
+ If `False` (the default), the timezone from the aware datetime is copied to the naive one before comparing.
+
+## 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 %}
+```
+
+This extension also provides an `{% insert %}` placeholder tag that evaluates an expression to a `ChatMessage`
+or a list of `ChatMessage` objects and expands it into the prompt, so a runtime conversation can be interleaved
+with literal `{% message %}` blocks:
+
+```
+{% message role="system" %}You are a helpful assistant.{% endmessage %}
+{% insert messages %}
+{% message role="user" %}{{ query }}{% endmessage %}
+```
+
+The expression can be a plain variable (`{% insert messages %}`), a slice or index
+(`{% insert messages[-1:] %}`, `{% insert messages[-1] %}`), or a combination of variables
+(`{% insert previous + current %}`).
+
+### 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 configuration
+
+### templatize_part
+
+```python
+templatize_part(
+ environment: Any, value: ChatMessageContentT
+) -> _TemplatizedPart
+```
+
+Jinja filter to convert a ChatMessageContentT object into a JSON string wrapped in sentinel content tags.
+
+**Parameters:**
+
+- **environment** (Any) – The Jinja2 environment
+- **value** (ChatMessageContentT) – The ChatMessageContentT object to convert
+
+**Returns:**
+
+- \_TemplatizedPart – A `_TemplatizedPart` holding a JSON string wrapped in special XML content tags
+
+**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
+
+**Raises:**
+
+- ValueError – If any element is not a valid integer or a range string in the format `'start-end'`.
+
+### 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]]`.
+
+Every module path with a `.` prefix is checked against the deserialization
+allowlist (see `haystack.core.serialization_security`) before being imported. Modules outside
+the allowlist are rejected with a `DeserializationError`. Builtin and `typing`/`collections`
+names without a module prefix bypass this check.
+
+**Parameters:**
+
+- **type_str** (str) – The string representation of the type's full import path.
+
+**Returns:**
+
+- Any – The deserialized type object.
+
+**Raises:**
+
+- DeserializationError – If the module is not on the deserialization allowlist, or if the type cannot be
+ deserialized due to a 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-3.2-unstable/haystack-api/validators_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/haystack-api/validators_api.md
new file mode 100644
index 00000000000..e89fc78087f
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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 the last message has no text content, or if no JSON schema is provided either in
+ the `run` method or in the component init.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/index.mdx b/docs-website/reference_versioned_docs/version-3.2-unstable/index.mdx
new file mode 100644
index 00000000000..203df45bd6d
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/index.mdx
@@ -0,0 +1,17 @@
+---
+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, `DocumentStore) – The document store the metadata inspection tools and the `fetch_documents_by_filter` tool
+ run against.
+- **retriever** (TextRetriever | Pipeline | None) – What retrieves for the `search_documents` tool (required). Either a standalone retriever
+ component following the `TextRetriever` protocol, i.e. its `run` method accepts `query` and `filters`
+ (e.g. `InMemoryBM25Retriever`, or an embedding retriever wrapped in `TextEmbeddingRetriever`), or a custom
+ retrieval `Pipeline` (e.g. embedder -> retriever, or hybrid retrieval) — a pipeline additionally requires
+ `retrieval_pipeline_input_mapping`. It should retrieve by relevance scoring (keyword or embedding-based) —
+ direct, unscored fetching is already covered by the built-in `fetch_documents_by_filter` tool.
+- **retrieval_pipeline_input_mapping** (dict\[str, list\[str\]\] | None) – Required when `retriever` is a `Pipeline`: maps the tool inputs to
+ pipeline input sockets; must have exactly the keys "query" and "filters",
+ e.g. `{"query": ["embedder.text"], "filters": ["retriever.filters"]}`.
+- **retrieval_pipeline_output_mapping** (dict\[str, str\] | None) – Optional when `retriever` is a `Pipeline`: maps pipeline output sockets
+ to tool outputs, e.g. `{"retriever.documents": "documents"}`.
+- **llm** (ChatGenerator | None) – LLM that drives the agent loop. Defaults to `OpenAIResponsesChatGenerator("gpt-5.4")` with low
+ reasoning effort.
+- **backup_answer_llm** (ChatGenerator | None) – LLM the built-in `BackupAnswerHook` uses to write a best-effort answer when the run
+ is cut off by `max_agent_steps`. Defaults to a separate `OpenAIResponsesChatGenerator("gpt-5.4")` with low
+ reasoning effort.
+- **system_prompt** (str | None) – Overrides the pre-made system prompt.
+- **max_agent_steps** (int) – Maximum steps for the agent loop. If the loop is cut off by this limit before writing an
+ answer, an `after_run` hook (`BackupAnswerHook`) makes one extra LLM call to produce a best-effort answer from
+ the evidence gathered so far, so `last_message` always carries a text answer.
+- **max_fetched_docs** (int) – Maximum number of documents `fetch_documents_by_filter` shows per fetch. A filter fetch is
+ not bounded by a retriever's `top_k`, so this caps the tool result instead; the scored `search_documents` tool
+ is bounded by the `top_k` configured on your retrieval components.
+
+**Returns:**
+
+- Agent – The advanced RAG `Agent`. Call it with the question as a user message,
+ `agent.run(messages=[ChatMessage.from_user(question)])`; the answer is in `last_message` (a `ChatMessage`) and
+ `documents` carries every document the agent retrieved during the run (deduplicated by id, in first-retrieved
+ order) — the answer cites them by the first 8 characters of their id, e.g. `[doc a1b2c3d4]`. The standard Agent
+ outputs `messages`, `step_count`, `token_usage` and `tool_call_counts` are also returned.
+
+## haystack_integrations.agent_pack.advanced_rag.hooks
+
+### BackupAnswerHook
+
+Produce a final answer when the agent run ends without one. Runs as an `after_run` hook.
+
+When the agent exhausts `max_agent_steps` mid-investigation, the run ends on a tool call or tool result instead of
+an assistant text answer (and only `after_run` hooks run in this situation). This hook detects that case and makes
+one LLM call over the conversation so far to produce a best-effort answer from the already-gathered evidence.
+
+#### __init__
+
+```python
+__init__(chat_generator: ChatGenerator) -> None
+```
+
+Create the hook.
+
+**Parameters:**
+
+- **chat_generator** (ChatGenerator) – LLM that writes the backup answer from the gathered evidence.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Prepare the hook's generator for use; called from the Agent's `warm_up`.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the hook's generator resources; called from the Agent's `close`.
+
+#### to_dict
+
+```python
+to_dict() -> dict
+```
+
+Serialize the hook to a dictionary.
+
+**Returns:**
+
+- dict – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict) -> BackupAnswerHook
+```
+
+Deserialize the hook from a dictionary.
+
+**Parameters:**
+
+- **data** (dict) – Dictionary to deserialize from.
+
+**Returns:**
+
+- BackupAnswerHook – Deserialized hook.
+
+#### run
+
+```python
+run(state: State) -> None
+```
+
+Append a best-effort final answer when the run ended without one (e.g. step exhaustion).
+
+**Parameters:**
+
+- **state** (State) – The agent run's state.
+
+## haystack_integrations.agent_pack.advanced_rag.tools
+
+### ListMetadataFieldsTool
+
+Bases: Tool
+
+Tool that lists all metadata fields and their types from a document store.
+
+#### __init__
+
+```python
+__init__(document_store: DocumentStore) -> None
+```
+
+Create the tool.
+
+**Parameters:**
+
+- **document_store** (DocumentStore) – The document store to inspect. Must implement `get_metadata_fields_info`.
+
+**Raises:**
+
+- ValueError – If the store does not implement `get_metadata_fields_info`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ListMetadataFieldsTool
+```
+
+Deserialize the tool from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary produced by `to_dict`.
+
+**Returns:**
+
+- ListMetadataFieldsTool – The deserialized tool.
+
+### GetMetadataFieldValuesTool
+
+Bases: Tool
+
+Tool that returns the distinct values of a metadata field from a document store.
+
+#### __init__
+
+```python
+__init__(document_store: DocumentStore) -> None
+```
+
+Create the tool.
+
+**Parameters:**
+
+- **document_store** (DocumentStore) – The document store to inspect. Must implement `get_metadata_field_unique_values`.
+
+**Raises:**
+
+- ValueError – If the store does not implement `get_metadata_field_unique_values`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GetMetadataFieldValuesTool
+```
+
+Deserialize the tool from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary produced by `to_dict`.
+
+**Returns:**
+
+- GetMetadataFieldValuesTool – The deserialized tool.
+
+### GetMetadataFieldRangeTool
+
+Bases: Tool
+
+Tool that returns the minimum and maximum values of a metadata field from a document store.
+
+#### __init__
+
+```python
+__init__(document_store: DocumentStore) -> None
+```
+
+Create the tool.
+
+**Parameters:**
+
+- **document_store** (DocumentStore) – The document store to inspect. Must implement `get_metadata_field_min_max`.
+
+**Raises:**
+
+- ValueError – If the store does not implement `get_metadata_field_min_max`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GetMetadataFieldRangeTool
+```
+
+Deserialize the tool from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary produced by `to_dict`.
+
+**Returns:**
+
+- GetMetadataFieldRangeTool – The deserialized tool.
+
+### FetchDocumentsByFilterTool
+
+Bases: Tool
+
+Tool that fetches documents directly from a document store by metadata filter.
+
+Unlike a scored retrieval tool, this fetches without any relevance ranking, so an agent can grab specific documents
+(e.g. a known title or source file) without going through a relevance search. The fetched documents are put into
+reading order first: grouped by their parent file (`file_name`/`file_path`/`source_id`) and sorted by their
+position within it (`split_id`/`split_idx_start`/`page_number`), using whichever of those metadata fields the
+documents carry. Match sets larger than `max_docs` are paged: each call returns one page plus the total match
+count, and the tool's `offset` input continues where the previous page ended.
+
+#### __init__
+
+```python
+__init__(
+ document_store: DocumentStore,
+ max_docs: int = 10,
+ max_fetch_factor: int = 10,
+) -> None
+```
+
+Create the tool.
+
+**Parameters:**
+
+- **document_store** (DocumentStore) – The document store to fetch documents from.
+- **max_docs** (int) – Ceiling on the number of documents shown to the agent per fetch. Unlike scored retrieval, a
+ filter fetch is not bounded by a retriever's `top_k`, so this caps the tool result instead. The LLM can
+ request fewer via the tool's optional `max_docs` input, but never more.
+- **max_fetch_factor** (int) – How many times the `max_docs` ceiling a filter may match before the fetch is
+ refused outright (when the store supports `count_documents_by_filter`) — the refusal is surfaced to the
+ LLM as an error it can recover from by narrowing the filter.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FetchDocumentsByFilterTool
+```
+
+Deserialize the tool from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary produced by `to_dict`.
+
+**Returns:**
+
+- FetchDocumentsByFilterTool – The deserialized tool.
+
+### DocumentStoreToolset
+
+Bases: Toolset
+
+All document-store-backed tools as one unit.
+
+Bundles the three metadata inspection tools (`ListMetadataFieldsTool`, `GetMetadataFieldValuesTool`,
+`GetMetadataFieldRangeTool`) and the direct `FetchDocumentsByFilterTool`, so they can be handed to an `Agent`
+(or combined with a retrieval tool) as a single object.
+
+#### __init__
+
+```python
+__init__(document_store: DocumentStore, max_fetched_docs: int = 10) -> None
+```
+
+Create the toolset.
+
+**Parameters:**
+
+- **document_store** (DocumentStore) – The document store all tools run against. Must implement the metadata introspection
+ methods (`get_metadata_fields_info`, `get_metadata_field_unique_values`, `get_metadata_field_min_max`).
+- **max_fetched_docs** (int) – Maximum number of documents `fetch_documents_by_filter` shows per fetch (see
+ `FetchDocumentsByFilterTool.max_docs`).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the toolset to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DocumentStoreToolset
+```
+
+Deserialize the toolset from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary produced by `to_dict`.
+
+**Returns:**
+
+- DocumentStoreToolset – The deserialized toolset.
+
+## haystack_integrations.agent_pack.deep_research.agent
+
+### create_deep_research_agent
+
+```python
+create_deep_research_agent(
+ *,
+ llm: ChatGenerator | None = None,
+ system_prompt: str | None = None,
+ max_agent_steps: int = 8,
+ brief_llm: ChatGenerator | None = None,
+ researcher_llm: ChatGenerator | None = None,
+ search_tool: Tool | None = None,
+ page_summary_llm: ChatGenerator | None = None,
+ report_llm: ChatGenerator | None = None,
+ max_researcher_steps: int = 20,
+ max_concurrent_researchers: int = 5,
+ max_subtopics: int = 5,
+ max_page_chars: int = 50000
+) -> Agent
+```
+
+Create the deep research agent.
+
+To customize the returned agent further (e.g. add tools or hooks), use `Agent.clone`:
+`agent = agent.clone(tools=[*agent.tools, my_tool])`.
+
+**Parameters:**
+
+- **llm** (ChatGenerator | None) – LLM that plans the investigation and delegates the sub-questions.
+ Defaults to `OpenAIResponsesChatGenerator("gpt-5.4")`.
+- **system_prompt** (str | None) – Overrides the pre-made system prompt. `{{ max_subtopics }}` is replaced with the value of
+ `max_subtopics`.
+- **max_agent_steps** (int) – Maximum steps for the agent loop (reflect -> delegate rounds).
+- **brief_llm** (ChatGenerator | None) – LLM that rewrites the user query into a focused research brief.
+ Defaults to `OpenAIResponsesChatGenerator("gpt-5.4")`.
+- **researcher_llm** (ChatGenerator | None) – LLM that drives each sub-researcher's search/read/think loop.
+ Defaults to `OpenAIResponsesChatGenerator("gpt-5.4-mini")`.
+- **search_tool** (Tool | None) – Web search tool used by each sub-researcher. Defaults to `TavilyWebSearchTool(top_k=10)`,
+ which requires `tavily-haystack`. The pre-made researcher prompt refers to the tool as `web_search`.
+- **page_summary_llm** (ChatGenerator | None) – LLM used inside the `read_url` tool to summarize a fetched page toward
+ the question. Defaults to `OpenAIResponsesChatGenerator("gpt-5.4-mini")`.
+- **report_llm** (ChatGenerator | None) – LLM that turns the brief plus collected notes into the final report.
+ Defaults to `OpenAIResponsesChatGenerator("gpt-5.4")`.
+- **max_researcher_steps** (int) – Maximum steps for each sub-researcher's agent loop.
+- **max_concurrent_researchers** (int) – Maximum number of sub-researchers that run at the same time.
+- **max_subtopics** (int) – Maximum number of sub-questions the agent may delegate (breadth).
+- **max_page_chars** (int) – Maximum raw page characters fed to the summarizer, before summarization.
+
+**Returns:**
+
+- Agent – The deep research `Agent`. Call it with the question as a user message,
+ `agent.run(messages=[ChatMessage.from_user(question)])`; it returns a dict whose main output is
+ `report` (the final markdown report, a `str`). The dict also carries the intermediate `brief`
+ (`str`) and `notes` (`list[str]`), plus the standard Agent outputs `messages`, `last_message`,
+ `step_count`, `token_usage` and `tool_call_counts`.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/aimlapi.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/aimlapi.md
new file mode 100644
index 00000000000..db443de40e8
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/aimlapi.md
@@ -0,0 +1,118 @@
+---
+title: "AIMLAPI"
+id: integrations-aimlapi
+description: "AIMLAPI integration for Haystack"
+slug: "/integrations-aimlapi"
+---
+
+
+## haystack_integrations.components.generators.aimlapi.chat.chat_generator
+
+### AIMLAPIChatGenerator
+
+Bases: OpenAIChatGenerator
+
+Enables text generation using AIMLAPI generative models.
+
+For supported models, see AIMLAPI documentation.
+
+Users can pass any text generation parameters valid for the AIMLAPI 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 AIMLAPI chat completion endpoint.
+- **Streaming Support**: Supports streaming responses from the AIMLAPI chat completion endpoint.
+- **Customizability**: Supports all parameters supported by the AIMLAPI 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 AIMLAPI API, refer to the
+AIMLAPI documentation.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.aimlapi import AIMLAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = AIMLAPIChatGenerator(model="openai/gpt-5-chat-latest")
+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=Secret) – The AIMLAPI API key.
+- **model** (str) – The name of the AIMLAPI 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 AIMLAPI API Base url.
+ For more details, see AIMLAPI documentation.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the AIMLAPI endpoint. See AIMLAPI API docs 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.
+- **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 AIMLAPI API call.
+- **extra_headers** (dict\[str, Any\] | None) – Additional HTTP headers to include in requests to the AIMLAPI API.
+- **max_retries** (int | None) – Maximum number of retries to contact AIMLAPI after an internal error.
+ If not set, it defaults to either the `AIMLAPI_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-3.2-unstable/integrations-api/alloydb.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/alloydb.md
new file mode 100644
index 00000000000..39a02f5a088
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/alloydb.md
@@ -0,0 +1,623 @@
+---
+title: "AlloyDB"
+id: integrations-alloydb
+description: "AlloyDB integration for Haystack"
+slug: "/integrations-alloydb"
+---
+
+
+## haystack_integrations.components.retrievers.alloydb.embedding_retriever
+
+### AlloyDBEmbeddingRetriever
+
+Retrieves documents from the `AlloyDBDocumentStore` by embedding similarity.
+
+Must be connected to the `AlloyDBDocumentStore`.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: AlloyDBDocumentStore,
+ 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
+```
+
+Create the `AlloyDBEmbeddingRetriever` 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.
+- **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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+## 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+## 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
+```
+
+Release the associated synchronous resources.
+
+#### 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(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Returns unique values for a given metadata field, optionally restricted by filters and/or a search term.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name (with or without the "meta." prefix).
+- **search_term** (str | None) – Optional search term to filter unique values by a case-insensitive substring
+ match against the metadata field's own value. If None, all values are considered.
+- **from\_** (int) – The offset for pagination (0-based).
+- **size** (int) – The number of unique values to return.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing:
+- A list of unique values in their original type
+- The total count of unique values
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/amazon_bedrock.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/amazon_bedrock.md
new file mode 100644
index 00000000000..5a7c4eb42e8
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/amazon_bedrock.md
@@ -0,0 +1,1673 @@
+---
+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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the S3 client owned by this storage instance.
+
+#### 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 | str | 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 | str | 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.
+ Downloads are confined to this directory: a document whose file name resolves outside of it
+ (for example an absolute path or one containing `..`) is logged and skipped instead of written.
+- **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, relative to `file_root_path`.
+ 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.
+- AWSConfigurationError – If the provided AWS credentials are invalid.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the component by initializing the settings and storage.
+
+**Raises:**
+
+- ValueError – If the environment variable naming the S3 bucket (`s3_bucket_name_env`, by default
+ `S3_DOWNLOADER_BUCKET`) is not set.
+- S3ConfigurationError – If the S3 client cannot be created.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the owned S3 client.
+
+#### 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']`. Documents whose file name
+ is missing, or resolves outside of `file_root_path`, are logged and skipped.
+
+**Raises:**
+
+- S3Error – If a download attempt fails or the file does not exist in the S3 bucket.
+
+#### 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 | str | 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 | str | 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, or `dimensions` and `normalize` for Amazon Titan Text Embeddings V2.
+
+**Raises:**
+
+- ValueError – If the model is not supported.
+- AmazonBedrockConfigurationError – If the AWS environment is not configured correctly.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Amazon Bedrock client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Amazon Bedrock client.
+
+#### 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 | str | 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 | str | 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Amazon Bedrock client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Amazon Bedrock 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]) -> 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 | str | 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 | str | 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, or `dimensions` and `normalize` for Amazon Titan Text Embeddings V2.
+
+**Raises:**
+
+- ValueError – If the model is not supported.
+- AmazonBedrockConfigurationError – If the AWS environment is not configured correctly.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Amazon Bedrock client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Amazon Bedrock client.
+
+#### 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.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 | str | 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,
+ system_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 | str | 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"}`
+
+- **system_cachepoint_config** (dict\[str, str\] | None) – Optional configuration to use prompt caching for system messages.
+ 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Amazon Bedrock client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Amazon Bedrock 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]) -> 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] | str,
+ 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\] | str) – A list of `ChatMessage` objects forming the chat history.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **streaming_callback** (StreamingCallbackT | None) – Optional callback for handling streaming outputs.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional dictionary of generation parameters. These are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only at
+ initialization are kept. 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] | str,
+ 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\] | str) – A list of `ChatMessage` objects forming the chat history.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **streaming_callback** (StreamingCallbackT | None) – Optional callback for handling streaming outputs. Async callbacks are preferred.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional dictionary of generation parameters. These are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only at
+ initialization are kept. 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.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 | str | 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 | str | 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.
+
+**Raises:**
+
+- ValueError – If `model` is empty or if `top_k` is not > 0.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Amazon Bedrock client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Amazon Bedrock 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]) -> 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.
+
+## haystack_integrations.components.retrievers.amazon_bedrock.knowledge_base_retriever
+
+### AmazonBedrockKnowledgeBaseRetriever
+
+Retrieves documents from an Amazon Bedrock Managed Knowledge Base.
+
+Uses AgenticRetrieveStream when available, falling back to the standard Retrieve API otherwise.
+
+Usage example:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.retrievers.amazon_bedrock import AmazonBedrockKnowledgeBaseRetriever
+
+retriever = AmazonBedrockKnowledgeBaseRetriever(
+ knowledge_base_id="ABCDEFGHIJ",
+ aws_region_name=Secret.from_token("eu-central-1"),
+)
+
+result = retriever.run(query="What are the benefits of managed knowledge bases?")
+for doc in result["documents"]:
+ print(doc.content)
+ print(doc.meta["source"])
+ print(doc.score)
+```
+
+AmazonBedrockKnowledgeBaseRetriever 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.
+
+#### __init__
+
+```python
+__init__(
+ knowledge_base_id: str | None = None,
+ 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 | str | None = Secret.from_env_var(
+ "AWS_DEFAULT_REGION", strict=False
+ ),
+ aws_profile_name: Secret | None = Secret.from_env_var(
+ "AWS_PROFILE", strict=False
+ ),
+ number_of_results: int = 5,
+ use_agentic_retrieval: bool | None = None,
+) -> None
+```
+
+Create the AmazonBedrockKnowledgeBaseRetriever component.
+
+**Parameters:**
+
+- **knowledge_base_id** (str | None) – The ID of the Bedrock Knowledge Base. Falls back to the AWS_KNOWLEDGE_BASE_ID
+ environment variable.
+- **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 | str | None) – AWS region name.
+- **aws_profile_name** (Secret | None) – AWS profile name.
+- **number_of_results** (int) – Maximum number of results to return.
+- **use_agentic_retrieval** (bool | None) – If True, try AgenticRetrieveStream before plain Retrieve.
+ Defaults to the USE_AGENTIC_RETRIEVAL environment variable, or True.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Amazon Bedrock client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Amazon Bedrock client.
+
+#### run
+
+```python
+run(query: str, top_k: int | None = None) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the Bedrock Knowledge Base.
+
+**Parameters:**
+
+- **query** (str) – The search query.
+- **top_k** (int | None) – Maximum number of results. Overrides number_of_results if provided.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with a "documents" key containing the retrieved Documents.
+
+**Raises:**
+
+- AmazonBedrockInferenceError – If the retrieval call 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]) -> AmazonBedrockKnowledgeBaseRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- AmazonBedrockKnowledgeBaseRetriever – The deserialized component.
+
+## haystack_integrations.token_counters.amazon_bedrock.token_counter
+
+### AmazonBedrockTokenCounter
+
+Counts tokens with Amazon Bedrock's `CountTokens` API.
+
+Implements Haystack's `TokenCounter` protocol. Unlike local, tokenizer-based counters, this counter sends the
+input to Bedrock's `CountTokens` operation, so the returned count reflects the model's exact tokenization,
+including the formatting Bedrock applies to messages, system prompts, and tool schemas.
+
+The messages and tools are converted to the Bedrock `Converse` format (the same conversion the
+`AmazonBedrockChatGenerator` uses), so the count matches what an equivalent `Converse` request would consume.
+
+Because it delegates to a server-side API, `count()` measures a complete, valid conversation rather than an
+arbitrary set of messages: Bedrock validates the input the same way the `Converse` inference API does (it must
+begin with a user message, and tool results must pair with the tool calls that produced them). This is the right
+fit for sizing a whole request before sending it - its intended use - but it cannot size a stand-alone fragment
+such as a single tool-result message. For fragment-level counting (for example inside a compactor that measures
+individual messages), use a local counter such as `ApproximateTokenCounter`.
+
+## Usage Example:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.token_counters.amazon_bedrock import AmazonBedrockTokenCounter
+
+counter = AmazonBedrockTokenCounter(model="anthropic.claude-3-5-sonnet-20240620-v1:0")
+messages = [ChatMessage.from_user("Hello, how are you?")]
+token_count = counter.count(messages)
+print(f"Token count: {token_count}")
+```
+
+#### __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 | str | 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
+) -> None
+```
+
+Initialize the counter.
+
+**Parameters:**
+
+- **model** (str) – The Bedrock model id (or ARN) whose tokenization should be used, for example
+ `"anthropic.claude-3-5-sonnet-20240620-v1:0"`. Token counts are model-specific.
+- **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 | str | None) – AWS region name. Make sure the region you set supports Amazon Bedrock.
+- **aws_profile_name** (Secret | None) – AWS profile name.
+- **boto3_config** (dict\[str, Any\] | None) – Dictionary of configuration options for the underlying Boto3 client.
+
+**Raises:**
+
+- ValueError – If `model` is empty.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Amazon Bedrock client.
+
+**Raises:**
+
+- AmazonBedrockConfigurationError – If the AWS environment is not configured correctly.
+
+#### count
+
+```python
+count(messages: list[ChatMessage], tools: ToolsType | None = None) -> int
+```
+
+Return the number of input tokens Bedrock will use for the given messages and tools.
+
+`messages` must form a complete, valid conversation: Bedrock validates it the same way the `Converse`
+inference API does (it must begin with a user message, and tool results must pair with their tool calls).
+To size an arbitrary fragment such as a single message, use a local counter like `ApproximateTokenCounter`.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The messages to measure.
+- **tools** (ToolsType | None) – Tools whose schemas are sent alongside the messages, and so consume tokens too. Pass them to
+ have them counted; leave as None to measure the messages alone.
+
+**Returns:**
+
+- int – The token count, or `0` when there is nothing to measure.
+
+**Raises:**
+
+- AmazonBedrockInferenceError – If the Bedrock `CountTokens` request fails.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Amazon Bedrock client and release its resources.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the counter.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the counter.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AmazonBedrockTokenCounter
+```
+
+Deserialize the counter.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – A dictionary representation of the counter.
+
+**Returns:**
+
+- AmazonBedrockTokenCounter – The deserialized counter.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/amazon_sagemaker.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/amazon_sagemaker.md
new file mode 100644
index 00000000000..4e0bdb8322c
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/amazon_sagemaker.md
@@ -0,0 +1,142 @@
+---
+title: "Amazon Sagemaker"
+id: integrations-amazon-sagemaker
+description: "Amazon Sagemaker integration for Haystack"
+slug: "/integrations-amazon-sagemaker"
+---
+
+
+## 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': [{}]}
+```
+
+#### __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
+ ),
+ aws_custom_attributes: dict[str, Any] | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Instantiates the session with SageMaker.
+
+**Parameters:**
+
+- **aws_access_key_id** (Secret | None) – The `Secret` for AWS access key ID.
+- **aws_secret_access_key** (Secret | None) – The `Secret` for AWS secret access key.
+- **aws_session_token** (Secret | None) – The `Secret` for AWS session token.
+- **aws_region_name** (Secret | None) – The `Secret` for AWS region name. If not provided, the default region will be used.
+- **aws_profile_name** (Secret | None) – The `Secret` for AWS profile name. If not provided, the default profile will be used.
+- **model** (str) – The name for SageMaker Model Endpoint.
+- **aws_custom_attributes** (dict\[str, Any\] | None) – Custom attributes to be passed to SageMaker, for example `{"accept_eula": True}`
+ in case of Llama-2 models.
+- **generation_kwargs** (dict\[str, Any\] | None) – 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`.
+
+#### 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]) -> SagemakerGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SagemakerGenerator – Deserialized component.
+
+#### run
+
+```python
+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.
+
+**Parameters:**
+
+- **prompt** (str) – The string prompt to use for text generation.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation.
+ These are merged per key with the `generation_kwargs` passed at initialization: keys provided here
+ take precedence, keys set only at initialization are kept.
+
+**Returns:**
+
+- dict\[str, list\[str\] | list\[dict\[str, Any\]\]\] – 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.
+
+**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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/amazon_textract.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/amazon_textract.md
new file mode 100644
index 00000000000..e6497858bc8
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/amazon_textract.md
@@ -0,0 +1,159 @@
+---
+title: "Amazon Textract"
+id: integrations-amazon_textract
+description: "Amazon Textract integration for Haystack"
+slug: "/integrations-amazon_textract"
+---
+
+
+## haystack_integrations.components.converters.amazon_textract.converter
+
+### AmazonTextractConverter
+
+Converts documents to Haystack Documents using AWS Textract.
+
+This component uses AWS Textract to extract text and optionally structured data
+(tables, forms) from images and single-page PDFs.
+
+When `feature_types` is not set, the component uses `DetectDocumentText` for
+plain text OCR. When `feature_types` is set (e.g. `["TABLES", "FORMS"]`), it
+uses `AnalyzeDocument` for richer structural analysis.
+
+Natural-language queries are also supported via the `queries` parameter on
+`run()`. When queries are provided, the `QUERIES` feature type is added
+automatically and Textract returns answers extracted from the document.
+
+Supported input formats: JPEG, PNG, TIFF, BMP, and single-page PDF (up to 10 MB).
+
+AWS credentials are resolved via `Secret` parameters or the default boto3
+credential chain (environment variables, AWS config files, IAM roles).
+
+### Usage example
+
+```python
+from haystack_integrations.components.converters.amazon_textract import AmazonTextractConverter
+
+converter = AmazonTextractConverter()
+results = converter.run(sources=["document.png"])
+documents = results["documents"]
+```
+
+#### __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
+ ),
+ feature_types: list[str] | None = None,
+ store_full_path: bool = False,
+ boto3_config: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an AmazonTextractConverter component.
+
+**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. Must be a region that supports Textract.
+- **aws_profile_name** (Secret | None) – AWS profile name from the credentials file.
+- **feature_types** (list\[str\] | None) – List of feature types to detect when using AnalyzeDocument.
+ Valid values: "TABLES", "FORMS", "SIGNATURES", "LAYOUT".
+ If None, uses DetectDocumentText for basic text extraction.
+ The "QUERIES" feature type is managed automatically when the
+ `queries` parameter is passed to `run()`.
+- **store_full_path** (bool) – If True, stores the complete file path in Document metadata.
+ If False, stores only the filename (default).
+- **boto3_config** (dict\[str, Any\] | None) – Dictionary of configuration options for the underlying boto3 client.
+ Can be used to tune retry behavior, timeouts, and connection management.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the AWS Textract client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Closes the AWS Textract client.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+ queries: list[str] | None = None,
+) -> dict[str, Any]
+```
+
+Convert documents to Haystack Documents using AWS Textract.
+
+**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 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.
+- **queries** (list\[str\] | None) – Optional list of natural-language questions to ask about each document.
+ When provided, the Textract `QUERIES` feature type is enabled
+ automatically and each question is sent as a query. Answers are
+ included in the raw Textract response. Example:
+ `["What is the patient name?", "What is the total due?"]`
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: List of created Documents with extracted text as content.
+- `raw_textract_response`: List of raw Textract API responses.
+
+#### 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]) -> AmazonTextractConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- AmazonTextractConverter – The deserialized component.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/anthropic.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/anthropic.md
new file mode 100644
index 00000000000..1ddb4641cf8
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/anthropic.md
@@ -0,0 +1,740 @@
+---
+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-fable-5-1",
+ "claude-fable-5",
+ "claude-opus-5",
+ "claude-opus-4-8",
+ "claude-opus-4-7",
+ "claude-opus-4-6",
+ "claude-opus-4-5-20251101",
+ "claude-sonnet-5",
+ "claude-sonnet-4-6",
+ "claude-sonnet-4-5-20250929",
+ "claude-haiku-4-5-20251001",
+]
+
+```
+
+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,
+ anthropic_server_tools: list[dict[str, Any]] | 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. Defaults to 8192. A response that hits
+ this limit is cut off; if the model was writing a tool call at the time, that call is dropped
+ and the reply carries a `length` finish reason.
+- `metadata`: A dictionary of metadata to be passed to the model.
+- `service_tier`: Whether the request may use priority capacity (`auto`) or standard capacity only
+ (`standard_only`). See [service tiers](https://platform.claude.com/docs/en/api/service-tiers).
+- `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.
+- **anthropic_server_tools** (list\[dict\[str, Any\]\] | None) – A list of Anthropic server-side tools passed directly to the API.
+ Use this for native Anthropic tools such as web search (`{"type": "web_search_20250305"}`),
+ code execution tool, or other provider-managed tools. Refer to the
+ [Anthropic documentation](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool)
+ for the exact dict format each native tool expects.
+- **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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Anthropic client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Anthropic client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Anthropic client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous 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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **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. These are merged
+ per key with the `generation_kwargs` passed at initialization: keys provided here take precedence, keys set
+ only at initialization are kept.
+- **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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **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. These are merged
+ per key with the `generation_kwargs` passed at initialization: keys provided here take precedence, keys set
+ only at initialization are kept.
+- **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. Defaults to 8192. A response that hits
+ this limit is cut off; if the model was writing a tool call at the time, that call is dropped
+ and the reply carries a `length` finish reason.
+- `metadata`: A dictionary of metadata to be passed to the model.
+- `service_tier`: Whether the request may use priority capacity (`auto`) or standard capacity only
+ (`standard_only`). See [service tiers](https://platform.claude.com/docs/en/api/service-tiers).
+- `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.
+- **anthropic_server_tools** (list\[dict\[str, Any\]\] | None) – A list of Anthropic server-side tools passed directly to the API.
+ Use this for native Anthropic tools such as web search (`{"type": "web_search_20250305"}`),
+ code execution tool, or other provider-managed tools. Refer to the
+ [Anthropic documentation](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool)
+ for the exact dict format each native tool expects.
+- **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 synchronous Anthropic Foundry client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Anthropic Foundry 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]) -> 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-5@20250929",
+ 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. Defaults to 8192. A response that hits
+ this limit is cut off; if the model was writing a tool call at the time, that call is dropped
+ and the reply carries a `length` finish reason.
+- `metadata`: A dictionary of metadata to be passed to the model.
+- `service_tier`: Whether the request may use priority capacity (`auto`) or standard capacity only
+ (`standard_only`). See [service tiers](https://platform.claude.com/docs/en/api/service-tiers).
+- `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.
+- **anthropic_server_tools** (list\[dict\[str, Any\]\] | None) – A list of Anthropic server-side tools passed directly to the API.
+ On Vertex AI only the basic web search tool (`{"type": "web_search_20250305"}`) is available:
+ web search with dynamic filtering, web fetch and code execution are not supported. Refer to the
+ [Anthropic documentation](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool)
+ for the exact dict format each native tool expects.
+- **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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Anthropic Vertex client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Anthropic Vertex 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.token_counters.anthropic.token_counter
+
+### AnthropicTokenCounter
+
+Counts input tokens for Anthropic models using the Anthropic token counting API.
+
+Uses the `POST /v1/messages/count_tokens` endpoint, which returns an exact token
+count without generating a response or incurring generation costs.
+
+Usage example:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.token_counters.anthropic import AnthropicTokenCounter
+
+counter = AnthropicTokenCounter(model="claude-sonnet-4-5")
+messages = [
+ ChatMessage.from_system("You are a helpful assistant."),
+ ChatMessage.from_user("How many tokens is this?"),
+]
+token_count = counter.count(messages)
+print(token_count)
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ *,
+ api_key: Secret = Secret.from_env_var("ANTHROPIC_API_KEY"),
+ timeout: float | None = None,
+ max_retries: int | None = None
+) -> None
+```
+
+Create an AnthropicTokenCounter.
+
+**Parameters:**
+
+- **model** (str) – The Anthropic model to use for tokenization. Token counts are
+ model-specific; always count against the model you intend to use.
+- **api_key** (Secret) – The Anthropic API key. Defaults to the `ANTHROPIC_API_KEY`
+ environment variable.
+- **timeout** (float | None) – HTTP timeout in seconds for the Anthropic client.
+- **max_retries** (int | None) – Maximum number of retries for failed requests.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Anthropic client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Anthropic client and release its underlying HTTP resources.
+
+#### count
+
+```python
+count(messages: list[ChatMessage], tools: ToolsType | None = None) -> int
+```
+
+Count the tokens for the given messages and optional tools.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The list of ChatMessages to count tokens for.
+- **tools** (ToolsType | None) – Optional list of Tools whose schemas are included in the count.
+
+**Returns:**
+
+- int – The number of input tokens, or `0` when there is nothing to measure.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this token counter to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – The serialized token counter.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnthropicTokenCounter
+```
+
+Deserialize a token counter from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- AnthropicTokenCounter – The deserialized token counter.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/arangodb.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/arangodb.md
new file mode 100644
index 00000000000..2cb16e8d059
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/arangodb.md
@@ -0,0 +1,260 @@
+---
+title: "Arangodb"
+id: integrations-arangodb
+description: "Arangodb integration for Haystack"
+slug: "/integrations-arangodb"
+---
+
+
+## haystack_integrations.components.retrievers.arangodb.embedding_retriever
+
+### ArangoEmbeddingRetriever
+
+Retrieves documents from an `ArangoDocumentStore` using vector similarity on embeddings.
+
+The similarity function is configured on the `ArangoDocumentStore` (cosine, dot product, or L2).
+
+Example usage:
+
+```python
+from haystack_integrations.document_stores.arangodb import ArangoDocumentStore
+from haystack_integrations.components.retrievers.arangodb import ArangoEmbeddingRetriever
+
+store = ArangoDocumentStore(host="http://localhost:8529", database="haystack",
+ username="root", collection_name="docs", embedding_dimension=768)
+retriever = ArangoEmbeddingRetriever(document_store=store, top_k=5)
+result = retriever.run(query_embedding=[0.1, 0.2, ...])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: ArangoDocumentStore,
+ top_k: int = 10,
+ filters: dict[str, Any] | None = None
+) -> None
+```
+
+Creates a new ArangoEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (ArangoDocumentStore) – The `ArangoDocumentStore` to retrieve documents from.
+- **top_k** (int) – Maximum number of documents to return.
+- **filters** (dict\[str, Any\] | None) – Optional Haystack metadata filters applied at retrieval time.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ top_k: int | None = None,
+ filters: dict[str, Any] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieves documents most similar to `query_embedding`.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – The query vector.
+- **top_k** (int | None) – Overrides the instance-level `top_k` for this call.
+- **filters** (dict\[str, Any\] | None) – Overrides the instance-level `filters` for this call.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with `documents` — a list of `Document` objects sorted by score.
+
+#### 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]) -> ArangoEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ArangoEmbeddingRetriever – Deserialized component.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+## haystack_integrations.document_stores.arangodb.document_store
+
+### ArangoDocumentStore
+
+A Haystack DocumentStore backed by [ArangoDB](https://www.arangodb.com/).
+
+Documents are stored in an ArangoDB collection and support vector similarity search
+via AQL vector functions (requires ArangoDB 3.12+).
+
+Example usage:
+
+```python
+from haystack_integrations.document_stores.arangodb import ArangoDocumentStore
+from haystack.utils import Secret
+
+store = ArangoDocumentStore(
+ host="http://localhost:8529",
+ database="haystack",
+ username=Secret.from_env_var("ARANGO_USERNAME", strict=False),
+ password=Secret.from_env_var("ARANGO_PASSWORD"),
+ collection_name="documents",
+ embedding_dimension=768,
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ host: str = "http://localhost:8529",
+ database: str = "haystack",
+ username: Secret = Secret.from_env_var("ARANGO_USERNAME", strict=False),
+ password: Secret = Secret.from_env_var("ARANGO_PASSWORD"),
+ collection_name: str = "haystack_documents",
+ embedding_dimension: int = 768,
+ recreate_collection: bool = False,
+ similarity_function: Literal["cosine", "dot_product", "l2"] = "cosine"
+) -> None
+```
+
+Creates a new ArangoDocumentStore instance.
+
+**Parameters:**
+
+- **host** (str) – ArangoDB server URL, e.g. `http://localhost:8529`.
+- **database** (str) – Name of the ArangoDB database to use. Created if it does not exist.
+- **username** (Secret) – ArangoDB username as a `Secret`. Defaults to `ARANGO_USERNAME` env var,
+ falling back to `root` if the variable is not set.
+- **password** (Secret) – ArangoDB password as a `Secret`. Defaults to `ARANGO_PASSWORD` env var.
+- **collection_name** (str) – Name of the collection to store documents in.
+- **embedding_dimension** (int) – Dimensionality of document embeddings.
+- **recreate_collection** (bool) – If `True`, drop and recreate the collection on startup.
+- **similarity_function** (Literal['cosine', 'dot_product', 'l2']) – Vector similarity function to use for embedding retrieval.
+ One of `"cosine"` (default), `"dot_product"`, or `"l2"`.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns the number of documents in the store.
+
+**Returns:**
+
+- int – Document count.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Haystack metadata filters. If `None`, all documents are returned.
+
+**Returns:**
+
+- list\[Document\] – List of matching `Document` objects.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents to the store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to write.
+- **policy** (DuplicatePolicy) – How to handle duplicates — `OVERWRITE`, `SKIP`, or `FAIL` (default).
+
+**Returns:**
+
+- int – Number of documents written.
+
+**Raises:**
+
+- ValueError – If `documents` contains non-`Document` objects.
+- DuplicateDocumentError – If a duplicate is found and policy is `FAIL`.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents by their IDs.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – List of document IDs to delete.
+
+#### 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]) -> ArangoDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- ArangoDocumentStore – Deserialized component.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/arcadedb.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/arcadedb.md
new file mode 100644
index 00000000000..972aad4197e
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/arcadedb.md
@@ -0,0 +1,419 @@
+---
+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
+
+# Requires: pip install sentence-transformers-haystack
+from haystack_integrations.components.embedders.sentence_transformers 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Retrieves unique values for a field matching a search term or all possible values
+if no search term is given.
+
+**Note**: values of different types are kept distinct even when they compare equal in Python, so
+the int `1`, the float `1.0`, the bool `True` and the str `"1"` are returned as four separate
+values.
+
+**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.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing the paginated values (in their original type) and the total count.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/astra.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/astra.md
new file mode 100644
index 00000000000..8c4f892ec57
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/astra.md
@@ -0,0 +1,531 @@
+---
+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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Retrieves unique values for a field matching a search term or all possible values if no search term is given.
+
+**Note**: values of different types are kept distinct even when they compare equal in Python
+(e.g. the int `1`, the bool `True` and the str `"1"` are returned as three separate values), with
+one exception.
+AstraDB's Data API canonicalizes any whole-number float (e.g. `1.0`) to an int on storage, unconditionally so a
+whole-number float is always returned back as an int, never as a float.
+Example: 1.0 (float) is sent to storage and comes back a 1 (int)
+
+Exception are floats with a fractional part (e.g. `1.5`) are unaffected and round-trip normally.
+
+**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.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing the paginated values (in their original type) 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-3.2-unstable/integrations-api/azure_ai_search.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/azure_ai_search.md
new file mode 100644
index 00000000000..a3a82ee749d
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/azure_ai_search.md
@@ -0,0 +1,482 @@
+---
+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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], 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.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – Tuple of (list of unique values in their original type, total count of matching values).
+ A field that is not defined in the index schema has no values, so it returns `([], 0)`.
+
+#### 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-3.2-unstable/integrations-api/azure_doc_intelligence.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/azure_doc_intelligence.md
new file mode 100644
index 00000000000..03f5fdb694a
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/azure_doc_intelligence.md
@@ -0,0 +1,147 @@
+---
+title: "Azure Document Intelligence"
+id: integrations-azure_doc_intelligence
+description: "Azure Document Intelligence integration for Haystack"
+slug: "/integrations-azure_doc_intelligence"
+---
+
+
+## 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)
+```
+
+#### __init__
+
+```python
+__init__(
+ endpoint: str,
+ *,
+ api_key: Secret = Secret.from_env_var("AZURE_DI_API_KEY"),
+ model_id: str = "prebuilt-layout",
+ store_full_path: bool = False
+) -> None
+```
+
+Creates an AzureDocumentIntelligenceConverter component.
+
+**Parameters:**
+
+- **endpoint** (str) – The endpoint URL of your Azure Document Intelligence resource.
+ Example: "https://YOUR_RESOURCE.cognitiveservices.azure.com/"
+- **api_key** (Secret) – API key for Azure authentication. Can use Secret.from_env_var()
+ to load from AZURE_DI_API_KEY environment variable.
+- **model_id** (str) – Azure model to use for analysis. Options:
+- "prebuilt-layout": Layout analysis with table and structure detection (default)
+- "prebuilt-read": Fast OCR for text extraction
+- Custom model IDs from your Azure resource
+- **store_full_path** (bool) – If True, stores complete file path in metadata.
+ If False, stores only the filename (default).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the Azure Document Intelligence client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Azure Document Intelligence client.
+
+#### run
+
+```python
+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.
+
+**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\[dict\]\] – 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]) -> AzureDocumentIntelligenceConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- AzureDocumentIntelligenceConverter – The deserialized component.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/azure_documentdb.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/azure_documentdb.md
new file mode 100644
index 00000000000..63bebe960c0
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/azure_documentdb.md
@@ -0,0 +1,683 @@
+---
+title: "Azure DocumentDB"
+id: integrations-azure-documentdb
+description: "Azure DocumentDB integration for Haystack"
+slug: "/integrations-azure-documentdb"
+---
+
+
+## haystack_integrations.components.retrievers.azure_documentdb.embedding_retriever
+
+### AzureDocumentDBEmbeddingRetriever
+
+Retrieve documents from Azure DocumentDB using `cosmosSearch` vector similarity.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: AzureDocumentDBDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create the embedding retriever.
+
+**Parameters:**
+
+- **document_store** (AzureDocumentDBDocumentStore) – Azure DocumentDB document store to query.
+- **filters** (dict\[str, Any\] | None) – Default Haystack metadata filters.
+- **top_k** (int) – Maximum number of documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy for combining initialization and runtime filters.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized retriever configuration.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureDocumentDBEmbeddingRetriever
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Serialized retriever configuration.
+
+**Returns:**
+
+- AzureDocumentDBEmbeddingRetriever – The deserialized retriever.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release synchronous document-store resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release asynchronous document-store resources.
+
+#### 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 vector.
+- **filters** (dict\[str, Any\] | None) – Runtime Haystack metadata filters.
+- **top_k** (int | None) – Runtime maximum number of documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing the retrieved `documents`.
+
+#### 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 by vector similarity.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Query vector.
+- **filters** (dict\[str, Any\] | None) – Runtime Haystack metadata filters.
+- **top_k** (int | None) – Runtime maximum number of documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing the retrieved `documents`.
+
+## haystack_integrations.components.retrievers.azure_documentdb.full_text_retriever
+
+### AzureDocumentDBFullTextRetriever
+
+Retrieve documents using Azure DocumentDB BM25 full-text search, currently a gated preview.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: AzureDocumentDBDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create the full-text retriever.
+
+**Parameters:**
+
+- **document_store** (AzureDocumentDBDocumentStore) – Azure DocumentDB document store to query.
+- **filters** (dict\[str, Any\] | None) – Default Haystack metadata filters.
+- **top_k** (int) – Maximum number of documents to return.
+- **filter_policy** (str | FilterPolicy) – Policy for combining initialization and runtime filters.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized retriever configuration.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureDocumentDBFullTextRetriever
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Serialized retriever configuration.
+
+**Returns:**
+
+- AzureDocumentDBFullTextRetriever – The deserialized retriever.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release synchronous document-store resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release asynchronous document-store resources.
+
+#### run
+
+```python
+run(
+ query: str | list[str],
+ fuzzy: dict[str, int] | None = None,
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by BM25 keyword search.
+
+**Parameters:**
+
+- **query** (str | list\[str\]) – Query string or strings.
+- **fuzzy** (dict\[str, int\] | None) – Azure DocumentDB fuzzy-search options such as `maxEdits`.
+- **filters** (dict\[str, Any\] | None) – Runtime Haystack metadata filters.
+- **top_k** (int | None) – Runtime maximum number of documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing the retrieved `documents`.
+
+#### run_async
+
+```python
+run_async(
+ query: str | list[str],
+ fuzzy: dict[str, int] | None = None,
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents by BM25 keyword search.
+
+**Parameters:**
+
+- **query** (str | list\[str\]) – Query string or strings.
+- **fuzzy** (dict\[str, int\] | None) – Azure DocumentDB fuzzy-search options such as `maxEdits`.
+- **filters** (dict\[str, Any\] | None) – Runtime Haystack metadata filters.
+- **top_k** (int | None) – Runtime maximum number of documents.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary containing the retrieved `documents`.
+
+## haystack_integrations.document_stores.azure_documentdb.document_store
+
+### AzureIdentityTokenCallback
+
+Bases: OIDCCallback
+
+Fetch Microsoft Entra access tokens for PyMongo's OIDC authentication.
+
+#### fetch
+
+```python
+fetch(context: OIDCCallbackContext) -> OIDCCallbackResult
+```
+
+Fetch an access token for Azure DocumentDB.
+
+**Parameters:**
+
+- **context** (OIDCCallbackContext) – PyMongo OIDC callback context.
+
+**Returns:**
+
+- OIDCCallbackResult – The OIDC callback result containing a Microsoft Entra access token.
+
+### AzureDocumentDBDocumentStore
+
+A Haystack document store backed by Azure DocumentDB.
+
+The default authentication mode uses Microsoft Entra ID through `DefaultAzureCredential`. Supply the Azure
+DocumentDB cluster name with `cluster_name` or the `AZURE_DOCUMENTDB_CLUSTER_NAME` environment variable.
+
+A connection string can be supplied through `mongo_connection_string` or
+`AZURE_DOCUMENTDB_CONNECTION_STRING` for local development and integration tests. Connection strings can contain
+credentials and aren't recommended for production workloads.
+
+The collection must already exist. For embedding retrieval, create a `cosmosSearch` vector index by calling
+`create_vector_index` or provisioning it separately. Filtered vector search also requires a regular index for
+every filtered metadata field, such as `meta.category`. Values used with `>`, `>=`, `<`, or `<=` must be numbers
+or ISO-formatted date strings.
+
+Usage:
+
+```python
+from haystack_integrations.document_stores.azure_documentdb import AzureDocumentDBDocumentStore
+
+document_store = AzureDocumentDBDocumentStore(database_name="haystack", collection_name="documents")
+document_store.create_vector_index(dimensions=1536, similarity="COS")
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ database_name: str,
+ collection_name: str,
+ vector_search_index: str = "haystack_vector_index",
+ full_text_search_index: str | None = None,
+ cluster_name: str | None = None,
+ mongo_connection_string: Secret | None = Secret.from_env_var(
+ "AZURE_DOCUMENTDB_CONNECTION_STRING", strict=False
+ ),
+ azure_token_credential: TokenCredential | None = None,
+ embedding_field: str = "embedding",
+ content_field: str = "content"
+) -> None
+```
+
+Create an Azure DocumentDB document store.
+
+**Parameters:**
+
+- **database_name** (str) – Name of the existing database.
+- **collection_name** (str) – Name of the existing collection.
+- **vector_search_index** (str) – Name used when creating the vector index. Azure DocumentDB selects vector indexes
+ by path at query time, so this name is not included in vector search queries.
+- **full_text_search_index** (str | None) – Name of an Azure DocumentDB full-text search index. Full-text search is currently
+ a gated preview and must be enabled on the cluster before using the full-text retriever.
+- **cluster_name** (str | None) – Azure DocumentDB cluster name. If omitted, `AZURE_DOCUMENTDB_CLUSTER_NAME` is used.
+- **mongo_connection_string** (Secret | None) – Optional MongoDB connection string intended only for local development and
+ integration tests. Microsoft Entra authentication is used when this value is absent.
+- **azure_token_credential** (TokenCredential | None) – Azure credential used for Microsoft Entra authentication. If omitted,
+ `DefaultAzureCredential` is used.
+- **embedding_field** (str) – Field containing document embeddings.
+- **content_field** (str) – Field containing document content.
+
+**Raises:**
+
+- ValueError – If database, collection, or field names are invalid.
+
+#### connection
+
+```python
+connection: MongoClient | AsyncMongoClient
+```
+
+Return the active Azure DocumentDB client.
+
+**Returns:**
+
+- MongoClient | AsyncMongoClient – The synchronous or asynchronous PyMongo client.
+
+**Raises:**
+
+- DocumentStoreError – If no connection has been established.
+
+#### collection
+
+```python
+collection: Collection | AsyncCollection
+```
+
+Return the active Azure DocumentDB collection.
+
+**Returns:**
+
+- Collection | AsyncCollection – The synchronous or asynchronous PyMongo collection.
+
+**Raises:**
+
+- DocumentStoreError – If no collection has been initialized.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release synchronous client resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release asynchronous client resources.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this document store to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized document-store configuration.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureDocumentDBDocumentStore
+```
+
+Deserialize this document store from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Serialized document-store configuration.
+
+**Returns:**
+
+- AzureDocumentDBDocumentStore – The deserialized document store.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Return the number of documents in the store.
+
+**Returns:**
+
+- int – The number of documents.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously return the number of documents in the store.
+
+**Returns:**
+
+- int – The number of documents.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Return documents matching Haystack metadata filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Haystack metadata filters. Strings in ordered comparisons must be ISO-formatted dates.
+
+**Returns:**
+
+- list\[Document\] – Documents matching the filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously return documents matching Haystack metadata filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Haystack metadata filters. Strings in ordered comparisons must be ISO-formatted dates.
+
+**Returns:**
+
+- list\[Document\] – Documents matching the filters.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to Azure DocumentDB using the requested duplicate policy.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to write.
+- **policy** (DuplicatePolicy) – How to handle documents whose IDs already exist.
+
+**Returns:**
+
+- int – The number of documents written.
+
+**Raises:**
+
+- ValueError – If `documents` contains an object that is not a `Document`.
+- DuplicateDocumentError – If a duplicate ID is written with `DuplicatePolicy.FAIL`.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously write documents using the requested duplicate policy.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to write.
+- **policy** (DuplicatePolicy) – How to handle documents whose IDs already exist.
+
+**Returns:**
+
+- int – The number of documents written.
+
+**Raises:**
+
+- ValueError – If `documents` contains an object that is not a `Document`.
+- DuplicateDocumentError – If a duplicate ID is written with `DuplicatePolicy.FAIL`.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents with matching Haystack IDs.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – IDs of documents to delete.
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously delete documents with matching Haystack IDs.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – IDs of documents to delete.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Delete documents matching filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters selecting documents to delete.
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously delete documents matching filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters selecting documents to delete.
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Update metadata on documents matching filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters selecting documents to update.
+- **meta** (dict\[str, Any\]) – Metadata fields and values to set.
+
+**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 update metadata on documents matching filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters selecting documents to update.
+- **meta** (dict\[str, Any\]) – Metadata fields and values to set.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+#### delete_all_documents
+
+```python
+delete_all_documents(*, recreate_collection: bool = False) -> None
+```
+
+Delete all documents, optionally recreating the collection.
+
+**Parameters:**
+
+- **recreate_collection** (bool) – Drop and recreate the collection instead of deleting documents individually.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async(*, recreate_collection: bool = False) -> None
+```
+
+Asynchronously delete all documents, optionally recreating the collection.
+
+**Parameters:**
+
+- **recreate_collection** (bool) – Drop and recreate the collection instead of deleting documents individually.
+
+#### create_vector_index
+
+```python
+create_vector_index(
+ *,
+ dimensions: int,
+ similarity: Literal["COS", "L2", "IP"] = "COS",
+ kind: Literal[
+ "vector-ivf", "vector-hnsw", "vector-diskann"
+ ] = "vector-hnsw",
+ **index_options: Any
+) -> None
+```
+
+Create the configured Azure DocumentDB `cosmosSearch` vector index.
+
+**Parameters:**
+
+- **dimensions** (int) – Number of dimensions in each embedding.
+- **similarity** (Literal['COS', 'L2', 'IP']) – Similarity metric: cosine (`COS`), Euclidean (`L2`), or inner product (`IP`).
+- **kind** (Literal['vector-ivf', 'vector-hnsw', 'vector-diskann']) – Vector index algorithm.
+- **index_options** (Any) – Algorithm-specific Azure DocumentDB index options.
+
+**Raises:**
+
+- ValueError – If `dimensions` is not positive.
+- DocumentStoreError – If index creation fails.
+
+#### create_vector_index_async
+
+```python
+create_vector_index_async(
+ *,
+ dimensions: int,
+ similarity: Literal["COS", "L2", "IP"] = "COS",
+ kind: Literal[
+ "vector-ivf", "vector-hnsw", "vector-diskann"
+ ] = "vector-hnsw",
+ **index_options: Any
+) -> None
+```
+
+Asynchronously create the configured `cosmosSearch` vector index.
+
+**Parameters:**
+
+- **dimensions** (int) – Number of dimensions in each embedding.
+- **similarity** (Literal['COS', 'L2', 'IP']) – Similarity metric: cosine (`COS`), Euclidean (`L2`), or inner product (`IP`).
+- **kind** (Literal['vector-ivf', 'vector-hnsw', 'vector-diskann']) – Vector index algorithm.
+- **index_options** (Any) – Algorithm-specific Azure DocumentDB index options.
+
+**Raises:**
+
+- ValueError – If `dimensions` is not positive.
+- DocumentStoreError – If index creation fails.
+
+## haystack_integrations.document_stores.azure_documentdb.filters
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/azure_form_recognizer.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/azure_form_recognizer.md
new file mode 100644
index 00000000000..0f4c0c2a24e
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/azure_form_recognizer.md
@@ -0,0 +1,150 @@
+---
+title: "Azure Form Recognizer"
+id: integrations-azure_form_recognizer
+description: "Azure Form Recognizer integration for Haystack"
+slug: "/integrations-azure_form_recognizer"
+---
+
+
+## haystack_integrations.components.converters.azure_form_recognizer.converter
+
+### 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_integrations.components.converters.azure_form_recognizer 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Azure Document Analysis client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Azure Document Analysis client.
+
+#### 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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/brave.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/brave.md
new file mode 100644
index 00000000000..c81cf38f0ad
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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-3.2-unstable/integrations-api/chonkie.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/chonkie.md
new file mode 100644
index 00000000000..ba5d4219010
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/chonkie.md
@@ -0,0 +1,418 @@
+---
+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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Chonkie recursive chunker.
+
+#### 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Chonkie sentence chunker.
+
+#### 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Chonkie token chunker.
+
+#### 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-3.2-unstable/integrations-api/chroma.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/chroma.md
new file mode 100644
index 00000000000..2ef11cf51fe
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/chroma.md
@@ -0,0 +1,1014 @@
+---
+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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Return unique metadata field values, optionally filtered by a 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 values, matched as a
+ case-insensitive substring against the metadata field's value.
+- **from\_** (int) – The offset to start returning values from (for pagination).
+- **size** (int) – The maximum number of unique values to return.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing list of unique values (in their original type) 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Asynchronously return unique metadata field values, optionally filtered by a search term, 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 values, matched as a
+ case-insensitive substring against the metadata field's value.
+- **from\_** (int) – The offset to start returning values from (for pagination).
+- **size** (int) – The maximum number of unique values to return.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing list of unique values (in their original type) 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-3.2-unstable/integrations-api/cognee.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/cognee.md
new file mode 100644
index 00000000000..1b614963b0f
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/cognee.md
@@ -0,0 +1,255 @@
+---
+title: "Cognee"
+id: integrations-cognee
+description: "Cognee integration for Haystack"
+slug: "/integrations-cognee"
+---
+
+
+## haystack_integrations.components.retrievers.cognee.memory_retriever
+
+### CogneeRetriever
+
+Retrieves memories from a `CogneeMemoryStore` as `ChatMessage` instances.
+
+Configuration (`search_type`, `top_k`, `dataset_name`, `session_id`) lives on
+the store; this retriever is a thin pipeline adapter over `search_memories`.
+
+#### __init__
+
+```python
+__init__(*, memory_store: CogneeMemoryStore, top_k: int | None = None) -> None
+```
+
+Initialize the retriever.
+
+**Parameters:**
+
+- **memory_store** (CogneeMemoryStore) – Backing `CogneeMemoryStore` to query.
+- **top_k** (int | None) – Default max results; falls back to the store's `top_k` when `None`.
+
+#### run
+
+```python
+run(
+ query: str, top_k: int | None = None, user_id: str | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Search the attached store and return matching memories as ChatMessages.
+
+**Parameters:**
+
+- **query** (str) – Natural-language query.
+- **top_k** (int | None) – Per-call override; falls back to init `top_k`, then the store's default.
+- **user_id** (str | None) – Cognee user UUID; scopes the search to that user.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CogneeRetriever
+```
+
+Deserialize a component from a dictionary.
+
+## haystack_integrations.components.writers.cognee.memory_writer
+
+### CogneeWriter
+
+Persists `ChatMessage`s into a `CogneeMemoryStore`.
+
+Use without `session_id` to write to the permanent graph; pass `session_id` to
+target cognee's session cache for that writer's writes. The writer's
+`session_id` overrides the store's own `session_id` per call, so one store can
+back multiple writers writing to different tiers.
+
+#### __init__
+
+```python
+__init__(
+ *, memory_store: CogneeMemoryStore, session_id: str | None = None
+) -> None
+```
+
+Initialize the writer.
+
+**Parameters:**
+
+- **memory_store** (CogneeMemoryStore) – Backing `CogneeMemoryStore` to write into.
+- **session_id** (str | None) – Overrides the store's `session_id` for this writer's writes.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage], user_id: str | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Store `messages` in Cognee memory and pass them through unchanged.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – Messages to persist.
+- **user_id** (str | None) – Cognee user UUID; scopes the write to that user.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CogneeWriter
+```
+
+Deserialize a component from a dictionary.
+
+## haystack_integrations.memory_stores.cognee.memory_store
+
+### CogneeMemoryStore
+
+Memory backend backed by Cognee.
+
+Wraps cognee's V2 memory API: `add_memories` -> `cognee.remember`,
+`search_memories` -> `cognee.recall`, `improve` -> `cognee.improve`,
+`delete_all_memories` -> `cognee.forget`.
+
+`session_id` selects the tier — set it to use cognee's session cache (cheap,
+no LLM extraction, session-aware recall); leave `None` for the permanent
+graph.
+
+`self_improvement` is forwarded to `cognee.remember` and defaults to `True`
+(same as cognee). On the permanent tier it awaits `improve` inline; on the
+session tier it schedules `improve` as a fire-and-forget background task.
+Set to `False` when you want `improve()` to be the only improve trigger
+— otherwise an explicit `improve()` runs improve twice and produces
+near-duplicate graph nodes.
+
+`timeout` (seconds) caps how long any single cognee call may run before
+raising `concurrent.futures.TimeoutError`. The default of 300s covers
+single-message agent-memory writes comfortably; bulk ingestion of long
+documents may need a larger value.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ search_type: CogneeSearchType = "GRAPH_COMPLETION",
+ top_k: int = 5,
+ dataset_name: str = "haystack_memory",
+ session_id: str | None = None,
+ self_improvement: bool = True,
+ timeout: float = 300
+) -> None
+```
+
+Initialize the store.
+
+**Parameters:**
+
+- **search_type** (CogneeSearchType) – Cognee search strategy used by `search_memories`.
+- **top_k** (int) – Default max results for `search_memories`.
+- **dataset_name** (str) – Cognee dataset backing this store.
+- **session_id** (str | None) – When set, use the session-cache tier; otherwise the permanent graph.
+- **self_improvement** (bool) – Forwarded to `cognee.remember` (default `True`, matches cognee).
+ Set to `False` when `improve()` should be the only improve trigger.
+- **timeout** (float) – Per-call timeout in seconds for any cognee operation.
+ Raise this for bulk ingestion workloads that legitimately need >300s.
+
+#### add_memories
+
+```python
+add_memories(
+ *,
+ messages: list[ChatMessage],
+ user_id: str | None = None,
+ session_id: str | None = None
+) -> None
+```
+
+Persist messages via `cognee.remember`.
+
+Permanent tier batches all texts into one call; session tier writes one
+entry per message (matches cognee's session example). Empty messages
+are skipped.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – Messages to store.
+- **user_id** (str | None) – Cognee user UUID; `None` uses cognee's default user.
+- **session_id** (str | None) – Per-call override of the store's `session_id`.
+
+#### search_memories
+
+```python
+search_memories(
+ *,
+ query: str | None = None,
+ top_k: int | None = None,
+ user_id: str | None = None
+) -> list[ChatMessage]
+```
+
+Search via `cognee.recall` and wrap each hit in a system `ChatMessage`.
+
+**Parameters:**
+
+- **query** (str | None) – Natural-language query. Empty/`None` returns `[]`.
+- **top_k** (int | None) – Per-call override of the store's default.
+- **user_id** (str | None) – Cognee user UUID; `None` uses cognee's default user.
+
+#### improve
+
+```python
+improve(*, session_id: str | None = None, user_id: str | None = None) -> None
+```
+
+Promote session-cache content into the permanent graph via `cognee.improve`.
+
+Without any session_id this is a plain graph-enrichment pass.
+
+**Parameters:**
+
+- **session_id** (str | None) – Session to promote; defaults to the store's `session_id`.
+- **user_id** (str | None) – Cognee user UUID; `None` uses cognee's default user.
+
+#### delete_all_memories
+
+```python
+delete_all_memories(*, user_id: str | None = None) -> None
+```
+
+Delete this dataset via `cognee.forget(dataset=...)`.
+
+Session cache survives (sessions aren't dataset-scoped) — use
+`cognee.forget(everything=True)` for a full wipe.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this store for pipeline persistence.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CogneeMemoryStore
+```
+
+Deserialize a store from a dict produced by `to_dict`.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/cohere.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/cohere.md
new file mode 100644
index 00000000000..4dbf5b7f009
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/cohere.md
@@ -0,0 +1,1009 @@
+---
+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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Cohere client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous 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]) -> 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Cohere client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous 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]) -> 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Cohere client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous 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]) -> 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,
+ 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 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.
+- **batch_size** (int) – the batch size to use. The Cohere embed endpoint caps the number of texts per call, so the
+ texts are sent in batches just like the synchronous path.
+- **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.
+
+### 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Cohere client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous 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] | str,
+ 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\] | str) – list of `ChatMessage` instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – additional keyword arguments for chat generation. These are merged per key
+ with the `generation_kwargs` passed at initialization: keys provided here take precedence, keys set
+ only at initialization are kept.
+ 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] | str,
+ 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\] | str) – list of `ChatMessage` instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – additional keyword arguments for chat generation. These are merged per key
+ with the `generation_kwargs` passed at initialization: keys provided here take precedence, keys set
+ only at initialization are kept.
+ 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.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.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Cohere client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous 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]) -> 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-3.2-unstable/integrations-api/cometapi.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/cometapi.md
new file mode 100644
index 00000000000..a1e242728e6
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/cometapi.md
@@ -0,0 +1,62 @@
+---
+title: "Comet API"
+id: integrations-cometapi
+description: "Comet API integration for Haystack"
+slug: "/integrations-cometapi"
+---
+
+
+## haystack_integrations.components.generators.cometapi.chat.chat_generator
+
+### CometAPIChatGenerator
+
+Bases: OpenAIChatGenerator
+
+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.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("COMET_API_KEY"),
+ model: str = "gpt-5-mini",
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: int | None = None,
+ max_retries: int | None = None,
+ tools: list[Tool | Toolset] | Toolset | None = None,
+ tools_strict: bool = False,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates a `CometAPIChatGenerator` instance.
+
+**Parameters:**
+
+- **api_key** (Secret) – The API key for authenticating with the CometAPI.
+- **model** (str) – The name of the model to use for chat generation (e.g., `"gpt-5-mini"`, `"grok-3-mini"`).
+- **streaming_callback** (StreamingCallbackT | None) – An optional callable invoked with each chunk of a streaming response.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional keyword arguments passed to the underlying generation API call.
+- **timeout** (int | None) – The maximum time in seconds to wait for a response from the API.
+- **max_retries** (int | None) – The maximum number of times to retry a failed API request.
+- **tools** (list\[Tool | Toolset\] | Toolset | None) – An optional list of tools the model can use.
+- **tools_strict** (bool) – If `True`, the model is forced to use one of the provided tools.
+- **http_client_kwargs** (dict\[str, Any\] | None) – Optional keyword arguments passed to the HTTP 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-3.2-unstable/integrations-api/datadog.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/datadog.md
new file mode 100644
index 00000000000..68d6ec4185c
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/datadog.md
@@ -0,0 +1,190 @@
+---
+title: "Datadog"
+id: integrations-datadog
+description: "Datadog integration for Haystack"
+slug: "/integrations-datadog"
+---
+
+
+## haystack_integrations.components.connectors.datadog.datadog_connector
+
+### DatadogConnector
+
+DatadogConnector connects Haystack to [Datadog](https://www.datadoghq.com/) in order to enable the tracing of
+
+operations and data flow within the components of a pipeline.
+
+To use the DatadogConnector, add it to your pipeline without connecting it to any other component. It will
+automatically trace all pipeline operations when tracing is enabled.
+
+**Environment Configuration:**
+
+- `HAYSTACK_CONTENT_TRACING_ENABLED`: Must be set to `"true"` to trace the content (inputs and outputs) of the
+ pipeline components.
+- Datadog is configured through the standard `ddtrace` mechanisms, e.g. the `DD_SERVICE`, `DD_ENV` and
+ `DD_VERSION` environment variables or by running your application with the `ddtrace-run` command. See the
+ [ddtrace documentation](https://ddtrace.readthedocs.io/en/stable/) for more details.
+
+Here is an example of how to use the DatadogConnector 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.datadog import DatadogConnector
+
+pipe = Pipeline()
+pipe.add_component("tracer", DatadogConnector("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])
+```
+
+#### __init__
+
+```python
+__init__(name: str = 'datadog') -> None
+```
+
+Initialize the DatadogConnector component.
+
+**Parameters:**
+
+- **name** (str) – The name used to identify this tracing component. It is returned by the `run` method and can be
+ used to mark traces produced by this connector.
+
+#### run
+
+```python
+run() -> dict[str, str]
+```
+
+Runs the DatadogConnector component.
+
+**Returns:**
+
+- dict\[str, str\] – A dictionary with the following keys:
+- `name`: The name of the tracing component.
+
+#### 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]) -> DatadogConnector
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- DatadogConnector – The deserialized component instance.
+
+## haystack_integrations.tracing.datadog.tracer
+
+### DatadogSpan
+
+Bases: Span
+
+#### __init__
+
+```python
+__init__(span: ddSpan) -> None
+```
+
+Creates an instance of DatadogSpan.
+
+#### set_tag
+
+```python
+set_tag(key: str, value: Any) -> None
+```
+
+Set a single tag on the span.
+
+**Parameters:**
+
+- **key** (str) – the name of the tag.
+- **value** (Any) – the value of the tag.
+
+#### raw_span
+
+```python
+raw_span() -> Any
+```
+
+Provides access to the underlying span object of the tracer.
+
+**Returns:**
+
+- Any – The underlying span object.
+
+#### get_correlation_data_for_logs
+
+```python
+get_correlation_data_for_logs() -> dict[str, Any]
+```
+
+Return a dictionary with correlation data for logs.
+
+### DatadogTracer
+
+Bases: Tracer
+
+#### __init__
+
+```python
+__init__(tracer: ddTracer) -> None
+```
+
+Creates an instance of DatadogTracer.
+
+#### trace
+
+```python
+trace(
+ operation_name: str,
+ tags: dict[str, Any] | None = None,
+ parent_span: Span | None = None,
+) -> Iterator[Span]
+```
+
+Activate and return a new span that inherits from the current active span.
+
+#### current_span
+
+```python
+current_span() -> Span | None
+```
+
+Return the current active span
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ddgs.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ddgs.md
new file mode 100644
index 00000000000..ea53341d004
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ddgs.md
@@ -0,0 +1,137 @@
+---
+title: "ddgs"
+id: integrations-ddgs
+description: "ddgs (Dux Distributed Global Search) integration for Haystack"
+slug: "/integrations-ddgs"
+---
+
+
+## haystack_integrations.components.websearch.ddgs.ddgs_websearch
+
+### DDGSWebSearch
+
+Searches the web with ddgs (Dux Distributed Global Search) and returns results as Haystack Documents.
+
+[ddgs](https://github.com/deedy5/ddgs) is a free, **keyless** metasearch library that aggregates
+results from multiple backends (DuckDuckGo, Google, Bing, Brave, Yahoo, Yandex, Mullvad, and more),
+so no API key is required.
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.ddgs import DDGSWebSearch
+
+websearch = DDGSWebSearch(top_k=5)
+result = websearch.run(query="What is Haystack by deepset?")
+
+documents = result["documents"]
+links = result["links"]
+```
+
+#### __init__
+
+```python
+__init__(
+ top_k: int = 10,
+ backend: str = "auto",
+ region: str = "us-en",
+ safesearch: str = "moderate",
+ search_params: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the DDGSWebSearch component.
+
+**Parameters:**
+
+- **top_k** (int) – Maximum number of results to return.
+- **backend** (str) – Comma-separated ddgs backends to query, or `"auto"` to let ddgs choose
+ (for example `"duckduckgo, google, brave"`). See the ddgs docs for the full list.
+- **region** (str) – Region/locale for the search, for example `"us-en"`, `"de-de"`, or `"wt-wt"` (no region).
+- **safesearch** (str) – Safe-search level: `"on"`, `"moderate"`, or `"off"`.
+- **search_params** (dict\[str, Any\] | None) – Additional keyword arguments forwarded to `DDGS().text()` (for example `page` or
+ `timelimit`). Values here override `backend`, `region`, `safesearch`, and `top_k`
+ on conflict.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the ddgs client.
+
+Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+
+#### run
+
+```python
+run(
+ query: str,
+ top_k: int | None = None,
+ *,
+ backend: str | None = None,
+ region: str | None = None,
+ safesearch: str | None = None,
+ search_params: dict[str, Any] | None = None
+) -> dict[str, list[Document] | list[str]]
+```
+
+Use ddgs to search the web.
+
+**Parameters:**
+
+- **query** (str) – Search query.
+- **top_k** (int | None) – Optional per-run override of the maximum number of results. If not provided, the
+ init-time `top_k` is used.
+- **backend** (str | None) – Optional per-run override of the ddgs backends. If not provided, the init-time
+ `backend` is used.
+- **region** (str | None) – Optional per-run override of the region/locale. If not provided, the init-time
+ `region` is used.
+- **safesearch** (str | None) – Optional per-run override of the safe-search level. If not provided, the init-time
+ `safesearch` is used.
+- **search_params** (dict\[str, Any\] | None) – Optional per-run override of the extra `DDGS().text()` arguments. If provided, fully
+ replaces the init-time `search_params`.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | list\[str\]\] – A dictionary with the following keys:
+- `documents`: List of documents returned by the search backends.
+- `links`: List of links returned by the search backends.
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ top_k: int | None = None,
+ *,
+ backend: str | None = None,
+ region: str | None = None,
+ safesearch: str | None = None,
+ search_params: dict[str, Any] | None = None
+) -> dict[str, list[Document] | list[str]]
+```
+
+Asynchronously use ddgs to search the web.
+
+ddgs has no native async API, so the blocking search runs in a worker thread. Same parameters
+and return values as :meth:`run`.
+
+**Parameters:**
+
+- **query** (str) – Search query.
+- **top_k** (int | None) – Optional per-run override of the maximum number of results. If not provided, the
+ init-time `top_k` is used.
+- **backend** (str | None) – Optional per-run override of the ddgs backends. If not provided, the init-time
+ `backend` is used.
+- **region** (str | None) – Optional per-run override of the region/locale. If not provided, the init-time
+ `region` is used.
+- **safesearch** (str | None) – Optional per-run override of the safe-search level. If not provided, the init-time
+ `safesearch` is used.
+- **search_params** (dict\[str, Any\] | None) – Optional per-run override of the extra `DDGS().text()` arguments. If provided, fully
+ replaces the init-time `search_params`.
+
+**Returns:**
+
+- dict\[str, list\[Document\] | list\[str\]\] – A dictionary with `documents` and `links` keys.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/deepeval.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/deepeval.md
new file mode 100644
index 00000000000..1211eff8051
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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-3.2-unstable/integrations-api/docling.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/docling.md
new file mode 100644
index 00000000000..5c99f716f9b
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/docling.md
@@ -0,0 +1,187 @@
+---
+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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Build the default `HybridChunker` for `ExportType.DOC_CHUNKS` if no `chunker` was passed at init time.
+
+Deferred to warm-up time because constructing the default chunker downloads a Hugging Face tokenizer.
+
+#### 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-3.2-unstable/integrations-api/docling_serve.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/docling_serve.md
new file mode 100644
index 00000000000..9bb800bf79d
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/docling_serve.md
@@ -0,0 +1,180 @@
+---
+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.
+
+### ConversionMode
+
+Bases: str, Enum
+
+Execution mode for DoclingServe conversions.
+
+- `SYNC`: Uses DoclingServe's synchronous conversion endpoints.
+- `ASYNC`: Uses DoclingServe's async job endpoints and polls for completion.
+
+### DoclingServeConversionError
+
+Bases: Exception
+
+Raised when DoclingServe reports an async task or conversion failure.
+
+### DoclingServeTimeoutError
+
+Bases: DoclingServeConversionError
+
+Raised when a DoclingServe async task exceeds job_timeout.
+
+### 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
+ ),
+ mode: ConversionMode | str = ConversionMode.SYNC,
+ poll_interval: float = 2.0,
+ job_timeout: float = 600.0
+) -> 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.
+- **mode** (ConversionMode | str) – Conversion mode. `sync` uses DoclingServe's synchronous endpoints. `async` submits
+ conversion jobs to DoclingServe's async endpoints and polls until completion.
+- **poll_interval** (float) – Controls both the server-side long-poll wait (?wait= parameter) and the maximum local sleep between polls.
+ A higher value reduces round-trips; a lower value increases polling frequency.
+- **job_timeout** (float) – Maximum time in seconds to wait for each async conversion job.
+
+#### 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-3.2-unstable/integrations-api/dynamodb.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/dynamodb.md
new file mode 100644
index 00000000000..f9c5ca8db58
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/dynamodb.md
@@ -0,0 +1,495 @@
+---
+title: "Amazon DynamoDB"
+id: integrations-dynamodb
+description: "Amazon DynamoDB integration for Haystack"
+slug: "/integrations-dynamodb"
+---
+
+
+## haystack_integrations.components.retrievers.dynamodb.embedding_retriever
+
+### DynamoDBEmbeddingRetriever
+
+Retrieves documents from a `DynamoDBDocumentStore` using vector similarity on embeddings.
+
+Uses DynamoDB's native `SearchVectors` API (cosine similarity). DynamoDB returns at most 100
+candidates per search, so `top_k` cannot exceed 100. Metadata filters are applied client-side
+to those candidates, so a selective filter can return fewer than `top_k` documents even when
+more matching documents exist.
+
+Example usage:
+
+```python
+from haystack_integrations.document_stores.dynamodb import DynamoDBDocumentStore
+from haystack_integrations.components.retrievers.dynamodb import DynamoDBEmbeddingRetriever
+
+store = DynamoDBDocumentStore(table_name="docs", index_name="doc-index", embedding_dimension=768)
+retriever = DynamoDBEmbeddingRetriever(document_store=store, top_k=5)
+result = retriever.run(query_embedding=[0.1, 0.2, ...])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: DynamoDBDocumentStore,
+ top_k: int = 10,
+ filters: dict[str, Any] | None = None,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Creates a new DynamoDBEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (DynamoDBDocumentStore) – The `DynamoDBDocumentStore` to retrieve documents from.
+- **top_k** (int) – Maximum number of documents to return, between 1 and 100 (the DynamoDB
+ `SearchVectors` limit).
+- **filters** (dict\[str, Any\] | None) – Optional Haystack metadata filters applied at retrieval time. Applied
+ client-side after the native vector search, since DynamoDB's `SearchVectors`
+ filter expressions can only reference attributes declared in the index's
+ `SearchSchema` at index-creation time.
+- **filter_policy** (str | FilterPolicy) – How run-time filters combine with `filters`: `REPLACE` (default)
+ uses the run-time filters alone when they are given, `MERGE` combines both.
+
+**Raises:**
+
+- ValueError – If `document_store` is not a `DynamoDBDocumentStore` or `top_k` is
+ outside the allowed range.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ top_k: int | None = None,
+ filters: dict[str, Any] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieves documents most similar to `query_embedding`.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – The query vector.
+- **top_k** (int | None) – Overrides the instance-level `top_k` for this call; must stay between 1 and 100.
+- **filters** (dict\[str, Any\] | None) – Run-time filters, combined with the instance-level `filters` according to
+ `filter_policy`.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with `documents`, a list of `Document` objects sorted by score.
+
+#### run_async
+
+```python
+run_async(
+ query_embedding: list[float],
+ top_k: int | None = None,
+ filters: dict[str, Any] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieves documents most similar to `query_embedding`.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – The query vector.
+- **top_k** (int | None) – Overrides the instance-level `top_k` for this call; must stay between 1 and 100.
+- **filters** (dict\[str, Any\] | None) – Run-time filters, combined with the instance-level `filters` according to
+ `filter_policy`.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with `documents`, a list of `Document` objects sorted by score.
+
+#### 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]) -> DynamoDBEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- DynamoDBEmbeddingRetriever – Deserialized component.
+
+## haystack_integrations.document_stores.dynamodb.document_store
+
+### DynamoDBDocumentStore
+
+A Haystack DocumentStore backed by Amazon DynamoDB native vector search.
+
+Uses the `SearchVectors` API (GA 2026-08-05). Documents are stored as items in a
+DynamoDB table with a vector index, and retrieved via cosine similarity search. Every
+method has an `_async` counterpart built on `aiobotocore`.
+
+Limitations to weigh before choosing this store:
+
+- `filter_documents`, `count_documents` and the filter-based bulk operations run a
+ consistent full-table `Scan` and evaluate Haystack filters client-side, so their cost
+ grows with the table size. `SearchVectors` can only filter on attributes fixed in the
+ index `SearchSchema` at creation time, which arbitrary Haystack filters cannot use.
+- `SearchVectors` returns at most 100 candidates per request
+ (`SEARCH_VECTORS_MAX_TOP_K`), so `top_k` cannot exceed 100 and filtered retrieval can
+ only choose among those candidates.
+- A DynamoDB item is limited to 400 KB, which bounds a document's content, metadata and
+ embedding together.
+
+Example usage:
+
+```python
+from haystack_integrations.document_stores.dynamodb import DynamoDBDocumentStore
+
+store = DynamoDBDocumentStore(
+ table_name="haystack-documents",
+ index_name="haystack-vector-index",
+ embedding_dimension=768,
+ region_name="us-east-1",
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ table_name: str = "haystack_documents",
+ index_name: str = "haystack_vector_index",
+ embedding_dimension: int = 768,
+ region_name: str | None = None,
+ aws_access_key_id: Secret = Secret.from_env_var(
+ "AWS_ACCESS_KEY_ID", strict=False
+ ),
+ aws_secret_access_key: Secret = Secret.from_env_var(
+ "AWS_SECRET_ACCESS_KEY", strict=False
+ ),
+ aws_session_token: Secret = Secret.from_env_var(
+ "AWS_SESSION_TOKEN", strict=False
+ ),
+ create_table_if_not_exists: bool = True,
+ similarity_function: str = "cosine"
+) -> None
+```
+
+Creates a new DynamoDBDocumentStore instance.
+
+**Parameters:**
+
+- **table_name** (str) – Name of the DynamoDB table to store documents in. Created if it
+ does not exist and `create_table_if_not_exists` is `True`.
+- **index_name** (str) – Name of the vector index on the table.
+- **embedding_dimension** (int) – Dimensionality of document embeddings.
+- **region_name** (str | None) – AWS region. Defaults to the boto3 session's configured region.
+- **aws_access_key_id** (Secret) – AWS access key as a `Secret`. Defaults to `AWS_ACCESS_KEY_ID`
+ env var, falling back to the default boto3 credential chain if not set.
+- **aws_secret_access_key** (Secret) – AWS secret key as a `Secret`. Defaults to
+ `AWS_SECRET_ACCESS_KEY` env var.
+- **aws_session_token** (Secret) – AWS session token as a `Secret`, for temporary credentials.
+ Defaults to `AWS_SESSION_TOKEN` env var.
+- **create_table_if_not_exists** (bool) – If `True`, create the table and vector index on
+ first use if they don't already exist.
+- **similarity_function** (str) – Vector similarity function. This integration currently supports
+ only `"cosine"`. DynamoDB itself also offers `DOT_PRODUCT` and `EUCLIDEAN` indexes, but
+ their score conversion is not implemented yet.
+
+**Raises:**
+
+- ValueError – If `similarity_function` is not `"cosine"`.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns the number of documents in the store.
+
+Counts with a consistent `Scan`, so the cost grows with the table size.
+
+**Returns:**
+
+- int – Exact document count.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns documents matching the provided filters.
+
+DynamoDB's `SearchVectors`/`Query` filter expressions can only reference attributes
+declared in the index's `SearchSchema` at index-creation time. Since Haystack's metadata
+filters are arbitrary and not known at index-creation time, filtering here is applied
+client-side after a consistent full-table scan, so the cost grows with the table size.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Haystack metadata filters. If `None`, all documents are returned.
+
+**Returns:**
+
+- list\[Document\] – List of matching `Document` objects.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents to the store.
+
+Documents are written one by one. With `FAIL`, documents preceding the first duplicate
+stay written.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to write.
+- **policy** (DuplicatePolicy) – How to handle duplicates: `OVERWRITE`, `SKIP`, or `FAIL`. `NONE` (the
+ default) behaves like `FAIL`.
+
+**Returns:**
+
+- int – Number of documents written.
+
+**Raises:**
+
+- ValueError – If `documents` contains non-`Document` objects.
+- DuplicateDocumentError – If a duplicate is found and policy is `FAIL`.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes 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 store.
+
+Items are deleted one by one after a consistent scan; the table and its vector index are kept.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents matching the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters selecting the documents to delete. Must not be
+ empty; use `delete_all_documents` to clear the store.
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+**Raises:**
+
+- ValueError – If `filters` is empty.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Merges `meta` into the metadata of all documents matching the filters.
+
+Existing metadata keys not present in `meta` are kept; matching keys are overwritten.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters selecting the documents to update. Must not be empty.
+- **meta** (dict\[str, Any\]) – The metadata fields to set on each matching document.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+**Raises:**
+
+- ValueError – If `filters` is empty.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns the number of documents in the store.
+
+**Returns:**
+
+- int – Exact document count.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns documents matching the provided filters.
+
+See `filter_documents` for how filters are evaluated.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Haystack metadata filters. If `None`, all documents are returned.
+
+**Returns:**
+
+- list\[Document\] – List of matching `Document` objects.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously writes documents to the store.
+
+See `write_documents` for the duplicate handling semantics.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to write.
+- **policy** (DuplicatePolicy) – How to handle duplicates: `OVERWRITE`, `SKIP`, or `FAIL`. `NONE` (the
+ default) behaves like `FAIL`.
+
+**Returns:**
+
+- int – Number of documents written.
+
+**Raises:**
+
+- ValueError – If `documents` contains non-`Document` objects.
+- DuplicateDocumentError – If a duplicate is found and policy is `FAIL`.
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes documents by their IDs.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – List of document IDs to delete.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async() -> None
+```
+
+Asynchronously deletes all documents in the store.
+
+Items are deleted one by one after a consistent scan; the table and its vector index are kept.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents matching the filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters selecting the documents to delete. Must not be
+ empty; use `delete_all_documents_async` to clear the store.
+
+**Returns:**
+
+- int – The number of documents deleted.
+
+**Raises:**
+
+- ValueError – If `filters` 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 filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters selecting the documents to update. Must not be empty.
+- **meta** (dict\[str, Any\]) – The metadata fields to set on each matching document.
+
+**Returns:**
+
+- int – The number of documents updated.
+
+**Raises:**
+
+- ValueError – If `filters` is empty.
+
+#### 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]) -> DynamoDBDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- DynamoDBDocumentStore – Deserialized component.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/e2b.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/e2b.md
new file mode 100644
index 00000000000..88af83f295e
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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-3.2-unstable/integrations-api/edenai.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/edenai.md
new file mode 100644
index 00000000000..57658671939
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/edenai.md
@@ -0,0 +1,267 @@
+---
+title: "Eden AI"
+id: integrations-edenai
+description: "Eden AI integration for Haystack"
+slug: "/integrations-edenai"
+---
+
+
+## haystack_integrations.components.embedders.edenai.document_embedder
+
+### EdenAIDocumentEmbedder
+
+Bases: OpenAIDocumentEmbedder
+
+A component for computing Document embeddings using Eden AI's OpenAI-compatible API.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Eden AI routes embedding requests to many providers (OpenAI, Mistral, Cohere, Google, Jina, and
+more) through a single API key, with EU data residency. Models use Eden AI's `provider/model`
+naming convention, for example `"openai/text-embedding-3-small"` or `"mistral/mistral-embed"`.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.edenai import EdenAIDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = EdenAIDocumentEmbedder(model="mistral/mistral-embed")
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "openai/text-embedding-3-small",
+ "openai/text-embedding-3-large",
+ "mistral/mistral-embed",
+ "cohere/embed-english-v3.0",
+ "google/text-embedding-004",
+]
+
+```
+
+A non-exhaustive list of embedding models supported by this component.
+See the [Eden AI models catalog](https://www.edenai.co/models) for the full list.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "openai/text-embedding-3-small",
+ api_key: Secret = Secret.from_env_var("EDENAI_API_KEY"),
+ api_base_url: str | None = "https://api.edenai.run/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",
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an `EdenAIDocumentEmbedder` component.
+
+**Parameters:**
+
+- **model** (str) – The name of the Eden AI embedding model to use, in `provider/model` format.
+- **api_key** (Secret) – The Eden AI API key. Defaults to the `EDENAI_API_KEY` environment variable.
+- **api_base_url** (str | None) – The Eden AI API base URL.
+- **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 the 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 Eden AI 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.edenai.text_embedder
+
+### EdenAITextEmbedder
+
+Bases: OpenAITextEmbedder
+
+A component for embedding strings using Eden AI's OpenAI-compatible API.
+
+Eden AI routes embedding requests to many providers (OpenAI, Mistral, Cohere, Google, Jina, and
+more) through a single API key, with EU data residency. Models use Eden AI's `provider/model`
+naming convention, for example `"openai/text-embedding-3-small"` or `"mistral/mistral-embed"`.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.edenai import EdenAITextEmbedder
+
+text_embedder = EdenAITextEmbedder(model="mistral/mistral-embed")
+print(text_embedder.run("I love pizza!"))
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "openai/text-embedding-3-small",
+ "openai/text-embedding-3-large",
+ "mistral/mistral-embed",
+ "cohere/embed-english-v3.0",
+ "google/text-embedding-004",
+]
+
+```
+
+A non-exhaustive list of embedding models supported by this component.
+See the [Eden AI models catalog](https://www.edenai.co/models) for the full list.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "openai/text-embedding-3-small",
+ api_key: Secret = Secret.from_env_var("EDENAI_API_KEY"),
+ api_base_url: str | None = "https://api.edenai.run/v3",
+ prefix: str = "",
+ suffix: str = "",
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an `EdenAITextEmbedder` component.
+
+**Parameters:**
+
+- **model** (str) – The name of the Eden AI embedding model to use, in `provider/model` format.
+- **api_key** (Secret) – The Eden AI API key. Defaults to the `EDENAI_API_KEY` environment variable.
+- **api_base_url** (str | None) – The Eden AI API base URL.
+- **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 the 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 Eden AI 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.edenai.chat.chat_generator
+
+### EdenAIChatGenerator
+
+Bases: OpenAIChatGenerator
+
+A chat generator that uses Eden AI's OpenAI-compatible API to generate chat responses.
+
+Eden AI is a unified API that gives access to 500+ AI models from many providers (OpenAI,
+Anthropic, Mistral, Google, Cohere, and more) through a single API key, with built-in
+provider fallback and EU data residency. This makes it a convenient, sovereignty-friendly
+gateway for building LLM and RAG applications with Haystack.
+
+This class extends Haystack's `OpenAIChatGenerator` to talk to Eden AI. It sets the
+`api_base_url` to Eden AI's OpenAI-compatible endpoint and keeps all the standard
+configurations available in the `OpenAIChatGenerator`.
+
+Models are selected using Eden AI's `provider/model` naming convention, for example
+`"openai/gpt-4o-mini"`, `"anthropic/claude-sonnet-4-5"`, or `"mistral/mistral-large-latest"`.
+See the [Eden AI models catalog](https://www.edenai.co/models) for the full list.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.edenai import EdenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = EdenAIChatGenerator(model="mistral/mistral-large-latest")
+response = client.run(messages)
+print(response["replies"][0].text)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("EDENAI_API_KEY"),
+ model: str = "openai/gpt-4o-mini",
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: int | None = None,
+ max_retries: int | None = None,
+ tools: ToolsType | None = None,
+ tools_strict: bool = False,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an `EdenAIChatGenerator` instance.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Eden AI API key. Defaults to the `EDENAI_API_KEY` environment variable.
+- **model** (str) – The model to use, in Eden AI's `provider/model` format
+ (e.g. `"openai/gpt-4o-mini"`, `"anthropic/claude-sonnet-4-5"`, `"mistral/mistral-large-latest"`).
+- **streaming_callback** (StreamingCallbackT | None) – An optional callable invoked with each chunk of a streaming response.
+- **generation_kwargs** (dict\[str, Any\] | None) – Optional keyword arguments passed to the underlying generation API call,
+ such as `max_tokens`, `temperature`, or `top_p`. Eden AI-specific parameters (for example a
+ fallback model) are forwarded as-is to the Eden AI endpoint.
+- **timeout** (int | None) – The maximum time in seconds to wait for a response from the API.
+- **max_retries** (int | None) – The maximum number of times to retry a failed API request.
+- **tools** (ToolsType | None) – An optional list of tools or a Toolset the model can use for function calling.
+- **tools_strict** (bool) – If `True`, enable strict schema adherence for tool calls.
+- **http_client_kwargs** (dict\[str, Any\] | None) – Optional keyword arguments passed to the underlying HTTP client.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/elasticsearch.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/elasticsearch.md
new file mode 100644
index 00000000000..c180b56a0e5
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/elasticsearch.md
@@ -0,0 +1,1201 @@
+---
+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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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
+
+# Requires: pip install sentence-transformers-haystack
+from haystack_integrations.components.embedders.sentence_transformers 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()
+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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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, constructing it if necessary.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the associated asynchronous resources.
+
+#### 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,
+ from_: int = 0,
+ size: int = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Returns unique values for a metadata field, optionally filtered by a search term.
+
+Internally still backed by composite aggregations, which only support cursor-based iteration.
+Reaching offset `from_` therefore requires walking and discarding the first `from_` buckets -
+cost scales with `from_`, not `size`.
+
+**Note**: To keep this signature uniform across document stores, offset-based pagination is
+emulated on top of the cursor by re-fetching and discarding every bucket before `from_` on each
+call, requiring additional search round-trips proportional to `from_`.
+
+**Note**: `total_count` is computed via an approximate cardinality aggregation; for fields with
+very high cardinality it may not be exact.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get unique values for. Can include or omit the
+ "meta." prefix.
+- **search_term** (str | None) – Optional case-insensitive substring to filter the returned values by, matched
+ against the metadata field's own value (not the document content).
+ NOTE: The matching is done with a server-side script to accomplish the substring matching on the value
+ of the field and this operation is quite expensive for a large corpus
+- **from\_** (int) – Offset to start returning values from. Defaults to 0.
+- **size** (int) – The number of unique values to return per page. Defaults to 10.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple of (list of unique values in their original type, total count of distinct values
+ for the field matching `search_term`). Note that filters also narrows down the number of documents
+ against which the search term is matched.
+
+#### 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Asynchronous counterpart of `get_metadata_field_unique_values`.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to get unique values for. Can include or omit the
+ "meta." prefix.
+- **search_term** (str | None) – Optional case-insensitive substring to filter the returned values by, matched
+ against the metadata field's own value (not the document content).
+ NOTE: The matching is done with a server-side script to accomplish the substring matching on the value
+ of the field and this operation is quite expensive for a large corpus
+- **from\_** (int) – Offset to start returning values from. Defaults to 0.
+- **size** (int) – The number of unique values to return per page. Defaults to 10.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple of (list of unique values in their original type, total count of distinct values
+ for the field matching `search_term`). Note that filters also narrows down the number of documents
+ against which the search term is matched.
+
+## haystack_integrations.document_stores.elasticsearch.filters
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/faiss.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/faiss.md
new file mode 100644
index 00000000000..80b4b23d8b2
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/faiss.md
@@ -0,0 +1,469 @@
+---
+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
+# Requires: pip install sentence-transformers-haystack
+from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
+from haystack_integrations.components.embedders.sentence_transformers import 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()
+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(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Returns unique values for a metadata field, optionally filtered by a 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 values, matched as a case-insensitive substring
+ against the metadata field's value.
+- **from\_** (int) – The offset to start returning values from (for pagination).
+- **size** (int) – The maximum number of unique values to return.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing list of unique values (in their original type) and total count of
+ unique values.
+
+#### 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-3.2-unstable/integrations-api/falkordb.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/falkordb.md
new file mode 100644
index 00000000000..7408bda4fcd
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/falkordb.md
@@ -0,0 +1,566 @@
+---
+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).
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+## 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+## 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### 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.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Delete all documents from the graph.
+
+#### 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 dict.
+
+**Returns:**
+
+- int – Number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Update metadata fields on all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dict selecting which documents to update.
+- **meta** (dict\[str, Any\]) – Metadata fields to set. Keys may include or omit the `meta.` prefix.
+
+**Returns:**
+
+- int – Number of documents updated.
+
+#### 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 dict.
+
+**Returns:**
+
+- int – Integer count of matching document nodes.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Return the number of unique values for each metadata field among matching documents.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack filter dict. Pass an empty dict to count across all documents.
+- **metadata_fields** (list\[str\]) – List of metadata field names. May include or omit the `meta.` prefix.
+
+**Returns:**
+
+- dict\[str, int\] – Dict mapping each field name (without `meta.` prefix) to its unique value count.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Return type information for each metadata field present on document nodes.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – Dict mapping field names to a `{"type": str) – Metadata field name. May include or omit the `meta.` prefix.
+
+**Returns:**
+
+- dict\[str, Any\] – Dict with keys `"min"` and `"max"`. Values are `None` when no documents
+ have a non-null value for the field.
+
+#### 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Return distinct values for the given metadata field with optional filtering and pagination.
+
+**Note**: values of different types are kept distinct even when they compare equal in Python
+(e.g. the int `1`, the bool `True` and the str `"1"` are returned as three separate values), with
+one exception: Cypher's `DISTINCT` treats a whole-number float (e.g. `1.0`) as identical to a
+numerically equal int (`1`), so those two collapse into a single value. Floats with a fractional
+part (e.g. `1.5`) are unaffected.
+
+**Parameters:**
+
+- **metadata_field** (str) – Metadata field name. May include or omit the `meta.` prefix.
+- **search_term** (str | None) – Optional case-insensitive substring filter applied to the metadata
+ field's own value.
+- **from\_** (int) – The offset for pagination (0-based).
+- **size** (int) – Maximum number of values to return per page. Defaults to 10.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – Tuple of `(values, total_count)`. Values are returned in their original type.
+ `total_count` is the number of distinct values matching the filter, independent of
+ pagination.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/fastembed.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/fastembed.md
new file mode 100644
index 00000000000..e79d1239d20
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/fastembed.md
@@ -0,0 +1,781 @@
+---
+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)}")
+```
+
+Running on GPU:
+
+```python
+# NVIDIA GPU (requires onnxruntime-gpu)
+doc_embedder = FastembedDocumentEmbedder(
+ model="BAAI/bge-small-en-v1.5",
+ model_kwargs={"providers": ["CUDAExecutionProvider"]},
+)
+
+# Intel GPU / XPU (requires onnxruntime-openvino)
+doc_embedder = FastembedDocumentEmbedder(
+ model="BAAI/bge-small-en-v1.5",
+ model_kwargs={"providers": ["OpenVINOExecutionProvider"]},
+)
+```
+
+#### __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",
+ 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 `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.
+- **model_kwargs** (dict\[str, Any\] | None) – Dictionary containing additional keyword arguments to pass to the Fastembed model,
+ such as `providers` (e.g. `["CUDAExecutionProvider"]` for NVIDIA GPU or
+ `["OpenVINOExecutionProvider"]` for Intel GPU/XPU), `cuda`, or `device_ids`.
+
+#### 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"Number of non-zero elements: {len(result['documents'][0].sparse_embedding.indices)}")
+```
+
+#### __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 a FastembedSparseDocumentEmbedder 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:
+- `sparse_embedding`: The `SparseEmbedding` 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"]
+```
+
+Running on GPU:
+
+```python
+# NVIDIA GPU (requires onnxruntime-gpu)
+text_embedder = FastembedTextEmbedder(
+ model="BAAI/bge-small-en-v1.5",
+ model_kwargs={"providers": ["CUDAExecutionProvider"]},
+)
+
+# Intel GPU / XPU (requires onnxruntime-openvino)
+text_embedder = FastembedTextEmbedder(
+ model="BAAI/bge-small-en-v1.5",
+ model_kwargs={"providers": ["OpenVINOExecutionProvider"]},
+)
+```
+
+#### __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,
+ model_kwargs: dict[str, Any] | None = None,
+) -> 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`.
+- **model_kwargs** (dict\[str, Any\] | None) – Dictionary containing additional keyword arguments to pass to the Fastembed model,
+ such as `providers` (e.g. `["CUDAExecutionProvider"]` for NVIDIA GPU or
+ `["OpenVINOExecutionProvider"]` for Intel GPU/XPU), `cuda`, or `device_ids`.
+
+#### 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
+```
+
+Running on GPU:
+
+```python
+# NVIDIA GPU (requires onnxruntime-gpu)
+ranker = FastembedLateInteractionRanker(
+ model_name="colbert-ir/colbertv2.0",
+ model_kwargs={"providers": ["CUDAExecutionProvider"]},
+)
+
+# Intel GPU / XPU (requires onnxruntime-openvino)
+ranker = FastembedLateInteractionRanker(
+ model_name="colbert-ir/colbertv2.0",
+ model_kwargs={"providers": ["OpenVINOExecutionProvider"]},
+)
+```
+
+#### __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,
+ model_kwargs: dict[str, Any] | 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.
+- **model_kwargs** (dict\[str, Any\] | None) – Dictionary containing additional keyword arguments to pass to the Fastembed model,
+ such as `providers` (e.g. `["CUDAExecutionProvider"]` to run on an NVIDIA GPU or
+ `["OpenVINOExecutionProvider"]` to run on an Intel GPU), `cuda`, or `device_ids`.
+
+#### 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
+```
+
+Running on GPU:
+
+```python
+# NVIDIA GPU (requires onnxruntime-gpu)
+ranker = FastembedRanker(
+ model_name="Xenova/ms-marco-MiniLM-L-6-v2",
+ model_kwargs={"providers": ["CUDAExecutionProvider"]},
+)
+
+# Intel GPU / XPU (requires onnxruntime-openvino)
+ranker = FastembedRanker(
+ model_name="Xenova/ms-marco-MiniLM-L-6-v2",
+ model_kwargs={"providers": ["OpenVINOExecutionProvider"]},
+)
+```
+
+#### __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,
+ model_kwargs: dict[str, Any] | 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.
+- **model_kwargs** (dict\[str, Any\] | None) – Dictionary containing additional keyword arguments to pass to the Fastembed model,
+ such as `providers` (e.g. `["CUDAExecutionProvider"]` to run on an NVIDIA GPU or
+ `["OpenVINOExecutionProvider"]` to run on an Intel GPU), `cuda`, or `device_ids`.
+
+#### 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-3.2-unstable/integrations-api/firecrawl.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/firecrawl.md
new file mode 100644
index 00000000000..52f4c6427e3
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/firecrawl.md
@@ -0,0 +1,220 @@
+---
+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 FirecrawlCrawler
+
+crawler = FirecrawlCrawler(
+ api_key=Secret.from_env_var("FIRECRAWL_API_KEY"),
+ params={"limit": 5},
+)
+crawler.warm_up()
+
+result = crawler.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 FirecrawlCrawler.
+
+**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 synchronous Firecrawl client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the asynchronous Firecrawl client.
+
+## 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 synchronous Firecrawl client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Warm up the asynchronous Firecrawl client.
+
+#### 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-3.2-unstable/integrations-api/funasr.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/funasr.md
new file mode 100644
index 00000000000..e3a1348295a
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/funasr.md
@@ -0,0 +1,157 @@
+---
+title: "FunASR"
+id: integrations-funasr
+description: "FunASR speech-to-text integration for Haystack"
+slug: "/integrations-funasr"
+---
+
+
+## haystack_integrations.components.audio.funasr.transcriber
+
+### FunASRTranscriber
+
+Transcribes audio files to Documents using [FunASR](https://github.com/modelscope/FunASR).
+
+FunASR is an open-source speech recognition toolkit from Alibaba DAMO Academy.
+It supports 50+ languages, speaker diarization, and timestamp extraction, and runs
+entirely locally — no API key required.
+
+Models are downloaded from ModelScope on first use and cached in `~/.cache/modelscope`.
+
+**Usage Example:**
+
+```python
+from haystack_integrations.components.audio.funasr import FunASRTranscriber
+
+transcriber = FunASRTranscriber()
+result = transcriber.run(sources=["speech.wav", "interview.mp3"])
+documents = result["documents"]
+```
+
+**Speaker diarization and punctuation:**
+
+```python
+from haystack.utils import ComponentDevice
+
+transcriber = FunASRTranscriber(
+ model="paraformer-zh",
+ vad_model="fsmn-vad",
+ punc_model="ct-punc",
+ spk_model="cam++",
+ device=ComponentDevice.from_str("cuda"),
+)
+```
+
+**SenseVoice with inverse text normalisation:**
+
+```python
+transcriber = FunASRTranscriber(
+ model="iic/SenseVoiceSmall",
+ generation_kwargs={"use_itn": True, "merge_vad": True, "language": "auto"},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "iic/SenseVoiceSmall",
+ vad_model: str | None = "fsmn-vad",
+ punc_model: str | None = "ct-punc",
+ spk_model: str | None = None,
+ device: ComponentDevice | None = None,
+ batch_size_s: int = 300,
+ store_full_path: bool = False,
+ generation_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Create a FunASRTranscriber component.
+
+**Parameters:**
+
+- **model** (str) – FunASR model name or local path. Defaults to `"iic/SenseVoiceSmall"`,
+ a multilingual model supporting 50+ languages that is 5-10x faster than Whisper.
+ Alternatives include `"paraformer-zh"` (Chinese) or `"paraformer-en"` (English).
+ Browse available models at https://modelscope.github.io/FunASR/model-selection.html.
+- **vad_model** (str | None) – Voice activity detection model used to split long audio into segments.
+ Set to `None` to process the audio as a single stream.
+ Browse available VAD models at https://www.modelscope.cn/models.
+- **punc_model** (str | None) – Punctuation restoration model. Set to `None` to disable punctuation.
+ Browse available punctuation models at https://www.modelscope.cn/models.
+- **spk_model** (str | None) – Speaker diarization model (e.g. `"cam++"`). When set, a `"speakers"`
+ key is included in the Document metadata. Defaults to `None` (diarization disabled).
+ Browse available speaker diarization models at https://www.modelscope.cn/models.
+- **device** (ComponentDevice | None) – The device to run inference on. If `None`, the default device is selected
+ automatically. Use `ComponentDevice.from_str("cuda")` for GPU inference.
+- **batch_size_s** (int) – Batch size in seconds for VAD-segmented audio. Larger values
+ improve throughput at the cost of memory.
+- **store_full_path** (bool) – If `True`, store the full audio file path in Document metadata.
+ If `False` (default), store only the file name.
+- **generation_kwargs** (dict\[str, Any\] | None) – Extra keyword arguments forwarded to `AutoModel.generate()`.
+ Use this for model-specific options such as `use_itn=True` or `merge_vad=True`
+ for SenseVoice, or `hotword="..."` for contextual recognition.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Load the FunASR model into memory.
+
+Models are downloaded from ModelScope on first call and cached locally.
+This method is idempotent — calling it multiple times is safe.
+
+#### 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]) -> FunASRTranscriber
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- FunASRTranscriber – Deserialized component.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Transcribe audio sources to Documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – Audio file paths (`str` or `Path`) or `ByteStream` objects.
+ Supported formats: WAV, MP3, FLAC, OGG, M4A, AAC, and any format that
+ FunASR's underlying audio backend (soundfile/ffmpeg) can decode.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Metadata to attach to the produced Documents. Pass a single dict
+ to apply the same metadata to all Documents, or a list aligned with `sources`.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Dictionary with key `"documents"` — one `Document` per source whose
+ `content` holds the full transcript text.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/github.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/github.md
new file mode 100644
index 00000000000..5fa0be2f569
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/github.md
@@ -0,0 +1,620 @@
+---
+title: "GitHub"
+id: integrations-github
+description: "GitHub integration for Haystack"
+slug: "/integrations-github"
+---
+
+
+## haystack_integrations.components.connectors.github.file_editor
+
+### Command
+
+Bases: str, Enum
+
+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"
+ }
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+ repo: str | None = None,
+ branch: str = "main",
+ raise_on_failure: bool = True
+) -> None
+```
+
+Initialize the component.
+
+**Parameters:**
+
+- **github_token** (Secret) – GitHub personal access token for API authentication
+- **repo** (str | None) – Default repository in owner/repo format
+- **branch** (str) – Default branch to work with
+- **raise_on_failure** (bool) – If True, raises exceptions on API errors
+
+**Raises:**
+
+- TypeError – If github_token is not a Secret
+
+#### run
+
+```python
+run(
+ command: Command | str,
+ payload: dict[str, Any],
+ repo: str | None = None,
+ branch: str | None = None,
+) -> dict[str, str]
+```
+
+Process GitHub file operations.
+
+**Parameters:**
+
+- **command** (Command | str) – Operation to perform ("edit", "undo", "create", "delete")
+- **payload** (dict\[str, Any\]) – Dictionary containing command-specific parameters
+- **repo** (str | None) – Repository in owner/repo format (overrides default if provided)
+- **branch** (str | None) – Branch to perform operations on (overrides default if provided)
+
+**Returns:**
+
+- dict\[str, str\] – Dictionary containing operation result
+
+**Raises:**
+
+- ValueError – If command is not a valid Command enum value
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GitHubFileEditor
+```
+
+Deserialize the component from a dictionary.
+
+## 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"])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+ raise_on_failure: bool = True,
+ retry_attempts: int = 2
+) -> None
+```
+
+Initialize the component.
+
+**Parameters:**
+
+- **github_token** (Secret) – GitHub personal access token for API authentication as a Secret
+- **raise_on_failure** (bool) – If True, raises exceptions on API errors
+- **retry_attempts** (int) – Number of retry attempts for failed requests
+
+#### 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]) -> GitHubIssueCommenter
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- GitHubIssueCommenter – Deserialized component.
+
+#### run
+
+```python
+run(url: str, comment: str) -> dict
+```
+
+Post a comment to a GitHub issue.
+
+**Parameters:**
+
+- **url** (str) – GitHub issue URL
+- **comment** (str) – Comment text to post
+
+**Returns:**
+
+- dict – Dictionary containing success status
+
+## 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)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ github_token: Secret | None = None,
+ raise_on_failure: bool = True,
+ retry_attempts: int = 2
+) -> None
+```
+
+Initialize the component.
+
+**Parameters:**
+
+- **github_token** (Secret | None) – GitHub personal access token for API authentication as a Secret
+- **raise_on_failure** (bool) – If True, raises exceptions on API errors
+- **retry_attempts** (int) – Number of retry attempts for failed requests
+
+#### 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]) -> GitHubIssueViewer
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- GitHubIssueViewer – Deserialized component.
+
+#### run
+
+```python
+run(url: str) -> dict
+```
+
+Process a GitHub issue URL and return documents.
+
+**Parameters:**
+
+- **url** (str) – GitHub issue URL
+
+**Returns:**
+
+- dict – Dictionary containing list of documents
+
+## 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
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+ raise_on_failure: bool = True
+) -> None
+```
+
+Initialize the component.
+
+**Parameters:**
+
+- **github_token** (Secret) – GitHub personal access token for authentication (from the fork owner)
+- **raise_on_failure** (bool) – If True, raises exceptions on API errors
+
+#### run
+
+```python
+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.
+
+**Parameters:**
+
+- **issue_url** (str) – URL of the GitHub issue to link the PR to
+- **title** (str) – Title of the pull request
+- **branch** (str) – Name of the branch in your fork where changes are implemented
+- **base** (str) – Name of the branch in the original repo you want to merge into
+- **body** (str) – Additional content for the pull request description
+- **draft** (bool) – Whether to create a draft pull request
+
+**Returns:**
+
+- dict\[str, str\] – Dictionary containing operation result
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GitHubPRCreator
+```
+
+Deserialize the component from a dictionary.
+
+## 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"
+```
+
+#### __init__
+
+```python
+__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
+) -> None
+```
+
+Initialize the component.
+
+**Parameters:**
+
+- **github_token** (Secret) – GitHub personal access token for API authentication
+- **raise_on_failure** (bool) – If True, raises exceptions on API errors
+- **wait_for_completion** (bool) – If True, waits until fork is fully created
+- **max_wait_seconds** (int) – Maximum time to wait for fork completion in seconds
+- **poll_interval** (int) – Time between status checks in seconds
+- **auto_sync** (bool) – If True, syncs fork with original repository if it already exists
+- **create_branch** (bool) – If True, creates a fix branch based on the issue number
+
+#### 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]) -> GitHubRepoForker
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- GitHubRepoForker – Deserialized component.
+
+#### run
+
+```python
+run(url: str) -> dict
+```
+
+Process a GitHub issue URL and create or sync a fork of the repository.
+
+**Parameters:**
+
+- **url** (str) – GitHub issue URL
+
+**Returns:**
+
+- dict – Dictionary containing repository path in owner/repo format
+
+## haystack_integrations.components.connectors.github.repo_viewer
+
+### GitHubItem
+
+Represents an item (file or directory) in a GitHub repository
+
+### 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)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ github_token: Secret | None = None,
+ raise_on_failure: bool = True,
+ max_file_size: int = 1000000,
+ repo: str | None = None,
+ branch: str = "main"
+) -> None
+```
+
+Initialize the component.
+
+**Parameters:**
+
+- **github_token** (Secret | None) – GitHub personal access token for API authentication
+- **raise_on_failure** (bool) – If True, raises exceptions on API errors
+- **max_file_size** (int) – Maximum file size in bytes to fetch (default: 1MB)
+- **repo** (str | None) – Repository in format "owner/repo"
+- **branch** (str) – Git reference (branch, tag, commit) to use
+
+#### 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]) -> GitHubRepoViewer
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- GitHubRepoViewer – Deserialized component.
+
+#### run
+
+```python
+run(
+ path: str, repo: str | None = None, branch: str | None = None
+) -> dict[str, list[Document]]
+```
+
+Process a GitHub repository path and return documents.
+
+**Parameters:**
+
+- **repo** (str | None) – Repository in format "owner/repo"
+- **path** (str) – Path within repository (default: root)
+- **branch** (str | None) – Git reference (branch, tag, commit) to use
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Dictionary containing list of documents
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/google_ai.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/google_ai.md
new file mode 100644
index 00000000000..871ae8eccdb
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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("str) – The Drive API base URL. Defaults to `https://www.googleapis.com/drive/v3`.
+- **timeout** (float) – The HTTP timeout in seconds for each request to the Drive API.
+- **max_retries** (int) – The maximum number of retries for throttled (HTTP 429) or transient server errors.
+- **max_concurrent_requests** (int) – The maximum number of files fetched concurrently by `run_async`. Bounds
+ the in-flight requests to Drive to avoid tripping its rate limits. Has no effect on the synchronous
+ `run`, which fetches files one at a time.
+- **raise_on_failure** (bool) – If `True`, a fetch failure raises an exception. If `False`, the failure is
+ logged and the file is skipped, so the other files are still returned.
+- **export_mime_types** (dict\[str, str\] | None) – Optional mapping of native Google mime type (for example
+ `application/vnd.google-apps.document`) to the mime type to export it as. Replaces the default mapping
+ (Docs/Sheets/Slides to DOCX/XLSX/PPTX). Drive caps a single export at 10 MB.
+
+**Raises:**
+
+- GoogleDriveConfigError – If `max_retries` is negative or `max_concurrent_requests` is not positive.
+
+#### run
+
+```python
+run(
+ access_token: str | Secret, targets: list[Document | str]
+) -> dict[str, list[ByteStream]]
+```
+
+Fetch the content of Google Drive files and return them as `ByteStream`s.
+
+**Parameters:**
+
+- **access_token** (str | Secret) – A delegated Google OAuth bearer token for the user whose files are fetched, typically
+ wired from an upstream `OAuthTokenResolver` (which emits a plain `str`). A `Secret` is also accepted and
+ resolved internally.
+- **targets** (list\[Document | str\]) – The files to fetch, as either `Document`s emitted by `GoogleDriveRetriever` or raw Google
+ Drive file ids / URLs (the two may also be mixed in one list). For a `Document`, the `file_id` in its
+ meta is fetched and `mime_type`, `file_name`, and `web_url` are reused when present. For a raw string,
+ the file id is parsed from a Drive URL (or used as-is) and the file's mime type is looked up. Folders
+ and non-downloadable Google types are skipped.
+
+**Returns:**
+
+- dict\[str, list\[ByteStream\]\] – A dictionary with a `streams` key holding the fetched content as `ByteStream` objects. Each
+ stream's `meta` carries `file_id`, `web_url`, `file_name`, and `content_type`.
+
+**Raises:**
+
+- GoogleDriveConfigError – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+ `Secret` that does not resolve to a string.
+- GoogleDriveRequestError – If a fetch fails and `raise_on_failure` is `True`.
+
+#### run_async
+
+```python
+run_async(
+ access_token: str | Secret, targets: list[Document | str]
+) -> dict[str, list[ByteStream]]
+```
+
+Asynchronously fetch the content of Google Drive files and return them as `ByteStream`s.
+
+**Parameters:**
+
+- **access_token** (str | Secret) – A delegated Google OAuth bearer token for the user whose files are fetched, typically
+ wired from an upstream `OAuthTokenResolver` (which emits a plain `str`). A `Secret` is also accepted and
+ resolved internally.
+- **targets** (list\[Document | str\]) – The files to fetch, as either `Document`s emitted by `GoogleDriveRetriever` or raw Google
+ Drive file ids / URLs (the two may also be mixed in one list). For a `Document`, the `file_id` in its
+ meta is fetched and `mime_type`, `file_name`, and `web_url` are reused when present. For a raw string,
+ the file id is parsed from a Drive URL (or used as-is) and the file's mime type is looked up. Folders
+ and non-downloadable Google types are skipped.
+
+**Returns:**
+
+- dict\[str, list\[ByteStream\]\] – A dictionary with a `streams` key holding the fetched content as `ByteStream` objects. Each
+ stream's `meta` carries `file_id`, `web_url`, `file_name`, and `content_type`.
+
+**Raises:**
+
+- GoogleDriveConfigError – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+ `Secret` that does not resolve to a string.
+- GoogleDriveRequestError – If a fetch fails and `raise_on_failure` is `True`.
+
+#### 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]) -> GoogleDriveFetcher
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- GoogleDriveFetcher – The deserialized component instance.
+
+## haystack_integrations.components.retrievers.google_drive.retriever
+
+### GoogleDriveRetriever
+
+Retrieves files from Google Drive via the Drive API v3 search (`files.list`) endpoint.
+
+Given a query, the retriever runs a full-text search over the user's Drive (and optionally shared
+drives) and maps each matching file to a Haystack `Document`. By default, each `Document` carries
+resource metadata (`file_name`, `file_id`, `web_url`, `mime_type`, `file_extension`, author, and
+timestamps) and uses the file `description` or `name` as `content`, because the Drive search API does
+not return a text snippet. Set `include_content=True` to additionally export native Google
+Docs/Sheets/Slides to text and use that as the `Document` content. Binary files (PDF, DOCX, ...) are
+never downloaded. Compose a downstream fetcher/converter on the returned `web_url`/`file_id` when full
+file content is needed.
+
+The retriever takes a per-user `access_token` as a run input, typically wired from an upstream
+`OAuthResolver`. The token must carry a delegated Google OAuth scope that allows search
+(for example `https://www.googleapis.com/auth/drive.readonly`). The metadata-only
+`drive.metadata.readonly` scope cannot search file content or export documents.
+
+### Usage example
+
+```python
+from haystack import Pipeline
+from haystack.utils import Secret
+from haystack_integrations.components.connectors.oauth import OAuthResolver
+from haystack_integrations.utils.oauth import RefreshTokenSource
+from haystack_integrations.components.retrievers.google_drive import GoogleDriveRetriever
+
+pipeline = Pipeline()
+pipeline.add_component(
+ "resolver",
+ OAuthResolver(
+ token_source=RefreshTokenSource(
+ token_url="https://oauth2.googleapis.com/token",
+ client_id="aaa-bbb-ccc",
+ refresh_token=Secret.from_env_var("GOOGLE_REFRESH_TOKEN"),
+ scopes=["https://www.googleapis.com/auth/drive.readonly"],
+ ),
+ ),
+)
+pipeline.add_component("retriever", GoogleDriveRetriever(top_k=5))
+pipeline.connect("resolver.access_token", "retriever.access_token")
+
+result = pipeline.run({"retriever": {"query": "quarterly roadmap"}})
+documents = result["retriever"]["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ include_content: bool = False,
+ top_k: int = 10,
+ query_filter: str | None = None,
+ include_shared_drives: bool = False,
+ order_by: str | None = None,
+ fields: list[str] | None = None,
+ api_base_url: str = DEFAULT_API_BASE_URL,
+ timeout: float = 30.0,
+ max_retries: int = 3
+) -> None
+```
+
+Initialize the retriever.
+
+**Parameters:**
+
+- **include_content** (bool) – When `True`, native Google Docs/Sheets/Slides are exported to text and the
+ result becomes the `Document` content. Binary files are never downloaded. When `False` (the
+ default), `content` is the file `description` or `name` and no export request is made.
+- **top_k** (int) – The maximum number of documents to return. Maps to the Drive `pageSize` and is
+ paginated when it exceeds a single page.
+- **query_filter** (str | None) – Optional Drive query clause AND-ed with the full-text search term, for example
+ `"mimeType != 'application/vnd.google-apps.folder'"` or `"'bool) – When `True`, the search spans shared drives as well as the user's My
+ Drive (sets `includeItemsFromAllDrives`, `supportsAllDrives`, and `corpora=allDrives`).
+- **order_by** (str | None) – Optional Drive `orderBy` expression, for example `"modifiedTime desc"`.
+- **fields** (list\[str\] | None) – Optional list of file properties to request via the Drive `fields` selection.
+ Defaults to a standard set covering the returned metadata.
+- **api_base_url** (str) – The Drive API base URL. Defaults to `https://www.googleapis.com/drive/v3`.
+- **timeout** (float) – The HTTP timeout in seconds for each request to the Drive API.
+- **max_retries** (int) – The maximum number of retries on HTTP 429 (rate limit), 500, 502, 503,
+ or 504 responses. Set to 0 to disable retries.
+
+**Raises:**
+
+- GoogleDriveConfigError – If `top_k` is not positive or `max_retries` is negative.
+
+#### run
+
+```python
+run(
+ query: str, access_token: str | Secret, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Search Google Drive and return the matching documents.
+
+**Parameters:**
+
+- **query** (str) – The search query string, matched against the full text of files via
+ `fullText contains`.
+- **access_token** (str | Secret) – A delegated Google OAuth bearer token for the user whose Drive is searched,
+ typically wired from an upstream `OAuthResolver` (which emits a plain `str`). A `Secret` is also
+ accepted and resolved internally.
+- **top_k** (int | None) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- GoogleDriveConfigError – If `access_token` is a `Secret` that does not resolve to a string.
+- GoogleDriveRequestError – If the Drive API returns an error response.
+- httpx.HTTPError – If a network-level error occurs (for example a timeout or connection failure).
+
+#### run_async
+
+```python
+run_async(
+ query: str, access_token: str | Secret, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously search Google Drive and return the matching documents.
+
+**Parameters:**
+
+- **query** (str) – The search query string, matched against the full text of files via
+ `fullText contains`.
+- **access_token** (str | Secret) – A delegated Google OAuth bearer token for the user whose Drive is searched,
+ typically wired from an upstream `OAuthResolver` (which emits a plain `str`). A `Secret` is also
+ accepted and resolved internally.
+- **top_k** (int | None) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- GoogleDriveConfigError – If `access_token` is a `Secret` that does not resolve to a string.
+- GoogleDriveRequestError – If the Drive API returns an error response.
+- httpx.HTTPError – If a network-level error occurs (for example a timeout or connection failure).
+
+#### 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]) -> GoogleDriveRetriever
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- GoogleDriveRetriever – The deserialized component instance.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/google_genai.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/google_genai.md
new file mode 100644
index 00000000000..9bde84f3962
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/google_genai.md
@@ -0,0 +1,1159 @@
+---
+title: "Google GenAI"
+id: integrations-google-genai
+description: "Google GenAI integration for Haystack"
+slug: "/integrations-google-genai"
+---
+
+
+## haystack_integrations.components.embedders.google_genai.document_embedder
+
+### GoogleGenAIDocumentEmbedder
+
+Computes document embeddings using Google AI models.
+
+### Authentication examples
+
+**1. Gemini Developer API (API Key Authentication)**
+
+````python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+document_embedder = GoogleGenAIDocumentEmbedder(model="gemini-embedding-001")
+
+**2. Vertex AI (Application Default Credentials)**
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
+
+# Using Application Default Credentials (requires gcloud auth setup)
+document_embedder = GoogleGenAIDocumentEmbedder(
+ 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 GoogleGenAIDocumentEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+document_embedder = GoogleGenAIDocumentEmbedder(
+ api="vertex",
+ model="gemini-embedding-001"
+)
+```
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = GoogleGenAIDocumentEmbedder()
+
+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,
+ model: str = "gemini-embedding-001",
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n",
+ config: dict[str, Any] | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None
+) -> None
+```
+
+Creates an GoogleGenAIDocumentEmbedder 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.
+- **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.
+- **timeout** (float | None) – The timeout in seconds for the underlying Google GenAI client network requests.
+- **max_retries** (int | None) – The maximum number of retries for the underlying Google GenAI client network requests.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Google Gen AI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Google Gen AI client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Google Gen AI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Google Gen AI 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]) -> 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,
+ timeout: float | None = None,
+ max_retries: int | 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 and are guaranteed to stay within it.
+ If None, file paths are treated as absolute paths with no containment check.
+ If document metadata, in particular `file_path_meta_field`, may be influenced by untrusted input,
+ set `root_path` to a dedicated data directory so that path-traversal beyond it is rejected.
+- **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.
+- **timeout** (float | None) – The timeout in seconds for the underlying Google GenAI client network requests.
+- **max_retries** (int | None) – The maximum number of retries for the underlying Google GenAI client network requests.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Google Gen AI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Google Gen AI client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Google Gen AI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Google Gen AI 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]) -> GoogleGenAIMultimodalDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- GoogleGenAIMultimodalDocumentEmbedder – 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.
+
+**Raises:**
+
+- TypeError – If the input is not a list of `Documents`.
+- ValueError – If a document is missing the file path metadata field, its file path escapes `root_path`, or its
+ MIME type is not supported.
+- RuntimeError – If the conversion of some documents fails.
+
+#### 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.
+
+**Raises:**
+
+- TypeError – If the input is not a list of `Documents`.
+- ValueError – If a document is missing the file path metadata field, its file path escapes `root_path`, or its
+ MIME type is not supported.
+- RuntimeError – If the conversion of some documents fails.
+
+## 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,
+ timeout: float | None = None,
+ max_retries: int | 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.
+- **timeout** (float | None) – The timeout in seconds for the underlying Google GenAI client network requests.
+- **max_retries** (int | None) – The maximum number of retries for the underlying Google GenAI client network requests.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Google Gen AI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Google Gen AI client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Google Gen AI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Google Gen AI 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]) -> 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-3.8-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 and Gemini 3 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-3.8-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-3.8-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-3.8-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-3.8-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-3.8-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-3.8-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.8-flash",
+ "gemini-3.7-flash",
+ "gemini-3.6-flash",
+ "gemini-3.5-flash",
+ "gemini-3.5-flash-lite",
+ "gemini-3.1-pro-preview",
+ "gemini-3.1-flash-lite",
+ "gemini-3-flash-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-3.8-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-3.8-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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Google Gen AI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Google Gen AI client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Google Gen AI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Google Gen AI 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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – Configuration for generation. These are merged per key with the
+ `generation_kwargs` passed during component initialization: keys provided here take precedence,
+ keys set only at initialization are kept. 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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – Configuration for generation. These are merged per key with the
+ `generation_kwargs` passed during component initialization: keys provided here take precedence,
+ keys set only at initialization are kept. 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.
+
+## haystack_integrations.token_counters.google_genai.token_counter
+
+### GoogleGenAITokenCounter
+
+Counts input tokens for Gemini models with Google's token counting API.
+
+Unlike local token counters, this counter sends the input to the `countTokens` endpoint of the Google Gen AI
+SDK, so the returned count includes the model-specific formatting Gemini applies to messages.
+
+Inputs are assembled exactly as `GoogleGenAIChatGenerator` sends them: a leading system message becomes the
+system instruction and the remaining messages become the request contents.
+
+### Backend support for system instructions and tools
+
+The Google Gen AI SDK only accepts a system instruction and tool schemas on `countTokens` when the client
+targets Vertex AI. On the Gemini Developer API, a leading system message is therefore measured as a user turn,
+which gives a close approximation rather than the exact count, and tools raise a `ValueError` instead of
+silently returning a count that omits their schemas. Counting plain messages works on either backend.
+
+## Usage Example:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.token_counters.google_genai import GoogleGenAITokenCounter
+
+counter = GoogleGenAITokenCounter("gemini-3.8-flash")
+messages = [ChatMessage.from_user("Hello, how are you?")]
+token_count = counter.count(messages)
+print(f"Token count: {token_count}")
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ *,
+ 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,
+ timeout: float | None = None,
+ max_retries: int | None = None
+) -> None
+```
+
+Initialize the counter.
+
+**Parameters:**
+
+- **model** (str) – The model whose tokenization should be used. Token counts are model-specific, so count
+ against the same model you intend to generate with.
+- **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.
+- **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.
+- **timeout** (float | None) – Timeout for Google Gen AI client calls. If not set, it defaults to the default set by the
+ Google Gen AI 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 Gen AI client.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Google Gen AI client.
+
+#### count
+
+```python
+count(messages: list[ChatMessage], tools: ToolsType | None = None) -> int
+```
+
+Return the number of input tokens Gemini will use for the given messages and tools.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – The messages to measure. A leading system message is measured as the system instruction on
+ Vertex AI and as a user turn on the Gemini Developer API, which cannot measure system instructions.
+- **tools** (ToolsType | None) – Tools whose schemas are sent alongside the messages, and so consume tokens too.
+
+**Returns:**
+
+- int – The token count, or `0` when there is nothing to measure.
+
+**Raises:**
+
+- ValueError – If tools are passed while targeting the Gemini Developer API, which cannot measure them.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Google Gen AI client and its underlying HTTP resources.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the counter.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary representation of the counter.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAITokenCounter
+```
+
+Deserialize the counter.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- GoogleGenAITokenCounter – The deserialized counter.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/google_vertex.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/google_vertex.md
new file mode 100644
index 00000000000..78cac5ef8fc
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/google_vertex.md
@@ -0,0 +1,1102 @@
+---
+title: "Google Vertex"
+id: integrations-google-vertex
+description: "Google Vertex integration for Haystack"
+slug: "/integrations-google-vertex"
+---
+
+
+## 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,
+```
+
+#### __init__
+
+```python
+__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).
+
+**Parameters:**
+
+- **model** (Literal['text-embedding-004', 'text-embedding-005', 'textembedding-gecko-multilingual@001', 'text-multilingual-embedding-002', 'text-embedding-large-exp-03-07']) – Name of the model to use.
+- **task_type** (Literal['RETRIEVAL_DOCUMENT', 'RETRIEVAL_QUERY', 'SEMANTIC_SIMILARITY', 'CLASSIFICATION', 'CLUSTERING', 'QUESTION_ANSWERING', 'FACT_VERIFICATION', 'CODE_RETRIEVAL_QUERY']) – 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** (Optional\[Secret\]) – The default location to use when making API calls, if not set uses us-central-1.
+- **gcp_project_id** (Optional\[Secret\]) – ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- **batch_size** (int) – The number of documents to process in a single batch.
+- **max_tokens_total** (int) – The maximum number of tokens to process in total.
+- **time_sleep** (int) – The time to sleep between retries in seconds.
+- **retries** (int) – The number of retries in case of failure.
+- **progress_bar** (bool) – Whether to display a progress bar during processing.
+- **truncate_dim** (Optional\[int\]) – The dimension to truncate the embeddings to, if specified.
+- **meta_fields_to_embed** (Optional\[list\[str\]\]) – A list of metadata fields to include in the embeddings.
+- **embedding_separator** (str) – The separator to use between different embeddings.
+
+**Raises:**
+
+- ValueError – If the provided model is not in the list of supported models.
+
+#### get_text_embedding_input
+
+```python
+get_text_embedding_input(batch: list[Document]) -> list[TextEmbeddingInput]
+```
+
+Converts a batch of Document objects into a list of TextEmbeddingInput objects.
+
+Args:
+batch (List[Document]): A list of Document objects to be converted.
+
+Returns:
+List\[TextEmbeddingInput\]: A list of TextEmbeddingInput objects created from the input documents.
+
+#### embed_batch_by_smaller_batches
+
+```python
+embed_batch_by_smaller_batches(
+ batch: list[str], subbatch: list[str] = 1
+) -> list[list[float]]
+```
+
+Embeds a batch of text strings by dividing them into smaller sub-batches.
+Args:
+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.
+
+#### embed_batch
+
+```python
+embed_batch(batch: list[str]) -> list[list[float]]
+```
+
+Generate embeddings for a batch of text strings.
+
+Args:
+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.
+
+#### run
+
+```python
+run(documents: list[Document])
+```
+
+Processes all documents in batches while adhering to the API's token limit per request.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of documents to embed.
+
+**Returns:**
+
+- – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+
+#### 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]) -> VertexAIDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- VertexAIDocumentEmbedder – Deserialized component.
+
+## 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, ...]
+```
+
+#### __init__
+
+```python
+__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.
+
+**Parameters:**
+
+- **model** (Literal['text-embedding-004', 'text-embedding-005', 'textembedding-gecko-multilingual@001', 'text-multilingual-embedding-002', 'text-embedding-large-exp-03-07']) – Name of the model to use.
+- **task_type** (Literal['RETRIEVAL_DOCUMENT', 'RETRIEVAL_QUERY', 'SEMANTIC_SIMILARITY', 'CLASSIFICATION', 'CLUSTERING', 'QUESTION_ANSWERING', 'FACT_VERIFICATION', 'CODE_RETRIEVAL_QUERY']) – 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** (Optional\[Secret\]) – The default location to use when making API calls, if not set uses us-central-1.
+- **gcp_project_id** (Optional\[Secret\]) – ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- **progress_bar** (bool) – Whether to display a progress bar during processing.
+- **truncate_dim** (Optional\[int\]) – The dimension to truncate the embeddings to, if specified.
+
+#### run
+
+```python
+run(text: Union[list[Document], list[str], str])
+```
+
+Processes text in batches while adhering to the API's token limit per request.
+
+**Parameters:**
+
+- **text** (Union\[list\[Document\], list\[str\], str\]) – The text to embed.
+
+**Returns:**
+
+- – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+
+#### 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]) -> VertexAITextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- VertexAITextEmbedder – Deserialized component.
+
+## 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
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "imagetext",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ **kwargs: Optional[str]
+)
+```
+
+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).
+
+**Parameters:**
+
+- **project_id** (Optional\[str\]) – ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- **model** (str) – Name of the model to use.
+- **location** (Optional\[str\]) – 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.
+
+#### 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]) -> VertexAIImageCaptioner
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- VertexAIImageCaptioner – Deserialized component.
+
+#### run
+
+```python
+run(image: ByteStream)
+```
+
+Prompts the model to generate captions for the given image.
+
+**Parameters:**
+
+- **image** (ByteStream) – The image to generate captions for.
+
+**Returns:**
+
+- – A dictionary with the following keys:
+- `captions`: A list of captions generated by the model.
+
+## 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)
+````
+
+#### __init__
+
+```python
+__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).
+
+**Parameters:**
+
+- **model** (str) – Name of the model to use. For available models, see https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models.
+- **project_id** (Optional\[str\]) – ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- **location** (Optional\[str\]) – The default location to use when making API calls, if not set uses us-central-1.
+ Defaults to None.
+- **generation_config** (Optional\[Union\[GenerationConfig, dict\[str, Any\]\]\]) – 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** (Optional\[dict\[HarmCategory, HarmBlockThreshold\]\]) – 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** (Optional\[list\[Tool\]\]) – A list of tools for which the model can prepare calls.
+- **tool_config** (Optional\[ToolConfig\]) – 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** (Optional\[StreamingCallbackT\]) – A callback function that is called when a new token is received from
+ the stream. The callback function accepts StreamingChunk as an argument.
+
+#### 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]) -> VertexAIGeminiChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- VertexAIGeminiChatGenerator – Deserialized component.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ streaming_callback: Optional[StreamingCallbackT] = None,
+ *,
+ tools: Optional[list[Tool]] = None
+)
+```
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of `ChatMessage` instances, representing the input messages.
+- **streaming_callback** (Optional\[StreamingCallbackT\]) – A callback function that is called when a new token is received from the stream.
+- **tools** (Optional\[list\[Tool\]\]) – 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.
+
+#### run_async
+
+```python
+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.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – A list of `ChatMessage` instances, representing the input messages.
+- **streaming_callback** (Optional\[StreamingCallbackT\]) – A callback function that is called when a new token is received from the stream.
+- **tools** (Optional\[list\[Tool\]\]) – 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.
+
+## 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)
+ >>> ```
+````
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "code-bison",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ **kwargs: Optional[str]
+)
+```
+
+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).
+
+**Parameters:**
+
+- **project_id** (Optional\[str\]) – ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- **model** (str) – Name of the model to use.
+- **location** (Optional\[str\]) – 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.
+
+#### 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]) -> VertexAICodeGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- VertexAICodeGenerator – Deserialized component.
+
+#### run
+
+```python
+run(prefix: str, suffix: Optional[str] = None)
+```
+
+Generate code using a Google Vertex AI model.
+
+**Parameters:**
+
+- **prefix** (str) – Code before the current point.
+- **suffix** (Optional\[str\]) – Code after the current point.
+
+**Returns:**
+
+- – A dictionary with the following keys:
+- `replies`: A list of generated code snippets.
+
+## 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 ...
+```
+
+#### __init__
+
+```python
+__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).
+
+**Parameters:**
+
+- **project_id** (Optional\[str\]) – ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- **model** (str) – Name of the model to use. For available models, see https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models.
+- **location** (Optional\[str\]) – The default location to use when making API calls, if not set uses us-central-1.
+- **generation_config** (Optional\[Union\[GenerationConfig, dict\[str, Any\]\]\]) – 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** (Optional\[dict\[HarmCategory, HarmBlockThreshold\]\]) – 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** (Optional\[Union\[str, ByteStream, Part\]\]) – Default system instruction to use for generating content.
+- **streaming_callback** (Optional\[Callable\\[[StreamingChunk\], None\]\]) – A callback function that is called when a new token is received from the stream.
+ The callback function accepts StreamingChunk as an argument.
+
+#### 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]) -> VertexAIGeminiGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- VertexAIGeminiGenerator – Deserialized component.
+
+#### run
+
+```python
+run(
+ parts: Variadic[Union[str, ByteStream, Part]],
+ streaming_callback: Optional[Callable[[StreamingChunk], None]] = None,
+)
+```
+
+Generates content using the Gemini model.
+
+**Parameters:**
+
+- **parts** (Variadic\[Union\[str, ByteStream, Part\]\]) – Prompt for the model.
+- **streaming_callback** (Optional\[Callable\\[[StreamingChunk\], None\]\]) – 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.
+
+## 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"))
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "imagegeneration",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ **kwargs: Optional[str]
+)
+```
+
+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).
+
+**Parameters:**
+
+- **project_id** (Optional\[str\]) – ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- **model** (str) – Name of the model to use.
+- **location** (Optional\[str\]) – 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.
+
+#### 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]) -> VertexAIImageGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- VertexAIImageGenerator – Deserialized component.
+
+#### run
+
+```python
+run(prompt: str, negative_prompt: Optional[str] = None)
+```
+
+Produces images based on the given prompt.
+
+**Parameters:**
+
+- **prompt** (str) – The prompt to generate images from.
+- **negative_prompt** (Optional\[str\]) – 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.
+
+## 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
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "imagetext",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ **kwargs: Optional[str]
+)
+```
+
+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).
+
+**Parameters:**
+
+- **project_id** (Optional\[str\]) – ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- **model** (str) – Name of the model to use.
+- **location** (Optional\[str\]) – 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.
+
+#### 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]) -> VertexAIImageQA
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- VertexAIImageQA – Deserialized component.
+
+#### run
+
+```python
+run(image: ByteStream, question: str)
+```
+
+Prompts model to answer a question about an image.
+
+**Parameters:**
+
+- **image** (ByteStream) – The image to ask the question about.
+- **question** (str) – The question to ask.
+
+**Returns:**
+
+- – A dictionary with the following keys:
+- `replies`: A list of answers to the question.
+
+## 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?
+````
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str = "text-bison",
+ project_id: Optional[str] = None,
+ location: Optional[str] = None,
+ **kwargs: Optional[str]
+)
+```
+
+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).
+
+**Parameters:**
+
+- **project_id** (Optional\[str\]) – ID of the GCP project to use. By default, it is set during Google Cloud authentication.
+- **model** (str) – Name of the model to use.
+- **location** (Optional\[str\]) – 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.
+
+#### 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]) -> VertexAITextGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- VertexAITextGenerator – Deserialized component.
+
+#### run
+
+```python
+run(prompt: str)
+```
+
+Prompts the model to generate text.
+
+**Parameters:**
+
+- **prompt** (str) – 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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/hanlp.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/hanlp.md
new file mode 100644
index 00000000000..4d0eac98bda
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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-3.2-unstable/integrations-api/hetzner.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/hetzner.md
new file mode 100644
index 00000000000..e3c79cb9d25
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/hetzner.md
@@ -0,0 +1,119 @@
+---
+title: "Hetzner"
+id: integrations-hetzner
+description: "Hetzner integration for Haystack"
+slug: "/integrations-hetzner"
+---
+
+
+## haystack_integrations.components.generators.hetzner.chat.chat_generator
+
+### HetznerChatGenerator
+
+Bases: OpenAIChatGenerator
+
+Enables text generation using the models served by the Hetzner Inference API.
+
+For the list of available models, see the
+[Hetzner Inference API docs](https://docs.hetzner.com/general/company-and-policy/experiments/inference/) or query
+the `/v1/models` endpoint of the API, whose response is definitive.
+
+You can pass any text generation parameters valid for the Hetzner chat completion API directly to this component
+using the `generation_kwargs` parameter in `__init__` or in the `run` method.
+
+The served models accept images alongside text, so
+[`ImageContent`](https://docs.haystack.deepset.ai/docs/imagecontent) parts can be included in the
+[`ChatMessage`](https://docs.haystack.deepset.ai/docs/chatmessage)s passed to `run`.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.hetzner import HetznerChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = HetznerChatGenerator()
+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=Secret) – The Hetzner Inference API token.
+- **model** (str) – The name of the Hetzner chat completion model to use. See `SUPPORTED_MODELS`.
+- **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 Hetzner Inference API base url.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the Hetzner 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.
+- `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 Hetzner API call.
+- **max_retries** (int | None) – Maximum number of retries to contact Hetzner 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-3.2-unstable/integrations-api/huggingface_api.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/huggingface_api.md
new file mode 100644
index 00000000000..69716090140
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/huggingface_api.md
@@ -0,0 +1,1088 @@
+---
+title: "Hugging Face API"
+id: integrations-huggingface-api
+description: "Hugging Face API integration for Haystack"
+slug: "/integrations-huggingface-api"
+---
+
+
+## haystack_integrations.components.embedders.huggingface_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_integrations.components.embedders.huggingface_api 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.
+
+**Raises:**
+
+- ValueError – If the required `model` or `url` is missing from `api_params`, the `url` is invalid,
+ or the `api_type` is unknown.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Hugging Face client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Hugging Face client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Hugging Face client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Hugging Face 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]) -> 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.
+
+**Raises:**
+
+- TypeError – If `documents` is not a list of Documents.
+- ValueError – If the embeddings returned by the API have an unexpected shape.
+
+#### 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.
+
+**Raises:**
+
+- TypeError – If `documents` is not a list of Documents.
+- ValueError – If the embeddings returned by the API have an unexpected shape.
+
+## haystack_integrations.components.embedders.huggingface_api.sparse_document_embedder
+
+### HuggingFaceAPISparseDocumentEmbedder
+
+Embeds Documents into sparse vectors using a Hugging Face Text Embeddings Inference (TEI) server.
+
+The component batches requests and returns copies of the input Documents with `sparse_embedding` set.
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPISparseDocumentEmbedder
+
+embedder = HuggingFaceAPISparseDocumentEmbedder(api_base_url="http://localhost:8080")
+documents = embedder.run([Document(content="Sparse retrieval")])["documents"]
+print(documents[0].sparse_embedding)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_base_url: str = "http://localhost:8080",
+ 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",
+ timeout: float | None = 30.0,
+ headers: dict[str, str] | None = None,
+ concurrency_limit: int = 4
+) -> None
+```
+
+Create a sparse Document embedder backed by TEI.
+
+**Parameters:**
+
+- **api_base_url** (str) – Base URL of the TEI server.
+- **token** (Secret | None) – Token sent to TEI as HTTP bearer authorization, if set.
+- **prefix** (str) – A string to add before each prepared Document text.
+- **suffix** (str) – A string to add after each prepared Document text.
+- **batch_size** (int) – Number of Documents sent in each request.
+- **progress_bar** (bool) – If `True`, show a progress bar while embedding.
+- **meta_fields_to_embed** (list\[str\] | None) – Metadata fields to embed before the Document content.
+- **embedding_separator** (str) – Separator for metadata fields and Document content.
+- **timeout** (float | None) – HTTP request timeout in seconds. Set to `None` to disable it.
+- **headers** (dict\[str, str\] | None) – Additional HTTP headers to send with each request.
+- **concurrency_limit** (int) – Maximum concurrent requests made by `run_async`.
+
+**Raises:**
+
+- ValueError – If `api_base_url` is invalid or a numeric parameter is not positive.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPISparseDocumentEmbedder
+```
+
+Deserialize this component from a dictionary.
+
+#### 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\]\] – Copies of the Documents with sparse embeddings.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of Documents asynchronously.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Copies of the Documents with sparse embeddings.
+
+## haystack_integrations.components.embedders.huggingface_api.sparse_text_embedder
+
+### HuggingFaceAPISparseTextEmbedder
+
+Embeds text into a sparse vector using a Hugging Face Text Embeddings Inference (TEI) server.
+
+The TEI server must be running a sparse embedding model and expose the `/embed_sparse` endpoint.
+
+```python
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPISparseTextEmbedder
+
+embedder = HuggingFaceAPISparseTextEmbedder(api_base_url="http://localhost:8080")
+result = embedder.run("What is sparse retrieval?")
+print(result["sparse_embedding"])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_base_url: str = "http://localhost:8080",
+ token: Secret | None = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+ ),
+ prefix: str = "",
+ suffix: str = "",
+ timeout: float | None = 30.0,
+ headers: dict[str, str] | None = None
+) -> None
+```
+
+Create a sparse text embedder backed by TEI.
+
+**Parameters:**
+
+- **api_base_url** (str) – Base URL of the TEI server.
+- **token** (Secret | None) – Token sent to TEI as HTTP bearer authorization, if set.
+- **prefix** (str) – A string to add before the text.
+- **suffix** (str) – A string to add after the text.
+- **timeout** (float | None) – HTTP request timeout in seconds. Set to `None` to disable it.
+- **headers** (dict\[str, str\] | None) – Additional HTTP headers to send with each request.
+
+**Raises:**
+
+- ValueError – If `api_base_url` is not a valid HTTP URL.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPISparseTextEmbedder
+```
+
+Deserialize this component from a dictionary.
+
+#### run
+
+```python
+run(text: str) -> dict[str, SparseEmbedding]
+```
+
+Embed a single string.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, SparseEmbedding\] – The sparse embedding of the input text.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, SparseEmbedding]
+```
+
+Embed a single string asynchronously.
+
+**Parameters:**
+
+- **text** (str) – Text to embed.
+
+**Returns:**
+
+- dict\[str, SparseEmbedding\] – The sparse embedding of the input text.
+
+## haystack_integrations.components.embedders.huggingface_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_integrations.components.embedders.huggingface_api 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.
+
+**Raises:**
+
+- ValueError – If the required `model` or `url` is missing from `api_params`, the `url` is invalid,
+ or the `api_type` is unknown.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Hugging Face client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Hugging Face client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Hugging Face client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Hugging Face 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]) -> 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.
+
+**Raises:**
+
+- TypeError – If `text` is not a string.
+- ValueError – If the embedding returned by the API has an unexpected shape.
+
+#### 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.
+
+**Raises:**
+
+- TypeError – If `text` is not a string.
+- ValueError – If the embedding returned by the API has an unexpected shape.
+
+## haystack_integrations.components.generators.huggingface_api.chat.chat_generator
+
+### 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_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack_integrations.common.huggingface_api.utils 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/Qwen3.5-9B",
+ "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.
+
+**Raises:**
+
+- ValueError – If the required `model` or `url` is missing from `api_params`, the `url` is invalid, the `api_type`
+ is unknown, `tools` and `streaming_callback` are used together, or duplicate tool names are provided.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Hugging Face API chat generator.
+
+This creates the synchronous client and warms up the configured tools.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Hugging Face client and warm up the configured tools.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Hugging Face client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Hugging Face client.
+
+#### 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] | str,
+ 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\] | str) – A list of ChatMessage objects representing the input messages. If a string is provided, it is converted
+ to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only
+ at initialization are kept.
+- **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.
+
+**Raises:**
+
+- ValueError – If `tools` and a streaming callback are used together, or if duplicate tool names are provided.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage] | str,
+ 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\] | str) – A list of ChatMessage objects representing the input messages. If a string is provided, it is converted
+ to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only
+ at initialization are kept.
+- **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.
+
+**Raises:**
+
+- ValueError – If `tools` and a streaming callback are used together, or if duplicate tool names are provided.
+
+## haystack_integrations.components.rankers.huggingface_api.ranker
+
+### 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.utils import Secret
+
+from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker
+
+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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ibm_db.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ibm_db.md
new file mode 100644
index 00000000000..75e77f2242b
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ibm_db.md
@@ -0,0 +1,407 @@
+---
+title: "IBM Db2"
+id: integrations-ibm-db
+description: "IBM Db2 integration for Haystack"
+slug: "/integrations-ibm-db"
+---
+
+
+## haystack_integrations.components.retrievers.ibm_db.embedding_retriever
+
+### IBMDb2EmbeddingRetriever
+
+Retrieves documents from a IBMDb2DocumentStore using vector similarity.
+
+Use inside a Haystack pipeline after a text embedder:
+
+```python
+pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
+pipeline.add_component("retriever", IBMDb2EmbeddingRetriever(
+ document_store=store, top_k=5
+))
+pipeline.connect("embedder.embedding", "retriever.query_embedding")
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: IBMDb2DocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the IBMDb2EmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (IBMDb2DocumentStore) – An instance of `IBMDb2DocumentStore`.
+- **filters** (dict\[str, Any\] | None) – Filters applied to the retrieved Documents.
+- **top_k** (int) – Maximum number of Documents to return.
+- **filter_policy** (FilterPolicy) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- TypeError – If `document_store` is not an instance of `IBMDb2DocumentStore`.
+
+#### 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\]) – Dense float vector from an embedder component.
+- **filters** (dict\[str, Any\] | None) – Runtime filters, merged with constructor filters according to filter_policy.
+- **top_k** (int | None) – Override the constructor top_k for this call.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with key `documents` containing a list of matching :class:`Document` objects.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying 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]) -> IBMDb2EmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- IBMDb2EmbeddingRetriever – Deserialized component.
+
+## haystack_integrations.document_stores.ibm_db.document_store
+
+IBM Db2 Document Store for Haystack.
+
+### IBMDb2DocumentStore
+
+IBM Db2 Document Store for Haystack using vector search capabilities.
+
+This document store uses IBM Db2's native vector search functionality
+to store and retrieve documents with embeddings.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ database: str,
+ hostname: str,
+ username: Secret = Secret.from_env_var("DB2_USERNAME"),
+ password: Secret = Secret.from_env_var("DB2_PASSWORD"),
+ port: int = 50000,
+ protocol: str = "TCPIP",
+ schema: str | None = None,
+ use_ssl: bool = False,
+ ssl_certificate: str | None = None,
+ connection_options: dict[str, Any] | None = None,
+ table_name: str = "haystack_documents",
+ embedding_dim: int = 768,
+ distance_metric: Literal["EUCLIDEAN", "COSINE", "MANHATTAN"] = "COSINE",
+ recreate_table: bool = False
+)
+```
+
+Initialize the IBM Db2 Document Store.
+
+**Parameters:**
+
+- **database** (str) – Database name
+- **hostname** (str) – Database server hostname
+- **username** (Secret) – Database username as a `Secret`, e.g. `Secret.from_env_var("DB2_USERNAME")`.
+- **password** (Secret) – Database password as a `Secret`, e.g. `Secret.from_env_var("DB2_PASSWORD")`.
+- **port** (int) – Database server port (default: 50000)
+- **protocol** (str) – Connection protocol (default: "TCPIP")
+- **schema** (str | None) – Database schema (optional)
+- **use_ssl** (bool) – Enable SSL/TLS connection (default: False)
+- **ssl_certificate** (str | None) – Path to SSL certificate file (optional, required if use_ssl is True)
+- **connection_options** (dict\[str, Any\] | None) – Additional connection options as dict (optional)
+- **table_name** (str) – Name of the table to store documents (default: "haystack_documents")
+- **embedding_dim** (int) – Dimension of embedding vectors (default: 768)
+- **distance_metric** (Literal['EUCLIDEAN', 'COSINE', 'MANHATTAN']) – Distance metric for similarity search (default: "COSINE")
+- **recreate_table** (bool) – If True, drop and recreate the table (default: False)
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Count all documents in the store.
+
+**Returns:**
+
+- int – Number of documents
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any] | None = None) -> int
+```
+
+Count documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Filters to apply. See Haystack documentation for filter syntax.
+
+**Returns:**
+
+- int – Number of documents matching the filters
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to the store.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – List of documents to write
+- **policy** (DuplicatePolicy) – Policy for handling duplicate documents
+
+**Returns:**
+
+- int – Number of documents written
+
+**Raises:**
+
+- ValueError – If documents is not a list of Document objects or has invalid embeddings
+- TypeError – If embeddings have invalid types
+- DuplicateDocumentError – If a document with the same id already exists and policy is FAIL or NONE
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Filter documents using SQL-based metadata and field conditions.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Optional filter dictionary to constrain the returned documents.
+
+**Returns:**
+
+- list\[Document\] – List of matching documents.
+
+#### 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_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any] | None = None) -> int
+```
+
+Delete documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Filters to apply. See Haystack documentation for filter syntax.
+
+**Returns:**
+
+- int – Number of documents deleted
+
+#### delete_all_documents
+
+```python
+delete_all_documents(recreate_index: bool = False) -> int
+```
+
+Delete all documents from the document store.
+
+**Parameters:**
+
+- **recreate_index** (bool) – If True, recreate the table after deletion
+
+**Returns:**
+
+- int – Number of documents deleted
+
+#### update_by_filter
+
+```python
+update_by_filter(
+ filters: dict[str, Any] | None = None, meta: dict[str, Any] | None = None
+) -> int
+```
+
+Update documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Filters to apply. See Haystack documentation for filter syntax.
+- **meta** (dict\[str, Any\] | None) – Dictionary of metadata fields to update
+
+**Returns:**
+
+- int – Number of documents updated
+
+#### 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Get unique values for a given metadata field, optionally filtered by a search term.
+
+**Note**: values of different types are kept distinct even when they compare equal in Python
+or share a textual form (e.g. the int `1`, the bool `True` and the str `"1"` are returned as
+three separate values, and a whole-number float like `1.0` stays distinct from the int `1`).
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field name (can include or omit the 'meta.' prefix).
+- **search_term** (str | None) – Optional term to filter the returned values by, matching as a case-insensitive
+ substring of the metadata field's own value (not the document content). If None, all values
+ are considered.
+- **from\_** (int) – The offset for pagination (0-based).
+- **size** (int) – The number of unique values to return.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing (list of unique values in their original JSON type, total count of
+ unique values matching `search_term`).
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(field: str) -> dict[str, Any]
+```
+
+Get the minimum and maximum values for a numeric metadata field.
+
+**Parameters:**
+
+- **field** (str) – The metadata field name (can include 'meta.' prefix)
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with 'min' and 'max' keys
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, Any]]
+```
+
+Get information about all metadata fields including their types.
+
+**Returns:**
+
+- dict\[str, dict\[str, Any\]\] – Dictionary mapping field names to their type information
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any] | None = None,
+ metadata_fields: list[str] | None = None,
+) -> dict[str, int]
+```
+
+Count unique values for specified metadata fields, optionally filtered.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Optional filters to apply before counting
+- **metadata_fields** (list\[str\] | None) – List of metadata field names to count unique values for
+
+**Returns:**
+
+- dict\[str, int\] – Dictionary mapping field names to their unique value counts
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the document store to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary representation
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> IBMDb2DocumentStore
+```
+
+Deserialize the document store from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary representation
+
+**Returns:**
+
+- IBMDb2DocumentStore – IBMDb2DocumentStore instance
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/jina.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/jina.md
new file mode 100644
index 00000000000..b83d8a6d3ea
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/jina.md
@@ -0,0 +1,687 @@
+---
+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, 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.
+- **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, Any\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+- `meta`: A dictionary with metadata about the request, including the model used and usage information.
+
+**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, Any]
+```
+
+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, Any\] – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+- `meta`: A dictionary with metadata about the request, including the model used and usage information.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/kreuzberg.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/kreuzberg.md
new file mode 100644
index 00000000000..220043d0ece
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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-3.2-unstable/integrations-api/langdetect.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/langdetect.md
new file mode 100644
index 00000000000..6303fdaaa43
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/langdetect.md
@@ -0,0 +1,163 @@
+---
+title: "Langdetect"
+id: integrations-langdetect
+description: "Langdetect integration for Haystack"
+slug: "/integrations-langdetect"
+---
+
+
+## haystack_integrations.components.classifiers.langdetect.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_integrations.components.classifiers.langdetect 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.
+
+## haystack_integrations.components.routers.langdetect.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_integrations.components.routers.langdetect 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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/langfuse.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/langfuse.md
new file mode 100644
index 00000000000..ed5b558c98d
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/langfuse.md
@@ -0,0 +1,503 @@
+---
+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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Langfuse client and enable tracing once.
+
+#### 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-3.2-unstable/integrations-api/lara.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/lara.md
new file mode 100644
index 00000000000..ab42181ed02
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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-3.2-unstable/integrations-api/libreoffice.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/libreoffice.md
new file mode 100644
index 00000000000..53afdc68b5a
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/libreoffice.md
@@ -0,0 +1,196 @@
+---
+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.
+- subprocess.CalledProcessError – If soffice exits with a non-zero status.
+
+#### 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.
+- subprocess.CalledProcessError – If soffice exits with a non-zero status.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/linkup.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/linkup.md
new file mode 100644
index 00000000000..df5f20db351
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/linkup.md
@@ -0,0 +1,126 @@
+---
+title: "Linkup"
+id: integrations-linkup
+description: "Linkup integration for Haystack"
+slug: "/integrations-linkup"
+---
+
+
+## haystack_integrations.components.websearch.linkup.linkup_websearch
+
+### LinkupWebSearch
+
+A component that uses Linkup to search the web and return results as Haystack Documents.
+
+This component wraps the Linkup Search API, enabling web search queries that return
+structured documents with content and links.
+
+Linkup is a web search API optimized for LLM applications. You need a Linkup API key
+from [linkup.so](https://www.linkup.so).
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.linkup import LinkupWebSearch
+from haystack.utils import Secret
+
+websearch = LinkupWebSearch(
+ api_key=Secret.from_env_var("LINKUP_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("LINKUP_API_KEY"),
+ top_k: int | None = 10,
+ depth: Literal["fast", "standard", "deep"] = "standard",
+ search_params: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the LinkupWebSearch component.
+
+**Parameters:**
+
+- **api_key** (Secret) – API key for Linkup. Defaults to the `LINKUP_API_KEY` environment variable.
+- **top_k** (int | None) – Maximum number of results to return. Maps to the `max_results` parameter of the Linkup API.
+- **depth** (Literal['fast', 'standard', 'deep']) – The depth of the search. Can be `"fast"` (beta, sub-second, keyword-based queries only),
+ `"standard"` for a simple search, or `"deep"` for a more powerful agentic workflow.
+- **search_params** (dict\[str, Any\] | None) – Additional parameters passed to the Linkup search API.
+ See the [Linkup API reference](https://docs.linkup.so/pages/documentation/api-reference/endpoint/post-search)
+ for available options. Supported keys include: `include_images`, `from_date`, `to_date`,
+ `include_domains`, `exclude_domains`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Linkup client.
+
+Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+
+#### run
+
+```python
+run(
+ query: str,
+ top_k: int | None = None,
+ depth: Literal["fast", "standard", "deep"] | None = None,
+ search_params: dict[str, Any] | None = None,
+) -> dict[str, Any]
+```
+
+Search the web using Linkup 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.
+- **depth** (Literal['fast', 'standard', 'deep'] | None) – Optional per-run override of the search depth.
+ If not provided, the init-time `depth` is used.
+- **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,
+ top_k: int | None = None,
+ depth: Literal["fast", "standard", "deep"] | None = None,
+ search_params: dict[str, Any] | None = None,
+) -> dict[str, Any]
+```
+
+Asynchronously search the web using Linkup 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.
+- **depth** (Literal['fast', 'standard', 'deep'] | None) – Optional per-run override of the search depth.
+ If not provided, the init-time `depth` is used.
+- **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-3.2-unstable/integrations-api/litellm.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/litellm.md
new file mode 100644
index 00000000000..75e09545497
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/litellm.md
@@ -0,0 +1,138 @@
+---
+title: "LiteLLM"
+id: integrations-litellm
+description: "LiteLLM integration for Haystack"
+slug: "/integrations-litellm"
+---
+
+
+## haystack_integrations.components.generators.litellm.chat.chat_generator
+
+### LiteLLMChatGenerator
+
+Completes chats using any of 100+ LLM providers via LiteLLM.
+
+LiteLLM routes to OpenAI, Anthropic, Google, AWS Bedrock, Azure, Cohere,
+Mistral, Groq, and many more through a single unified interface.
+
+Model names use LiteLLM format: `provider/model-name`, e.g.
+`anthropic/claude-sonnet-4-20250514`, `openai/gpt-4o`,
+`bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0`.
+
+See https://docs.litellm.ai/docs/providers for the full list.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.litellm import LiteLLMChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = LiteLLMChatGenerator(
+ model="anthropic/claude-sonnet-4-20250514",
+ generation_kwargs={"max_tokens": 1024, "temperature": 0.7},
+)
+
+messages = [
+ ChatMessage.from_system("You are a helpful assistant"),
+ ChatMessage.from_user("What's Natural Language Processing?"),
+]
+result = generator.run(messages=messages)
+print(result["replies"][0].text)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret | None = None,
+ model: str = "openai/gpt-4o",
+ streaming_callback: StreamingCallbackT | None = None,
+ api_base_url: str | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None
+) -> None
+```
+
+Create a LiteLLMChatGenerator instance.
+
+**Parameters:**
+
+- **api_key** (Secret | None) – The API key for the provider. Optional: when not set, LiteLLM resolves
+ credentials itself from the provider's standard environment variable
+ (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`). Pass a `Secret` only
+ when you want Haystack to manage and serialize the key explicitly.
+- **model** (str) – The model name in LiteLLM format (provider/model-name).
+- **streaming_callback** (StreamingCallbackT | None) – A callback function invoked with each new StreamingChunk.
+- **api_base_url** (str | None) – Custom API base URL (e.g. for a self-hosted LiteLLM proxy).
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional parameters passed to litellm.completion().
+ See https://docs.litellm.ai/docs/completion/input for details.
+- **tools** (ToolsType | None) – A list of Tool / Toolset objects the model can prepare calls for.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage] | str,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ *,
+ tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Invoke chat completion via LiteLLM.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | str) – Input messages as ChatMessage instances.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **streaming_callback** (StreamingCallbackT | None) – Override the streaming callback for this call.
+- **generation_kwargs** (dict\[str, Any\] | None) – Override generation parameters for this call.
+- **tools** (ToolsType | None) – Override tools for this call.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dict with key `replies` containing ChatMessage instances.
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage] | str,
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ *,
+ tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Async version of run(). Invoke chat completion via LiteLLM.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | str) – Input messages as ChatMessage instances.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **streaming_callback** (StreamingCallbackT | None) – Override the streaming callback for this call.
+- **generation_kwargs** (dict\[str, Any\] | None) – Override generation parameters for this call.
+- **tools** (ToolsType | None) – Override tools for this call.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dict with key `replies` containing ChatMessage instances.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LiteLLMChatGenerator
+```
+
+Deserialize a component from a dictionary.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/llama_cpp.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/llama_cpp.md
new file mode 100644
index 00000000000..be1e962dfeb
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/llama_cpp.md
@@ -0,0 +1,276 @@
+---
+title: "Llama.cpp"
+id: integrations-llama-cpp
+description: "Llama.cpp integration for Haystack"
+slug: "/integrations-llama-cpp"
+---
+
+
+## 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=str) – The path of a quantized model for text generation, for example, "zephyr-7b-beta.Q4_0.gguf".
+ If the model path is also specified in the `model_kwargs`, this parameter will be ignored.
+- **n_ctx** (int | None) – The number of tokens in the context. When set to 0, the context will be taken from the model.
+- **n_batch** (int | None) – Prompt processing maximum batch size.
+- **model_kwargs** (dict\[str, Any\] | None) – Dictionary containing keyword arguments used to initialize the LLM for text generation.
+ These keyword arguments provide fine-grained control over the model loading.
+ In case of duplication, these kwargs override `model`, `n_ctx`, and `n_batch` init parameters.
+ For more information on the available kwargs, see
+ [llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.__init__).
+- **generation_kwargs** (dict\[str, Any\] | None) – A dictionary containing keyword arguments to customize text generation.
+ For more information on the available kwargs, see
+ [llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion).
+- **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.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function that is called when a new token is received from the stream.
+- **chat_handler_name** (str | None) – Name of the chat handler for multimodal models.
+ Common options include: "Llava16ChatHandler", "MoondreamChatHandler", "Qwen25VLChatHandler".
+ For other handlers, check
+ [llama-cpp-python documentation](https://llama-cpp-python.readthedocs.io/en/latest/#multi-modal-models).
+- **model_clip_path** (str | None) – Path to the CLIP model for vision processing (e.g., "mmproj.bin").
+ Required when chat_handler_name is provided for multimodal models.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Load and initialize the llama.cpp model.
+
+#### 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]) -> LlamaCppChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- LlamaCppChatGenerator – Deserialized component.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage] | str,
+ generation_kwargs: dict[str, Any] | None = None,
+ *,
+ tools: ToolsType | None = None,
+ streaming_callback: StreamingCallbackT | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Run the text generation model on the given list of ChatMessages.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – A dictionary containing keyword arguments to customize text generation.
+ For more information on the available kwargs, see
+ [llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion).
+- **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. 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.
+ 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`: The responses from the model
+
+#### run_async
+
+```python
+run_async(
+ messages: list[ChatMessage] | str,
+ 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 the text generation model on the given list of ChatMessages.
+
+Uses a thread pool to avoid blocking the event loop, since llama-cpp-python provides
+only synchronous inference.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – A dictionary containing keyword arguments to customize text generation.
+ For more information on the available kwargs, see
+ [llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion).
+- **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. 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.
+ 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`: The responses from the model
+
+## haystack_integrations.components.generators.llama_cpp.generator
+
+### LlamaCppGenerator
+
+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).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+generator = LlamaCppGenerator(model="zephyr-7b-beta.Q4_0.gguf", n_ctx=2048, n_batch=512)
+
+print(generator.run("Who is the best American actor?", generation_kwargs={"max_tokens": 128}))
+# {'replies': ['John Cusack'], 'meta': [{"object": "text_completion", ...}]}
+```
+
+#### __init__
+
+```python
+__init__(
+ model: str,
+ n_ctx: int | None = 0,
+ n_batch: int | None = 512,
+ model_kwargs: dict[str, Any] | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize LlamaCppGenerator.
+
+**Parameters:**
+
+- **model** (str) – The path of a quantized model for text generation, for example, "zephyr-7b-beta.Q4_0.gguf".
+ If the model path is also specified in the `model_kwargs`, this parameter will be ignored.
+- **n_ctx** (int | None) – The number of tokens in the context. When set to 0, the context will be taken from the model.
+- **n_batch** (int | None) – Prompt processing maximum batch size.
+- **model_kwargs** (dict\[str, Any\] | None) – Dictionary containing keyword arguments used to initialize the LLM for text generation.
+ These keyword arguments provide fine-grained control over the model loading.
+ In case of duplication, these kwargs override `model`, `n_ctx`, and `n_batch` init parameters.
+ For more information on the available kwargs, see
+ [llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.__init__).
+- **generation_kwargs** (dict\[str, Any\] | None) – A dictionary containing keyword arguments to customize text generation.
+ For more information on the available kwargs, see
+ [llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_completion).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Load and initialize the llama.cpp model.
+
+#### run
+
+```python
+run(
+ prompt: str, generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Run the text generation model on the given prompt.
+
+**Parameters:**
+
+- **prompt** (str) – the prompt to be sent to the generative model.
+- **generation_kwargs** (dict\[str, Any\] | None) – A dictionary containing keyword arguments to customize text generation.
+ For more information on the available kwargs, see
+ [llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_completion).
+
+**Returns:**
+
+- dict\[str, list\[str\] | list\[dict\[str, Any\]\]\] – A dictionary with the following keys:
+- `replies`: the list of replies generated by the model.
+- `meta`: metadata about the request.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/llama_stack.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/llama_stack.md
new file mode 100644
index 00000000000..017d16080dd
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/llama_stack.md
@@ -0,0 +1,144 @@
+---
+title: "Llama Stack"
+id: integrations-llama-stack
+description: "Llama Stack integration for Haystack"
+slug: "/integrations-llama-stack"
+---
+
+
+
+## Module haystack\_integrations.components.generators.llama\_stack.chat.chat\_generator
+
+
+
+### LlamaStackChatGenerator
+
+Enables text generation using Llama Stack framework.
+Llama Stack Server supports multiple inference providers, including Ollama, Together,
+and vLLM and other cloud providers.
+For a complete list of inference providers, see [Llama Stack docs](https://llama-stack.readthedocs.io/en/latest/providers/inference/index.html).
+
+Users can pass any text generation parameters valid for the OpenAI 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:
+You need to setup Llama Stack Server before running this example and have a model available. For a quick start on
+how to setup server with Ollama, see [Llama Stack docs](https://llama-stack.readthedocs.io/en/latest/getting_started/index.html).
+
+```python
+from haystack_integrations.components.generators.llama_stack import LlamaStackChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = LlamaStackChatGenerator(model="ollama/llama3.2:3b")
+response = client.run(messages)
+print(response)
+
+>>{'replies': [ChatMessage(_content=[TextContent(text='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=MariaDBDocumentStore) – A `MariaDBDocumentStore` instance.
+- **filters** (dict\[str, Any\] | None) – Default Haystack metadata filters applied to every query.
+- **top_k** (int) – Maximum number of documents to return.
+- **score_threshold** (float | None) – Minimum score to include a document. Documents below this score are excluded.
+- **filter_policy** (str | FilterPolicy) – How runtime filters interact with init-time filters.
+
+**Raises:**
+
+- ValueError – If `document_store` is not a `MariaDBDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MariaDBEmbeddingRetriever
+```
+
+Deserialize the component from a dictionary.
+
+#### run
+
+```python
+run(
+ query_embedding: list[float],
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ score_threshold: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents similar to the query embedding.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – The query vector.
+- **filters** (dict\[str, Any\] | None) – Runtime filters merged with init-time filters per `filter_policy`.
+- **top_k** (int | None) – Override the retriever's `top_k`.
+- **score_threshold** (float | None) – Override the retriever's `score_threshold`.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Dictionary with `"documents"` key containing the ranked results.
+
+## haystack_integrations.components.retrievers.mariadb.keyword_retriever
+
+### MariaDBKeywordRetriever
+
+Retrieves documents from `MariaDBDocumentStore` using full-text keyword search.
+
+Uses MariaDB's `MATCH ... AGAINST` full-text search in natural language mode,
+backed by a FULLTEXT index on the `content` column.
+
+### Usage example
+
+```python
+from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore
+from haystack_integrations.components.retrievers.mariadb import MariaDBKeywordRetriever
+
+store = MariaDBDocumentStore(host="127.0.0.1", database="haystack", embedding_dimension=768)
+retriever = MariaDBKeywordRetriever(document_store=store, top_k=5)
+result = retriever.run(query="climate change")
+documents = result["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: MariaDBDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the MariaDBKeywordRetriever.
+
+**Parameters:**
+
+- **document_store** (MariaDBDocumentStore) – A `MariaDBDocumentStore` instance.
+- **filters** (dict\[str, Any\] | None) – Default Haystack metadata filters.
+- **top_k** (int) – Maximum number of documents to return.
+- **filter_policy** (str | FilterPolicy) – How runtime filters interact with init-time filters.
+
+**Raises:**
+
+- ValueError – If `document_store` is not a `MariaDBDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MariaDBKeywordRetriever
+```
+
+Deserialize the component from a dictionary.
+
+#### run
+
+```python
+run(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents matching the query via full-text search.
+
+**Parameters:**
+
+- **query** (str) – The keyword query string.
+- **filters** (dict\[str, Any\] | None) – Runtime filters merged with init-time filters per `filter_policy`.
+- **top_k** (int | None) – Override the retriever's `top_k`.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Dictionary with `"documents"` key containing results ranked by relevance.
+
+## haystack_integrations.document_stores.mariadb.document_store
+
+### MariaDBDocumentStore
+
+A Document Store backed by MariaDB 11.7+ using native VECTOR support.
+
+Uses MariaDB's `VECTOR` datatype with `MHNSW` indexing for approximate nearest-neighbour
+vector search, and `MATCH ... AGAINST` for full-text keyword search.
+
+### Usage example
+
+```python
+from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore
+
+store = MariaDBDocumentStore(
+ host="127.0.0.1",
+ port=3306,
+ database="haystack",
+ embedding_dimension=768,
+)
+store.write_documents(documents)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ host: str = "127.0.0.1",
+ port: int = 3306,
+ database: str = "haystack",
+ user: Secret = Secret.from_env_var("MARIADB_USER"),
+ password: Secret = Secret.from_env_var("MARIADB_PASSWORD"),
+ table_name: str = "haystack_documents",
+ recreate_table: bool = False,
+ embedding_dimension: int = 768,
+ distance: str = "cosine",
+ create_vector_index: bool = False
+) -> None
+```
+
+Initialize the MariaDBDocumentStore.
+
+**Parameters:**
+
+- **host** (str) – MariaDB host.
+- **port** (int) – MariaDB port.
+- **database** (str) – Database name.
+- **user** (Secret) – Database user, read from the `MARIADB_USER` environment variable.
+- **password** (Secret) – Database password, read from the `MARIADB_PASSWORD` environment variable.
+- **table_name** (str) – Table used to store documents. Must contain only letters, digits, and underscores.
+- **recreate_table** (bool) – Drop and recreate the table on init. **Deletes all data.**
+- **embedding_dimension** (int) – Dimension of embedding vectors. Applied only when the table is created;
+ ignored on an existing table.
+- **distance** (str) – Distance function for vector similarity — `"cosine"` or `"euclidean"`. Applied only when
+ the table is created; ignored on an existing table.
+- **create_vector_index** (bool) – If `True`, creates an MHNSW vector index for fast ANN search. Requires every
+ document to have a non-null embedding. Applied only when the table is created; ignored on an existing
+ table.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this document store to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MariaDBDocumentStore
+```
+
+Deserialize this document store from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- MariaDBDocumentStore – Deserialized document store.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### delete_table
+
+```python
+delete_table() -> None
+```
+
+Drop the documents table
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Return 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 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
+```
+
+Write documents to the 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
+```
+
+Delete documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – The document ids to delete.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/markitdown.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/markitdown.md
new file mode 100644
index 00000000000..17b7fc5c395
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/markitdown.md
@@ -0,0 +1,61 @@
+---
+title: "Markitdown"
+id: integrations-markitdown
+description: "Markitdown integration for Haystack"
+slug: "/integrations-markitdown"
+---
+
+
+## haystack_integrations.components.converters.markitdown.markitdown_converter
+
+### MarkItDownConverter
+
+Converts files to Haystack Documents using [MarkItDown](https://github.com/microsoft/markitdown).
+
+MarkItDown is a Microsoft library that converts many file formats to Markdown,
+including PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), HTML, images,
+audio, and more. All processing is performed locally.
+
+### Usage example
+
+```python
+from haystack_integrations.components.converters.markitdown import MarkItDownConverter
+
+converter = MarkItDownConverter()
+result = converter.run(sources=["document.pdf", "report.docx"])
+documents = result["documents"]
+```
+
+#### __init__
+
+```python
+__init__(store_full_path: bool = False) -> None
+```
+
+Initializes the MarkItDownConverter.
+
+**Parameters:**
+
+- **store_full_path** (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-3.2-unstable/integrations-api/mcp.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mcp.md
new file mode 100644
index 00000000000..a8d7f3ef827
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mcp.md
@@ -0,0 +1,967 @@
+---
+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
+
+from haystack import Pipeline
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+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 an Agent that owns the tool-calling loop.
+# The Agent passes the toolset to the chat generator, executes any requested
+# tool calls, and continues until a final answer is produced.
+pipeline = Pipeline()
+pipeline.add_component("agent", Agent(chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"), tools=mcp_toolset))
+
+# 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({"agent": {"messages": [user_input_msg]}})
+print(result["agent"]["messages"][-1].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
+
+# 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 `Agent.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-3.2-unstable/integrations-api/mem0.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mem0.md
new file mode 100644
index 00000000000..6c5a4b82e51
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mem0.md
@@ -0,0 +1,589 @@
+---
+title: "Mem0"
+id: integrations-mem0
+description: "Mem0 integration for Haystack"
+slug: "/integrations-mem0"
+---
+
+
+## haystack_integrations.components.retrievers.mem0.retriever
+
+### Mem0MemoryRetriever
+
+Retrieves memories from a Mem0MemoryStore as a list of ChatMessage objects.
+
+Use this component in a Haystack Pipeline to fetch relevant memories before passing
+context to a language model or Agent. The returned memories are system messages.
+
+Provide either `filters` or at least one Mem0 entity ID (`user_id`, `run_id`, `agent_id`, or `app_id`)
+when running the component. If both are provided, the filters and entity IDs are combined.
+
+### Usage example
+
+```python
+from haystack_integrations.components.retrievers.mem0 import Mem0MemoryRetriever
+from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+
+store = Mem0MemoryStore()
+retriever = Mem0MemoryRetriever(memory_store=store, top_k=3)
+
+result = retriever.run(query="What does Alice like?", user_id="alice")
+memories = result["memories"]
+print([message.text for message in memories])
+
+# Pass query=None to retrieve all memories in scope.
+all_memories = retriever.run(query=None, user_id="alice")["memories"]
+```
+
+#### __init__
+
+```python
+__init__(*, memory_store: Mem0MemoryStore, top_k: int = 5) -> None
+```
+
+Initialize the Mem0MemoryRetriever.
+
+**Parameters:**
+
+- **memory_store** (Mem0MemoryStore) – The Mem0MemoryStore instance to retrieve memories from.
+- **top_k** (int) – Default maximum number of memories to return per query.
+
+#### run
+
+```python
+run(
+ query: str | None,
+ *,
+ user_id: str | None = None,
+ run_id: str | None = None,
+ agent_id: str | None = None,
+ app_id: str | None = None,
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Retrieve memories matching the query from Mem0.
+
+**Parameters:**
+
+- **query** (str | None) – Text query used to search for relevant memories. Pass `None` to retrieve all memories matching
+ the scope.
+- **user_id** (str | None) – User ID to scope the search.
+- **run_id** (str | None) – Run ID to scope the search.
+- **agent_id** (str | None) – Agent ID to scope the search.
+- **app_id** (str | None) – App ID to scope the search.
+- **filters** (dict\[str, Any\] | None) – Haystack-style filters to apply. When provided with ID parameters, they are combined.
+ Mem0 requires entity IDs inside filters and supports a fixed set of native fields and operators:
+ [Search Memories API](https://docs.mem0.ai/api-reference/memory/search-memories) and
+ [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters). Fields that are not native
+ Mem0 filter fields are treated as Mem0 metadata fields.
+- **top_k** (int | None) – Maximum number of memories to return. Overrides the init-time default.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – Dictionary with key `memories` containing a list of ChatMessage objects. User-provided
+ Mem0 metadata is included in each message's meta. Mem0 retrieval fields such as `memory_id`, `user_id`,
+ `score`, and timestamps are included under `meta["mem0"]`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Mem0MemoryRetriever
+```
+
+Deserialize this component from a dictionary.
+
+## haystack_integrations.components.writers.mem0.writer
+
+### Mem0MemoryWriter
+
+Writes ChatMessage objects as memories to a Mem0MemoryStore.
+
+Use this component in a Haystack Pipeline to persist conversation messages.
+Scoping IDs (`user_id`, `run_id`, `agent_id`, `app_id`) are runtime parameters so the
+same pipeline instance can serve multiple users or agents. The `infer` setting controls whether
+Mem0 extracts memories from messages or stores message text as-is.
+
+### Usage example
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.writers.mem0 import Mem0MemoryWriter
+from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+
+store = Mem0MemoryStore()
+writer = Mem0MemoryWriter(memory_store=store, infer=False)
+
+result = writer.run(
+ messages=[ChatMessage.from_user("Alice prefers concise Python examples.")],
+ user_id="alice",
+)
+print(result["memories_written"])
+```
+
+#### __init__
+
+```python
+__init__(*, memory_store: Mem0MemoryStore, infer: bool = True) -> None
+```
+
+Initialize the Mem0MemoryWriter.
+
+**Parameters:**
+
+- **memory_store** (Mem0MemoryStore) – The Mem0MemoryStore instance to write memories to.
+- **infer** (bool) – If True, Mem0 extracts memories from messages. If False, Mem0 stores message text as-is.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage],
+ *,
+ user_id: str | None = None,
+ run_id: str | None = None,
+ agent_id: str | None = None,
+ app_id: str | None = None
+) -> dict[str, int]
+```
+
+Write messages as memories to the Mem0 store.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – List of ChatMessage objects to store.
+- **user_id** (str | None) – User ID to scope the stored memories.
+- **run_id** (str | None) – Run ID to scope the stored memories.
+- **agent_id** (str | None) – Agent ID to scope the stored memories.
+- **app_id** (str | None) – App ID to scope the stored memories.
+
+**Returns:**
+
+- dict\[str, int\] – Dictionary with key `memories_written` containing the count of stored memory items.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Mem0MemoryWriter
+```
+
+Deserialize this component from a dictionary.
+
+## haystack_integrations.memory_stores.mem0.errors
+
+### Mem0MemoryStoreError
+
+Bases: RuntimeError
+
+Raised when a Mem0 API operation fails.
+
+## haystack_integrations.memory_stores.mem0.memory_store
+
+### Mem0MemoryStore
+
+A memory store backed by the Mem0 cloud API.
+
+Stores and retrieves ChatMessage-based memories scoped by user_id, run_id, agent_id, or app_id.
+The Mem0 client is created lazily on first use (or explicitly via warm_up()).
+Requires a Mem0 API key set via the MEM0_API_KEY environment variable or passed explicitly.
+
+#### __init__
+
+```python
+__init__(*, api_key: Secret = Secret.from_env_var('MEM0_API_KEY')) -> None
+```
+
+Initialize the Mem0 memory store.
+
+The Mem0 client is not created until warm_up() is called (or the first method that
+needs the client is invoked).
+
+**Parameters:**
+
+- **api_key** (Secret) – The Mem0 API key. Defaults to the MEM0_API_KEY environment variable.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Mem0 client. Called automatically on first use if not called explicitly.
+
+Calling this method explicitly is useful when you want to validate the API key
+or pre-connect before the first pipeline run.
+
+#### client
+
+```python
+client: MemoryClient
+```
+
+Return the initialized client, calling warm_up() if necessary.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the store configuration to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Mem0MemoryStore
+```
+
+Deserialize the store from a dictionary.
+
+#### add_memories
+
+```python
+add_memories(
+ *,
+ messages: list[ChatMessage],
+ user_id: str | None = None,
+ run_id: str | None = None,
+ agent_id: str | None = None,
+ app_id: str | None = None,
+ infer: bool = True,
+ **kwargs: Any
+) -> list[dict[str, Any]]
+```
+
+Add ChatMessage memories to Mem0.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\]) – List of ChatMessage objects to store as memories.
+- **user_id** (str | None) – User ID to scope these memories.
+- **run_id** (str | None) – Run ID to scope these memories.
+- **agent_id** (str | None) – Agent ID to scope these memories. Required for Mem0 to store assistant messages.
+- **app_id** (str | None) – App ID to scope these memories.
+- **infer** (bool) – If True, Mem0 extracts memories from messages. If False, Mem0 stores message text as-is.
+- **kwargs** (Any) – Additional keyword arguments forwarded to the Mem0 client add method.
+ Note: ChatMessage.meta is ignored because Mem0 doesn't support per-message metadata.
+ Pass `metadata` as a kwarg to attach metadata to the whole batch instead.
+
+**Returns:**
+
+- list\[dict\[str, Any\]\] – List of objects with `memory_id` and `memory` text for each stored memory.
+
+**Raises:**
+
+- Mem0MemoryStoreError – If the Mem0 API call fails.
+
+#### search_memories
+
+```python
+search_memories(
+ *,
+ query: str | None = None,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 5,
+ user_id: str | None = None,
+ run_id: str | None = None,
+ agent_id: str | None = None,
+ app_id: str | None = None,
+ **kwargs: Any
+) -> list[ChatMessage]
+```
+
+Search for memories in Mem0.
+
+Either `filters` or at least one of `user_id`, `run_id`, `agent_id`, or `app_id` must be provided.
+When both `filters` and IDs are provided, they are combined with an `AND` condition.
+
+**Parameters:**
+
+- **query** (str | None) – Text query to search. If omitted, returns all memories matching the scope.
+- **filters** (dict\[str, Any\] | None) – Haystack-style filters to apply. See
+ [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+ Mem0 requires entity IDs inside filters and supports a fixed set of native fields and operators:
+ [Search Memories API](https://docs.mem0.ai/api-reference/memory/search-memories) and
+ [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters).
+ Fields that are not native Mem0 filter fields are treated as Mem0 metadata fields.
+- **top_k** (int) – Maximum number of results to return.
+- **user_id** (str | None) – User ID to scope the search.
+- **run_id** (str | None) – Run ID to scope the search.
+- **agent_id** (str | None) – Agent ID to scope the search.
+- **app_id** (str | None) – App ID to scope the search.
+- **kwargs** (Any) – Additional keyword arguments forwarded to the Mem0 client.
+
+**Returns:**
+
+- list\[ChatMessage\] – List of ChatMessage (system role) objects containing the retrieved memories. User-provided
+ Mem0 metadata is included in each message's meta. Mem0 retrieval fields such as `memory_id`, `user_id`,
+ `score`, and timestamps are included under `meta["mem0"]`.
+
+**Raises:**
+
+- Mem0MemoryStoreError – If the Mem0 API call fails.
+
+## haystack_integrations.tools.mem0.retriever_tool
+
+### Mem0MemoryRetrieverTool
+
+Bases: Tool
+
+A tool that searches a Mem0MemoryStore for memories.
+
+The `user_id` is injected at runtime from Agent State via `inputs_from_state`,
+so a single tool instance can serve many users. The LLM only sees `query` and `top_k` by default.
+If the LLM omits `query` or passes `None`, Mem0 returns all memories matching the injected scope.
+Pass a custom `inputs_from_state` mapping to inject other supported Mem0 entity IDs such as
+`run_id`, `agent_id`, or `app_id`. The mapping keys are Agent State keys and the values are this
+tool's parameter names. For example, use
+`inputs_from_state={"user_id": "user_id", "session_id": "run_id"}` to pass `state["session_id"]`
+to the tool's `run_id` parameter at runtime.
+
+### Usage example
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+from haystack_integrations.tools.mem0 import Mem0MemoryRetrieverTool
+
+store = Mem0MemoryStore()
+retrieve_memories = Mem0MemoryRetrieverTool(memory_store=store, top_k=5)
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+ tools=[retrieve_memories],
+ state_schema={"user_id": {"type": str}, "session_id": {"type": str}},
+)
+
+# The Agent can call retrieve_memories with a query for targeted recall,
+# or without a query when it needs all scoped memories.
+result = agent.run(
+ messages=[ChatMessage.from_user("What do you remember about me?")],
+ user_id="alice",
+ session_id="chat-42",
+)
+print(result["last_message"].text)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ memory_store: Mem0MemoryStore,
+ top_k: int = 5,
+ name: str = "retrieve_memories",
+ description: str = _DEFAULT_DESCRIPTION,
+ parameters: dict[str, Any] = _PARAMETERS,
+ inputs_from_state: dict[str, str] = _DEFAULT_INPUTS_FROM_STATE
+) -> None
+```
+
+Initialize the Mem0MemoryRetrieverTool.
+
+**Parameters:**
+
+- **memory_store** (Mem0MemoryStore) – The Mem0MemoryStore instance to query.
+- **top_k** (int) – Default maximum number of memories to return. The LLM may override this.
+- **name** (str) – Tool name exposed to the LLM.
+- **description** (str) – Tool description exposed to the LLM.
+- **parameters** (dict\[str, Any\]) – JSON schema for the parameters exposed to the LLM. Defaults to optional `query` and `top_k`.
+- **inputs_from_state** (dict\[str, str\]) – Mapping from Agent State keys to this tool's parameter names.
+ Defaults to `{"user_id": "user_id"}`, which injects `state["user_id"]` into the `user_id`
+ parameter. To pass more Mem0 IDs at runtime, add the state fields to the Agent's
+ `state_schema` and map them to the corresponding tool parameters, for example
+ `{"user_id": "user_id", "session_id": "run_id", "agent_name": "agent_id", "app_name": "app_id"}`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Mem0 client. Subsequent calls are no-ops.
+
+#### retrieve
+
+```python
+retrieve(
+ query: str | None = None,
+ *,
+ top_k: int | None = None,
+ user_id: str | None = None,
+ run_id: str | None = None,
+ agent_id: str | None = None,
+ app_id: str | None = None
+) -> str
+```
+
+Retrieve memories relevant to a query, or all memories when no query is provided.
+
+**Parameters:**
+
+- **query** (str | None) – Text query used to search for relevant memories. If omitted or `None`, all memories matching
+ the scope are returned.
+- **top_k** (int | None) – Maximum number of memories to return for query searches. Overrides the tool default.
+- **user_id** (str | None) – User ID to scope the search. Injected from Agent State by default.
+- **run_id** (str | None) – Run ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+- **agent_id** (str | None) – Agent ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+- **app_id** (str | None) – App ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+
+**Returns:**
+
+- str – Retrieved memories formatted for the Agent, or a message when no memories were found.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Mem0MemoryRetrieverTool
+```
+
+Deserialize this tool from a dictionary.
+
+## haystack_integrations.tools.mem0.writer_tool
+
+### Mem0MemoryWriterTool
+
+Bases: Tool
+
+A tool that writes a memory to a Mem0MemoryStore.
+
+The `user_id` is injected at runtime from Agent State via `inputs_from_state`,
+so a single tool instance can serve many users. The LLM only sees `text` and `infer`.
+Pass a custom `inputs_from_state` mapping to inject other supported Mem0 entity IDs such as
+`run_id`, `agent_id`, or `app_id`. The mapping keys are Agent State keys and the values are this
+tool's parameter names. For example, use
+`inputs_from_state={"user_id": "user_id", "session_id": "run_id"}` to pass `state["session_id"]`
+to the tool's `run_id` parameter at runtime.
+
+### Usage example
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+from haystack_integrations.tools.mem0 import Mem0MemoryWriterTool
+
+store = Mem0MemoryStore()
+store_memory = Mem0MemoryWriterTool(memory_store=store)
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+ tools=[store_memory],
+ state_schema={"user_id": {"type": str}, "session_id": {"type": str}},
+)
+
+result = agent.run(
+ messages=[ChatMessage.from_user("Remember that I prefer concise Python examples.")],
+ user_id="alice",
+ session_id="chat-42",
+)
+print(result["last_message"].text)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ memory_store: Mem0MemoryStore,
+ name: str = "store_memory",
+ description: str = _DEFAULT_DESCRIPTION,
+ parameters: dict[str, Any] = _PARAMETERS,
+ inputs_from_state: dict[str, str] = _DEFAULT_INPUTS_FROM_STATE
+) -> None
+```
+
+Initialize the Mem0MemoryWriterTool.
+
+**Parameters:**
+
+- **memory_store** (Mem0MemoryStore) – The Mem0MemoryStore instance to write to.
+- **name** (str) – Tool name exposed to the LLM.
+- **description** (str) – Tool description exposed to the LLM.
+- **parameters** (dict\[str, Any\]) – JSON schema for the parameters exposed to the LLM. Defaults to `text` and `infer`.
+- **inputs_from_state** (dict\[str, str\]) – Mapping from Agent State keys to this tool's parameter names.
+ Defaults to `{"user_id": "user_id"}`, which injects `state["user_id"]` into the `user_id`
+ parameter. To pass more Mem0 IDs at runtime, add the state fields to the Agent's
+ `state_schema` and map them to the corresponding tool parameters, for example
+ `{"user_id": "user_id", "session_id": "run_id", "agent_name": "agent_id", "app_name": "app_id"}`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Mem0 client. Subsequent calls are no-ops.
+
+#### store
+
+```python
+store(
+ text: str,
+ *,
+ infer: bool = False,
+ user_id: str | None = None,
+ run_id: str | None = None,
+ agent_id: str | None = None,
+ app_id: str | None = None
+) -> str
+```
+
+Store text as a memory.
+
+**Parameters:**
+
+- **text** (str) – The information to store as a memory.
+- **infer** (bool) – If True, Mem0 extracts memories from the text. If False, Mem0 stores the text as-is.
+- **user_id** (str | None) – User ID to scope the stored memory. Injected from Agent State by default.
+- **run_id** (str | None) – Run ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+- **agent_id** (str | None) – Agent ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+- **app_id** (str | None) – App ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+
+**Returns:**
+
+- str – A string indicating how many memory items were stored.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Mem0MemoryWriterTool
+```
+
+Deserialize this tool from a dictionary.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/meta_llama.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/meta_llama.md
new file mode 100644
index 00000000000..7f691610f7c
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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-3.2-unstable/integrations-api/microsoft_sharepoint.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/microsoft_sharepoint.md
new file mode 100644
index 00000000000..c928b2655ad
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/microsoft_sharepoint.md
@@ -0,0 +1,341 @@
+---
+title: "Microsoft SharePoint"
+id: integrations-microsoft-sharepoint
+description: "Microsoft SharePoint integration for Haystack"
+slug: "/integrations-microsoft-sharepoint"
+---
+
+
+## haystack_integrations.components.fetchers.microsoft_sharepoint.fetcher
+
+### MSSharePointFetcher
+
+Fetches the full content of Microsoft SharePoint and OneDrive items via the Microsoft Graph API.
+
+The fetcher complements `MSSharePointRetriever`, which only returns Search snippets and metadata. Wire the
+retriever's `documents` (or a list of `web_url`s) into this fetcher to download the full content. It
+dispatches on the entity type of each hit and always returns `ByteStream`s, ready for a downstream converter
+(for example a `FileTypeRouter` in front of `PyPDFToDocument`, `DOCXToDocument`, `HTMLToDocument`, or a JSON
+converter):
+
+- **Files** (`driveItem`) are downloaded as their raw bytes (PDF, DOCX, ...).
+- **List items** (`listItem`) are returned as a JSON `ByteStream` of the item's column values (`fields`).
+- **SharePoint pages** (`sitePage`) are returned as an HTML `ByteStream` built from the page's web parts.
+
+Each `ByteStream`'s `meta` carries `url`, `file_name`, `content_type`, and a normalized `entity_type`
+(`driveItem`, `listItem`, or `sitePage`).
+
+Everything is resolved through the Microsoft Graph `shares` endpoint (plus the Pages API for pages), so only
+the `web_url` already exposed by the retriever is needed. The fetcher takes a per-user `access_token` as a run
+input, typically wired from an upstream `OAuthTokenResolver`. The token must carry delegated Microsoft Graph
+permissions (for example `Files.Read.All` for files and `Sites.Read.All` for list items and pages).
+
+### Usage example
+
+```python
+from haystack_integrations.components.fetchers.microsoft_sharepoint import MSSharePointFetcher
+
+fetcher = MSSharePointFetcher()
+
+# `access_token` is a per-user delegated Microsoft Graph bearer token.
+result = fetcher.run(
+ access_token="my-delegated-graph-token",
+ targets=["https://contoso.sharepoint.com/sites/contoso-team/contoso-designs.docx"],
+)
+streams = result["streams"]
+```
+
+In a pipeline, connect `MSSharePointRetriever.documents` to the fetcher's `targets` input and an upstream
+component that emits a per-user `access_token` to the fetcher's `access_token` input.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ graph_url: str = DEFAULT_GRAPH_URL,
+ timeout: float = 30.0,
+ max_retries: int = 3,
+ max_concurrent_requests: int = 5,
+ raise_on_failure: bool = True
+) -> None
+```
+
+Initialize the fetcher.
+
+**Parameters:**
+
+- **graph_url** (str) – The Microsoft Graph base URL. Defaults to `https://graph.microsoft.com/v1.0`.
+ Override for sovereign clouds.
+- **timeout** (float) – The HTTP timeout in seconds for each request to Microsoft Graph.
+- **max_retries** (int) – The maximum number of retries for throttled (HTTP 429) or transient server errors.
+- **max_concurrent_requests** (int) – The maximum number of items fetched concurrently by `run_async`. Bounds
+ the in-flight requests to Microsoft Graph to avoid tripping its rate limits. Has no effect on the
+ synchronous `run`, which fetches items one at a time.
+- **raise_on_failure** (bool) – If `True`, a fetch failure raises an exception. If `False`, the failure is
+ logged and the item is skipped, so the other items are still returned.
+
+**Raises:**
+
+- SharePointConfigError – If `max_retries` is negative or `max_concurrent_requests` is not positive.
+
+#### run
+
+```python
+run(
+ access_token: str | Secret, targets: list[Document | str]
+) -> dict[str, list[ByteStream]]
+```
+
+Fetch the content of SharePoint and OneDrive items and return them as `ByteStream`s.
+
+**Parameters:**
+
+- **access_token** (str | Secret) – A delegated Microsoft Graph bearer token for the user whose content is fetched,
+ typically wired from an upstream `OAuthTokenResolver` (which emits a plain `str`). A `Secret` is also
+ accepted and resolved internally.
+- **targets** (list\[Document | str\]) – The items to fetch, as either `Document`s emitted by `MSSharePointRetriever` or raw
+ SharePoint/OneDrive `web_url` strings (the two may also be mixed in one list). For a `Document`, the
+ `web_url` in its meta is fetched and `file_name`, `mime_type`, `entity_type`, and the SharePoint IDs
+ are reused when present; container hits with no extractable content (for example `site` or `list`) are
+ skipped. For a raw URL, the item is probed as a file and falls back to a list item.
+
+**Returns:**
+
+- dict\[str, list\[ByteStream\]\] – A dictionary with a `streams` key holding the fetched content as `ByteStream` objects. Each
+ stream's `meta` carries `url`, `file_name`, `content_type`, and `entity_type`.
+
+**Raises:**
+
+- SharePointConfigError – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+ `Secret` that does not resolve to a string.
+- SharePointRequestError – If a fetch fails and `raise_on_failure` is `True`.
+
+#### run_async
+
+```python
+run_async(
+ access_token: str | Secret, targets: list[Document | str]
+) -> dict[str, list[ByteStream]]
+```
+
+Asynchronously fetch the content of SharePoint and OneDrive items and return them as `ByteStream`s.
+
+**Parameters:**
+
+- **access_token** (str | Secret) – A delegated Microsoft Graph bearer token for the user whose content is fetched,
+ typically wired from an upstream `OAuthTokenResolver` (which emits a plain `str`). A `Secret` is also
+ accepted and resolved internally.
+- **targets** (list\[Document | str\]) – The items to fetch, as either `Document`s emitted by `MSSharePointRetriever` or raw
+ SharePoint/OneDrive `web_url` strings (the two may also be mixed in one list). For a `Document`, the
+ `web_url` in its meta is fetched and `file_name`, `mime_type`, `entity_type`, and the SharePoint IDs
+ are reused when present; container hits with no extractable content (for example `site` or `list`) are
+ skipped. For a raw URL, the item is probed as a file and falls back to a list item.
+
+**Returns:**
+
+- dict\[str, list\[ByteStream\]\] – A dictionary with a `streams` key holding the fetched content as `ByteStream` objects. Each
+ stream's `meta` carries `url`, `file_name`, `content_type`, and `entity_type`.
+
+**Raises:**
+
+- SharePointConfigError – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+ `Secret` that does not resolve to a string.
+- SharePointRequestError – If a fetch fails and `raise_on_failure` is `True`.
+
+#### 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]) -> MSSharePointFetcher
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- MSSharePointFetcher – The deserialized component instance.
+
+## haystack_integrations.components.retrievers.microsoft_sharepoint.retriever
+
+### MSSharePointRetriever
+
+Retrieves content from Microsoft SharePoint and OneDrive via the Microsoft Search (Graph) API.
+
+Given a query, the retriever calls `POST /search/query` and maps each hit to a Haystack `Document`
+whose `content` is the search snippet and whose `meta` carries the resource metadata (`file_name`,
+`web_url`, `entity_type`, `created_date_time`, `last_modified_date_time`, `created_by`, `last_modified_by`,
+`mime_type`, and `file_extension`), plus the SharePoint identifiers a downstream fetcher needs to read
+list items and pages by ID (`site_id`, `list_id`, `list_item_id`, `list_item_unique_id`). It does not
+download or convert the underlying files. Compose a downstream fetcher/converter (such as
+`MSSharePointFetcher`) when full content is needed.
+
+The retriever takes a per-user `access_token` as a run input, typically wired
+from an upstream `OAuthResolver`. The token must carry delegated Microsoft Graph permissions
+(for example `Files.Read.All` and, for site/list scoping, `Sites.Read.All`). The Search API supports
+delegated permissions only.
+
+### Usage example
+
+```python
+from haystack_integrations.components.retrievers.microsoft_sharepoint import (
+ MSSharePointRetriever,
+)
+
+retriever = MSSharePointRetriever(top_k=5)
+
+# `access_token` is a per-user delegated Microsoft Graph bearer token.
+result = retriever.run(
+ query="quarterly roadmap", access_token="my-delegated-graph-token"
+)
+documents = result["documents"]
+```
+
+In a pipeline, connect an upstream component that emits a per-user `access_token` to the retriever's
+`access_token` input. See the integration documentation for a full example that obtains the token from
+an OAuth provider.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ entity_types: list[str] | None = None,
+ top_k: int = 10,
+ fields: list[str] | None = None,
+ query_template: str | None = None,
+ graph_url: str = DEFAULT_GRAPH_URL,
+ timeout: float = 30.0,
+ max_retries: int = 3
+) -> None
+```
+
+Initialize the retriever.
+
+**Parameters:**
+
+- **entity_types** (list\[str\] | None) – The Microsoft Search entity types to query. Defaults to `["driveItem", "listItem"]`,
+ which covers files, folders, SharePoint pages and news, and list items. Other valid values are
+ `"list"` and `"site"`. See the supported values and combinations in the
+ [Microsoft docs](https://learn.microsoft.com/en-us/graph/api/resources/searchrequest).
+- **top_k** (int) – The maximum number of documents to return. Maps to the Search API `size` and is paginated
+ when it exceeds a single page.
+- **fields** (list\[str\] | None) – Optional list of resource properties to request via the Search API `fields` selection
+ (only honored for `listItem` and `driveItem` entity types). See
+ [Get selected properties](https://learn.microsoft.com/en-us/graph/api/resources/search-api-overview#get-selected-properties).
+- **query_template** (str | None) – Optional query template used to scope the search, for example
+ `'{searchTerms} path:"https://contoso.sharepoint.com/sites/Team"'`. The literal `{searchTerms}`
+ placeholder is replaced by the run-time query. The template uses
+ [Keyword Query Language (KQL)](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference).
+- **graph_url** (str) – The Microsoft Graph base URL. Defaults to `https://graph.microsoft.com/v1.0`.
+ Override for sovereign clouds.
+- **timeout** (float) – The HTTP timeout in seconds for each request to Microsoft Graph.
+- **max_retries** (int) – The maximum number of retries for throttled (HTTP 429) or transient server errors.
+
+**Raises:**
+
+- SharePointConfigError – If `entity_types` is empty, `top_k` is not positive, or `max_retries` is
+ negative.
+
+#### run
+
+```python
+run(
+ query: str, access_token: str | Secret, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Search SharePoint and OneDrive and return the matching documents.
+
+**Parameters:**
+
+- **query** (str) – The search query string. Filter results by embedding Keyword Query Language (KQL)
+ operators directly in the query, for example `filetype:docx`, `author:"Jane Doe"`, or
+ `path:"https://contoso.sharepoint.com/sites/Team"`. See the
+ [KQL syntax reference](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference).
+- **access_token** (str | Secret) – A delegated Microsoft Graph bearer token for the user whose content is searched,
+ typically wired from an upstream `OAuthResolver` (which emits a plain `str`). A `Secret` is also
+ accepted and resolved internally.
+- **top_k** (int | None) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- SharePointConfigError – If `access_token` is a `Secret` that does not resolve to a string.
+- SharePointRequestError – If Microsoft Graph returns an error response.
+
+#### run_async
+
+```python
+run_async(
+ query: str, access_token: str | Secret, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously search SharePoint and OneDrive and return the matching documents.
+
+**Parameters:**
+
+- **query** (str) – The search query string. Filter results by embedding Keyword Query Language (KQL)
+ operators directly in the query, for example `filetype:docx`, `author:"Jane Doe"`, or
+ `path:"https://contoso.sharepoint.com/sites/Team"`. See the
+ [KQL syntax reference](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference).
+- **access_token** (str | Secret) – A delegated Microsoft Graph bearer token for the user whose content is searched,
+ typically wired from an upstream `OAuthResolver` (which emits a plain `str`). A `Secret` is also
+ accepted and resolved internally.
+- **top_k** (int | None) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- SharePointConfigError – If `access_token` is a `Secret` that does not resolve to a string.
+- SharePointRequestError – If Microsoft Graph returns an error response.
+
+#### 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]) -> MSSharePointRetriever
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- MSSharePointRetriever – The deserialized component instance.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mirage.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mirage.md
new file mode 100644
index 00000000000..09bcf73a40d
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mirage.md
@@ -0,0 +1,288 @@
+---
+title: "Mirage"
+id: integrations-mirage
+description: "Mirage integration for Haystack"
+slug: "/integrations-mirage"
+---
+
+
+## haystack_integrations.tools.mirage.shell_tool
+
+### MirageShellTool
+
+Bases: Tool
+
+A Haystack `Tool` that lets an `Agent` run bash commands across a Mirage virtual filesystem.
+
+Mirage mounts heterogeneous backends (object storage, databases, SaaS apps, local disk) as one
+filesystem; this tool exposes Mirage's single `execute` surface to an Agent as one well-described
+tool with a `command` parameter. Output is normalized to text and truncated before it reaches the
+model.
+
+### Security model
+
+Mirage never shells out to the host: every command runs inside Mirage's own virtual-filesystem
+interpreter, so the blast radius is confined to the mounts you attach. Two controls shape what an
+Agent can do:
+
+- **Per-mount read-only mode** (`MirageMount(..., read_only=True)`) is the authoritative write
+ boundary. Mirage refuses any write to a read-only mount regardless of the command used, so this
+ -- not the allowlist -- is how you prevent modification or deletion. Mount anything the Agent
+ should not change as read-only.
+- **The command allowlist** (`allowed_commands`) restricts *which* commands may run. It is
+ enforced against every command Mirage would execute, including commands nested inside
+ `$(...)`, backticks, `<(...)` and subshells, so `ls "$(rm x)"` is rejected unless `rm`
+ is also allowed. Treat it as a best-effort filter to steer the Agent, not a sandbox: allowing a
+ command that itself runs other commands (`eval`, `bash`, `sh`, `source`, `xargs`,
+ `timeout`) effectively allows anything, so do not list those for untrusted/hosted use.
+- **`denied_paths`** rejects any command whose text references one of the given path substrings.
+
+### Usage example
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.tools.mirage import MirageWorkspace, MirageMount, MirageShellTool
+
+workspace = MirageWorkspace([
+ MirageMount(path="/data", resource="ram"),
+ MirageMount(path="/s3", resource="s3", config={"bucket": "my-bucket"}, read_only=True),
+])
+tool = MirageShellTool(workspace, allowed_commands=["ls", "cat", "grep", "head", "wc", "cp"])
+
+agent = Agent(chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"), tools=[tool])
+result = agent.run(messages=[ChatMessage.from_user("How many lines in /s3/log.txt mention 'alert'?")])
+print(result["messages"][-1].text)
+```
+
+#### __init__
+
+```python
+__init__(
+ workspace: MirageWorkspace,
+ *,
+ name: str = "mirage_shell",
+ description: str | None = None,
+ invocation_timeout: float = 60.0,
+ max_output_chars: int = 20000,
+ allowed_commands: list[str] | None = None,
+ denied_paths: list[str] | None = None
+) -> None
+```
+
+Initialize the Mirage shell tool.
+
+**Parameters:**
+
+- **workspace** (MirageWorkspace) – The :class:`MirageWorkspace` describing the mount tree.
+- **name** (str) – Tool name exposed to the LLM.
+- **description** (str | None) – Custom description. If None, one is generated from the mount tree.
+- **invocation_timeout** (float) – Maximum seconds to wait for a command to finish.
+- **max_output_chars** (int) – Truncate command output to this many characters before returning it.
+- **allowed_commands** (list\[str\] | None) – If set, only these command names may run, e.g.
+ `["ls", "cat", "grep", "head", "wc"]`. The allowlist is enforced against *every* command
+ Mirage would execute -- including commands nested in substitutions/subshells -- so
+ `ls "$(rm x)"` is rejected unless `rm` is also allowed. It is a filter over Mirage's
+ virtual commands to steer the Agent, not a security sandbox; the write boundary is
+ per-mount `read_only` (see the class "Security model" section). If None, any command is
+ allowed (not recommended for untrusted/hosted use).
+- **denied_paths** (list\[str\] | None) – If set, any command referencing one of these path substrings is rejected.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Build the underlying live workspace eagerly. Called by `Agent.warm_up()`/`Pipeline.warm_up()`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the tool to a dictionary in the `{"type": ..., "data": ...}` format.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MirageShellTool
+```
+
+Deserialize the tool from a dictionary.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the underlying workspace.
+
+## haystack_integrations.tools.mirage.workspace
+
+### MirageMount
+
+Declarative description of a single backend mounted into a :class:`MirageWorkspace`.
+
+A mount is the serializable unit of a Mirage workspace: it names *where* a backend is mounted
+(`path`), *which* backend it is (`resource`, a Mirage registry name such as `"s3"` or `"gdrive"`),
+and *how* to configure it (`config`).
+
+`config` values may be plain values, Haystack `Secret` objects for credentials, or an OAuth token
+source (e.g. `OAuthRefreshTokenSource`) for backends whose config accepts a token-provider callable
+(such as Mirage's OneDrive `access_token`). Secrets and token sources are resolved only when the
+live workspace is built.
+
+Every backend is created the same way. Use the Mirage registry name and the config keys that backend expects
+(discover names with `MirageMount.available_resources()`; config keys come from the backend's Mirage config class):
+
+```python
+from haystack.utils import Secret
+
+MirageMount(path="/data", resource="ram") # in-memory scratch
+MirageMount(path="/local", resource="disk", config={"root": "/srv/data"}) # local disk
+MirageMount(path="/s3", resource="s3", config={"bucket": "my-bucket"}, read_only=True)
+MirageMount(
+ path="/drive",
+ resource="gdrive",
+ config={"client_id": "...", "refresh_token": Secret.from_env_var("GDRIVE_REFRESH_TOKEN")},
+ read_only=True,
+)
+```
+
+**Parameters:**
+
+- **path** (str) – Mount point in the virtual filesystem, e.g. `"/s3"`.
+- **resource** (str) – Mirage registry name of the backend, e.g. `"ram"`, `"disk"`, `"s3"`, `"gdrive"`.
+ See `mirage.resource.registry.REGISTRY` or `MirageMount.available_resources()` for the full list.
+- **config** (dict\[str, Any\]) – Keyword arguments passed to the backend's Mirage config. Values may be `Secret`s, or
+ an OAuth token source that is turned into a token-provider callable when the workspace is built.
+- **read_only** (bool) – If True, the mount is mounted in Mirage's READ mode and writes are rejected by
+ Mirage itself.
+
+#### available_resources
+
+```python
+available_resources() -> list[str]
+```
+
+Return the Mirage registry names usable as `resource`.
+
+These are short backend names such as `"s3"`, `"gdrive"`, `"postgres"`. Pass one to
+`MirageMount(resource=...)`; the config keys each backend expects come from its Mirage
+config class.
+
+### MirageWorkspace
+
+A description of a Mirage mount tree that lazily builds a live `mirage.Workspace`.
+
+`MirageWorkspace` is the shared backend behind the Mirage tools and components: it holds the list of
+:class:`MirageMount`s and the cache configuration, serializes cleanly (resolving `Secret`s only at
+build time), and constructs the live workspace on first use via Mirage's resource registry.
+
+### Usage example
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.tools.mirage import MirageWorkspace, MirageMount
+
+ws = MirageWorkspace(
+ mounts=[
+ MirageMount(path="/data", resource="ram"),
+ MirageMount(path="/s3", resource="s3", config={"bucket": "my-bucket"}, read_only=True),
+ ]
+)
+print(ws.run("ls /s3"))
+```
+
+#### __init__
+
+```python
+__init__(
+ mounts: list[MirageMount], *, cache_limit: str | int = "512MB"
+) -> None
+```
+
+Initialize the workspace description.
+
+**Parameters:**
+
+- **mounts** (list\[MirageMount\]) – The backends to mount, as a list of :class:`MirageMount`.
+- **cache_limit** (str | int) – Mirage file-cache size limit (e.g. `"512MB"` or an int byte count).
+
+**Raises:**
+
+- MirageConfigError – If no mounts are provided or mount paths are not unique.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Build the live `mirage.Workspace` eagerly. Idempotent.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the live workspace and release its resources, if it was built. Thread-safe.
+
+#### run
+
+```python
+run(
+ command: str, *, timeout: float = 60.0, max_chars: int | None = None
+) -> str
+```
+
+Run a bash `command` against the mount tree from a synchronous context and return its output.
+
+**Parameters:**
+
+- **command** (str) – A bash command line, e.g. `"grep -r alert /s3/logs | wc -l"`.
+- **timeout** (float) – Maximum seconds to wait for the command.
+- **max_chars** (int | None) – If set, truncate the returned text to this many characters.
+
+**Returns:**
+
+- str – Combined stdout (plus a trailing error note on non-zero exit) as a string.
+
+#### run_async
+
+```python
+run_async(
+ command: str, *, timeout: float = 60.0, max_chars: int | None = None
+) -> str
+```
+
+Async counterpart of :meth:`run`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the workspace description to a dictionary (Secret-safe).
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MirageWorkspace
+```
+
+Deserialize a workspace description from a dictionary.
+
+#### describe
+
+```python
+describe() -> str
+```
+
+Return a human/LLM-readable summary of the mount tree (used in tool descriptions).
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mistral.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mistral.md
new file mode 100644
index 00000000000..3401b966756
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mistral.md
@@ -0,0 +1,667 @@
+---
+title: "Mistral"
+id: integrations-mistral
+description: "Mistral integration for Haystack"
+slug: "/integrations-mistral"
+---
+
+
+## haystack_integrations.components.converters.mistral.ocr_document_converter
+
+### MistralOCRDocumentConverter
+
+Extract text from documents using Mistral's OCR API with optional structured annotations.
+
+Supports optional structured annotations for 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,
+) -> None
+```
+
+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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Mistral client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Mistral 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]) -> 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
+) -> 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
+) -> 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**: Compatible 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.
+- **Reasoning Support**: Extracts reasoning/thinking content from models that support it
+ (e.g., mistral-small with `reasoning_effort`, magistral models) and stores it in the
+ `ReasoningContent` field on `ChatMessage`.
+
+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.
+- `reasoning_effort`: Controls reasoning/thinking tokens for models that support adjustable reasoning
+ (e.g., `mistral-small-latest`, `mistral-medium`). Accepted values: `"high"`, `"none"`.
+ See [Mistral reasoning docs](https://docs.mistral.ai/capabilities/reasoning/).
+- `prompt_mode`: For native reasoning models (magistral). Set to `"reasoning"` to use the default
+ reasoning system prompt, or omit for the model's default behavior.
+- `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).
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage] | str,
+ 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 on the Mistral API.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **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 are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only
+ at initialization are kept.
+ For details on Mistral API parameters, see
+ [Mistral docs](https://docs.mistral.ai/api/).
+- **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.
+
+**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] | str,
+ 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 on the Mistral API.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **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 are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only
+ at initialization are kept.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset.
+- **tools_strict** (bool | None) – Whether to enable strict schema adherence for tool calls.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+#### 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-3.2-unstable/integrations-api/mongodb_atlas.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mongodb_atlas.md
new file mode 100644
index 00000000000..01677c7ea8c
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/mongodb_atlas.md
@@ -0,0 +1,922 @@
+---
+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
+) -> None
+```
+
+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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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 MongoDBAtlasDocumentStore based on 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
+) -> None
+```
+
+**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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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 backed by [MongoDB Atlas](https://www.mongodb.com/atlas/database).
+
+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",
+ meta_project_mapping: dict[str, str] | None = None
+) -> None
+```
+
+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.
+- **meta_project_mapping** (dict\[str, str\] | None) – A dictionary mapping metadata fields in the Haystack Document (keys)
+ to custom fields in the MongoDB document (values). Values must be bare field paths, e.g.
+ `"source"` or `"metadata.author"`. A leading `"$"` is accepted for backward compatibility
+ and is stripped once during initialization. Default is None.
+
+**Raises:**
+
+- ValueError – If the collection name contains invalid characters.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the associated asynchronous resources.
+
+#### connection
+
+```python
+connection: AsyncMongoClient | MongoClient
+```
+
+Return the active MongoDB client connection.
+
+#### collection
+
+```python
+collection: AsyncCollection | Collection
+```
+
+Return the active MongoDB collection.
+
+#### 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 unique metadata values for each meta field.
+
+**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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Retrieves unique values for a field matching a search_term or all possible values if no search term is given.
+
+**Note**: values of different types are kept distinct even when they compare equal in Python
+(e.g. the int `1`, the bool `True` and the str `"1"` are returned as three separate values), with
+one exception: MongoDB's aggregation `$group` compares numeric values across BSON subtypes, so a
+whole-number float (e.g. `1.0`) is grouped together with a numerically equal int (`1`) and only
+one of the two survives - regardless of whether they were written to the same metadata field.
+Floats with a fractional part (e.g. `1.5`) are unaffected and stay distinct from ints.
+
+**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.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing a list of unique values (in their original type) 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Asynchronously retrieves unique values for a metadata field, optionally filtered by a search term.
+
+Asynchronously retrieves unique values for a metadata field, optionally filtered by a search term.
+**Note**: values of different types are kept distinct even when they compare equal in Python
+(e.g. the int `1`, the bool `True` and the str `"1"` are returned as three separate values), with
+one exception: MongoDB's aggregation `$group` compares numeric values across BSON subtypes, so a
+whole-number float (e.g. `1.0`) is grouped together with a numerically equal int (`1`) and only
+one of the two survives - regardless of whether they were written to the same metadata field.
+Floats with a fractional part (e.g. `1.5`) are unaffected and stay distinct from ints.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field to retrieve unique values for.
+ :param search_term: The search term to filter values. Matches as a case-insensitive substring.
+ :param from\_: The starting index for pagination.
+ :param size: The number of values to return.
+ :param filters: Optional filters to restrict the documents considered.
+ :returns: A tuple containing a list of unique values (in their original type) 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-3.2-unstable/integrations-api/nvidia.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/nvidia.md
new file mode 100644
index 00000000000..f0d52e379b0
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/nvidia.md
@@ -0,0 +1,618 @@
+---
+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/nemotron-3-embed-1b", 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the backend and release its resources.
+
+#### 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/nemotron-3-embed-1b", 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the backend and release its resources.
+
+#### 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 = "nvidia/nemotron-3.5-lightning-30b-a3b",
+ 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.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/llama-nemotron-rerank-vl-1b-v2",
+ 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.
+
+**Raises:**
+
+- ValueError – If `top_k` is not > 0.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the backend and release its resources.
+
+#### 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.
+- ValueError – If `top_k` is not > 0.
+
+## 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-3.2-unstable/integrations-api/oauth.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/oauth.md
new file mode 100644
index 00000000000..13391fe1ebf
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/oauth.md
@@ -0,0 +1,500 @@
+---
+title: "OAuth"
+id: integrations-oauth
+description: "OAuth integration for Haystack"
+slug: "/integrations-oauth"
+---
+
+
+## haystack_integrations.components.connectors.oauth.resolver
+
+### OAuthTokenResolver
+
+Resolves an OAuth access token at pipeline runtime and emits it on the `access_token` output socket.
+
+The resolver component is a thin wrapper over a pluggable token source that decides *where* the token comes from:
+a standalone OAuth refresh grant (`OAuthRefreshTokenSource`), a per-request token exchange
+(`OAuthTokenExchangeSource`), a static long-lived token (`OAuthStaticTokenSource`), or a custom source you
+provide. A downstream component (for
+example a SharePoint or Google Drive retriever) consumes the token via a normal connection and never knows how
+it was resolved.
+
+The run input depends on the token source. A source that needs a per-request credential (it sets
+`requires_subject_token = True`, like `OAuthTokenExchangeSource`) makes the resolver declare a **mandatory**
+`subject_token` input — a controller-injected per-request credential (for example an incoming user assertion),
+not chosen by an end user. A config-only source declares no run input, so the resolver is a source node.
+
+### Usage example
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.connectors.oauth import OAuthTokenResolver
+from haystack_integrations.utils.oauth import OAuthRefreshTokenSource
+
+resolver = OAuthTokenResolver(
+ token_source=OAuthRefreshTokenSource(
+ token_url="https://login.microsoftonline.com/common/oauth2/v2.0/token",
+ client_id="aaa-bbb-ccc",
+ refresh_token=Secret.from_env_var("MS_REFRESH_TOKEN"),
+ scopes=["https://graph.microsoft.com/Files.Read.All", "offline_access"],
+ ),
+)
+access_token = resolver.run()["access_token"]
+```
+
+#### __init__
+
+```python
+__init__(token_source: TokenSource | SubjectTokenSource) -> None
+```
+
+Initialize the resolver.
+
+**Parameters:**
+
+- **token_source** (TokenSource | SubjectTokenSource) – The strategy that resolves the access token. If it sets `requires_subject_token = True`
+ (for example `OAuthTokenExchangeSource`), the resolver declares a mandatory `subject_token` run input;
+ otherwise the resolver takes no run input.
+
+**Raises:**
+
+- OAuthConfigError – If `token_source` does not implement a token-source protocol.
+
+#### run
+
+```python
+run(**kwargs: Any) -> dict[str, str]
+```
+
+Resolve an access token and emit it.
+
+**Parameters:**
+
+- **kwargs** (Any) – Carries `subject_token` when the configured source requires it (declared as a mandatory
+ input in that case, injected by the application/controller per request). For config-only sources no
+ input is declared and `kwargs` is empty.
+
+**Returns:**
+
+- dict\[str, str\] – A dictionary with a single `access_token` key containing a bearer token string.
+
+**Raises:**
+
+- OAuthConfigError – If the source requires a `subject_token` but it is missing or empty.
+
+#### run_async
+
+```python
+run_async(**kwargs: Any) -> dict[str, str]
+```
+
+Asynchronously resolve an access token and emit it.
+
+**Parameters:**
+
+- **kwargs** (Any) – Carries `subject_token` when the configured source requires it.
+
+**Returns:**
+
+- dict\[str, str\] – A dictionary with a single `access_token` key containing a bearer token string.
+
+**Raises:**
+
+- OAuthConfigError – If the source requires a `subject_token` but it is missing or empty.
+
+#### 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]) -> OAuthTokenResolver
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- OAuthTokenResolver – The deserialized component instance.
+
+**Raises:**
+
+- ImportError – If the serialized `token_source` type cannot be imported.
+
+## haystack_integrations.utils.oauth.errors
+
+### OAuthError
+
+Bases: Exception
+
+Base class for errors raised by the OAuth integration.
+
+### OAuthConfigError
+
+Bases: OAuthError
+
+Raised when an OAuth component or token source is misconfigured.
+
+### TokenRefreshError
+
+Bases: OAuthError
+
+Raised when a token cannot be resolved or refreshed at the identity provider.
+
+## haystack_integrations.utils.oauth.protocols
+
+### TokenSource
+
+Bases: Protocol
+
+A token source that resolves an access token with no per-request input (a config-only source).
+
+Implemented by sources whose credential is fixed at construction time — e.g. `OAuthRefreshTokenSource` and
+`OAuthStaticTokenSource`. Such sources set the class attribute `requires_subject_token = False`, and
+`OAuthTokenResolver` runs them as source nodes (no run input).
+
+#### resolve
+
+```python
+resolve() -> str
+```
+
+Return a valid access token.
+
+#### resolve_async
+
+```python
+resolve_async() -> str
+```
+
+Asynchronous counterpart of `resolve`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the source to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TokenSource
+```
+
+Deserialize the source from a dictionary.
+
+### SubjectTokenSource
+
+Bases: Protocol
+
+A token source that resolves an access token by exchanging a per-request subject token.
+
+The `subject_token` is a controller-injected per-request credential (for example an incoming user assertion),
+not chosen by an end user. Implemented by `OAuthTokenExchangeSource`. Such sources set the class attribute
+`requires_subject_token = True`, which makes `OAuthTokenResolver` declare a mandatory `subject_token` run input.
+
+#### resolve
+
+```python
+resolve(subject_token: str) -> str
+```
+
+Return a valid access token for the per-request `subject_token`.
+
+#### resolve_async
+
+```python
+resolve_async(subject_token: str) -> str
+```
+
+Asynchronous counterpart of `resolve`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the source to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SubjectTokenSource
+```
+
+Deserialize the source from a dictionary.
+
+## haystack_integrations.utils.oauth.sources
+
+### OAuthRefreshTokenSource
+
+Resolves access tokens by running the RFC 6749 refresh-token grant against an OAuth token endpoint.
+
+Given a stored refresh token plus client credentials, it exchanges them for an access token and caches it in
+process until shortly before expiry. If the identity provider rotates the refresh token on exchange, the new value
+is kept for the lifetime of the process and surfaced through the optional `on_rotate` callback so it can be
+persisted.
+
+This source is **single-identity**: one refresh token per instance, and its in-process cache is not shared across
+processes. In a multi-replica deployment each replica keeps its own cache, so for providers that rotate (issue
+single-use) refresh tokens the replicas can invalidate one another's token unless rotations are persisted to a
+shared store via `on_rotate` and a single owner drives the refresh.
+
+Choose this source for a single fixed identity backed by a refresh grant. For a long-lived, non-expiring token
+use `OAuthStaticTokenSource`; for multi-replica or multi-user backends use `OAuthTokenExchangeSource`.
+
+#### __init__
+
+```python
+__init__(
+ token_url: str,
+ client_id: str,
+ *,
+ refresh_token: Secret = Secret.from_env_var("OAUTH_REFRESH_TOKEN"),
+ client_secret: Secret | None = None,
+ scopes: list[str] | None = None,
+ scope_delimiter: str = " ",
+ expiry_buffer_seconds: int = DEFAULT_EXPIRY_BUFFER_SECONDS,
+ timeout: float = DEFAULT_TIMEOUT_SECONDS,
+ on_rotate: Callable[[str], None] | None = None
+) -> None
+```
+
+Initialize the source.
+
+**Parameters:**
+
+- **token_url** (str) – The OAuth 2.0 token endpoint.
+- **client_id** (str) – The OAuth client identifier.
+- **refresh_token** (Secret) – The refresh token to exchange. Defaults to the value of the `OAUTH_REFRESH_TOKEN`
+ environment variable.
+- **client_secret** (Secret | None) – The client secret for confidential clients. Omit it for public clients.
+- **scopes** (list\[str\] | None) – The OAuth scopes to request, joined with `scope_delimiter`. Scope *values* are
+ provider-specific (consult your identity provider's documentation).
+- **scope_delimiter** (str) – The delimiter used to join scopes. Defaults to a space (some providers use a comma).
+- **expiry_buffer_seconds** (int) – Refresh the cached access token this many seconds before its declared expiry.
+- **timeout** (float) – The timeout, in seconds, for the request to the token endpoint.
+- **on_rotate** (Callable\\[[str\], None\] | None) – An optional callback invoked with the new refresh token whenever the provider rotates it.
+ Use it to persist the rotated token durably (the source itself only keeps it in process).
+
+**Raises:**
+
+- OAuthConfigError – If the configuration is invalid.
+
+#### resolve
+
+```python
+resolve() -> str
+```
+
+Return a cached access token, or run the refresh-token grant to obtain a fresh one.
+
+**Returns:**
+
+- str – A valid bearer access token.
+
+#### resolve_async
+
+```python
+resolve_async() -> str
+```
+
+Asynchronous counterpart of `resolve`. Use a single instance in either sync or async mode, not both.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the source to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OAuthRefreshTokenSource
+```
+
+Deserialize the source from a dictionary.
+
+### OAuthTokenExchangeSource
+
+Resolves access tokens by exchanging a per-request subject token at an OAuth token endpoint.
+
+This implements RFC 8693 token exchange (and, via configuration, Microsoft's on-behalf-of flow). Unlike
+`OAuthRefreshTokenSource`, it is **multi-user without any persistent storage**: the per-request `subject_token` (the
+incoming user assertion) *is* the user identity and is exchanged fresh for a downstream token. Resolved tokens
+are cached in memory per subject token (bounded, LRU) until shortly before expiry. Because no per-instance state
+is persisted, it is also the right choice for multi-replica deployments.
+
+Provider differences are expressed as configuration: `grant_type`, `subject_token_param` (for example
+`assertion` for Microsoft), `scopes`, and `extra_token_params` (for example
+`{"requested_token_use": "on_behalf_of"}`).
+
+#### __init__
+
+```python
+__init__(
+ token_url: str,
+ client_id: str,
+ *,
+ client_secret: Secret | None = None,
+ grant_type: str = DEFAULT_TOKEN_EXCHANGE_GRANT,
+ subject_token_param: str = "subject_token",
+ subject_token_type: str | None = None,
+ requested_token_type: str | None = None,
+ scopes: list[str] | None = None,
+ scope_delimiter: str = " ",
+ extra_token_params: dict[str, str] | None = None,
+ expiry_buffer_seconds: int = DEFAULT_EXPIRY_BUFFER_SECONDS,
+ cache_max_size: int = DEFAULT_CACHE_MAX_SIZE,
+ timeout: float = DEFAULT_TIMEOUT_SECONDS
+) -> None
+```
+
+Initialize the source.
+
+**Parameters:**
+
+- **token_url** (str) – The OAuth 2.0 token endpoint.
+- **client_id** (str) – The OAuth client identifier.
+- **client_secret** (Secret | None) – The client secret for confidential clients. Omit it for public clients.
+- **grant_type** (str) – The grant type sent as the `grant_type` form parameter. Defaults to the RFC 8693
+ token-exchange grant. Set it to the value your provider expects (for example the
+ `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for Microsoft on-behalf-of).
+- **subject_token_param** (str) – The name of the form parameter carrying the per-request subject token. Defaults
+ to `subject_token` (RFC 8693). Some providers expect a different name, such as `assertion`.
+- **subject_token_type** (str | None) – The RFC 8693 identifier for the type of the supplied subject token, sent as the
+ `subject_token_type` form parameter (omitted when not set). Required by RFC 8693 token exchange
+ (e.g. `urn:ietf:params:oauth:token-type:access_token`); not used by Microsoft's on-behalf-of flow.
+- **requested_token_type** (str | None) – The RFC 8693 identifier for the token to return, sent as the
+ `requested_token_type` form parameter (omitted when not set). Optional.
+- **scopes** (list\[str\] | None) – The OAuth scopes to request, joined with `scope_delimiter`. Scope *values* are
+ provider-specific (consult your identity provider's documentation); only the wire format is standardized
+ (RFC 6749 §3.3).
+- **scope_delimiter** (str) – The delimiter used to join scopes. Defaults to a space.
+- **extra_token_params** (dict\[str, str\] | None) – Additional form parameters included verbatim in every request (for example
+ `{"requested_token_use": "on_behalf_of"}`). Applied last, so any key here overrides the corresponding
+ form parameter derived from the other arguments (for example `grant_type`, `subject_token_type`,
+ `requested_token_type`, `scope`, or `client_secret`).
+- **expiry_buffer_seconds** (int) – Refresh a cached access token this many seconds before its declared expiry.
+- **cache_max_size** (int) – The maximum number of per-user tokens to keep in the in-memory cache. The
+ least-recently-used entry is evicted when the cache is full.
+- **timeout** (float) – The timeout, in seconds, for the request to the token endpoint.
+
+**Raises:**
+
+- OAuthConfigError – If the configuration is invalid.
+
+#### resolve
+
+```python
+resolve(subject_token: str) -> str
+```
+
+Exchange the per-request `subject_token` for an access token (cached per subject token).
+
+**Parameters:**
+
+- **subject_token** (str) – The controller-injected per-request subject token (for example an incoming user
+ assertion) to exchange for a downstream access token.
+
+**Returns:**
+
+- str – A valid bearer access token for the given `subject_token`.
+
+#### resolve_async
+
+```python
+resolve_async(subject_token: str) -> str
+```
+
+Asynchronous counterpart of `resolve`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the source to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OAuthTokenExchangeSource
+```
+
+Deserialize the source from a dictionary.
+
+### OAuthStaticTokenSource
+
+Returns a configured long-lived access token as-is.
+
+Suitable for providers that issue non-expiring tokens (for example Slack or Notion), where no refresh flow is
+needed and the token is managed out of band. If the provider issues short-lived tokens that must be refreshed,
+use `OAuthRefreshTokenSource` instead. It takes no per-request input.
+
+#### __init__
+
+```python
+__init__(token: Secret) -> None
+```
+
+Initialize the source.
+
+**Parameters:**
+
+- **token** (Secret) – The long-lived access token to return.
+
+#### resolve
+
+```python
+resolve() -> str
+```
+
+Return the configured token.
+
+**Returns:**
+
+- str – The configured long-lived access token.
+
+#### resolve_async
+
+```python
+resolve_async() -> str
+```
+
+Asynchronous counterpart of `resolve`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the source to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OAuthStaticTokenSource
+```
+
+Deserialize the source from a dictionary.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ollama.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ollama.md
new file mode 100644
index 00000000000..f6654a31ec5
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ollama.md
@@ -0,0 +1,475 @@
+---
+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,
+ dimensions: int | None = None,
+) -> 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.
+- **dimensions** (int | None) – The desired number of dimensions in the embedding output. Only supported by models
+ that implement Matryoshka Representation Learning (MRL), such as nomic-embed-text-v1.5,
+ mxbai-embed-large, and qwen3-embedding. If None (default), the full vector is returned.
+ Requires ollama-python >= 0.6.2.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Ollama client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Ollama client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Ollama client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Ollama client.
+
+#### 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 string using 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,
+ dimensions: int | 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.
+- **dimensions** (int | None) – The desired number of dimensions in the embedding output. Only supported by models
+ that implement Matryoshka Representation Learning (MRL), such as nomic-embed-text-v1.5,
+ mxbai-embed-large, and qwen3-embedding. If None (default), the full vector is returned.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Ollama client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Ollama client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Ollama client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Ollama client.
+
+#### 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)
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous Ollama client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous Ollama client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous Ollama client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Ollama 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]) -> 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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages. If a string is provided, it is converted
+ to a list containing a ChatMessage with user role.
+- **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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages. If a string is provided, it is converted
+ to a list containing a ChatMessage with user role.
+- **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
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/openapi.md
new file mode 100644
index 00000000000..9be19599c49
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/openapi.md
@@ -0,0 +1,340 @@
+---
+title: "OpenAPI"
+id: integrations-openapi
+description: "OpenAPI integration for Haystack"
+slug: "/integrations-openapi"
+---
+
+
+## haystack_integrations.components.connectors.openapi.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_integrations.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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the OpenAPI client.
+
+#### 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
+
+## haystack_integrations.components.connectors.openapi.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.dataclasses import ChatMessage, ToolCall
+from haystack.utils import Secret
+from haystack_integrations.components.connectors.openapi import OpenAPIServiceConnector
+
+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.
+
+## haystack_integrations.components.converters.openapi.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.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.converters.openapi import OpenAPIServiceToFunctions
+
+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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/opendataloader_pdf.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/opendataloader_pdf.md
new file mode 100644
index 00000000000..9afa304b62b
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/opendataloader_pdf.md
@@ -0,0 +1,113 @@
+---
+title: "Opendataloader Pdf"
+id: integrations-opendataloader-pdf
+description: "Opendataloader Pdf integration for Haystack"
+slug: "/integrations-opendataloader-pdf"
+---
+
+
+## haystack_integrations.components.converters.opendataloader_pdf.converter
+
+### OpenDataLoaderConverter
+
+OpenDataLoader PDF converter component.
+
+The component accepts PDF file paths and Haystack ByteStream objects, runs OpenDataLoader PDF extraction, and
+returns Haystack Document objects. It can also extract images to a persistent directory and return one image
+Document per extracted file.
+
+Java 11 or newer must be installed and available on PATH.
+
+### Usage example
+
+```python
+from haystack_integrations.components.converters.opendataloader_pdf import OpenDataLoaderConverter
+
+converter = OpenDataLoaderConverter(
+ output_format="markdown", extract_images=True, image_output_dir="extracted_images"
+)
+result = converter.run(sources=["report.pdf"], meta={"source": "annual-report"})
+
+documents = result["documents"]
+image_documents = result["image_documents"]
+print(documents[0].content)
+print(documents[0].meta["file_path"])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ output_format: OutputFormat = "markdown",
+ convert_kwargs: dict[str, Any] | None = None,
+ extract_images: bool = False,
+ image_output_dir: str | Path | None = None
+) -> None
+```
+
+Initialize the OpenDataLoader converter.
+
+**Parameters:**
+
+- **output_format** (OutputFormat) – Format OpenDataLoader should produce.
+- **convert_kwargs** (dict\[str, Any\] | None) – Additional arguments passed to `opendataloader_pdf.convert`. See the
+ [OpenDataLoader PDF Python options](https://opendataloader.org/docs/quick-start-python#convert-options).
+ The `image_output` and `image_dir` arguments are managed by this component; supplied values are ignored.
+- **extract_images** (bool) – Whether to extract images and return them through the `image_documents` output.
+- **image_output_dir** (str | Path | None) – Persistent root directory for extracted image files. Each `run()` stores its images
+ in a unique subdirectory of this directory. Required when `extract_images` is `True`.
+
+**Raises:**
+
+- ValueError – If image extraction is enabled without an output directory.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary representation of the converter.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenDataLoaderConverter
+```
+
+Deserialize the component.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Serialized component dictionary.
+
+**Returns:**
+
+- OpenDataLoaderConverter – Reconstructed OpenDataLoaderConverter.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Convert PDF sources into Haystack Documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – PDF file paths or Haystack ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata attached to the generated Documents. A single dictionary is applied to every
+ source. A list must contain one dictionary per source. ByteStream metadata is also preserved.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Dictionary containing the converted text Documents and image Documents. Each image Document has the
+ persistent extracted image path in its `file_path` metadata field.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/openrouter.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/openrouter.md
new file mode 100644
index 00000000000..63fc4bc5946
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/openrouter.md
@@ -0,0 +1,189 @@
+---
+title: "OpenRouter"
+id: integrations-openrouter
+description: "OpenRouter integration for Haystack"
+slug: "/integrations-openrouter"
+---
+
+
+## haystack_integrations.components.generators.openrouter.chat.chat_generator
+
+### OpenRouterChatGenerator
+
+Bases: OpenAIChatGenerator
+
+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**: Compatible 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.
+- **Reasoning Support**: Extracts reasoning/thinking content from models that support it
+ (e.g., DeepSeek R1, Claude with extended thinking) and stores it in the `ReasoningContent`
+ field on `ChatMessage`. Reasoning content is only captured for non-streaming requests.
+
+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(
+ model="deepseek/deepseek-r1",
+ generation_kwargs={"reasoning": {"effort": "high"}},
+)
+response = client.run(messages)
+print(response["replies"][0].reasoning) # Access reasoning content
+print(response["replies"][0].text) # Access final answer
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("OPENROUTER_API_KEY"),
+ model: str = "openai/gpt-5-mini",
+ streaming_callback: StreamingCallbackT | None = None,
+ api_base_url: str | None = "https://openrouter.ai/api/v1",
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ timeout: float | None = None,
+ extra_headers: dict[str, Any] | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of OpenRouterChatGenerator.
+
+**Parameters:**
+
+- **api_key** (Secret) – The OpenRouter API key.
+- **model** (str) – The name of the OpenRouter 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 OpenRouter API Base url.
+ For more details, see OpenRouter [docs](https://openrouter.ai/docs/quickstart).
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the OpenRouter endpoint. See [OpenRouter API docs](https://openrouter.ai/docs/quickstart) 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.
+- `reasoning`: A dict to configure reasoning/thinking tokens for models that support it.
+ Example: `{"effort": "high"}` or `{"max_tokens": 2000}`.
+ Reasoning content is only captured for non-streaming requests.
+ See [OpenRouter reasoning docs](https://openrouter.ai/docs/use-cases/reasoning-tokens).
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+- **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 OpenRouter API call.
+- **extra_headers** (dict\[str, Any\] | None) – Additional HTTP headers to include in requests to the OpenRouter API.
+ This can be useful for adding site URL or title for rankings on openrouter.ai
+ For more details, see OpenRouter [docs](https://openrouter.ai/docs/quickstart).
+- **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.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage] | str,
+ 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 on the OpenRouter API.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **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 OpenRouter API parameters, see
+ [OpenRouter docs](https://openrouter.ai/docs/quickstart).
+- **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.
+
+**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] | str,
+ 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 on the OpenRouter API.
+
+**Parameters:**
+
+- **messages** (list\[ChatMessage\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **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.
+- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset.
+- **tools_strict** (bool | None) – Whether to enable strict schema adherence for tool calls.
+
+**Returns:**
+
+- dict\[str, list\[ChatMessage\]\] – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/opensearch.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/opensearch.md
new file mode 100644
index 00000000000..d0497f5b9ec
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/opensearch.md
@@ -0,0 +1,1965 @@
+---
+title: "OpenSearch"
+id: integrations-opensearch
+description: "OpenSearch integration for Haystack"
+slug: "/integrations-opensearch"
+---
+
+
+## haystack_integrations.components.retrievers.opensearch.bm25_retriever
+
+### OpenSearchBM25Retriever
+
+Fetches documents from OpenSearchDocumentStore using the keyword-based BM25 algorithm.
+
+BM25 computes a weighted word overlap between the query string and a document to determine its similarity.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: OpenSearchDocumentStore,
+ filters: dict[str, Any] | None = None,
+ fuzziness: int | str = 0,
+ top_k: int = 10,
+ scale_score: bool = False,
+ all_terms_must_match: bool = False,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+ custom_query: dict[str, Any] | None = None,
+ raise_on_failure: bool = True
+) -> None
+```
+
+Creates the OpenSearchBM25Retriever component.
+
+**Parameters:**
+
+- **document_store** (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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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
+# Requires: pip install sentence-transformers-haystack
+from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
+from haystack_integrations.components.embedders.sentence_transformers import 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+## 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the associated asynchronous resources.
+
+#### 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.
+ `recreate_index=True` is not supported when the configured index name is an alias; a
+ :class:`haystack.document_stores.errors.DocumentStoreError` is raised in that case.
+- **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.
+ `recreate_index=True` is not supported when the configured index name is an alias; a
+ :class:`haystack.document_stores.errors.DocumentStoreError` is raised in that case.
+- **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 = 10,
+ 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.
+
+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 term to filter the returned values by, matching as a case-insensitive substring
+ of the metadata field's own value (not the document content). NOTE: The matching is done with a server-side
+ script to accomplish the substring matching on the value of the field and this operation is quite expensive
+ for a large corpus.
+- **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.
+
+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 term to filter the returned values by, matching as a case-insensitive substring
+ of the metadata field's own value (not the document content). NOTE: The matching is done with a server-side
+ script to accomplish the substring matching on the value of the field and this operation is quite expensive
+ for a large corpus.
+- **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-3.2-unstable/integrations-api/opentelemetry.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/opentelemetry.md
new file mode 100644
index 00000000000..89aba50ee58
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/opentelemetry.md
@@ -0,0 +1,202 @@
+---
+title: "OpenTelemetry"
+id: integrations-opentelemetry
+description: "OpenTelemetry integration for Haystack"
+slug: "/integrations-opentelemetry"
+---
+
+
+## haystack_integrations.components.connectors.opentelemetry.opentelemetry_connector
+
+### OpenTelemetryConnector
+
+OpenTelemetryConnector connects Haystack to [OpenTelemetry](https://opentelemetry.io/) in order to enable the
+
+tracing of operations and data flow within the components of a pipeline.
+
+To use the OpenTelemetryConnector, add it to your pipeline without connecting it to any other component. It will
+automatically trace all pipeline operations when tracing is enabled. Make sure to configure an OpenTelemetry
+`TracerProvider` (for example, with an exporter) before initializing the connector.
+
+**Environment Configuration:**
+
+- `HAYSTACK_CONTENT_TRACING_ENABLED`: Must be set to `"true"` to trace the content (inputs and outputs) of the
+ pipeline components.
+
+Here is an example of how to use the OpenTelemetryConnector in a pipeline:
+
+```python
+import os
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.semconv.resource import ResourceAttributes
+
+# Configure the OpenTelemetry SDK. A service name is required for most backends.
+resource = Resource(attributes={ResourceAttributes.SERVICE_NAME: "haystack"})
+tracer_provider = TracerProvider(resource=resource)
+processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces"))
+tracer_provider.add_span_processor(processor)
+trace.set_tracer_provider(tracer_provider)
+
+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.opentelemetry import OpenTelemetryConnector
+
+pipe = Pipeline()
+pipe.add_component("tracer", OpenTelemetryConnector())
+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])
+```
+
+#### __init__
+
+```python
+__init__(name: str = 'opentelemetry') -> None
+```
+
+Initialize the OpenTelemetryConnector component.
+
+**Parameters:**
+
+- **name** (str) – The name used to identify this tracing component. It is returned by the `run` method and can be
+ used to mark traces produced by this connector.
+
+#### run
+
+```python
+run() -> dict[str, str]
+```
+
+Runs the OpenTelemetryConnector component.
+
+**Returns:**
+
+- dict\[str, str\] – A dictionary with the following keys:
+- `name`: The name of the tracing component.
+
+#### 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]) -> OpenTelemetryConnector
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- OpenTelemetryConnector – The deserialized component instance.
+
+## haystack_integrations.tracing.opentelemetry.tracer
+
+### OpenTelemetrySpan
+
+Bases: Span
+
+#### __init__
+
+```python
+__init__(span: opentelemetry.trace.Span) -> None
+```
+
+Creates an instance of OpenTelemetrySpan.
+
+#### set_tag
+
+```python
+set_tag(key: str, value: Any) -> None
+```
+
+Set a single tag on the span.
+
+**Parameters:**
+
+- **key** (str) – the name of the tag.
+- **value** (Any) – the value of the tag.
+
+#### raw_span
+
+```python
+raw_span() -> Any
+```
+
+Provides access to the underlying span object of the tracer.
+
+**Returns:**
+
+- Any – The underlying span object.
+
+#### get_correlation_data_for_logs
+
+```python
+get_correlation_data_for_logs() -> dict[str, Any]
+```
+
+Return a dictionary with correlation data for logs.
+
+### OpenTelemetryTracer
+
+Bases: Tracer
+
+#### __init__
+
+```python
+__init__(tracer: opentelemetry.trace.Tracer) -> None
+```
+
+Creates an instance of OpenTelemetryTracer.
+
+#### trace
+
+```python
+trace(
+ operation_name: str,
+ tags: dict[str, Any] | None = None,
+ parent_span: Span | None = None,
+) -> Iterator[Span]
+```
+
+Activate and return a new span that inherits from the current active span.
+
+#### current_span
+
+```python
+current_span() -> Span | None
+```
+
+Return the current active span
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/optimum.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/optimum.md
new file mode 100644
index 00000000000..e823475a866
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/optimum.md
@@ -0,0 +1,507 @@
+---
+title: "Optimum"
+id: integrations-optimum
+description: "Optimum integration for Haystack"
+slug: "/integrations-optimum"
+---
+
+
+## haystack_integrations.components.embedders.optimum.optimization
+
+### OptimumEmbedderOptimizationMode
+
+Bases: Enum
+
+ONNX Optimization modes supported by the Optimum Embedders.
+
+See [Optimum ONNX optimization docs](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/optimization)
+for more details.
+
+#### from_str
+
+```python
+from_str(string: str) -> OptimumEmbedderOptimizationMode
+```
+
+Create an optimization mode from a string.
+
+**Parameters:**
+
+- **string** (str) – String to convert.
+
+**Returns:**
+
+- OptimumEmbedderOptimizationMode – Optimization mode.
+
+### OptimumEmbedderOptimizationConfig
+
+Configuration for Optimum Embedder Optimization.
+
+**Parameters:**
+
+- **mode** (OptimumEmbedderOptimizationMode) – Optimization mode.
+- **for_gpu** (bool) – Whether to optimize for GPUs.
+
+#### to_optimum_config
+
+```python
+to_optimum_config() -> OptimizationConfig
+```
+
+Convert the configuration to a Optimum configuration.
+
+**Returns:**
+
+- OptimizationConfig – Optimum configuration.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the configuration to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OptimumEmbedderOptimizationConfig
+```
+
+Create an optimization configuration from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OptimumEmbedderOptimizationConfig – Optimization configuration.
+
+## haystack_integrations.components.embedders.optimum.optimum_document_embedder
+
+### OptimumDocumentEmbedder
+
+A component for computing `Document` embeddings using models loaded with the HuggingFace Optimum library.
+
+Uses the [HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library and leverages 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")
+# Components warm up automatically on first run.
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__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.
+
+**Parameters:**
+
+- **model** (str) – A string representing the model id on HF Hub.
+
+- **token** (Secret | None) – The HuggingFace token to use as HTTP bearer authorization.
+
+- **prefix** (str) – A string to add to the beginning of each text.
+
+- **suffix** (str) – A string to add to the end of each text.
+
+- **normalize_embeddings** (bool) – Whether to normalize the embeddings to unit length.
+
+- **onnx_execution_provider** (str) – 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** (str | OptimumEmbedderPooling | None) – The pooling mode to use. When `None`, pooling mode will be inferred from the model config.
+
+- **model_kwargs** (dict\[str, Any\] | None) – 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** (str | None) – The directory to use for storing intermediate files
+ generated during model optimization/quantization. Required
+ for optimization and quantization.
+
+- **optimizer_settings** (OptimumEmbedderOptimizationConfig | None) – Configuration for Optimum Embedder Optimization.
+ If `None`, no additional optimization is be applied.
+
+- **quantizer_settings** (OptimumEmbedderQuantizationConfig | None) – Configuration for Optimum Embedder Quantization.
+ If `None`, no quantization is be applied.
+
+- **batch_size** (int) – Number of Documents to encode at once.
+
+- **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.
+
+#### 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]) -> OptimumDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- OptimumDocumentEmbedder – The deserialized component.
+
+#### run
+
+```python
+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.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – A list of Documents to embed.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – The updated Documents with their embeddings.
+
+**Raises:**
+
+- TypeError – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.optimum.optimum_text_embedder
+
+### OptimumTextEmbedder
+
+A component to embed text using models loaded with the HuggingFace Optimum library.
+
+Uses the [HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library and leverages 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")
+# Components warm up automatically on first run.
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]}
+```
+
+#### __init__
+
+```python
+__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,
+) -> None
+```
+
+Create a OptimumTextEmbedder component.
+
+**Parameters:**
+
+- **model** (str) – A string representing the model id on HF Hub.
+
+- **token** (Secret | None) – The HuggingFace token to use as HTTP bearer authorization.
+
+- **prefix** (str) – A string to add to the beginning of each text.
+
+- **suffix** (str) – A string to add to the end of each text.
+
+- **normalize_embeddings** (bool) – Whether to normalize the embeddings to unit length.
+
+- **onnx_execution_provider** (str) – 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** (str | OptimumEmbedderPooling | None) – The pooling mode to use. When `None`, pooling mode will be inferred from the model config.
+
+- **model_kwargs** (dict\[str, Any\] | None) – 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** (str | None) – The directory to use for storing intermediate files
+ generated during model optimization/quantization. Required
+ for optimization and quantization.
+
+- **optimizer_settings** (OptimumEmbedderOptimizationConfig | None) – Configuration for Optimum Embedder Optimization.
+ If `None`, no additional optimization is be applied.
+
+- **quantizer_settings** (OptimumEmbedderQuantizationConfig | None) – Configuration for Optimum Embedder Quantization.
+ If `None`, no quantization is be applied.
+
+#### 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]) -> OptimumTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- OptimumTextEmbedder – The deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float]]
+```
+
+Embed a string.
+
+**Parameters:**
+
+- **text** (str) – The text to embed.
+
+**Returns:**
+
+- dict\[str, list\[float\]\] – The embeddings of the text.
+
+**Raises:**
+
+- TypeError – If the input is not a string.
+
+## haystack_integrations.components.embedders.optimum.pooling
+
+### OptimumEmbedderPooling
+
+Bases: Enum
+
+Pooling modes support by the Optimum Embedders.
+
+#### from_str
+
+```python
+from_str(string: str) -> OptimumEmbedderPooling
+```
+
+Create a pooling mode from a string.
+
+**Parameters:**
+
+- **string** (str) – String to convert.
+
+**Returns:**
+
+- OptimumEmbedderPooling – Pooling mode.
+
+## haystack_integrations.components.embedders.optimum.quantization
+
+### OptimumEmbedderQuantizationMode
+
+Bases: Enum
+
+Dynamic Quantization modes supported by the Optimum Embedders.
+
+See [Optimum ONNX quantization docs](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/quantization)
+for more details.
+
+#### from_str
+
+```python
+from_str(string: str) -> OptimumEmbedderQuantizationMode
+```
+
+Create an quantization mode from a string.
+
+**Parameters:**
+
+- **string** (str) – String to convert.
+
+**Returns:**
+
+- OptimumEmbedderQuantizationMode – Quantization mode.
+
+### OptimumEmbedderQuantizationConfig
+
+Configuration for Optimum Embedder Quantization.
+
+**Parameters:**
+
+- **mode** (OptimumEmbedderQuantizationMode) – Quantization mode.
+- **per_channel** (bool) – Whether to apply per-channel quantization.
+
+#### to_optimum_config
+
+```python
+to_optimum_config() -> QuantizationConfig
+```
+
+Convert the configuration to a Optimum configuration.
+
+**Returns:**
+
+- QuantizationConfig – Optimum configuration.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the configuration to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OptimumEmbedderQuantizationConfig
+```
+
+Create a configuration from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- OptimumEmbedderQuantizationConfig – Quantization configuration.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/oracle.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/oracle.md
new file mode 100644
index 00000000000..642b39074b5
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/oracle.md
@@ -0,0 +1,787 @@
+---
+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`.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying 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]) -> 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### 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 = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Return a paginated list of distinct values for a metadata field, plus the total distinct count.
+
+**Note**: values of different JSON type categories are kept distinct - a string, a number and a
+boolean never collapse into each other, even when they share a textual form (e.g. the string
+`"1"` and the number `1`). One exception: the `metadata` column is Oracle's native `JSON`
+type, which canonicalizes numeric storage, so a whole-number float (`1.0`) and a numerically
+equal int (`1`) collapse into the same value. Floats with a fractional part (e.g. `1.5`) are
+unaffected.
+
+**Parameters:**
+
+- **metadata_field** (str) – Metadata field name. May be prefixed with `"meta."`
+ (e.g. `"meta.lang"` or `"lang"`).
+- **search_term** (str | None) – Optional case-insensitive substring filter applied to the metadata field's own value.
+- **from\_** (int) – Zero-based offset for pagination. Defaults to `0`.
+- **size** (int | None) – Maximum number of values to return. Defaults to `10`. When `None` all values
+ from `from_` onward are returned.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple `(values, total)` where `values` is the paginated list of distinct field
+ values in their original type 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 = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], 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 case-insensitive substring filter applied to the metadata field's own value.
+- **from\_** (int) – Zero-based offset for pagination. Defaults to `0`.
+- **size** (int | None) – Maximum number of values to return. Defaults to `10`. When `None` all values
+ from `from_` onward are returned.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple `(values, total)` where `values` is the paginated list of distinct field
+ values in their original type 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-3.2-unstable/integrations-api/orcarouter.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/orcarouter.md
new file mode 100644
index 00000000000..da4f589a804
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/orcarouter.md
@@ -0,0 +1,91 @@
+---
+title: "OrcaRouter"
+id: integrations-orcarouter
+description: "OrcaRouter integration for Haystack"
+slug: "/integrations-orcarouter"
+---
+
+
+## haystack_integrations.components.generators.orcarouter.chat.chat_generator
+
+### OrcaRouterChatGenerator
+
+Bases: OpenAIChatGenerator
+
+Enables text generation using OrcaRouter generative models.
+
+OrcaRouter is an OpenAI-compatible model routing gateway that exposes 100+ chat models from providers such as
+OpenAI, Anthropic, Google, DeepSeek, and Qwen behind a single endpoint and API key. Models are addressed with a
+`provider/model` namespace (for example `openai/gpt-4o-mini` or `anthropic/claude-opus-4.8`). The special
+`orcarouter/auto` router selects an upstream model per request according to the routing policy configured in your
+OrcaRouter console.
+
+For the list of supported models, see the [OrcaRouter model catalog](https://www.orcarouter.ai/models).
+
+This component supports streaming, tool-calling, and structured outputs.
+It uses the ChatMessage format for both input and output; see the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage) for details.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.orcarouter import OrcaRouterChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = OrcaRouterChatGenerator(model="openai/gpt-4o-mini")
+response = client.run(messages)
+print(response)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("ORCAROUTER_API_KEY"),
+ model: str = "openai/gpt-4o-mini",
+ streaming_callback: StreamingCallbackT | None = None,
+ api_base_url: str | None = "https://api.orcarouter.ai/v1",
+ organization: str | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | None = None,
+ tools_strict: bool = False,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of OrcaRouterChatGenerator.
+
+Unless specified otherwise, the default model is `openai/gpt-4o-mini`.
+
+**Parameters:**
+
+- **api_key** (Secret) – The OrcaRouter API key.
+- **model** (str) – The name of the OrcaRouter chat completion model to use. Models use a `provider/model` namespace
+ (for example `openai/gpt-4o-mini`). Use `orcarouter/auto` to let OrcaRouter route the request.
+- **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 OrcaRouter API base URL. For more details, see the OrcaRouter
+ [documentation](https://docs.orcarouter.ai).
+- **organization** (str | None) – Your OrcaRouter organization ID, if any.
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are sent directly to the OrcaRouter endpoint.
+ See OrcaRouter [API docs](https://docs.orcarouter.ai) for more details. Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: The sampling temperature to use. Higher values mean the model takes more risks.
+- `top_p`: The nucleus sampling value to use.
+- `stream`: Whether to stream back partial progress.
+- `extra_body`: A dictionary of OrcaRouter-specific routing preferences (such as a fallback list of
+ models) that is passed straight through to the gateway.
+- **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.
+- **tools_strict** (bool) – Whether to enable strict schema adherence for tool calls. If set to `True`, the model follows exactly
+ the schema provided in the `parameters` field of the tool definition.
+- **timeout** (float | None) – The timeout for the OrcaRouter API call.
+- **max_retries** (int | None) – Maximum number of retries to contact OrcaRouter 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).
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/paddleocr.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/paddleocr.md
new file mode 100644
index 00000000000..3811d97e64b
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/paddleocr.md
@@ -0,0 +1,163 @@
+---
+title: "PaddleOCR"
+id: integrations-paddleocr
+description: "PaddleOCR integration for Haystack"
+slug: "/integrations-paddleocr"
+---
+
+
+## haystack_integrations.components.converters.paddleocr.paddleocr_vl_document_converter
+
+### PaddleOCRVLDocumentConverter
+
+Extracts text from documents using PaddleOCR's official document parsing API.
+
+Uses `PaddleOCRClient` to parse documents via the PaddleOCR serving API.
+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_integrations.components.converters.paddleocr import PaddleOCRVLDocumentConverter
+
+converter = PaddleOCRVLDocumentConverter(
+ base_url="http://xxxxx.aistudio-app.com",
+)
+result = converter.run(sources=["sample.pdf"])
+documents = result["documents"]
+raw_responses = result["raw_paddleocr_responses"]
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ base_url: str | None = None,
+ access_token: Secret = Secret.from_env_var(
+ ["PADDLEOCR_ACCESS_TOKEN", "AISTUDIO_ACCESS_TOKEN"]
+ ),
+ model: Model | str = Model.PADDLE_OCR_VL_16,
+ 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 | list | 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
+) -> None
+```
+
+Create a `PaddleOCRVLDocumentConverter` component.
+
+**Parameters:**
+
+- **base_url** (str | None) – Base URL for the PaddleOCR API. Falls back to `PADDLEOCR_BASE_URL`
+ env var, then the SDK default.
+- **access_token** (Secret) – PaddleOCR access token. Falls back to `PADDLEOCR_ACCESS_TOKEN` env var.
+- **model** (Model | str) – Document parsing model. Defaults to `Model.PADDLE_OCR_VL_16`.
+- **file_type** (FileTypeInput) – "pdf", "image", or None for auto-detection.
+- **use_doc_orientation_classify** (bool | None) – Enable document orientation classification.
+- **use_doc_unwarping** (bool | None) – Enable text image unwarping.
+- **use_layout_detection** (bool | None) – Enable layout detection.
+- **use_chart_recognition** (bool | None) – Enable chart recognition.
+- **use_seal_recognition** (bool | None) – Enable seal recognition.
+- **use_ocr_for_image_block** (bool | None) – Recognize text in image blocks.
+- **layout_threshold** (float | dict | None) – Layout detection threshold.
+- **layout_nms** (bool | None) – Perform NMS on layout detection results.
+- **layout_unclip_ratio** (float | list | dict | None) – Layout unclip ratio.
+- **layout_merge_bboxes_mode** (str | dict | None) – Layout merge bounding boxes mode.
+- **layout_shape_mode** (str | None) – Layout shape mode.
+- **prompt_label** (str | None) – Prompt type for the VLM ("ocr", "formula", "table", "chart", "seal", "spotting").
+- **format_block_content** (bool | None) – Format block content.
+- **repetition_penalty** (float | None) – Repetition penalty for VLM sampling.
+- **temperature** (float | None) – Temperature for VLM sampling.
+- **top_p** (float | None) – Top-p for VLM sampling.
+- **min_pixels** (int | None) – Minimum pixels for VLM preprocessing.
+- **max_pixels** (int | None) – Maximum pixels for VLM preprocessing.
+- **max_new_tokens** (int | None) – Maximum tokens generated by the VLM.
+- **merge_layout_blocks** (bool | None) – Merge layout detection boxes for cross-column content.
+- **markdown_ignore_labels** (list\[str\] | None) – Layout labels to ignore in Markdown output.
+- **vlm_extra_args** (dict | None) – Extra configuration for the VLM.
+- **prettify_markdown** (bool | None) – Prettify output Markdown.
+- **show_formula_number** (bool | None) – Include formula numbers in Markdown output.
+- **restructure_pages** (bool | None) – Restructure results across multiple pages.
+- **merge_tables** (bool | None) – Merge tables across pages.
+- **relevel_titles** (bool | None) – Relevel titles.
+- **visualize** (bool | None) – Return visualization results.
+- **additional_params** (dict\[str, Any\] | None) – Extra options passed to `PaddleOCRVLOptions.extra_options`.
+
+#### 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]) -> PaddleOCRVLDocumentConverter
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- PaddleOCRVLDocumentConverter – Deserialized component.
+
+#### run
+
+```python
+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.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – List of image or PDF file paths or ByteStream objects.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the Documents. A single dict is applied
+ to all documents; a list must match the number of sources.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with:
+- `documents`: List of created Documents.
+- `raw_paddleocr_responses`: List of raw PaddleOCR API responses.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/parallel.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/parallel.md
new file mode 100644
index 00000000000..8d2949034e4
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/parallel.md
@@ -0,0 +1,249 @@
+---
+title: "Parallel"
+id: integrations-parallel
+description: "Parallel integration for Haystack"
+slug: "/integrations-parallel"
+---
+
+
+## haystack_integrations.components.generators.parallel.chat.chat_generator
+
+### ParallelChatGenerator
+
+Bases: OpenAIResponsesChatGenerator
+
+Completes chats using Parallel's web-research model.
+
+Powered by the Parallel Responses API (`POST /v1/responses`, OpenAI Responses-compatible).
+Every answer is grounded in live web research with citations; the `reasoning.effort`
+parameter selects the research tier: `low` (~5-10s), `medium` (~15-20s, default), or
+`high` (~30-60s).
+See the [Parallel Responses API quickstart](https://docs.parallel.ai/responses-api/responses-quickstart)
+for details.
+
+It uses the [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage) format in input and output.
+Web grounding is built in, so tool calling and sampling parameters (`tools`, `temperature`,
+`top_p`, ...) are accepted for SDK compatibility but silently ignored by the API; this component
+warns when it sees them.
+
+Because a single call runs live research, `timeout` defaults to 120 seconds rather than the
+30 seconds inherited from the OpenAI client, so that the `high` tier fits comfortably.
+
+### Usage example
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.parallel import ParallelChatGenerator
+
+messages = [ChatMessage.from_user("What did Parallel Web Systems announce this year?")]
+
+client = ParallelChatGenerator(generation_kwargs={"reasoning": {"effort": "low"}})
+response = client.run(messages)
+print(response)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = ['parallel']
+```
+
+The Parallel Responses API models supported by this component.
+See https://docs.parallel.ai/responses-api/responses-quickstart for details.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("PARALLEL_API_KEY"),
+ model: str = "parallel",
+ api_base_url: str | None = "https://api.parallel.ai/v1",
+ streaming_callback: StreamingCallbackT | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ timeout: float | None = 120.0,
+ extra_headers: dict[str, Any] | None = None,
+ max_retries: int | None = 3,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Initialize the ParallelChatGenerator component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Parallel API key.
+- **model** (str) – The Parallel Responses API model to use.
+- **api_base_url** (str | None) – The Parallel API base URL.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function called when a new token is received from the stream.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional parameters sent directly to the Parallel Responses API, such as
+ `reasoning` (e.g. `{"effort": "low"}`) to select the research tier or
+ `text` for structured output.
+- **timeout** (float | None) – Timeout in seconds for Parallel API calls. Defaults to 120 seconds, which leaves room for
+ the `high` research tier (~30-60s). Pass `None` to fall back to the OpenAI client default
+ (the `OPENAI_TIMEOUT` environment variable, or 30 seconds), which is too short for most
+ research calls.
+- **extra_headers** (dict\[str, Any\] | None) – Additional HTTP headers to include in requests to the Parallel API.
+- **max_retries** (int | None) – Maximum number of retries to contact Parallel after an internal error. Kept low because
+ every retry runs a full research call. Pass `None` to fall back to the OpenAI client
+ default (the `OPENAI_MAX_RETRIES` environment variable, or 5).
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client` or `httpx.AsyncClient`.
+
+#### 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.websearch.parallel.parallel_websearch
+
+### ParallelWebSearch
+
+A component that uses Parallel to search the web and return results as Haystack Documents.
+
+This component wraps the Parallel Search API, enabling web search queries that return
+LLM-optimized excerpts as structured documents with content and links, plus the
+session identifier that ties related searches together.
+
+You need a Parallel API key from [parallel.ai](https://parallel.ai).
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.parallel import ParallelWebSearch
+from haystack.utils import Secret
+
+websearch = ParallelWebSearch(
+ api_key=Secret.from_env_var("PARALLEL_API_KEY"),
+ top_k=5,
+)
+result = websearch.run(query="What is Haystack by deepset?")
+documents = result["documents"]
+links = result["links"]
+
+# Pass the session back on follow-up searches that are part of the same task
+# to get better contextual results.
+follow_up = websearch.run(
+ query="Who maintains Haystack?",
+ search_params={"session_id": result["session_id"]},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("PARALLEL_API_KEY"),
+ top_k: int | None = 10,
+ search_params: dict[str, Any] | None = None,
+ timeout: float = 30.0
+) -> None
+```
+
+Initialize the ParallelWebSearch component.
+
+**Parameters:**
+
+- **api_key** (Secret) – API key for Parallel. Defaults to the `PARALLEL_API_KEY` environment variable.
+- **top_k** (int | None) – Maximum number of results to return. Maps to the `advanced_settings.max_results` API parameter.
+- **search_params** (dict\[str, Any\] | None) – Additional parameters passed to the Parallel Search API.
+ See the [Parallel Search API reference](https://docs.parallel.ai/api-reference/search/search)
+ for available options. Supported keys include: `objective` (natural-language search goal,
+ defaults to the query), `mode` (`turbo`, `fast`, `basic`, or `advanced`, in increasing
+ order of latency and quality; the API defaults to `advanced`), `max_chars_total`,
+ `session_id`, `client_model`, and `advanced_settings` (nested `source_policy` domain and
+ date filters, `fetch_policy`, `excerpt_settings`, `location`, `max_results`).
+ Pass `session_id` to link several searches into one task; the identifier the API used
+ is always returned in the `session_id` output, whether it was sent or server-generated.
+- **timeout** (float) – Request timeout in seconds.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the sync HTTP client.
+
+Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Initialize the async HTTP client on the serving event loop.
+
+Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the sync HTTP client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the async HTTP client.
+
+#### run
+
+```python
+run(query: str, search_params: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Search the web using Parallel 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 excerpts.
+- `links`: List of URLs from the search results.
+- `session_id`: Session identifier for this search, echoed back from
+ `search_params["session_id"]` if it was provided and generated by the API otherwise.
+ Pass it to subsequent searches that belong to the same task.
+
+#### run_async
+
+```python
+run_async(
+ query: str, search_params: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously search the web using Parallel 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 excerpts.
+- `links`: List of URLs from the search results.
+- `session_id`: Session identifier for this search, echoed back from
+ `search_params["session_id"]` if it was provided and generated by the API otherwise.
+ Pass it to subsequent searches that belong to the same task.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/perplexity.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/perplexity.md
new file mode 100644
index 00000000000..ce0c6e46727
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/perplexity.md
@@ -0,0 +1,445 @@
+---
+title: "Perplexity"
+id: integrations-perplexity
+description: "Perplexity integration for Haystack"
+slug: "/integrations-perplexity"
+---
+
+
+## haystack_integrations.components.embedders.perplexity.document_embedder
+
+### PerplexityDocumentEmbedder
+
+Bases: OpenAIDocumentEmbedder
+
+A component for computing Document embeddings using Perplexity models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+For supported models, see the
+[Perplexity Embeddings API reference](https://docs.perplexity.ai/api-reference/embeddings-post).
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.perplexity import PerplexityDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = PerplexityDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = ['pplx-embed-v1-0.6b', 'pplx-embed-v1-4b']
+```
+
+A list of models supported by the Perplexity Embeddings API.
+See https://docs.perplexity.ai/api-reference/embeddings-post for the current list of model IDs.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("PERPLEXITY_API_KEY"),
+ model: str = "pplx-embed-v1-0.6b",
+ api_base_url: str | None = "https://api.perplexity.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",
+ encoding_format: str = "base64_int8",
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates a PerplexityDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Perplexity API key.
+- **model** (str) – The name of the model to use.
+- **api_base_url** (str | None) – The Perplexity API base URL.
+- **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.
+- **encoding_format** (str) – The Perplexity embedding encoding format. Supported values are `base64_int8` and `base64_binary`.
+- **timeout** (float | None) – Timeout for Perplexity 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 Perplexity 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]) -> PerplexityDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- PerplexityDocumentEmbedder – Deserialized component.
+
+## haystack_integrations.components.embedders.perplexity.text_embedder
+
+### PerplexityTextEmbedder
+
+Bases: OpenAITextEmbedder
+
+A component for embedding strings using Perplexity models.
+
+For supported models, see the
+[Perplexity Embeddings API reference](https://docs.perplexity.ai/api-reference/embeddings-post).
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.perplexity.text_embedder import PerplexityTextEmbedder
+
+text_to_embed = "I love pizza!"
+text_embedder = PerplexityTextEmbedder()
+print(text_embedder.run(text_to_embed))
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = ['pplx-embed-v1-0.6b', 'pplx-embed-v1-4b']
+```
+
+A list of models supported by the Perplexity Embeddings API.
+See https://docs.perplexity.ai/api-reference/embeddings-post for the current list of model IDs.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("PERPLEXITY_API_KEY"),
+ model: str = "pplx-embed-v1-0.6b",
+ api_base_url: str | None = "https://api.perplexity.ai/v1",
+ prefix: str = "",
+ suffix: str = "",
+ encoding_format: str = "base64_int8",
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates a PerplexityTextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Perplexity API key.
+- **model** (str) – The name of the Perplexity embedding model to be used.
+- **api_base_url** (str | None) – The Perplexity API base URL.
+- **prefix** (str) – A string to add to the beginning of each text.
+- **suffix** (str) – A string to add to the end of each text.
+- **encoding_format** (str) – The Perplexity embedding encoding format. Supported values are `base64_int8` and `base64_binary`.
+- **timeout** (float | None) – Timeout for Perplexity 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 Perplexity 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]) -> PerplexityTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- PerplexityTextEmbedder – Deserialized component.
+
+## haystack_integrations.components.generators.perplexity.chat.chat_generator
+
+### PerplexityChatGenerator
+
+Bases: OpenAIResponsesChatGenerator
+
+Completes chats using Perplexity models.
+
+Powered by the Perplexity Agent API (`POST /v1/agent`, OpenAI Responses-compatible).
+See the [Perplexity Agent API quickstart](https://docs.perplexity.ai/docs/agent-api/quickstart)
+for details.
+
+It uses the [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage) format in input and output.
+You can customize generation by passing Perplexity Agent API parameters through `generation_kwargs`.
+
+### Usage example
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.perplexity import PerplexityChatGenerator
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = PerplexityChatGenerator()
+response = client.run(messages)
+print(response)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+ "openai/gpt-5.5",
+ "openai/gpt-5.4",
+ "openai/gpt-4o",
+ "anthropic/claude-sonnet-4-6",
+ "xai/grok-4-1",
+ "google/gemini-3-flash-preview",
+]
+
+```
+
+A non-exhaustive list of Agent API models supported by this component.
+See https://docs.perplexity.ai/docs/agent-api/models for the full and current list.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("PERPLEXITY_API_KEY"),
+ model: str = "openai/gpt-5.4",
+ api_base_url: str | None = "https://api.perplexity.ai/v1",
+ streaming_callback: StreamingCallbackT | None = None,
+ organization: str | None = None,
+ generation_kwargs: dict[str, Any] | None = None,
+ tools: ToolsType | list[dict[str, Any]] | None = None,
+ tools_strict: bool = False,
+ timeout: float | None = None,
+ extra_headers: dict[str, Any] | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Initialize the PerplexityChatGenerator component.
+
+**Parameters:**
+
+- **api_key** (Secret) – The Perplexity API key.
+- **model** (str) – The Perplexity Agent API model to use.
+- **api_base_url** (str | None) – The Perplexity API base URL.
+- **streaming_callback** (StreamingCallbackT | None) – A callback function called when a new token is received from the stream.
+- **organization** (str | None) – Organization ID forwarded to the OpenAI-compatible client.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional parameters sent directly to the Perplexity Agent API.
+- **tools** (ToolsType | list\[dict\[str, Any\]\] | None) – A list of Haystack tools, a Toolset, or OpenAI-compatible tool definitions.
+- **tools_strict** (bool) – Whether to enable strict schema adherence for Haystack tool calls.
+- **timeout** (float | None) – Timeout for Perplexity API calls.
+- **extra_headers** (dict\[str, Any\] | None) – Additional HTTP headers to include in requests to the Perplexity API.
+- **max_retries** (int | None) – Maximum number of retries to contact Perplexity after an internal error.
+- **http_client_kwargs** (dict\[str, Any\] | None) – A dictionary of keyword arguments to configure a custom `httpx.Client` or `httpx.AsyncClient`.
+
+#### 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]) -> PerplexityChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary representation of this component.
+
+**Returns:**
+
+- PerplexityChatGenerator – The deserialized component instance.
+
+## haystack_integrations.components.websearch.perplexity.perplexity_websearch
+
+### PerplexityWebSearch
+
+A component that uses Perplexity to search the web and return results as Haystack Documents.
+
+This component wraps the Perplexity Search API, enabling web search queries that return
+structured documents with content and links.
+
+You need a Perplexity API key from [perplexity.ai](https://www.perplexity.ai/).
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.perplexity import PerplexityWebSearch
+from haystack.utils import Secret
+
+websearch = PerplexityWebSearch(
+ api_key=Secret.from_env_var("PERPLEXITY_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("PERPLEXITY_API_KEY"),
+ top_k: int | None = 10,
+ search_params: dict[str, Any] | None = None,
+ timeout: float = 30.0
+) -> None
+```
+
+Initialize the PerplexityWebSearch component.
+
+**Parameters:**
+
+- **api_key** (Secret) – API key for Perplexity. Defaults to the `PERPLEXITY_API_KEY` environment variable.
+- **top_k** (int | None) – Maximum number of results to return. Maps to the `max_results` API parameter (1-20).
+- **search_params** (dict\[str, Any\] | None) – Additional parameters passed to the Perplexity Search API.
+ See the [Perplexity Search API reference](https://docs.perplexity.ai/api-reference/search-post)
+ for available options. Supported keys include: `max_tokens_per_page`, `country`,
+ `search_recency_filter`, `search_domain_filter`, `search_language_filter`,
+ `last_updated_after_filter`, `last_updated_before_filter`,
+ `search_after_date_filter`, `search_before_date_filter`.
+- **timeout** (float) – Request timeout in seconds.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the synchronous HTTP client.
+
+Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Initialize the asynchronous HTTP client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous HTTP client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous HTTP client.
+
+#### run
+
+```python
+run(
+ query: str, search_params: dict[str, Any] | None = None
+) -> dict[str, list[Document] | list[str]]
+```
+
+Search the web using Perplexity 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, list\[Document\] | list\[str\]\] – 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, list[Document] | list[str]]
+```
+
+Asynchronously search the web using Perplexity 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, list\[Document\] | list\[str\]\] – 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-3.2-unstable/integrations-api/pgvector.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/pgvector.md
new file mode 100644
index 00000000000..cbad50a83ed
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/pgvector.md
@@ -0,0 +1,962 @@
+---
+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
+# Requires: pip install sentence-transformers-haystack
+from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
+from haystack_integrations.components.embedders.sentence_transformers import 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()
+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
+) -> None
+```
+
+Initialize the PgvectorEmbeddingRetriever.
+
+**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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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
+) -> None
+````
+
+Initialize the PgvectorKeywordRetriever.
+
+**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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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"
+) -> None
+```
+
+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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the associated asynchronous resources.
+
+#### 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 `PgvectorDocumentStore`.
+
+#### delete_table_async
+
+```python
+delete_table_async() -> None
+```
+
+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.
+
+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.
+
+#### 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.
+
+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 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
+{
+ '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.
+ Returns `{"min": None, "max": None}` when the field has no values or the store is empty.
+
+#### 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.
+ 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(
+ metadata_field: str,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Returns unique values for a given metadata field, optionally filtered by a search term.
+
+**Note**: values of different JSON type categories are kept distinct - a string, a number and
+a boolean never collapse into each other, even when they share a textual form (e.g. the string
+`"1"` and the number `1`). One exception: the `meta` column is JSONB, whose equality treats a
+whole-number float (`1.0`) as identical to a numerically equal int (`1`), so those two collapse
+into a single value. Floats with a fractional part (e.g. `1.5`) are unaffected.
+
+**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 unique values by a case-insensitive substring
+ match against the metadata field's own value. If None, all values are considered.
+- **from\_** (int) – The offset for pagination (0-based).
+- **size** (int) – The number of unique values to return.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing:
+- A list of unique values in their original type
+- 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 = None,
+ from_: int = 0,
+ size: int = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Asynchronously returns unique values for a given metadata field, optionally filtered by a search term.
+
+**Note**: values of different JSON type categories are kept distinct - a string, a number and
+a boolean never collapse into each other, even when they share a textual form (e.g. the string
+`"1"` and the number `1`). One exception: the `meta` column is JSONB, whose equality treats a
+whole-number float (`1.0`) as identical to a numerically equal int (`1`), so those two collapse
+into a single value. Floats with a fractional part (e.g. `1.5`) are unaffected.
+
+**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 unique values by a case-insensitive substring
+ match against the metadata field's own value. If None, all values are considered.
+- **from\_** (int) – The offset for pagination (0-based).
+- **size** (int) – The number of unique values to return.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing:
+- A list of unique values in their original type
+- The total count of unique values
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/pinecone.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/pinecone.md
new file mode 100644
index 00000000000..e066bfc9648
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/pinecone.md
@@ -0,0 +1,733 @@
+---
+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
+# Requires: pip install sentence-transformers-haystack
+from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
+from haystack_integrations.components.embedders.sentence_transformers import 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()
+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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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
+```
+
+Release the associated synchronous resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the associated asynchronous resources.
+
+#### 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], 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.
+
+Note: Pinecone stores numeric metadata values as `float` (see `_convert_meta_to_int`), so an
+int written for an arbitrary field may come back as a numerically equal float rather than int.
+Values of different types are otherwise kept distinct even when they compare equal in Python
+(e.g. the int `1` and the bool `True` are returned as two separate values).
+
+**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).
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – Tuple of (list of unique values in their original type, 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], 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.
+
+Note: Pinecone stores numeric metadata values as `float` (see `_convert_meta_to_int`), so an
+int written for an arbitrary field may come back as a numerically equal float rather than int.
+Values of different types are otherwise kept distinct even when they compare equal in Python
+(e.g. the int `1` and the bool `True` are returned as two separate values).
+
+**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).
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – Tuple of (list of unique values in their original type, total count of matching values).
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/presidio.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/presidio.md
new file mode 100644
index 00000000000..3ab6215e0fa
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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-3.2-unstable/integrations-api/pyversity.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/pyversity.md
new file mode 100644
index 00000000000..00662bd24c0
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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-3.2-unstable/integrations-api/qdrant.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/qdrant.md
new file mode 100644
index 00000000000..174ff310f44
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/qdrant.md
@@ -0,0 +1,1389 @@
+---
+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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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 a QdrantDocumentStore using both dense and sparse vectors.
+
+Fuses 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,
+ rrf_k: int | None = None,
+ rrf_weights: list[float] | 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.
+- **rrf_k** (int | None) – The `k` constant for Reciprocal Rank Fusion. Controls ranking formula smoothing.
+ See https://qdrant.tech/documentation/search/hybrid-queries/#setting-rrf-constant-k.
+ Requires Qdrant server >= 1.16.0.
+- **rrf_weights** (list\[float\] | None) – Per-prefetch weights for RRF fusion — `[sparse_weight, dense_weight]`.
+ See https://qdrant.tech/documentation/search/hybrid-queries/#setting-rrf-weights.
+ Requires Qdrant server >= 1.17.0.
+
+**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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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,
+ rrf_k: int | None = None,
+ rrf_weights: list[float] | 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.
+- **rrf_k** (int | None) – Override the init-time `rrf_k` for this run.
+ See https://qdrant.tech/documentation/search/hybrid-queries/#setting-rrf-constant-k.
+ Requires Qdrant server >= 1.16.0.
+- **rrf_weights** (list\[float\] | None) – Override the init-time `rrf_weights` for this run.
+ See https://qdrant.tech/documentation/search/hybrid-queries/#setting-rrf-weights.
+ Requires Qdrant server >= 1.17.0.
+
+**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,
+ rrf_k: int | None = None,
+ rrf_weights: list[float] | 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.
+- **rrf_k** (int | None) – Override the init-time `rrf_k` for this run.
+ See https://qdrant.tech/documentation/search/hybrid-queries/#setting-rrf-constant-k.
+ Requires Qdrant server >= 1.16.0.
+- **rrf_weights** (list\[float\] | None) – Override the init-time `rrf_weights` for this run.
+ See https://qdrant.tech/documentation/search/hybrid-queries/#setting-rrf-weights.
+ Requires Qdrant server >= 1.17.0.
+
+**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.
+
+Supports 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the associated asynchronous resources.
+
+#### 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.
+
+Only documents that match the filters are considered.
+
+**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,
+ search_term: str | None = None,
+ from_: int = 0,
+ size: int = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Returns unique values for a metadata field, with optional filters, search term and pagination.
+
+Unique values are sorted by string representation, then by type name, before pagination is applied.
+
+**Note**: This operation can be expensive for metadata fields with many unique values, since all
+matching documents must be scrolled through to compute the total count.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field key (inside `meta`) to get unique values for.
+- **search_term** (str | None) – Optional case-insensitive substring filter applied to the metadata field's own value.
+- **from\_** (int) – The offset for pagination (0-based). Defaults to 0.
+- **size** (int) – The maximum number of unique values to return. Defaults to 10.
+- **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)
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing (list of unique values, total count of unique 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Asynchronously returns unique values for a metadata field, with optional filters, search term and pagination.
+
+Unique values are sorted by string representation, then by type name, before pagination is applied.
+
+**Note**: This operation can be expensive for metadata fields with many unique values, since all
+matching documents must be scrolled through to compute the total count.
+
+**Parameters:**
+
+- **metadata_field** (str) – The metadata field key (inside `meta`) to get unique values for.
+- **search_term** (str | None) – Optional case-insensitive substring filter applied to the metadata field's own value.
+- **from\_** (int) – The offset for pagination (0-based). Defaults to 0.
+- **size** (int) – The maximum number of unique values to return. Defaults to 10.
+- **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)
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple containing (list of unique values, total count of unique matching values).
+
+#### 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-3.2-unstable/integrations-api/ragas.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ragas.md
new file mode 100644
index 00000000000..d5d5bac4ff3
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ragas.md
@@ -0,0 +1,170 @@
+---
+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.
+
+With `haystack-ai` >= 3.0, the module a metric class lives in must be on the deserialization
+allowlist. Metrics shipped by ragas are trusted automatically; a custom metric class from
+your own package has to be trusted explicitly, e.g. via
+`Pipeline.load(..., allowed_modules=["mypackage.*"])`.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- RagasEvaluator – Deserialized component.
+
+**Raises:**
+
+- DeserializationError – If a metric class is not on the deserialization allowlist.
+
+#### 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-3.2-unstable/integrations-api/rhesis.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/rhesis.md
new file mode 100644
index 00000000000..ac807e9a08d
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/rhesis.md
@@ -0,0 +1,550 @@
+---
+title: "Rhesis"
+id: integrations-rhesis
+description: "Rhesis integration for Haystack"
+slug: "/integrations-rhesis"
+---
+
+
+## haystack_integrations.components.connectors.rhesis.rhesis_connector
+
+### RhesisConnector
+
+Connects Haystack to [Rhesis](https://rhesis.ai) for OpenTelemetry-based tracing of pipelines.
+
+Add this component to a pipeline without connecting it to other components. It enables tracing
+for all pipeline operations when Haystack tracing is active.
+
+**Environment Configuration:**
+
+- `RHESIS_API_KEY`: Required API key for trace ingestion.
+- `RHESIS_BASE_URL`: Backend URL (default `http://localhost:8080` for local development).
+- `RHESIS_PROJECT_ID`: Optional project identifier (resolved from the API key when omitted).
+- `RHESIS_ENVIRONMENT`: Deployment environment label (default `development`).
+- `RHESIS_FRONTEND_URL`: Optional frontend URL used to build `trace_url` deep links.
+- `HAYSTACK_CONTENT_TRACING_ENABLED`: Must be `"true"` **before importing Haystack** to
+ capture input/output on spans.
+- `HAYSTACK_RHESIS_ENFORCE_FLUSH`: When `"true"` (default), exports once per pipeline run,
+ as the root span closes. Set to `"false"` to leave exporting to the batch processor and
+ flush on shutdown instead.
+
+Example shutdown flush for FastAPI:
+
+```python
+from haystack.tracing import tracer
+
+@app.on_event("shutdown")
+async def shutdown_event():
+ tracer.actual_tracer.flush()
+```
+
+#### __init__
+
+```python
+__init__(
+ name: str,
+ api_key: Secret | None = Secret.from_env_var("RHESIS_API_KEY"),
+ base_url: str | None = None,
+ project_id: str | None = None,
+ environment: str | None = None,
+ frontend_url: str | None = None,
+ span_handler: SpanHandler | None = None,
+) -> None
+```
+
+Initialize the RhesisConnector component.
+
+**Parameters:**
+
+- **name** (str) – Trace name shown in the Rhesis UI.
+- **api_key** (Secret | None) – Rhesis API key. Defaults to `RHESIS_API_KEY`.
+- **base_url** (str | None) – Rhesis backend base URL. Defaults to `RHESIS_BASE_URL` or
+ `http://localhost:8080`.
+- **project_id** (str | None) – Rhesis project ID. Defaults to `RHESIS_PROJECT_ID`.
+- **environment** (str | None) – Environment label. Defaults to `RHESIS_ENVIRONMENT` or
+ `development`.
+- **frontend_url** (str | None) – Frontend base URL for `trace_url`. Defaults to `RHESIS_FRONTEND_URL`.
+- **span_handler** (SpanHandler | None) – Optional custom span handler. Uses :class:`DefaultSpanHandler` when omitted.
+
+**Raises:**
+
+- ValueError – If no API key resolves. A component the user explicitly added to a
+ pipeline should say so rather than silently trace nothing — but it does mean
+ `Pipeline.from_dict` on a YAML containing this component needs credentials present.
+ :class:`~haystack_integrations.tracing.rhesis.RhesisTracing` deliberately does the
+ opposite and degrades to a no-op, because there the caller did not put tracing in the
+ data path.
+
+#### run
+
+```python
+run(invocation_context: dict[str, Any] | None = None) -> dict[str, str]
+```
+
+Run the connector and return trace metadata.
+
+The context applies to the pipeline run that invoked this component and no other. The
+ContextVar it is written to is set by `RhesisTracer.trace` when the run's root span opens
+and restored when that span closes, so this write lands inside that scope and cannot outlive
+the run — which is why the context is only honoured when a root span is open. Outside one
+there is nothing to scope it to and nothing to stamp it on, so it is ignored rather than left
+behind for the next caller to inherit. To attach metadata to work that is not a pipeline run
+— a standalone `Agent`, say — wrap the call in
+:func:`~haystack_integrations.tracing.rhesis.rhesis_invocation_context` instead, which scopes
+the value to its own block.
+
+**Parameters:**
+
+- **invocation_context** (dict\[str, Any\] | None) – Optional key-value metadata attached to the root trace
+ (session, test run identifiers, tags, etc.).
+
+**Returns:**
+
+- dict\[str, str\] – Dictionary with `name`, `trace_url`, and `trace_id`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+Records the arguments as they were passed, not as they were resolved: anything left to the
+environment stays `None` so that deserializing on another machine resolves it there. This
+mirrors how `Secret.from_env_var` serializes a reference rather than the secret's value.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> RhesisConnector
+```
+
+Deserialize this component from a dictionary.
+
+## haystack_integrations.tracing.rhesis.conversation
+
+Conversation-aware tracing for applications that drive Haystack from their own loop.
+
+### ConversationTurn
+
+A single conversation turn, yielded by :meth:`RhesisTracing.turn`.
+
+Assign :attr:`output` with the reply the user actually sees. Only the application knows
+what that is — it may be a tool result or a value held in agent state rather than the last
+assistant message — so it cannot be inferred from the span tree.
+
+#### span
+
+```python
+span: Span | None
+```
+
+The underlying OTel span, or `None` when tracing is disabled.
+
+#### output
+
+```python
+output: str
+```
+
+The reply recorded for this turn.
+
+### RhesisTracing
+
+Enable Rhesis tracing for an application that runs Haystack from its own loop.
+
+:class:`RhesisConnector` covers the common case: add it to a pipeline and every run is
+traced. An application that owns its loop — a chat REPL, a batch script, a server handling
+one turn per request — needs two things a component inside the pipeline cannot provide:
+tracing switched on without a pipeline to attach to, and a span wrapping a whole pipeline
+run so a conversation turn has a root of its own.
+
+Without that root span, the Haystack pipeline span claims the turn and reports the
+serialized pipeline input and output as the conversation text.
+
+`HAYSTACK_CONTENT_TRACING_ENABLED` must still be set to `"true"` before Haystack is
+imported, exactly as when using the connector.
+
+### Usage example
+
+```python
+import os
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+from haystack_integrations.tracing.rhesis import RhesisTracing
+
+tracing = RhesisTracing("My Assistant")
+tracing.start_conversation("conversation-1")
+
+for message in ["Hello", "Tell me more"]:
+ with tracing.turn(message) as turn:
+ result = pipeline.run(...)
+ turn.output = result["llm"]["replies"][0].text
+
+tracing.flush()
+```
+
+#### __init__
+
+```python
+__init__(
+ name: str,
+ *,
+ enabled: bool = True,
+ turn_span_name: str = DEFAULT_TURN_SPAN_NAME,
+ **connector_kwargs: Any
+) -> None
+```
+
+Enable tracing, or fall back to a no-op when Rhesis is not configured.
+
+Construction never raises on a missing or rejected configuration: an application should
+run untraced rather than fail to start. Check :attr:`enabled` to report it.
+
+This is the opposite of :class:`~haystack_integrations.components.connectors.rhesis.RhesisConnector`,
+which raises when no API key resolves, and deliberately so. The connector is a component the
+user put in a pipeline; failing loudly there is the honest signal that the thing they wired
+up will not do its job. Here tracing wraps an application's own loop and is not in its data
+path, so the same failure should cost the application nothing.
+
+**Parameters:**
+
+- **name** (str) – Trace name shown in the Rhesis UI.
+- **enabled** (bool) – Set to `False` to build a no-op instance, so an application can gate
+ tracing on its own policy without branching around every call.
+- **turn_span_name** (str) – Span name for each conversation turn root.
+- **connector_kwargs** (Any) – Forwarded to :class:`RhesisConnector` (`api_key`,
+ `base_url`, `project_id`, `environment`, `frontend_url`, `span_handler`).
+
+#### enabled
+
+```python
+enabled: bool
+```
+
+Whether tracing was successfully enabled.
+
+#### start_conversation
+
+```python
+start_conversation(conversation_id: str, **invocation_context: Any) -> None
+```
+
+Group the turns that follow into one conversation, sharing one trace.
+
+Calling this again starts a new conversation: the next turn opens a new trace and later
+turns join it.
+
+**Parameters:**
+
+- **conversation_id** (str) – Identifier grouping the turns, shown as the conversation in Rhesis.
+- **invocation_context** (Any) – Extra metadata for the root span, as
+ :meth:`RhesisConnector.run` accepts (test run identifiers, tags, …).
+
+#### turn
+
+```python
+turn(user_input: str) -> Iterator[ConversationTurn]
+```
+
+Open the root span for one conversation turn.
+
+Run the turn's work inside the block and assign the reply to
+:attr:`ConversationTurn.output`. Every turn after the first joins the first one's trace,
+so a conversation reads as one trace rather than one per exchange.
+
+Yields an inert turn when tracing is disabled, so callers need no branching.
+
+**Parameters:**
+
+- **user_input** (str) – The user's message, recorded as the turn's conversation input.
+
+#### flush
+
+```python
+flush() -> None
+```
+
+Flush pending spans. Call before exit; batched spans are otherwise lost.
+
+## haystack_integrations.tracing.rhesis.tracer
+
+Rhesis tracing bridge for Haystack.
+
+Set `HAYSTACK_CONTENT_TRACING_ENABLED=true` before importing Haystack to capture
+input/output content on spans.
+
+### rhesis_invocation_context
+
+```python
+rhesis_invocation_context(
+ invocation_context: dict[str, Any] | None = None,
+) -> Iterator[None]
+```
+
+Attach Rhesis session/test metadata for the current async task or thread.
+
+### RhesisTelemetry
+
+Thin wrapper around the OTel provider used by the Haystack integration.
+
+#### flush
+
+```python
+flush() -> None
+```
+
+Flush pending spans to the Rhesis backend.
+
+### resolve_frontend_url
+
+```python
+resolve_frontend_url(base_url: str, frontend_url: str | None) -> str
+```
+
+Resolve the Rhesis frontend base URL for trace deep links.
+
+Only the two well-known deployments are derived from `base_url`. Any other backend returns an
+empty string — and therefore an empty `trace_url` — unless `RHESIS_FRONTEND_URL` is set.
+
+**Parameters:**
+
+- **base_url** (str) – The Rhesis backend base URL.
+- **frontend_url** (str | None) – An explicit frontend origin, which always wins when given.
+
+**Returns:**
+
+- str – The frontend origin without a trailing slash, or `""` when it cannot be derived.
+
+### build_trace_url
+
+```python
+build_trace_url(
+ frontend_url: str, trace_id: str, project_id: str | None
+) -> str
+```
+
+Build a frontend deep link for the given trace.
+
+### RhesisSpan
+
+Bases: Span
+
+Bridge between Haystack's span API and OpenTelemetry spans for Rhesis.
+
+#### set_tag
+
+```python
+set_tag(key: str, value: Any) -> None
+```
+
+Set a generic tag for this span.
+
+#### set_content_tag
+
+```python
+set_content_tag(key: str, value: Any) -> None
+```
+
+Set a content-specific tag for this span when content tracing is enabled.
+
+#### raw_span
+
+```python
+raw_span() -> trace.Span
+```
+
+Return the underlying OpenTelemetry span instance.
+
+#### close
+
+```python
+close(exc_info: tuple[Any, Any, Any] | None = None) -> None
+```
+
+End the underlying OpenTelemetry span.
+
+**Parameters:**
+
+- **exc_info** (tuple\[Any, Any, Any\] | None) – The `sys.exc_info()` triple when the span is closing because of an
+ exception, so the context manager sees it; `None` on the success path.
+
+#### get_data
+
+```python
+get_data() -> dict[str, Any]
+```
+
+Return the raw Haystack tag data collected for this span.
+
+#### get_correlation_data_for_logs
+
+```python
+get_correlation_data_for_logs() -> dict[str, Any]
+```
+
+Return trace and span identifiers for log correlation.
+
+#### set_tags
+
+```python
+set_tags(tags: dict[str, Any]) -> None
+```
+
+Set multiple tags on this span.
+
+### SpanContext
+
+Context for creating spans in Rhesis.
+
+### SpanHandler
+
+Bases: ABC
+
+Extension point for customizing Rhesis span creation and enrichment.
+
+#### init_tracer
+
+```python
+init_tracer(tracer: RhesisTelemetry) -> None
+```
+
+Initialize with the Rhesis telemetry wrapper.
+
+#### create_span
+
+```python
+create_span(context: SpanContext) -> RhesisSpan
+```
+
+Create a span of appropriate type based on the context.
+
+#### handle
+
+```python
+handle(span: RhesisSpan, component_type: str | None) -> None
+```
+
+Process a span after component execution.
+
+#### 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
+
+Default Rhesis tracing behavior for Haystack pipelines.
+
+#### create_span
+
+```python
+create_span(context: SpanContext) -> RhesisSpan
+```
+
+Create a Rhesis span based on the given Haystack context.
+
+#### handle
+
+```python
+handle(span: RhesisSpan, component_type: str | None) -> None
+```
+
+Process and enrich a span after component execution.
+
+### RhesisTracer
+
+Bases: Tracer
+
+Haystack tracer implementation that exports spans to Rhesis via OpenTelemetry.
+
+#### __init__
+
+```python
+__init__(
+ telemetry: RhesisTelemetry,
+ name: str = "Haystack",
+ span_handler: SpanHandler | None = None,
+) -> None
+```
+
+Initialize a RhesisTracer instance.
+
+**Parameters:**
+
+- **telemetry** (RhesisTelemetry) – Configured Rhesis OpenTelemetry telemetry wrapper.
+- **name** (str) – Trace name shown in the Rhesis UI.
+- **span_handler** (SpanHandler | None) – Custom handler for span creation and enrichment.
+
+#### telemetry
+
+```python
+telemetry: RhesisTelemetry
+```
+
+The Rhesis OTel provider and tracer backing this tracer.
+
+Public because the provider is private to this tracer: it is not installed as the
+OpenTelemetry global, so anything that needs to open a span destined for Rhesis — the
+conversation turn spans in :class:`~haystack_integrations.tracing.rhesis.RhesisTracing`, or a
+custom :class:`SpanHandler` — has to reach it through here rather than through
+`trace.get_tracer()`.
+
+#### 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 Rhesis.
+
+#### current_span
+
+```python
+current_span() -> Span | None
+```
+
+Return the current active span.
+
+#### get_trace_url
+
+```python
+get_trace_url() -> str
+```
+
+Return the frontend URL for the current trace, when available.
+
+#### get_trace_id
+
+```python
+get_trace_id() -> str
+```
+
+Return the trace ID of the root span currently open in this context.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/searchapi.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/searchapi.md
new file mode 100644
index 00000000000..a55ccbd860a
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/searchapi.md
@@ -0,0 +1,128 @@
+---
+title: "SearchApi"
+id: integrations-searchapi
+description: "SearchApi integration for Haystack"
+slug: "/integrations-searchapi"
+---
+
+
+## haystack_integrations.components.websearch.searchapi.websearch
+
+### SearchApiWebSearch
+
+Uses [SearchApi](https://www.searchapi.io/) to search the web for relevant documents.
+
+Usage example:
+
+```python
+from haystack.utils import Secret
+
+from haystack_integrations.components.websearch.searchapi import SearchApiWebSearch
+
+websearch = SearchApiWebSearch(top_k=10, api_key=Secret.from_env_var("SEARCHAPI_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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/sentence_transformers.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/sentence_transformers.md
new file mode 100644
index 00000000000..b2be5f991a2
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/sentence_transformers.md
@@ -0,0 +1,1095 @@
+---
+title: "Sentence Transformers"
+id: integrations-sentence-transformers
+description: "Sentence Transformers integration for Haystack"
+slug: "/integrations-sentence-transformers"
+---
+
+
+## haystack_integrations.components.embedders.sentence_transformers.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_integrations.components.embedders.sentence_transformers 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.
+
+## haystack_integrations.components.embedders.sentence_transformers.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_integrations.components.embedders.sentence_transformers 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,
+ quantization_ranges: list[list[float]] | 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.
+- **quantization_ranges** (list\[list\[float\]\] | None) – Calibration ranges to use when `precision` is "int8" or "uint8", with shape `(2, embedding_dim)`:
+ minimum values in the first row and maximum values in the second.
+ Scalar quantization calibrates the min/max range from the batch being encoded, which is degenerate
+ for small batches and inconsistent across batches. Pass ranges computed from a representative
+ sample of embeddings to get consistent quantized embeddings, compatible with query embeddings
+ quantized with the same ranges.
+
+#### 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.
+
+## haystack_integrations.components.embedders.sentence_transformers.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_integrations.components.embedders.sentence_transformers 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.
+
+## haystack_integrations.components.embedders.sentence_transformers.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_integrations.components.embedders.sentence_transformers 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.
+
+## haystack_integrations.components.embedders.sentence_transformers.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_integrations.components.embedders.sentence_transformers 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,
+ quantization_ranges: list[list[float]] | 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.
+- **quantization_ranges** (list\[list\[float\]\] | None) – Calibration ranges to use when `precision` is "int8" or "uint8", with shape `(2, embedding_dim)`:
+ minimum values in the first row and maximum values in the second.
+ Scalar quantization calibrates the min/max range from the batch being encoded, which is degenerate
+ for a single text and produces meaningless embeddings. Pass ranges computed from a representative
+ sample of embeddings to get consistent quantized embeddings.
+
+#### 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.
+
+## haystack_integrations.components.rankers.sentence_transformers.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_integrations.components.rankers.sentence_transformers 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.
+
+## haystack_integrations.components.rankers.sentence_transformers.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_integrations.components.rankers.sentence_transformers 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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/serperdev.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/serperdev.md
new file mode 100644
index 00000000000..4b5645bb1e0
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/serperdev.md
@@ -0,0 +1,143 @@
+---
+title: "SerperDev"
+id: integrations-serperdev
+description: "SerperDev integration for Haystack"
+slug: "/integrations-serperdev"
+---
+
+
+## haystack_integrations.components.websearch.serperdev.websearch
+
+### 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.utils import Secret
+
+from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
+
+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-3.2-unstable/integrations-api/snowflake.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/snowflake.md
new file mode 100644
index 00000000000..bad5f519b86
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-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="SolrDocumentStore) – the document store to search.
+- **filters** (dict\[str, Any\] | None) – filters applied to the search. Combined with the filters passed to `run`
+ according to `filter_policy`.
+- **fuzziness** (int) – per-term edit distance. `0`, the default, disables fuzzy matching.
+- **top_k** (int) – maximum number of documents to return.
+- **scale_score** (bool) – whether to scale scores into the `(0, 1)` range.
+- **all_terms_must_match** (bool) – whether every query term must match.
+- **filter_policy** (str | FilterPolicy) – how runtime filters combine with the filters given here.
+- **raise_on_failure** (bool) – whether a failing search raises, or logs and returns no documents.
+
+**Raises:**
+
+- ValueError – if `document_store` is not a `SolrDocumentStore`, or `top_k` is not positive.
+
+#### 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]) -> SolrBM25Retriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – dictionary to deserialize from.
+
+**Returns:**
+
+- SolrBM25Retriever – deserialized component.
+
+#### run
+
+```python
+run(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ fuzziness: int | None = None,
+ scale_score: bool | None = None,
+ all_terms_must_match: bool | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents matching `query`.
+
+**Parameters:**
+
+- **query** (str) – the query string.
+- **filters** (dict\[str, Any\] | None) – filters applied to the search.
+- **top_k** (int | None) – maximum number of documents to return.
+- **fuzziness** (int | None) – per-term edit distance.
+- **scale_score** (bool | None) – whether to scale scores into the `(0, 1)` range.
+- **all_terms_must_match** (bool | None) – whether every query term must match.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – a dictionary with a `documents` key holding the retrieved documents.
+
+**Raises:**
+
+- ValueError – if `top_k` is not positive.
+
+#### run_async
+
+```python
+run_async(
+ query: str,
+ filters: dict[str, Any] | None = None,
+ top_k: int | None = None,
+ fuzziness: int | None = None,
+ scale_score: bool | None = None,
+ all_terms_must_match: bool | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents matching `query`, asynchronously.
+
+**Parameters:**
+
+- **query** (str) – the query string.
+- **filters** (dict\[str, Any\] | None) – filters applied to the search.
+- **top_k** (int | None) – maximum number of documents to return.
+- **fuzziness** (int | None) – per-term edit distance.
+- **scale_score** (bool | None) – whether to scale scores into the `(0, 1)` range.
+- **all_terms_must_match** (bool | None) – whether every query term must match.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – a dictionary with a `documents` key holding the retrieved documents.
+
+**Raises:**
+
+- ValueError – if `top_k` is not positive.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the underlying document store connection.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the underlying document store async connection.
+
+## haystack_integrations.components.retrievers.solr.embedding_retriever
+
+### SolrEmbeddingRetriever
+
+Fetches documents from a `SolrDocumentStore` using Solr's `{!knn}` dense vector search.
+
+Usage example:
+
+```python
+from haystack import Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack_integrations.document_stores.solr import SolrDocumentStore
+from haystack_integrations.components.retrievers.solr import SolrEmbeddingRetriever
+
+document_store = SolrDocumentStore(core="haystack", embedding_dim=384)
+embedder = SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+
+pipeline = Pipeline()
+pipeline.add_component("embedder", embedder)
+pipeline.add_component("retriever", SolrEmbeddingRetriever(document_store=document_store))
+pipeline.connect("embedder.embedding", "retriever.query_embedding")
+
+result = pipeline.run(data={"embedder": {"text": "Apache Solr"}})
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: SolrDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+ raise_on_failure: bool = True
+) -> None
+```
+
+Create a `SolrEmbeddingRetriever`.
+
+**Parameters:**
+
+- **document_store** (SolrDocumentStore) – the document store to search.
+- **filters** (dict\[str, Any\] | None) – filters applied to the search. Combined with the filters passed to `run`
+ according to `filter_policy`. Filters act as a k-NN graph pre-filter, so the search still
+ returns up to `top_k` documents.
+- **top_k** (int) – maximum number of documents to return.
+- **filter_policy** (str | FilterPolicy) – how runtime filters combine with the filters given here.
+- **raise_on_failure** (bool) – whether a failing search raises, or logs and returns no documents.
+
+**Raises:**
+
+- ValueError – if `document_store` is not a `SolrDocumentStore`, or `top_k` is not positive.
+
+#### 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]) -> SolrEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – dictionary to deserialize from.
+
+**Returns:**
+
+- SolrEmbeddingRetriever – 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 similar to `query_embedding`.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – the query embedding.
+- **filters** (dict\[str, Any\] | None) – filters applied to the search.
+- **top_k** (int | None) – maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – a dictionary with a `documents` key holding the retrieved documents.
+
+**Raises:**
+
+- ValueError – if `top_k` is not positive.
+
+#### 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 similar to `query_embedding`, asynchronously.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – the query embedding.
+- **filters** (dict\[str, Any\] | None) – filters applied to the search.
+- **top_k** (int | None) – maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – a dictionary with a `documents` key holding the retrieved documents.
+
+**Raises:**
+
+- ValueError – if `top_k` is not positive.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the underlying document store connection.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the underlying document store async connection.
+
+## haystack_integrations.components.retrievers.solr.solr_hybrid_retriever
+
+### SolrHybridRetriever
+
+Hybrid retrieval over a `SolrDocumentStore`, combining BM25 and dense vector search.
+
+Wraps a pipeline that embeds the query, runs a BM25 and an embedding retriever over the same core,
+and fuses the two result lists with a `DocumentJoiner`.
+
+Usage example:
+
+```python
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack_integrations.document_stores.solr import SolrDocumentStore
+from haystack_integrations.components.retrievers.solr import SolrHybridRetriever
+
+document_store = SolrDocumentStore(core="haystack", embedding_dim=384)
+retriever = SolrHybridRetriever(
+ document_store=document_store,
+ embedder=SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"),
+)
+retriever.warm_up()
+result = retriever.run(query="Apache Solr")
+```
+
+#### __init__
+
+```python
+__init__(
+ document_store: SolrDocumentStore,
+ *,
+ embedder: TextEmbedder,
+ filters_bm25: dict[str, Any] | None = None,
+ fuzziness: int = 0,
+ top_k_bm25: int = 10,
+ scale_score: bool = False,
+ all_terms_must_match: bool = False,
+ filter_policy_bm25: str | FilterPolicy = FilterPolicy.REPLACE,
+ filters_embedding: dict[str, Any] | None = None,
+ top_k_embedding: int = 10,
+ filter_policy_embedding: str | FilterPolicy = FilterPolicy.REPLACE,
+ join_mode: str | JoinMode = JoinMode.RECIPROCAL_RANK_FUSION,
+ weights: list[float] | None = None,
+ top_k: int | None = None,
+ sort_by_score: bool = True,
+ **kwargs: Any
+) -> None
+```
+
+Create a `SolrHybridRetriever`.
+
+**Parameters:**
+
+- **document_store** (SolrDocumentStore) – the document store both retrievers search.
+- **embedder** (TextEmbedder) – the text embedder turning the query into a vector.
+- **filters_bm25** (dict\[str, Any\] | None) – filters for the BM25 branch.
+- **fuzziness** (int) – per-term edit distance for the BM25 branch.
+- **top_k_bm25** (int) – maximum number of documents from the BM25 branch.
+- **scale_score** (bool) – whether to scale BM25 scores into the `(0, 1)` range.
+- **all_terms_must_match** (bool) – whether every query term must match in the BM25 branch.
+- **filter_policy_bm25** (str | FilterPolicy) – filter policy for the BM25 branch.
+- **filters_embedding** (dict\[str, Any\] | None) – filters for the embedding branch.
+- **top_k_embedding** (int) – maximum number of documents from the embedding branch.
+- **filter_policy_embedding** (str | FilterPolicy) – filter policy for the embedding branch.
+- **join_mode** (str | JoinMode) – how the two result lists are fused.
+- **weights** (list\[float\] | None) – per-branch weights used by the joiner.
+- **top_k** (int | None) – maximum number of documents returned after fusion.
+- **sort_by_score** (bool) – whether the fused documents are sorted by score.
+- **kwargs** (Any) – extra init arguments for the underlying retrievers, given as
+ `bm25_retriever={...}` and/or `embedding_retriever={...}`.
+
+**Raises:**
+
+- ValueError – if `kwargs` contains a key other than those two.
+
+#### 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 the retrieved 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]) -> SolrHybridRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – dictionary to deserialize from.
+
+**Returns:**
+
+- SolrHybridRetriever – deserialized component.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the underlying document store connection.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the underlying document store async connection.
+
+## haystack_integrations.document_stores.solr.document_store
+
+### SolrDocumentStore
+
+A Document Store for [Apache Solr](https://solr.apache.org/).
+
+Supports keyword search through Solr's BM25 similarity and dense vector search through
+`DenseVectorField` and the `{!knn}` query parser. Requires **Solr 9.6 or newer**.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.solr import SolrDocumentStore
+
+store = SolrDocumentStore(url="http://localhost:8983/solr", core="haystack", embedding_dim=768)
+store.write_documents([Document(content="Apache Solr is a search platform.")])
+```
+
+Metadata is stored in Solr fields whose names encode the Python type of the value, so metadata
+round-trips with its type intact. See the `schema` module for the details of that mapping. Metadata
+keys become Solr field names and must therefore consist of letters, digits and underscores.
+
+Two things Solr cannot do:
+
+- `Document.sparse_embedding` is ignored, with a warning, because Solr has no sparse vector field.
+- Comparing `content` with `==` is a phrase match against an analysed field rather than exact
+ string equality. Filter on a metadata field when exact matching matters.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ url: str | None = None,
+ core: str = "haystack",
+ embedding_dim: int = 768,
+ similarity_function: Literal[
+ "cosine", "dot_product", "euclidean"
+ ] = "cosine",
+ return_embedding: bool = False,
+ create_core: bool = False,
+ manage_schema: bool = True,
+ config_set: str = "_default",
+ vector_field_type_params: dict[str, Any] | None = None,
+ auth: tuple[Secret, Secret] | tuple[str, str] | None = (
+ Secret.from_env_var("SOLR_USERNAME", strict=False),
+ Secret.from_env_var("SOLR_PASSWORD", strict=False),
+ ),
+ verify_certs: bool = True,
+ timeout: float = 30.0,
+ batch_size: int = DEFAULT_BATCH_SIZE,
+ commit: bool = True,
+ commit_within_ms: int | None = None,
+ query_page_size: int = DEFAULT_QUERY_PAGE_SIZE,
+ **kwargs: Any
+) -> None
+```
+
+Create a new `SolrDocumentStore`.
+
+**Parameters:**
+
+- **url** (str | None) – Solr base URL. Falls back to the `SOLR_URL` environment variable, then to
+ `http://localhost:8983/solr`.
+- **core** (str) – name of the Solr core (or SolrCloud collection) to read from and write to.
+- **embedding_dim** (int) – dimension of the embeddings. Solr fixes a vector field's dimension when
+ the field is created, so this cannot be changed for an existing core.
+- **similarity_function** (Literal['cosine', 'dot_product', 'euclidean']) – vector similarity to use, one of `cosine`, `dot_product` or
+ `euclidean`.
+- **return_embedding** (bool) – whether `filter_documents` and the retrievers return embeddings.
+ Leaving this `False` keeps large vectors off the wire.
+- **create_core** (bool) – whether to create the core if it does not exist. Requires the `config_set`
+ to be present in Solr's configset directory (`bool) – whether to create the fields the document store needs and disable Solr's
+ schemaless field guessing. Set to `False` to manage the schema yourself, in which case
+ `schema.schema_payload` is the definitive list of the fields and dynamic fields required.
+- **config_set** (str) – configset used when `create_core` is enabled.
+- **vector_field_type_params** (dict\[str, Any\] | None) – extra attributes for the vector field type, for example
+ `{"hnswM": 32}` on Solr 10 or `{"hnswMaxConnections": 32}` on Solr 9. Left unset by default
+ because Solr 10 renamed these attributes without a compatibility shim.
+- **auth** (tuple\[Secret, Secret\] | tuple\[str, str\] | None) – username and password for basic authentication. Reads the `SOLR_USERNAME` and
+ `SOLR_PASSWORD` environment variables by default. Pass `None` to disable authentication.
+- **verify_certs** (bool) – whether to verify TLS certificates.
+- **timeout** (float) – request timeout in seconds.
+- **batch_size** (int) – number of documents sent per update request.
+- **commit** (bool) – whether writes and deletes commit immediately, making them searchable at once.
+- **commit_within_ms** (int | None) – ask Solr to commit within this many milliseconds instead of blocking.
+- **query_page_size** (int) – number of documents fetched per page when paginating.
+- **kwargs** (Any) – extra keyword arguments forwarded to the underlying `httpx` clients, for
+ example `proxy` or `headers`.
+
+#### 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]) -> SolrDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – dictionary to deserialize from.
+
+**Returns:**
+
+- SolrDocumentStore – deserialized component.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the underlying HTTP client. The store reconnects on the next call.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the underlying async HTTP client. The store reconnects on the next call.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – the number of documents.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- int – the number of documents.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns how many documents match the given filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – the filters to apply.
+
+**Returns:**
+
+- int – the number of matching documents.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Returns how many documents match the given filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – the filters to apply.
+
+**Returns:**
+
+- int – the number of matching documents.
+
+#### 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).
+
+All Haystack operators are supported: `==`, `!=`, `>`, `>=`, `<`, `<=`, `in`, `not in`, and the
+`AND`, `OR` and `NOT` logical operators. Three behaviours are worth knowing:
+
+- `>`, `>=`, `<` and `<=` accept numbers and ISO-8601 date strings. Any other string raises a
+ `FilterError`, because Solr would compare it lexicographically and quietly give an answer
+ nobody meant.
+- Because the value's Python type selects the Solr field, `{"field": "meta.page", "value": 100}`
+ and `{"field": "meta.page", "value": "100"}` match different documents.
+- `==` on `content` is a phrase match against an analysed field, not exact equality.
+
+**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:**
+
+- FilterError – if the filters are malformed, or compare a value Solr cannot order.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+See `filter_documents` for the supported operators and their caveats.
+
+**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:**
+
+- FilterError – if the filters are malformed, or compare a value Solr cannot order.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes Documents to Solr.
+
+Metadata keys must consist of letters, digits and underscores only, because each key becomes a
+Solr field name. Sparse embeddings are dropped, as Solr has no sparse vector field.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – a list of Documents to write.
+- **policy** (DuplicatePolicy) – the policy to apply when a Document with the same id already exists.
+ The default `DuplicatePolicy.NONE` resolves to `DuplicatePolicy.FAIL`.
+
+**Returns:**
+
+- int – the number of Documents written.
+
+**Raises:**
+
+- ValueError – if `documents` is not a list of Documents, or a metadata key cannot be
+ expressed as a Solr field name.
+- DuplicateDocumentError – if `policy` is `FAIL` (or the default `NONE`) and a Document
+ already exists.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes Documents to Solr.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – a list of Documents to write.
+- **policy** (DuplicatePolicy) – the policy to apply when a Document with the same id already exists.
+ The default `DuplicatePolicy.NONE` resolves to `DuplicatePolicy.FAIL`.
+
+**Returns:**
+
+- int – the number of Documents written.
+
+**Raises:**
+
+- ValueError – if `documents` is not a list of Documents, or a metadata key cannot be
+ expressed as a Solr field name.
+- DuplicateDocumentError – if `policy` is `FAIL` (or the default `NONE`) and a Document
+ already exists.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with the given ids.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the ids of the documents to delete.
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Deletes all documents with the given ids.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – the ids of the documents to delete.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents in the core, leaving the schema in place.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async() -> None
+```
+
+Deletes all documents in the core, leaving the schema in place.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents matching the given filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – the filters selecting the documents to delete.
+
+**Returns:**
+
+- int – the number of documents deleted. The count is taken with a separate query before
+ the delete is issued, so a concurrent write landing in between can make it differ from
+ the number of documents the delete actually removes.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents matching the given filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – the filters selecting the documents to delete.
+
+**Returns:**
+
+- int – the number of documents deleted. The count is taken with a separate query before
+ the delete is issued, so a concurrent write landing in between can make it differ from
+ the number of documents the delete actually removes.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Merges `meta` into the metadata of every document matching `filters`.
+
+Matching documents are read, merged and rewritten in full rather than updated in place. A Solr
+atomic update sets one field at a time, which would leave the previous value behind in another
+field whenever a metadata value changes Python type, since the type is part of the field name.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – the filters selecting the documents to update.
+- **meta** (dict\[str, Any\]) – the metadata to merge into each matching document.
+
+**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
+```
+
+Merges `meta` into the metadata of every document matching `filters`.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – the filters selecting the documents to update.
+- **meta** (dict\[str, Any\]) – the metadata to merge into each matching document.
+
+**Returns:**
+
+- int – the number of documents updated.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the metadata fields present in the core and their types.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – a mapping of metadata field name to a dict with a `type` key.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Returns the metadata fields present in the core and their types.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – a mapping of metadata field name to a dict with a `type` key.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+ filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Counts the distinct values of each given metadata field among documents matching `filters`.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – the filters restricting which documents are considered.
+- **metadata_fields** (list\[str\]) – the metadata fields to count distinct values for.
+
+**Returns:**
+
+- dict\[str, int\] – a mapping of metadata field name to its number of distinct 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]
+```
+
+Counts the distinct values of each given metadata field among documents matching `filters`.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – the filters restricting which documents are considered.
+- **metadata_fields** (list\[str\]) – the metadata fields to count distinct values for.
+
+**Returns:**
+
+- dict\[str, int\] – a mapping of metadata field name to its number of distinct values.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(
+ metadata_field: str,
+) -> dict[str, float | int | None]
+```
+
+Returns the minimum and maximum value of a numeric metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – the metadata field, with or without a `meta.` prefix.
+
+**Returns:**
+
+- dict\[str, float | int | None\] – a dict with `min` and `max` keys, both `None` when the field has no numeric values.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(
+ metadata_field: str,
+) -> dict[str, float | int | None]
+```
+
+Returns the minimum and maximum value of a numeric metadata field.
+
+**Parameters:**
+
+- **metadata_field** (str) – the metadata field, with or without a `meta.` prefix.
+
+**Returns:**
+
+- dict\[str, float | int | None\] – a dict with `min` and `max` keys, both `None` when the field has no numeric 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Returns the distinct values of a metadata field, paginated.
+
+**Parameters:**
+
+- **metadata_field** (str) – the metadata field, with or without a `meta.` prefix.
+- **search_term** (str | None) – when given, only values containing it (case-insensitively) are returned.
+- **from\_** (int) – index of the first value to return.
+- **size** (int) – how many values to return.
+- **filters** (dict\[str, Any\] | None) – filters restricting which documents are considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – a `(values, total_count)` pair, where `total_count` counts all 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Returns the distinct values of a metadata field, paginated.
+
+**Parameters:**
+
+- **metadata_field** (str) – the metadata field, with or without a `meta.` prefix.
+- **search_term** (str | None) – when given, only values containing it (case-insensitively) are returned.
+- **from\_** (int) – index of the first value to return.
+- **size** (int) – how many values to return.
+- **filters** (dict\[str, Any\] | None) – filters restricting which documents are considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – a `(values, total_count)` pair, where `total_count` counts all matching values.
+
+## haystack_integrations.document_stores.solr.filters
+
+Translation of Haystack filters into Solr filter query (`fq`) clauses.
+
+### escape_query_chars
+
+```python
+escape_query_chars(value: str) -> str
+```
+
+Escape the Lucene syntax characters in `value`.
+
+**Parameters:**
+
+- **value** (str) – the raw string.
+
+**Returns:**
+
+- str – the string with every syntax character and every whitespace run backslash-escaped.
+
+### normalize_filters
+
+```python
+normalize_filters(filters: dict[str, Any]) -> str
+```
+
+Convert Haystack filters into a single Solr filter query clause.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – the filters to convert, in Haystack's comparison/logic dictionary form.
+
+**Returns:**
+
+- str – a clause suitable for Solr's `fq` parameter or for a delete-by-query.
+
+**Raises:**
+
+- FilterError – if `filters` is malformed or uses an unsupported operator or value type.
+
+## haystack_integrations.document_stores.solr.schema
+
+Mapping between Haystack `Document`s and Solr documents.
+
+Solr is strongly typed: a field's type is fixed the first time the field is created and a value of the
+wrong type is rejected. Haystack metadata, on the other hand, is an arbitrary `dict[str, Any]` whose
+value types are only known at write time. To reconcile the two, every metadata entry is stored in a
+Solr field whose name encodes the Python type of the value:
+
+```
+meta.page = "100" -> meta_s_page = "100" (string)
+meta.page = 100 -> meta_l_page = 100 (plong)
+```
+
+The type code lives in the *prefix* rather than the suffix because Solr dynamic field patterns accept
+only a leading or a trailing wildcard - `meta_*_s` is not a legal pattern, while `meta_s_*` is.
+
+Encoding the type in the field name buys two properties that a single JSON blob or Solr's schemaless
+type inference cannot provide:
+
+- metadata round-trips with its Python type intact, so `{"page": "100"}` never comes back as
+ `{"page": 100}`;
+- values that merely share a string form stay distinct, so the int `1`, the str `"1"`, the float `1.0`
+ and the bool `True` occupy four different fields and are reported as four distinct values.
+
+### type_code_for_value
+
+```python
+type_code_for_value(value: Any) -> str
+```
+
+Return the type code under which `value` is stored.
+
+Homogeneous lists of scalars use the multi-valued code for their element type. Everything else -
+dicts, mixed lists, nested structures - falls back to a JSON-encoded string.
+
+**Parameters:**
+
+- **value** (Any) – the metadata value to classify.
+
+**Returns:**
+
+- str – one of the codes in `ALL_TYPE_CODES`.
+
+### meta_field_name
+
+```python
+meta_field_name(key: str, type_code: str) -> str
+```
+
+Build the Solr field name holding metadata `key` at `type_code`.
+
+**Parameters:**
+
+- **key** (str) – the Haystack metadata key.
+- **type_code** (str) – one of the codes in `ALL_TYPE_CODES`.
+
+**Returns:**
+
+- str – the Solr field name, e.g. `meta_s_page`.
+
+### parse_meta_field_name
+
+```python
+parse_meta_field_name(field: str) -> tuple[str, str] | None
+```
+
+Invert `meta_field_name`.
+
+**Parameters:**
+
+- **field** (str) – a Solr field name.
+
+**Returns:**
+
+- tuple\[str, str\] | None – a `(type_code, key)` pair, or `None` if `field` is not a metadata field. Type codes
+ contain no underscore, so a single split is unambiguous even when the key does.
+
+### validate_meta_keys
+
+```python
+validate_meta_keys(meta: dict[str, Any]) -> None
+```
+
+Reject metadata keys that cannot be expressed as a Solr field name.
+
+**Parameters:**
+
+- **meta** (dict\[str, Any\]) – the metadata of a single document.
+
+**Raises:**
+
+- ValueError – if any key contains a character outside `[A-Za-z0-9_]`. Silently rewriting
+ such keys would let two distinct keys collide, so the write is refused instead.
+
+### document_to_solr
+
+```python
+document_to_solr(document: Document) -> dict[str, Any]
+```
+
+Convert a Haystack `Document` into a Solr document.
+
+**Parameters:**
+
+- **document** (Document) – the document to convert.
+
+**Returns:**
+
+- dict\[str, Any\] – a JSON-serializable dict ready to be posted to Solr's update handler.
+
+**Raises:**
+
+- ValueError – if a metadata key cannot be expressed as a Solr field name.
+
+### solr_to_document
+
+```python
+solr_to_document(
+ solr_document: dict[str, Any], *, score: float | None = None
+) -> Document
+```
+
+Convert a Solr document back into a Haystack `Document`.
+
+**Parameters:**
+
+- **solr_document** (dict\[str, Any\]) – a single entry from a Solr query response.
+- **score** (float | None) – the relevance score to attach, when the document came from a retrieval query.
+
+**Returns:**
+
+- Document – the reconstructed document.
+
+### vector_field_type_name
+
+```python
+vector_field_type_name(embedding_dim: int) -> str
+```
+
+Return the name of the `DenseVectorField` type backing embeddings of `embedding_dim` dimensions.
+
+**Parameters:**
+
+- **embedding_dim** (int) – the embedding dimension.
+
+**Returns:**
+
+- str – the Solr field type name.
+
+### schema_payload
+
+```python
+schema_payload(
+ *,
+ embedding_dim: int,
+ similarity_function: str,
+ existing_field_types: set[str],
+ existing_fields: set[str],
+ existing_dynamic_fields: set[str],
+ vector_field_type_params: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Build an idempotent Schema API payload creating only what the core is missing.
+
+**Parameters:**
+
+- **embedding_dim** (int) – dimension of the `DenseVectorField` backing embeddings.
+- **similarity_function** (str) – `cosine`, `dot_product` or `euclidean`.
+- **existing_field_types** (set\[str\]) – field type names already defined in the core.
+- **existing_fields** (set\[str\]) – field names already defined in the core.
+- **existing_dynamic_fields** (set\[str\]) – dynamic field patterns already defined in the core.
+- **vector_field_type_params** (dict\[str, Any\] | None) – extra attributes for the vector field type, for example
+ `{"hnswM": 32}` on Solr 10 or `{"hnswMaxConnections": 32}` on Solr 9. Left unset by default so
+ that one payload is valid on both major versions, which renamed these attributes.
+
+**Returns:**
+
+- dict\[str, Any\] – the Schema API payload. Empty when the core already has everything.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/spacy.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/spacy.md
new file mode 100644
index 00000000000..d56ca77965a
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/spacy.md
@@ -0,0 +1,158 @@
+---
+title: "Spacy"
+id: integrations-spacy
+description: "Spacy integration for Haystack"
+slug: "/integrations-spacy"
+---
+
+
+## haystack_integrations.components.extractors.spacy.named_entity_extractor
+
+### 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.
+
+### SpacyNamedEntityExtractor
+
+Annotates named entities in a collection of documents.
+
+The component 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_integrations.components.extractors.spacy import SpacyNamedEntityExtractor
+
+documents = [
+ Document(content="I'm Merlin, the happy pig!"),
+ Document(content="My name is Clara and I live in Berkeley, California."),
+]
+extractor = SpacyNamedEntityExtractor(model="en_core_web_sm")
+results = extractor.run(documents=documents)["documents"]
+annotations = [SpacyNamedEntityExtractor.get_stored_annotations(doc) for doc in results]
+print(annotations)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ model: str,
+ pipeline_kwargs: dict[str, Any] | None = None,
+ device: ComponentDevice | None = None
+) -> None
+```
+
+Create a Named Entity extractor component.
+
+**Parameters:**
+
+- **model** (str) – Name of the spaCy model or a path to the model on
+ the local disk.
+- **pipeline_kwargs** (dict\[str, Any\] | None) – Keyword arguments passed to the pipeline. The
+ pipeline can override these arguments.
+- **device** (ComponentDevice | None) – The device on which the model is loaded. If `None`,
+ the default device is automatically selected.
+
+**Raises:**
+
+- ValueError – If the device represents multiple devices, which the
+ spaCy backend does not support.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the component.
+
+**Raises:**
+
+- ComponentError – If the component 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 model 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]) -> SpacyNamedEntityExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SpacyNamedEntityExtractor – 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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/sqlalchemy.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/sqlalchemy.md
new file mode 100644
index 00000000000..50371edabfd
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/sqlalchemy.md
@@ -0,0 +1,118 @@
+---
+title: "SQLAlchemy"
+id: integrations-sqlalchemy
+description: "SQLAlchemy integration for Haystack"
+slug: "/integrations-sqlalchemy"
+---
+
+
+## haystack_integrations.components.retrievers.sqlalchemy.sqlalchemy_table_retriever
+
+### SQLAlchemyTableRetriever
+
+Connects to any SQLAlchemy-supported database and executes a SQL query.
+
+Returns results as a Pandas DataFrame and an optional Markdown-formatted table string.
+Supports any database backend that SQLAlchemy supports, including PostgreSQL, MySQL,
+SQLite, and MSSQL.
+
+### Usage example:
+
+```python
+from haystack_integrations.components.retrievers.sqlalchemy import SQLAlchemyTableRetriever
+
+retriever = SQLAlchemyTableRetriever(drivername="sqlite", database=":memory:")
+retriever.warm_up()
+result = retriever.run(query="SELECT 1 AS value")
+print(result["dataframe"])
+print(result["table"])
+```
+
+#### __init__
+
+```python
+__init__(
+ drivername: str,
+ username: str | None = None,
+ password: Secret | None = None,
+ host: str | None = None,
+ port: int | None = None,
+ database: str | None = None,
+ init_script: list[str] | None = None,
+) -> None
+```
+
+Initialize SQLAlchemyTableRetriever.
+
+**Parameters:**
+
+- **drivername** (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-3.2-unstable/integrations-api/stackit.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/stackit.md
new file mode 100644
index 00000000000..6352b0ea8aa
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/stackit.md
@@ -0,0 +1,301 @@
+---
+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",
+ *,
+ dimensions: int | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = 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.
+- **dimensions** (int | None) – The number of dimensions of the resulting embeddings. Only supported by some models -
+ check the STACKIT model card for the model you are using to see if this parameter is supported.
+- **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 = "",
+ *,
+ dimensions: int | None = None,
+ timeout: float | None = None,
+ max_retries: int | None = None,
+ http_client_kwargs: dict[str, Any] | None = 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.
+- **dimensions** (int | None) – The number of dimensions of the resulting embeddings. Only supported by some models -
+ check the STACKIT model card for the model you are using to see if this parameter is supported.
+- **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="cortecs/Llama-3.3-70B-Instruct-FP8-Dynamic")
+
+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",
+ "Qwen/Qwen3.6-27B",
+ "cortecs/Llama-3.3-70B-Instruct-FP8-Dynamic",
+ "openai/gpt-oss-120b",
+ "google/gemma-3-27b-it",
+ "openai/gpt-oss-20b",
+]
+
+```
+
+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
+) -> 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-3.2-unstable/integrations-api/supabase.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/supabase.md
new file mode 100644
index 00000000000..25ac7ef2bc8
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/supabase.md
@@ -0,0 +1,445 @@
+---
+title: "Supabase"
+id: integrations-supabase
+description: "Supabase integration for Haystack"
+slug: "/integrations-supabase"
+---
+
+
+## haystack_integrations.components.downloaders.supabase.supabase_bucket_downloader
+
+### SupabaseBucketDownloader
+
+Downloads files from a Supabase Storage bucket and returns them as ByteStream objects.
+
+Files are downloaded in-memory and returned as `ByteStream` objects ready for further
+processing in indexing pipelines (e.g. passing to a `DocumentConverter`).
+
+Example usage:
+
+```python
+from haystack_integrations.components.downloaders.supabase import SupabaseBucketDownloader
+from haystack.utils import Secret
+
+downloader = SupabaseBucketDownloader(
+ supabase_url="https://str) – The URL of your Supabase project, e.g. `https://Secret) – The Supabase API key used to authenticate requests. Defaults to the
+ `SUPABASE_SERVICE_KEY` environment variable. Use the service role key for private buckets.
+- **bucket_name** (str) – The name of the Supabase Storage bucket to download files from.
+- **file_extensions** (list\[str\] | None) – Optional list of file extensions to filter downloads (e.g. `[".pdf", ".txt"]`).
+ If `None`, all files are downloaded. Extensions are matched case-insensitively.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the Supabase client.
+
+Called automatically on the first run(), or can be called explicitly in a pipeline.
+
+#### run
+
+```python
+run(sources: list[str]) -> dict[str, list[ByteStream]]
+```
+
+Downloads files from the Supabase Storage bucket.
+
+**Parameters:**
+
+- **sources** (list\[str\]) – List of file paths within the bucket to download,
+ e.g. `["folder/file.pdf", "notes.txt"]`.
+
+**Returns:**
+
+- dict\[str, list\[ByteStream\]\] – A dictionary with:
+- `streams`: list of `ByteStream` objects, one per successfully downloaded file.
+ Each `ByteStream` has `meta["file_path"]` and `meta["bucket_name"]` set.
+
+#### 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]) -> SupabaseBucketDownloader
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- SupabaseBucketDownloader – Deserialized component.
+
+## 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
+# Requires: pip install sentence-transformers-haystack
+from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
+from haystack_integrations.components.embedders.sentence_transformers import 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()
+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-3.2-unstable/integrations-api/tavily.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/tavily.md
new file mode 100644
index 00000000000..fbc982ea74d
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/tavily.md
@@ -0,0 +1,349 @@
+---
+title: "Tavily"
+id: integrations-tavily
+description: "Tavily integration for Haystack"
+slug: "/integrations-tavily"
+---
+
+
+## haystack_integrations.components.fetchers.tavily.tavily_fetcher
+
+### TavilyFetcher
+
+A component that uses the Tavily Extract API to fetch and extract content from URLs as Haystack Documents.
+
+This component wraps the Tavily Extract API, which retrieves and parses web page content from
+one or more specified URLs. Unlike web search, it fetches content directly from the given URLs
+rather than discovering them via a query. PDF URLs are also supported for extraction.
+
+Tavily is an AI-powered search and extraction API optimized for LLM applications. You need a Tavily
+API key from [tavily.com](https://tavily.com).
+
+### Usage example
+
+```python
+from haystack_integrations.components.fetchers.tavily import TavilyFetcher
+from haystack.utils import Secret
+
+fetcher = TavilyFetcher(
+ api_key=Secret.from_env_var("TAVILY_API_KEY"),
+ extract_depth="basic",
+)
+result = fetcher.run(urls=["https://haystack.deepset.ai"])
+documents = result["documents"]
+meta = result["meta"]
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("TAVILY_API_KEY"),
+ *,
+ extract_depth: Literal["basic", "advanced"] = "basic",
+ include_images: bool = False,
+ extract_params: dict[str, Any] | None = None
+) -> None
+```
+
+Initialize the TavilyFetcher component.
+
+**Parameters:**
+
+- **api_key** (Secret) – API key for Tavily. Defaults to the `TAVILY_API_KEY` environment variable.
+- **extract_depth** (Literal['basic', 'advanced']) – Extraction depth: `"basic"` (fast, lower cost) or `"advanced"` (more data including
+ tables, higher latency and cost). Defaults to `"basic"`.
+- **include_images** (bool) – If `True`, extracted image URLs are included in each Document's metadata under
+ the `"images"` key. Defaults to `False`.
+- **extract_params** (dict\[str, Any\] | None) – Additional parameters passed to the Tavily Extract API, such as `format`,
+ `include_favicon`, `query`, or `chunks_per_source`.
+ See the [Tavily Extract API reference](https://docs.tavily.com/documentation/api-reference/endpoint/extract)
+ for available options.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Tavily sync client.
+
+Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Initialize the Tavily async client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Tavily sync client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the Tavily async client.
+
+#### run
+
+```python
+run(
+ urls: list[str], extract_params: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Fetch and extract content from the given URLs using the Tavily Extract API.
+
+**Parameters:**
+
+- **urls** (list\[str\]) – List of URLs to extract content from. Maximum 20 URLs per request.
+- **extract_params** (dict\[str, Any\] | None) – Optional per-run override of extract parameters.
+ If provided, fully replaces the init-time `extract_params`.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with:
+- `documents`: List of Documents containing extracted page content.
+ Each Document's `meta` includes `"url"` and, if `include_images` is True, `"images"`.
+- `meta`: Request-level metadata containing `"response_time"`, `"usage"`,
+ `"request_id"`, and `"failed_results"` for URLs that could not be processed.
+
+#### run_async
+
+```python
+run_async(
+ urls: list[str], extract_params: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously fetch and extract content from the given URLs using the Tavily Extract API.
+
+**Parameters:**
+
+- **urls** (list\[str\]) – List of URLs to extract content from. Maximum 20 URLs per request.
+- **extract_params** (dict\[str, Any\] | None) – Optional per-run override of extract parameters.
+ If provided, fully replaces the init-time `extract_params`.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with:
+- `documents`: List of Documents containing extracted page content.
+ Each Document's `meta` includes `"url"` and, if `include_images` is True, `"images"`.
+- `meta`: Request-level metadata containing `"response_time"`, `"usage"`,
+ `"request_id"`, and `"failed_results"` for URLs that could not be processed.
+
+## 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 client.
+
+Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Initialize the Tavily async client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the Tavily sync client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the Tavily async client.
+
+#### 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.
+
+## haystack_integrations.tools.tavily.websearch_tool
+
+### TavilyWebSearchTool
+
+Bases: ComponentTool
+
+A tool that searches the web with Tavily.
+
+Wraps the `TavilyWebSearch` component and formats its results as a string that an LLM can cite.
+The tool parameters are derived from the component's `run` method, so the LLM can pass a `query` and,
+optionally, `search_params` overriding the ones set at initialization time.
+
+### Usage example
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.tools.tavily import TavilyWebSearchTool
+
+web_search = TavilyWebSearchTool(top_k=5, search_params={"search_depth": "advanced"})
+
+agent = Agent(chat_generator=OpenAIChatGenerator(model="gpt-5-mini"), tools=[web_search])
+
+result = agent.run(messages=[ChatMessage.from_user("What is Haystack by deepset?")])
+print(result["last_message"].text)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret | None = None,
+ top_k: int | None = None,
+ search_params: dict[str, Any] | None = None,
+ name: str = "web_search",
+ description: str = _DEFAULT_DESCRIPTION
+) -> None
+```
+
+Initialize the TavilyWebSearchTool.
+
+**Parameters:**
+
+- **api_key** (Secret | None) – API key for Tavily. If unset, `TavilyWebSearch` reads the `TAVILY_API_KEY` environment variable.
+- **top_k** (int | None) – Maximum number of results to return. If unset, the `TavilyWebSearch` default applies.
+- **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`.
+- **name** (str) – Tool name exposed to the LLM.
+- **description** (str) – Tool description exposed to the LLM.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the tool to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TavilyWebSearchTool
+```
+
+Deserialize the tool from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- TavilyWebSearchTool – Deserialized tool.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/tika.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/tika.md
new file mode 100644
index 00000000000..0713ec6df51
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/tika.md
@@ -0,0 +1,129 @@
+---
+title: "Tika"
+id: integrations-tika
+description: "Tika integration for Haystack"
+slug: "/integrations-tika"
+---
+
+
+## haystack_integrations.components.converters.tika.converter
+
+### XHTMLParser
+
+Bases: HTMLParser
+
+Custom parser to extract pages from Tika XHTML content.
+
+#### __init__
+
+```python
+__init__() -> None
+```
+
+Initialize the XHTMLParser.
+
+#### handle_starttag
+
+```python
+handle_starttag(tag: str, attrs: list[tuple[str, str | None]]) -> None
+```
+
+Identify the start of a page div.
+
+**Parameters:**
+
+- **tag** (str) – The HTML tag name.
+- **attrs** (list\[tuple\[str, str | None\]\]) – The HTML tag attributes.
+
+#### handle_endtag
+
+```python
+handle_endtag(tag: str) -> None
+```
+
+Identify the end of a page div.
+
+**Parameters:**
+
+- **tag** (str) – The HTML tag name.
+
+#### handle_data
+
+```python
+handle_data(data: str) -> None
+```
+
+Populate the page content.
+
+**Parameters:**
+
+- **data** (str) – The text content of an HTML node.
+
+### TikaDocumentConverter
+
+Converts files of different types to Documents using Apache Tika.
+
+This component uses [Apache Tika](https://tika.apache.org/) for parsing the files and, therefore,
+requires a running Tika server.
+Use a Tika 3.x server; the `tika` Python client does not yet support Tika Server 4.x.
+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_integrations.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]]
+```
+
+Convert 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\]\] – A dictionary with the following keys:
+- `documents`: Created Documents
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/togetherai.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/togetherai.md
new file mode 100644
index 00000000000..ec23625c20a
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/togetherai.md
@@ -0,0 +1,122 @@
+---
+title: "Together AI"
+id: integrations-togetherai
+description: "Together AI integration for Haystack"
+slug: "/integrations-togetherai"
+---
+
+
+## haystack_integrations.components.generators.togetherai.chat.chat_generator
+
+### TogetherAIChatGenerator
+
+Bases: OpenAIChatGenerator
+
+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=Secret) – The Together API key.
+- **model** (str) – The name of the Together AI 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 Together AI API Base url.
+ For more details, see Together AI [docs](https://docs.together.ai/docs/openai-api-compatibility).
+- **generation_kwargs** (dict\[str, Any\] | None) – Other parameters to use for the model. These parameters are all sent directly to
+ the Together AI endpoint. See [Together AI API docs](https://docs.together.ai/reference/chat-completions-1)
+ 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 Together AI API call.
+- **max_retries** (int | None) – Maximum number of retries to contact Together AI 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-3.2-unstable/integrations-api/transformers.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/transformers.md
new file mode 100644
index 00000000000..b716d655348
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/transformers.md
@@ -0,0 +1,1062 @@
+---
+title: "Transformers"
+id: integrations-transformers
+description: "Transformers integration for Haystack"
+slug: "/integrations-transformers"
+---
+
+
+## haystack_integrations.components.classifiers.transformers.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.core.pipeline import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+from haystack_integrations.components.classifiers.transformers 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`.
+
+## haystack_integrations.components.extractors.transformers.named_entity_extractor
+
+### 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.
+
+### TransformersNamedEntityExtractor
+
+Annotates named entities in a collection of documents.
+
+The component can be used with any token classification model from the
+[Hugging Face model hub](https://huggingface.co/models). Annotations are
+stored as metadata in the documents.
+
+Usage example:
+
+```python
+from haystack import Document
+
+from haystack_integrations.components.extractors.transformers import TransformersNamedEntityExtractor
+
+documents = [
+ Document(content="I'm Merlin, the happy pig!"),
+ Document(content="My name is Clara and I live in Berkeley, California."),
+]
+extractor = TransformersNamedEntityExtractor(model="dslim/bert-base-NER")
+results = extractor.run(documents=documents)["documents"]
+annotations = [TransformersNamedEntityExtractor.get_stored_annotations(doc) for doc in results]
+print(annotations)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ 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:**
+
+- **model** (str) – Name of the model or a path to the model on
+ the local disk.
+- **pipeline_kwargs** (dict\[str, Any\] | None) – Keyword arguments passed to the pipeline. The
+ pipeline can override these arguments.
+- **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.
+- **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 component 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 model 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]) -> TransformersNamedEntityExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- TransformersNamedEntityExtractor – 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.
+
+## haystack_integrations.components.generators.transformers.chat.chat_generator
+
+### 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.
+
+### TransformersChatGenerator
+
+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.dataclasses import ChatMessage
+
+from haystack_integrations.components.generators.transformers import TransformersChatGenerator
+
+generator = TransformersChatGenerator(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', 'image-text-to-text'] | None) – The task for the Hugging Face pipeline. Possible options:
+- `text-generation`: Supported by decoder models, like GPT.
+- `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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component and warms up tools if provided.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the executor owned by 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]) -> TransformersChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- TransformersChatGenerator – The deserialized component.
+
+#### run
+
+```python
+run(
+ messages: list[ChatMessage] | str,
+ 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\] | str) – A list of ChatMessage objects representing the input messages. If a string is provided,
+ it is converted to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These are merged per key with
+ the `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only at
+ initialization are kept.
+- **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] | str,
+ 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\] | str) – A list of ChatMessage objects representing the input messages.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These are merged per key with
+ the `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only at
+ initialization are kept.
+- **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.
+
+## haystack_integrations.components.readers.transformers.extractive_reader
+
+### TransformersExtractiveReader
+
+Locates and extracts answers to a given query from Documents.
+
+The TransformersExtractiveReader 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_integrations.components.readers.transformers import TransformersExtractiveReader
+
+docs = [
+ Document(content="Python is a popular programming language"),
+ Document(content="python ist eine beliebte Programmiersprache"),
+]
+
+reader = TransformersExtractiveReader()
+
+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 TransformersExtractiveReader.
+
+**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]) -> TransformersExtractiveReader
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- TransformersExtractiveReader – 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.
+
+## haystack_integrations.components.routers.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.components.builders import PromptBuilder
+from haystack.components.generators import HuggingFaceLocalGenerator
+from haystack.core.pipeline import Pipeline
+
+from haystack_integrations.components.routers.transformers import TransformersTextRouter
+
+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.
+
+## haystack_integrations.components.routers.transformers.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
+# Requires: pip install sentence-transformers-haystack
+from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
+from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersDocumentEmbedder
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+from haystack.core.pipeline import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+from haystack_integrations.components.routers.transformers import TransformersZeroShotTextRouter
+
+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-3.2-unstable/integrations-api/twelvelabs.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/twelvelabs.md
new file mode 100644
index 00000000000..11b8501bb06
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/twelvelabs.md
@@ -0,0 +1,347 @@
+---
+title: "TwelveLabs"
+id: integrations-twelvelabs
+description: "TwelveLabs integration for Haystack"
+slug: "/integrations-twelvelabs"
+---
+
+
+## haystack_integrations.components.converters.twelvelabs.video_converter
+
+### TwelveLabsVideoConverter
+
+Converts videos to Haystack Documents using TwelveLabs Pegasus.
+
+Pegasus is a video-language model that analyzes a video on the fly (its
+visuals **and** its own audio ASR) and returns text. Each source video
+becomes one Document whose content is Pegasus's analysis (e.g. a description
+plus a transcript) — no frame extraction or separate transcription step.
+
+Sources may be publicly accessible direct video URLs or local file paths
+(uploaded to TwelveLabs, up to 200 MB).
+
+### Usage example
+
+```python
+from haystack_integrations.components.converters.twelvelabs import TwelveLabsVideoConverter
+
+# Set the TWELVELABS_API_KEY environment variable
+converter = TwelveLabsVideoConverter()
+result = converter.run(sources=["https://example.com/clip.mp4"])
+print(result["documents"][0].content)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("TWELVELABS_API_KEY"),
+ model: str = DEFAULT_MODEL,
+ prompt: str = DEFAULT_PROMPT,
+ temperature: float = 0.2,
+ max_tokens: int = 16384
+) -> None
+```
+
+Create a TwelveLabsVideoConverter.
+
+**Parameters:**
+
+- **api_key** (Secret) – The TwelveLabs API key. Read from the `TWELVELABS_API_KEY`
+ environment variable by default.
+- **model** (str) – The Pegasus model name (`pegasus1.5` or `pegasus1.2`).
+- **prompt** (str) – The analysis prompt sent to Pegasus for each video.
+- **temperature** (float) – Sampling temperature (0-1).
+- **max_tokens** (int) – Maximum output tokens per analysis.
+
+#### 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]) -> TwelveLabsVideoConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- TwelveLabsVideoConverter – Deserialized component.
+
+#### run
+
+```python
+run(
+ sources: list[str],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Convert videos to Documents with Pegasus.
+
+**Parameters:**
+
+- **sources** (list\[str\]) – Video sources — publicly accessible direct video URLs or
+ local file paths.
+- **meta** (dict\[str, Any\] | list\[dict\[str, Any\]\] | None) – Optional metadata to attach to the produced Documents. Either
+ a single dict applied to all, or a list aligned with `sources`.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – A dictionary with key `documents`: the produced Documents.
+
+## haystack_integrations.components.embedders.twelvelabs.document_embedder
+
+### TwelveLabsDocumentEmbedder
+
+Embeds the text content of Documents using TwelveLabs Marengo.
+
+Computes a Marengo embedding for each Document's `content` and stores it on
+`Document.embedding`. Because Marengo embeds text, images, audio, and video
+into one shared space, these embeddings support cross-modal retrieval.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.twelvelabs import TwelveLabsDocumentEmbedder
+
+# Set the TWELVELABS_API_KEY environment variable
+doc_embedder = TwelveLabsDocumentEmbedder()
+docs = [Document(content="a cat playing piano")]
+docs = doc_embedder.run(documents=docs)["documents"]
+print(docs[0].embedding)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("TWELVELABS_API_KEY"),
+ model: str = DEFAULT_MODEL,
+ prefix: str = "",
+ suffix: str = "",
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ meta_fields_to_embed: list[str] | None = None,
+ embedding_separator: str = "\n"
+) -> None
+```
+
+Create a TwelveLabsDocumentEmbedder.
+
+**Parameters:**
+
+- **api_key** (Secret) – The TwelveLabs API key. Read from the `TWELVELABS_API_KEY`
+ environment variable by default.
+- **model** (str) – The Marengo model name.
+- **prefix** (str) – A string to add to the beginning of each text before embedding.
+- **suffix** (str) – A string to add to the end of each text before embedding.
+- **batch_size** (int) – Number of Documents per batch; within a batch `run_async` embeds concurrently.
+- **progress_bar** (bool) – Whether to show a progress bar while embedding. 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.
+
+#### 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]) -> TwelveLabsDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- TwelveLabsDocumentEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, Any]
+```
+
+Embed a list of Documents.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The Documents to embed (their `content` is embedded).
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys:
+- `documents`: New Documents that are copies of the inputs with `embedding` populated.
+- `meta`: Metadata about the request (the model used).
+
+**Raises:**
+
+- TypeError – If the input is not a list of Documents.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, Any]
+```
+
+Asynchronously embed a list of Documents.
+
+Documents within each batch of `batch_size` are embedded concurrently.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – The Documents to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys `documents` (copies with `embedding` populated) and `meta`.
+
+**Raises:**
+
+- TypeError – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.twelvelabs.text_embedder
+
+### TwelveLabsTextEmbedder
+
+Embeds strings using TwelveLabs Marengo.
+
+Marengo embeds text, images, audio, and video into a single shared vector
+space, so embeddings from this component are directly comparable (cosine
+similarity) with image/video embeddings from the same model — enabling
+cross-modal retrieval. Use it to embed a query before searching a document
+store populated with Marengo embeddings.
+
+### Usage example
+
+```python
+from haystack_integrations.components.embedders.twelvelabs import TwelveLabsTextEmbedder
+
+# Set the TWELVELABS_API_KEY environment variable
+text_embedder = TwelveLabsTextEmbedder()
+result = text_embedder.run(text="a cat playing piano")
+print(result["embedding"])
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ api_key: Secret = Secret.from_env_var("TWELVELABS_API_KEY"),
+ model: str = DEFAULT_MODEL,
+ prefix: str = "",
+ suffix: str = ""
+) -> None
+```
+
+Create a TwelveLabsTextEmbedder.
+
+**Parameters:**
+
+- **api_key** (Secret) – The TwelveLabs API key. Read from the `TWELVELABS_API_KEY`
+ environment variable by default.
+- **model** (str) – The Marengo model name.
+- **prefix** (str) – A string to add to the beginning of the text before embedding.
+- **suffix** (str) – A string to add to the end of the text before 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]) -> TwelveLabsTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- TwelveLabsTextEmbedder – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embed a single string.
+
+**Parameters:**
+
+- **text** (str) – The string to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys:
+- `embedding`: The embedding vector for the input string.
+- `meta`: Metadata about the request (the model used).
+
+**Raises:**
+
+- TypeError – If the input is not a string.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, Any]
+```
+
+Asynchronously embed a single string.
+
+**Parameters:**
+
+- **text** (str) – The string to embed.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with keys `embedding` and `meta`.
+
+**Raises:**
+
+- TypeError – If the input is not a string.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/unstructured.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/unstructured.md
new file mode 100644
index 00000000000..130c5270937
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/unstructured.md
@@ -0,0 +1,136 @@
+---
+title: "Unstructured"
+id: integrations-unstructured
+description: "Unstructured integration for Haystack"
+slug: "/integrations-unstructured"
+---
+
+
+
+## Module haystack\_integrations.components.converters.unstructured.converter
+
+
+
+### UnstructuredFileConverter
+
+A component for converting files to Haystack Documents using the Unstructured API (hosted or running locally).
+
+For the supported file types and the specific API parameters, see
+[Unstructured docs](https://docs.unstructured.io/api-reference/api-services/overview).
+
+Usage example:
+```python
+from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter
+
+# make sure to either set the environment variable UNSTRUCTURED_API_KEY
+# or run the Unstructured API locally:
+# docker run -p 8000:8000 -d --rm --name unstructured-api quay.io/unstructured-io/unstructured-api:latest
+# --port 8000 --host 0.0.0.0
+
+converter = UnstructuredFileConverter(
+ # api_url="http://localhost:8000/general/v0/general" # <-- Uncomment this if running Unstructured locally
+)
+documents = converter.run(paths = ["a/file/path.pdf", "a/directory/path"])["documents"]
+```
+
+
+
+#### UnstructuredFileConverter.\_\_init\_\_
+
+```python
+def __init__(api_url: str = UNSTRUCTURED_HOSTED_API_URL,
+ api_key: Secret | None = Secret.from_env_var(
+ "UNSTRUCTURED_API_KEY", strict=False),
+ document_creation_mode: Literal[
+ "one-doc-per-file", "one-doc-per-page",
+ "one-doc-per-element"] = "one-doc-per-file",
+ separator: str = "\n\n",
+ unstructured_kwargs: dict[str, Any] | None = None,
+ progress_bar: bool = True)
+```
+
+**Arguments**:
+
+- `api_url`: URL of the Unstructured API. Defaults to the URL of the hosted version.
+If you run the API locally, specify the URL of your local API (e.g. `"http://localhost:8000/general/v0/general"`).
+- `api_key`: API key for the Unstructured API.
+It can be explicitly passed or read the environment variable `UNSTRUCTURED_API_KEY` (recommended).
+If you run the API locally, it is not needed.
+- `document_creation_mode`: How to create Haystack 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.
+- `separator`: Separator between elements when concatenating them into one text field.
+- `unstructured_kwargs`: Additional parameters that are passed to the Unstructured API.
+For the available parameters, see
+[Unstructured API docs](https://docs.unstructured.io/api-reference/api-services/api-parameters).
+- `progress_bar`: Whether to show a progress bar during the conversion.
+
+
+
+#### UnstructuredFileConverter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### UnstructuredFileConverter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "UnstructuredFileConverter"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### UnstructuredFileConverter.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(
+ paths: list[str] | list[os.PathLike],
+ meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, list[Document]]
+```
+
+Convert files to Haystack Documents using the Unstructured API.
+
+**Arguments**:
+
+- `paths`: List of paths to convert. Paths can be files or directories.
+If a path is a directory, all files in the directory are converted. Subdirectories are ignored.
+- `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 paths, because the two lists will be zipped.
+Please note that if the paths contain directories, `meta` can only be a single dictionary
+(same metadata for all files).
+
+**Raises**:
+
+- `ValueError`: If `meta` is a list and `paths` contains directories.
+
+**Returns**:
+
+A dictionary with the following key:
+- `documents`: List of Haystack Documents.
+
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/valkey.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/valkey.md
new file mode 100644
index 00000000000..f4bdeb05aff
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/valkey.md
@@ -0,0 +1,1017 @@
+---
+title: "Valkey"
+id: integrations-valkey
+description: "Valkey integration for Haystack"
+slug: "/integrations-valkey"
+---
+
+
+## haystack_integrations.components.retrievers.valkey.embedding_retriever
+
+### ValkeyEmbeddingRetriever
+
+A component for retrieving documents from a ValkeyDocumentStore using vector similarity search.
+
+This retriever uses dense embeddings to find semantically similar documents. It supports
+filtering by metadata fields and configurable similarity thresholds.
+
+Key features:
+
+- Vector similarity search using HNSW algorithm
+- Metadata filtering with tag and numeric field support
+- Configurable top-k results
+- Filter policy management for runtime filter application
+
+Usage example:
+
+```python
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document
+from haystack import Pipeline
+# Requires: pip install sentence-transformers-haystack
+from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
+from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersDocumentEmbedder
+from haystack_integrations.components.retrievers.valkey import ValkeyEmbeddingRetriever
+from haystack_integrations.document_stores.valkey import ValkeyDocumentStore
+
+document_store = ValkeyDocumentStore(index_name="my_index", 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..."),
+ Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+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", ValkeyEmbeddingRetriever(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: ValkeyDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create a `ValkeyEmbeddingRetriever` instance.
+
+**Parameters:**
+
+- **document_store** (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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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
+) -> 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the associated synchronous resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the associated asynchronous resources.
+
+#### 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Return unique values for a metadata field with optional search and pagination.
+
+Values are returned in their original type (e.g. int, bool). The `search_term` filter, when
+provided, matches against the string representation of each value.
+
+**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).
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – Tuple of (list of unique values for the requested page, total count of unique values).
+
+**Raises:**
+
+- 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], int]
+```
+
+Asynchronously return unique values for a metadata field with optional search and pagination.
+
+Values are returned in their original type (e.g. int, bool). The `search_term` filter, when
+provided, matches against the string representation of each value.
+
+**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).
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – Tuple of (list of unique values for the requested page, total count of unique values).
+
+**Raises:**
+
+- 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-3.2-unstable/integrations-api/vespa.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/vespa.md
new file mode 100644
index 00000000000..7af6435960f
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/vespa.md
@@ -0,0 +1,359 @@
+---
+title: "Vespa"
+id: integrations-vespa
+description: "Vespa integration for Haystack"
+slug: "/integrations-vespa"
+---
+
+
+## haystack_integrations.components.retrievers.vespa.embedding_retriever
+
+### VespaEmbeddingRetriever
+
+Retrieve documents from Vespa using dense vector similarity.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: VespaDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ ranking: str | None = DEFAULT_SEMANTIC_RANKING,
+ query_tensor_name: str = "query_embedding",
+ target_hits: int | None = None
+) -> None
+```
+
+Create a Vespa embedding retriever.
+
+**Parameters:**
+
+- **document_store** (VespaDocumentStore) – Configured `VespaDocumentStore` for your application, for example
+ `VespaDocumentStore(url="http://localhost", schema="doc", namespace="doc")` aligned with your
+ Vespa schema. See https://docs.vespa.ai/en/basics/documents.html and the integration package README.
+- **filters** (dict\[str, Any\] | None) – Optional static Haystack metadata filters unless overridden in :meth:`run`, for example
+ `{"field": "meta.category", "operator": "==", "value": "news"}`. See
+ https://docs.haystack.deepset.ai/docs/metadata-filtering and https://docs.vespa.ai/en/query-language.html.
+- **top_k** (int) – Default maximum number of documents to return per query (for example `10`).
+- **ranking** (str | None) – Vespa rank profile used after nearest-neighbor retrieval, for example `semantic` for a
+ profile that scores with `closeness(field, embedding)`. Defaults to `semantic`. Pass `None` to use the
+ schema default profile. See https://docs.vespa.ai/en/basics/ranking.html.
+- **query_tensor_name** (str) – Name of the query tensor in YQL and in `input.query(...)` in your rank profile.
+ For example `query_embedding` matches the default `semantic` profile. See
+ https://docs.vespa.ai/en/nearest-neighbor-search.html.
+- **target_hits** (int | None) – Optional nearest-neighbor `targetHits` value, for example `10` or `100`: how many
+ neighbors are considered per content node before first-phase ranking. See
+ https://docs.vespa.ai/en/nearest-neighbor-search.html.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of VespaDocumentStore.
+
+#### 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 Vespa.
+
+**Parameters:**
+
+- **query_embedding** (list\[float\]) – Dense query embedding.
+- **filters** (dict\[str, Any\] | None) – Filters applied when fetching documents from the Document Store.
+- **top_k** (int | None) – Maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Retrieved documents.
+
+## haystack_integrations.components.retrievers.vespa.keyword_retriever
+
+### VespaKeywordRetriever
+
+Retrieve documents from Vespa using lexical search.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: VespaDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ ranking: str | None = DEFAULT_BM25_RANKING
+) -> None
+```
+
+Create a Vespa keyword retriever.
+
+**Parameters:**
+
+- **document_store** (VespaDocumentStore) – Configured `VespaDocumentStore` for your application, for example
+ `VespaDocumentStore(url="http://localhost", schema="doc", namespace="doc")` so it matches the deployed
+ schema and endpoint. See https://docs.vespa.ai/en/basics/documents.html and the integration package README.
+- **filters** (dict\[str, Any\] | None) – Optional static Haystack metadata filters applied on each retrieval unless overridden in
+ :meth:`run`, for example `{"field": "meta.category", "operator": "==", "value": "news"}`. See
+ https://docs.haystack.deepset.ai/docs/metadata-filtering and https://docs.vespa.ai/en/query-language.html.
+- **top_k** (int) – Default maximum number of documents to return per query (for example `10`).
+- **ranking** (str | None) – Vespa rank profile for lexical matches, for example `bm25` for a profile that uses
+ `bm25(content)`. Defaults to `bm25`. Pass `None` to use the schema default. See
+ https://docs.vespa.ai/en/basics/ranking.html.
+
+**Raises:**
+
+- ValueError – If `document_store` is not an instance of VespaDocumentStore.
+
+#### run
+
+```python
+run(
+ query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from Vespa.
+
+**Parameters:**
+
+- **query** (str) – Query text.
+- **filters** (dict\[str, Any\] | None) – Filters applied when fetching documents from the Document Store.
+- **top_k** (int | None) – Maximum number of documents to return.
+
+**Returns:**
+
+- dict\[str, list\[Document\]\] – Retrieved documents.
+
+## haystack_integrations.document_stores.vespa.document_store
+
+### VespaDocumentStore
+
+Document store backed by an existing [Vespa](https://vespa.ai/) application.
+
+#### __init__
+
+```python
+__init__(
+ *,
+ url: str | None = None,
+ port: int = 8080,
+ cert: Secret | None = None,
+ key: Secret | None = None,
+ vespa_cloud_secret_token: Secret | None = None,
+ additional_headers: dict[str, str] | None = None,
+ content_cluster_name: str = "content",
+ schema: str = "doc",
+ namespace: str | None = None,
+ groupname: str | None = None,
+ content_field: str = "content",
+ embedding_field: str = "embedding",
+ id_field: str = "id",
+ metadata_fields: list[str] | None = None,
+ query_limit: int = DEFAULT_QUERY_LIMIT
+) -> None
+```
+
+Create a new Vespa document store.
+
+**Parameters:**
+
+- **url** (str | None) – Vespa endpoint base URL. If omitted, the `VESPA_URL` environment variable is used.
+- **port** (int) – Vespa HTTP port.
+- **cert** (Secret | None) – Secret resolving to the data plane certificate file path for mTLS authentication.
+- **key** (Secret | None) – Secret resolving to the data plane key file path for mTLS authentication.
+- **vespa_cloud_secret_token** (Secret | None) – Vespa Cloud data plane secret token for token authentication.
+ If omitted, the `VESPA_CLOUD_SECRET_TOKEN` environment variable is used when set, matching pyvespa.
+- **additional_headers** (dict\[str, str\] | None) – Additional headers to send to the Vespa application.
+- **content_cluster_name** (str) – Vespa content cluster name.
+- **schema** (str) – Vespa schema name to read from and write to.
+- **namespace** (str | None) – Vespa namespace. Defaults to the schema name when omitted.
+- **groupname** (str | None) – Optional Vespa group name.
+- **content_field** (str) – Vespa field containing the document text.
+- **embedding_field** (str) – Vespa field containing the dense embedding.
+- **id_field** (str) – Optional Vespa field containing the document id in query responses.
+ Vespa document IDs are always written via `data_id`. If this field is missing in the
+ schema or summaries, the integration falls back to parsing the Vespa document path.
+- **metadata_fields** (list\[str\] | None) – Optional allowlist of metadata fields to feed and return.
+- **query_limit** (int) – Maximum number of documents returned by bulk queries. Defaults to 400 to
+ stay within Vespa's common query hit limit unless explicitly overridden.
+
+#### app
+
+```python
+app: Any
+```
+
+Return the underlying `pyvespa` `Vespa` HTTP client.
+
+It is built from this store's `url`, `port`, and authentication settings
+(`cert`, `key`, `vespa_cloud_secret_token`, `additional_headers`) so mTLS, bearer token,
+and custom headers from the constructor (or environment) are applied.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the document store to a dictionary.
+
+Uses the same init-parameter names as :meth:`__init__` and `default_to_dict` so nested serialization stays
+aligned with Haystack's default component serialization.
+
+**Returns:**
+
+- dict\[str, Any\] – Serialized document store data.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Return the total number of documents in Vespa.
+
+**Returns:**
+
+- int – Document count.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Return the number of documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters.
+
+**Returns:**
+
+- int – Count of matching documents.
+
+#### write_documents
+
+```python
+write_documents(
+ documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to Vespa.
+
+**Parameters:**
+
+- **documents** (list\[Document\]) – Documents to store.
+- **policy** (DuplicatePolicy) – Duplicate handling policy.
+
+**Returns:**
+
+- int – Number of documents written.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents by id.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – Document ids to delete.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Delete all documents for this store's schema, namespace, and content cluster.
+
+Implemented with pyvespa `Vespa.delete_all_docs` (Document V1 bulk delete).
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Delete all documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters.
+
+**Returns:**
+
+- int – Number of deleted documents.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Update metadata fields for documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\]) – Haystack metadata filters.
+- **meta** (dict\[str, Any\]) – Metadata values to merge into the matched documents.
+
+**Returns:**
+
+- int – Number of updated documents.
+
+#### get_documents_by_id
+
+```python
+get_documents_by_id(document_ids: list[str]) -> list[Document]
+```
+
+Retrieve documents by their ids.
+
+**Parameters:**
+
+- **document_ids** (list\[str\]) – Document ids to fetch.
+
+**Returns:**
+
+- list\[Document\] – Matching documents.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Retrieve documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (dict\[str, Any\] | None) – Haystack metadata filters.
+
+**Returns:**
+
+- list\[Document\] – Matching documents.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Return best-effort metadata field information based on configured fields.
+
+**Returns:**
+
+- dict\[str, dict\[str, str\]\] – Field metadata information.
+
+## haystack_integrations.document_stores.vespa.filters
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/vllm.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/vllm.md
new file mode 100644
index 00000000000..c6840a3b962
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/vllm.md
@@ -0,0 +1,797 @@
+---
+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 synchronous OpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous OpenAI client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous OpenAI client.
+
+#### 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 synchronous OpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous OpenAI client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous OpenAI client.
+
+#### 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 synchronous OpenAI client and warm up tools.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous OpenAI client and warm up tools.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous OpenAI 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]) -> 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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **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 are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only
+ at initialization are kept.
+ 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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **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 are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only
+ at initialization are kept.
+ 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 synchronous HTTP client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous HTTP client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous HTTP client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous HTTP client.
+
+#### 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-3.2-unstable/integrations-api/watsonx.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/watsonx.md
new file mode 100644
index 00000000000..b10e457b1ad
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/watsonx.md
@@ -0,0 +1,493 @@
+---
+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"
+) -> None
+```
+
+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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Watsonx embeddings client.
+
+#### 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
+) -> 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Watsonx embeddings client.
+
+#### 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.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Watsonx client.
+
+#### 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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only
+ at initialization are kept.
+- **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] | str,
+ 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\] | str) – A list of ChatMessage instances representing the input messages.
+ If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **generation_kwargs** (dict\[str, Any\] | None) – Additional keyword arguments for text generation. These are merged per key with the
+ `generation_kwargs` passed at initialization: keys provided here take precedence, keys set only
+ at initialization are kept.
+- **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.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/weave.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/weave.md
new file mode 100644
index 00000000000..cc730ea4d95
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/weave.md
@@ -0,0 +1,268 @@
+---
+title: "Weave"
+id: integrations-weave
+description: "Weights & Bias integration for Haystack"
+slug: "/integrations-weave"
+---
+
+
+## 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/str) – The name of the pipeline you want to trace.
+- **weave_init_kwargs** (dict\[str, Any\] | None) – Additional arguments to pass to the WeaveTracer client.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the WeaveTracer.
+
+#### run
+
+```python
+run() -> dict[str, str]
+```
+
+Run the WeaveConnector, initializing the tracer if needed.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- dict\[str, Any\] – Dictionary with all the necessary information to recreate this component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WeaveConnector
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – Dictionary to deserialize from.
+
+**Returns:**
+
+- WeaveConnector – Deserialized component.
+
+## haystack_integrations.tracing.weave.tracer
+
+### WeaveSpan
+
+Bases: Span
+
+A bridge between Haystack's Span interface and Weave's Call object.
+
+Stores metadata about a component execution and its inputs and outputs, and manages the attributes/tags
+that describe the operation.
+
+#### set_tag
+
+```python
+set_tag(key: str, value: Any) -> None
+```
+
+Set a tag by adding it to the call's inputs.
+
+**Parameters:**
+
+- **key** (str) – The tag key.
+- **value** (Any) – The tag value.
+
+#### set_tags
+
+```python
+set_tags(tags: dict[str, Any]) -> None
+```
+
+Set multiple tags at once by iterating over the provided dictionary.
+
+#### raw_span
+
+```python
+raw_span() -> Any
+```
+
+Access to the underlying Weave Call object.
+
+#### get_correlation_data_for_logs
+
+```python
+get_correlation_data_for_logs() -> dict[str, Any]
+```
+
+Correlation data for logging.
+
+#### set_call
+
+```python
+set_call(call: Call) -> None
+```
+
+Set the underlying Weave Call object for this span.
+
+#### get_attributes
+
+```python
+get_attributes() -> dict[str, Any]
+```
+
+Return the accumulated attributes dictionary for this span.
+
+### WeaveTracer
+
+Bases: Tracer
+
+Implements a Haystack's Tracer to make an interface with Weights and Bias Weave.
+
+It's responsible for creating and managing Weave calls, and for converting Haystack spans
+to Weave spans. It creates spans for each Haystack component run.
+
+#### __init__
+
+```python
+__init__(project_name: str, **weave_init_kwargs: Any) -> None
+```
+
+Initialize the WeaveTracer.
+
+**Parameters:**
+
+- **project_name** (str) – The name of the project to trace, this is will be the name appearing in Weave project.
+- **weave_init_kwargs** (Any) – Additional arguments to pass to the Weave client.
+
+#### create_call
+
+```python
+create_call(
+ attributes: dict,
+ client: WeaveClient,
+ parent_span: WeaveSpan | None,
+ operation_name: str,
+) -> Call
+```
+
+Create and return a Weave Call from the given span attributes and client.
+
+#### current_span
+
+```python
+current_span() -> Span | None
+```
+
+Get the current active span.
+
+#### trace
+
+```python
+trace(
+ operation_name: str,
+ tags: dict[str, Any] | None = None,
+ parent_span: WeaveSpan | None = None,
+) -> Iterator[WeaveSpan]
+```
+
+A context manager that creates and manages spans for tracking operations in Weights & Biases Weave.
+
+It has two main workflows:
+
+A) For regular operations (operation_name != "haystack.component.run"):
+Creates a Weave Call immediately
+Creates a WeaveSpan with this call
+Sets any provided tags
+Yields the span for use in the with block
+When the block ends, updates the call with pipeline output data
+
+B) For component runs (operation_name == "haystack.component.run"):
+Creates a WeaveSpan WITHOUT a call initially (deferred creation)
+Sets any provided tags
+Yields the span for use in the with block
+Creates the actual Weave Call only at the end, when all component information is available
+Updates the call with component output data
+
+This distinction is important because Weave's calls can't be updated once created, but the content
+tags are only set on the Span at a later stage. To get the inputs on call creation, we need to create
+the call after we yield the span.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/weaviate.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/weaviate.md
new file mode 100644
index 00000000000..5850487ca7f
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/weaviate.md
@@ -0,0 +1,1313 @@
+---
+title: "Weaviate"
+id: integrations-weaviate
+description: "Weaviate integration for Haystack"
+slug: "/integrations-weaviate"
+---
+
+
+## haystack_integrations.components.retrievers.weaviate.bm25_retriever
+
+### WeaviateBM25Retriever
+
+A component for retrieving documents from Weaviate using the BM25 algorithm.
+
+Example usage:
+
+```python
+from haystack_integrations.document_stores.weaviate.document_store import (
+ WeaviateDocumentStore,
+)
+from haystack_integrations.components.retrievers.weaviate.bm25_retriever import (
+ WeaviateBM25Retriever,
+)
+
+document_store = WeaviateDocumentStore(url="http://localhost:8080")
+retriever = WeaviateBM25Retriever(document_store=document_store)
+retriever.run(query="How to make a pizza", top_k=3)
+```
+
+#### __init__
+
+```python
+__init__(
+ *,
+ document_store: WeaviateDocumentStore,
+ filters: dict[str, Any] | None = None,
+ top_k: int = 10,
+ filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create a new instance of WeaviateBM25Retriever.
+
+**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
+- **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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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.
+
+#### close
+
+```python
+close() -> None
+```
+
+Release the synchronous resources of the underlying Document Store.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the asynchronous resources of the underlying Document Store.
+
+#### 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
+```
+
+Release the associated synchronous resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Release the associated asynchronous resources.
+
+#### 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 = 10,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], 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 the metadata field's values by
+ before returning them. If provided, only values of `metadata_field` that
+ contain this term will be considered.
+ Note: Uses case-insensitive substring matching (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 10.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple of (list of unique values in their original type, total count of unique values).
+
+**Note**: a scalar `int` metadata value comes back as `float`, not `int`. weaviate-client has no
+wire-protocol field for a scalar int - non-list properties are packed into a
+`google.protobuf.Struct`, whose `Value` type only has `number_value` (a double), so the int/float
+distinction is lost before the value reaches Weaviate. `GroupByAggregate` decodes numeric group
+keys the same way, so this holds even when the field's schema type is explicitly `DataType.INT`.
+List-valued int fields (e.g. `meta={"tags": [1, 2]}`) are unaffected - those go through a
+dedicated `IntArrayProperties` wire type instead.
+
+#### 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,
+ filters: dict[str, Any] | None = None,
+) -> tuple[list[Any], 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 the metadata field's values by
+ before returning them. If provided, only values of `metadata_field` that
+ contain this term will be considered.
+ Note: Uses case-insensitive substring matching (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 10.
+- **filters** (dict\[str, Any\] | None) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- tuple\[list\[Any\], int\] – A tuple of (list of unique values in their original type, total count of unique values).
+
+**Note**: a scalar `int` metadata value comes back as `float`, not `int`. weaviate-client has no
+wire-protocol field for a scalar int - non-list properties are packed into a
+`google.protobuf.Struct`, whose `Value` type only has `number_value` (a double), so the int/float
+distinction is lost before the value reaches Weaviate. `GroupByAggregate` decodes numeric group
+keys the same way, so this holds even when the field's schema type is explicitly `DataType.INT`.
+List-valued int fields (e.g. `meta={"tags": [1, 2]}`) are unaffected - those go through a
+dedicated `IntArrayProperties` wire type instead.
+
+#### 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_docs/version-3.2-unstable/integrations-api/whisper.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/whisper.md
new file mode 100644
index 00000000000..6459164aca1
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/whisper.md
@@ -0,0 +1,273 @@
+---
+title: "Whisper"
+id: integrations-whisper
+description: "Whisper integration for Haystack"
+slug: "/integrations-whisper"
+---
+
+
+## haystack_integrations.components.audio.whisper.whisper_local
+
+### LocalWhisperTranscriber
+
+Transcribes audio files using OpenAI's Whisper model on your local machine.
+
+For the supported audio formats, languages, and other parameters, see the
+[Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper
+[GitHub repository](https://github.com/openai/whisper).
+
+### Usage example
+
+```python
+from haystack_integrations.components.audio.whisper import LocalWhisperTranscriber
+
+whisper = LocalWhisperTranscriber(model="small")
+whisper.warm_up()
+transcription = whisper.run(sources=["path/to/audio/file"])
+```
+
+#### __init__
+
+```python
+__init__(
+ model: WhisperLocalModel = "large",
+ device: ComponentDevice | None = None,
+ whisper_params: dict[str, Any] | None = None,
+) -> None
+```
+
+Creates an instance of the LocalWhisperTranscriber component.
+
+**Parameters:**
+
+- **model** (WhisperLocalModel) – The name of the model to use. Set to one of the following models:
+ "tiny", "base", "small", "medium", "large" (default).
+ For details on the models and their modifications, see the
+ [Whisper documentation](https://github.com/openai/whisper?tab=readme-ov-file#available-models-and-languages).
+- **device** (ComponentDevice | None) – The device for loading the model. If `None`, automatically selects the default device.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Loads the model in memory.
+
+#### 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]) -> LocalWhisperTranscriber
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- LocalWhisperTranscriber – The deserialized component.
+
+#### run
+
+```python
+run(
+ sources: list[str | Path | ByteStream],
+ whisper_params: dict[str, Any] | None = None,
+) -> dict[str, Any]
+```
+
+Transcribes a list of audio files into a list of documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – A list of paths or binary streams to transcribe.
+- **whisper_params** (dict\[str, Any\] | None) – For the supported audio formats, languages, and other parameters, see the
+ [Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper
+ [GitHup repo](https://github.com/openai/whisper).
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of documents where each document is a transcribed audio file. The content of
+ the document is the transcription text, and the document's metadata contains the values returned by
+ the Whisper model, such as the alignment data and the path to the audio file used
+ for the transcription.
+
+## haystack_integrations.components.audio.whisper.whisper_remote
+
+### RemoteWhisperTranscriber
+
+Transcribes audio files using the OpenAI's Whisper API.
+
+The component requires an OpenAI API key, see the
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/authentication) for more details.
+For the supported audio formats, languages, and other parameters, see the
+[Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text).
+
+### Usage example
+
+```python
+from haystack_integrations.components.audio.whisper import RemoteWhisperTranscriber
+
+whisper = RemoteWhisperTranscriber(model="whisper-1")
+transcription = whisper.run(sources=["path/to/audio/file"])
+```
+
+#### __init__
+
+```python
+__init__(
+ api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
+ model: str = "whisper-1",
+ api_base_url: str | None = None,
+ organization: str | None = None,
+ http_client_kwargs: dict[str, Any] | None = None,
+ **kwargs: Any
+) -> None
+```
+
+Creates an instance of the RemoteWhisperTranscriber component.
+
+**Parameters:**
+
+- **api_key** (Secret) – OpenAI API key.
+ You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter
+ during initialization.
+- **model** (str) – Name of the model to use. Currently accepts only `whisper-1`.
+- **organization** (str | None) – Your OpenAI organization ID. See OpenAI's documentation on
+ [Setting Up Your Organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization).
+- **api_base_url** (str | None) – An optional URL to use as the API base. For details, see the
+ OpenAI [documentation](https://platform.openai.com/docs/api-reference/audio).
+- **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).
+- **kwargs** (Any) – Other optional parameters for the model. These are sent directly to the OpenAI
+ endpoint. See OpenAI [documentation](https://platform.openai.com/docs/api-reference/audio) for more details.
+ Some of the supported parameters are:
+- `language`: The language of the input audio.
+ Provide the input language in ISO-639-1 format
+ to improve transcription accuracy and latency.
+- `prompt`: An optional text to guide the model's
+ style or continue a previous audio segment.
+ The prompt should match the audio language.
+- `response_format`: The format of the transcript
+ output. This component only supports `json`.
+- `temperature`: The sampling temperature, between 0
+ and 1. Higher values like 0.8 make the output more
+ random, while lower values like 0.2 make it more
+ focused and deterministic. If set to 0, the model
+ uses log probability to automatically increase the
+ temperature until certain thresholds are hit.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the synchronous OpenAI client.
+
+#### warm_up_async
+
+```python
+warm_up_async() -> None
+```
+
+Create the asynchronous OpenAI client.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the synchronous OpenAI client.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous OpenAI 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]) -> RemoteWhisperTranscriber
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (dict\[str, Any\]) – The dictionary to deserialize from.
+
+**Returns:**
+
+- RemoteWhisperTranscriber – The deserialized component.
+
+#### run
+
+```python
+run(sources: list[str | Path | ByteStream]) -> dict[str, Any]
+```
+
+Transcribes the list of audio files into a list of documents.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – A list of file paths or `ByteStream` objects containing the audio files to transcribe.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of documents, one document for each file.
+ The content of each document is the transcribed text.
+
+#### run_async
+
+```python
+run_async(sources: list[str | Path | ByteStream]) -> dict[str, Any]
+```
+
+Asynchronously transcribes the list of audio files into 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 an async code.
+
+**Parameters:**
+
+- **sources** (list\[str | Path | ByteStream\]) – A list of file paths or `ByteStream` objects containing the audio files to transcribe.
+
+**Returns:**
+
+- dict\[str, Any\] – A dictionary with the following keys:
+- `documents`: A list of documents, one document for each file.
+ The content of each document is the transcribed text.
diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/youcom.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/youcom.md
new file mode 100644
index 00000000000..6f1d5389ab5
--- /dev/null
+++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/youcom.md
@@ -0,0 +1,128 @@
+---
+title: "You.com Search"
+id: integrations-youcom
+description: "You.com Search integration for Haystack"
+slug: "/integrations-youcom"
+---
+
+
+## haystack_integrations.components.websearch.youcom.youcom_websearch
+
+### YouComError
+
+Bases: ComponentError
+
+An error occurred while querying the You.com Search API.
+
+### YouComWebSearch
+
+A component that uses the You.com Search API to search the web and return results as Haystack Documents.
+
+Works with zero configuration: when no API key is available, searches use You.com's
+[keyless free tier](https://you.com/docs/api-reference/search/v1-agents-search) (rate limited
+per IP), so getting-started pipelines run without any setup. Set the `YOUDOTCOM_API_KEY`
+environment variable (or pass `api_key`) to use the keyed
+[You.com Search API](https://you.com/docs/api-reference/search/v1-search) with higher limits.
+
+Pass `keyless_fallback=False` to require a key and fail fast instead of degrading to the
+keyless tier — useful in production pipelines where a missing key should surface as an error.
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.youcom import YouComWebSearch
+
+websearch = YouComWebSearch(top_k=5) # no API key needed to get started
+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(API_KEY_ENV_VAR, strict=False),
+ keyless_fallback: bool = True,
+ top_k: int | None = 10,
+ freshness: str | None = None,
+ country: str | None = None,
+ search_lang: str | None = None,
+ safesearch: str | None = None,
+ extra_params: dict[str, Any] | None = None,
+ timeout: int = 10,
+ max_retries: int = 3,
+) -> None
+```
+
+Initialize the YouComWebSearch component.
+
+**Parameters:**
+
+- **api_key** (Secret) – You.com API key. Defaults to the `YOUDOTCOM_API_KEY` environment variable. Resolved
+ leniently, so an unset key is not an error — see `keyless_fallback` for what happens then.
+- **keyless_fallback** (bool) – What to do when no API key resolves. When `True` (the default), search the
+ [keyless free tier](https://you.com/docs/api-reference/search/v1-agents-search),
+ which needs no credentials but is rate limited per IP; the component logs which
+ endpoint it selected. When `False`, raise `YouComError` instead, so a missing key
+ fails fast rather than silently degrading.
+- **top_k** (int | None) – Maximum number of results to return per section (web, news). Maps to the
+ `count` parameter in the You.com API (1-100).
+- **freshness** (str | None) – Only return results from within the given window: `"day"`, `"week"`, `"month"`,
+ `"year"`, or a date range in the format `"YYYY-MM-DDtoYYYY-MM-DD"`.
+- **country** (str | None) – 2-letter country code determining the geographical focus of web results (e.g. `"US"`, `"DE"`).
+- **search_lang** (str | None) – Language of the returned web results in BCP 47 format (e.g. `"EN"`, `"PT-BR"`).
+ Maps to the `language` parameter in the You.com API.
+- **safesearch** (str | None) – Content moderation level: `"off"`, `"moderate"`, or `"strict"`.
+- **extra_params** (dict\[str, Any\] | None) – Additional query parameters passed directly to the You.com Search API
+ (e.g. `{"include_domains": "nytimes.com,bbc.com"}`).
+- **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 the You.com Search API 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.
+
+**Raises:**
+
+- YouComError – If the You.com Search API request fails.
+
+#### run_async
+
+```python
+run_async(query: str, top_k: int | None = None) -> dict[str, Any]
+```
+
+Asynchronously search the web using the You.com Search API 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.
+
+**Raises:**
+
+- YouComError – If the You.com Search API request fails.
diff --git a/docs-website/reference_versioned_sidebars/version-3.2-unstable-sidebars.json b/docs-website/reference_versioned_sidebars/version-3.2-unstable-sidebars.json
new file mode 100644
index 00000000000..4ac9220cebd
--- /dev/null
+++ b/docs-website/reference_versioned_sidebars/version-3.2-unstable-sidebars.json
@@ -0,0 +1,37 @@
+{
+ "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"
+ }
+ ]
+ }
+ ]
+}
\ No newline at end of file
diff --git a/docs-website/reference_versions.json b/docs-website/reference_versions.json
index 0db11162e70..eaed7b5fc4c 100644
--- a/docs-website/reference_versions.json
+++ b/docs-website/reference_versions.json
@@ -1 +1 @@
-["3.1", "3.0", "2.31", "2.30", "2.29", "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
+["3.2-unstable", "3.1", "3.0", "2.31", "2.30", "2.29", "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/vercel.json b/docs-website/vercel.json
index 9c605f369af..20e13bb84b4 100644
--- a/docs-website/vercel.json
+++ b/docs-website/vercel.json
@@ -165,6 +165,16 @@
"source": "/reference/2.28/:slug*",
"destination": "/reference/:slug*",
"permanent": true
+ },
+ {
+ "source": "/docs/2.29/:slug*",
+ "destination": "/docs/:slug*",
+ "permanent": true
+ },
+ {
+ "source": "/reference/2.29/:slug*",
+ "destination": "/reference/:slug*",
+ "permanent": true
}
]
}
diff --git a/docs-website/versioned_docs/version-3.2-unstable/AGENTS.md b/docs-website/versioned_docs/version-3.2-unstable/AGENTS.md
new file mode 100644
index 00000000000..0f7e01ae2a1
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/AGENTS.md
@@ -0,0 +1,9 @@
+# docs-website/docs/ Guidelines
+
+## Documentation
+
+- Edit `docs-website/docs/pipeline-components/` pages only for outdated, incorrect, or materially useful guidance; keep examples concise and `Agent`-level and polish prose before merge — avoids churn while keeping docs copyable
+- Add `## Overview` near the top of `docs-website/docs/pipeline-components/**` pages — explains what the component does and why to use it before details
+- Document component outputs, extractor side effects, and exact `doc.meta` keys; link producers, API references, and the authoritative reference for any partial config summary
+- Use current chat APIs in new docs pipelines — `ChatPromptBuilder`, `ChatMessage`, chat generators, and `result["last_message"]` for agent output — matching wiring, edge names like `prompt`, and declared variables; keep YAML examples on current default model names
+- Mark joiners/adapters optional where smart pipeline connections already handle the composition
diff --git a/docs-website/versioned_docs/version-3.2-unstable/CLAUDE.md b/docs-website/versioned_docs/version-3.2-unstable/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/docs-website/versioned_docs/version-3.2-unstable/_templates/component-template.mdx b/docs-website/versioned_docs/version-3.2-unstable/_templates/component-template.mdx
new file mode 100644
index 00000000000..f1c5c42fb6e
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/_templates/document-store-template.mdx b/docs-website/versioned_docs/version-3.2-unstable/_templates/document-store-template.mdx
new file mode 100644
index 00000000000..6418824a44c
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/concepts/agents.mdx b/docs-website/versioned_docs/version-3.2-unstable/concepts/agents.mdx
new file mode 100644
index 00000000000..8ccaf71986d
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/concepts/agents.mdx
@@ -0,0 +1,128 @@
+---
+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 an `AgentTool` 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.
+- [`AgentTool`](../tools/agenttool.mdx) – Wraps an `Agent` as a callable tool, so another `Agent` can delegate to it.
+- [`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=
+
+
+### Alternatives to `AgentTool`
+
+Since `Agent` is a Haystack component, you can also wrap it with [`ComponentTool`](../../tools/componenttool.mdx). However, this exposes the agent's full component interface to the coordinator, including arguments such as `tools`, `generation_kwargs`, and `hook_context`, and the coordinator receives the complete result dictionary. By default, `AgentTool` exposes a single input, `messages`, carrying the task to delegate, plus one parameter for each mandatory prompt variable of the specialist. It returns only the text of the specialist's final reply.
+
+You can also create a similarly narrow interface with the [`@tool`](../../tools/tool.mdx#tool-decorator) decorator. This is useful when you need custom input arguments, want to transform the delegated task, or need to post-process the specialist's response. The trade-off is serialization: a decorated tool serializes as an import path to the function, so the specialist's configuration lives in your Python module rather than in the YAML above.
+
+## 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.
+`AgentTool` 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 the `tool_concurrency_limit` init parameter (default: `4`).
+
+The example below asks the coordinator about two topics: it calls `research_specialist` 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 OpenAIResponsesChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
+from haystack.dataclasses import ChatMessage
+from haystack.tools import AgentTool, 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=OpenAIResponsesChatGenerator(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."
+ ),
+)
+
+
+research_specialist = AgentTool(
+ agent=research_agent,
+ name="research_specialist",
+ description="Research a topic on the web and report a summary of the findings",
+)
+
+
+coordinator = Agent(
+ chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
+ tools=[research_specialist],
+ system_prompt=(
+ "You are a coordinator. Delegate research tasks to the research specialist. "
+ "For questions covering multiple topics, research each one independently. "
+ "Keep your final answer concise."
+ ),
+ streaming_callback=print_streaming_chunk,
+ tool_concurrency_limit=4, # run up to 4 specialist calls in parallel
+)
+
+result = coordinator.run(
+ messages=[
+ ChatMessage.from_user(
+ "What are the latest developments in the Haystack framework, "
+ "and what is the current state of the Model Context Protocol?",
+ ),
+ ],
+)
+```
+
+## Additional References
+
+📖 Related docs:
+
+- [Agent](../../pipeline-components/agents-1/agent.mdx)
+- [AgentTool](../../tools/agenttool.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-3.2-unstable/concepts/components.mdx b/docs-website/versioned_docs/version-3.2-unstable/concepts/components.mdx
new file mode 100644
index 00000000000..5cee6312cfb
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/concepts/components.mdx
@@ -0,0 +1,68 @@
+---
+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_responses.OpenAIResponsesChatGenerator + exit_conditions: + - text + hooks: null + max_agent_steps: 100 + raise_on_tool_invocation_failure: false + required_variables: '*' + state_schema: {} + streaming_callback: haystack.components.generators.utils.print_streaming_chunk + system_prompt: You are a coordinator. Delegate research tasks to the research + specialist. + tool_concurrency_limit: 4 + tool_streaming_callback_passthrough: false + tools: + - data: + 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_responses.OpenAIResponsesChatGenerator + exit_conditions: + - text + hooks: null + max_agent_steps: 100 + raise_on_tool_invocation_failure: false + required_variables: '*' + state_schema: {} + streaming_callback: null + system_prompt: You are a research specialist. Search the web to find + information. + tool_concurrency_limit: 4 + tool_streaming_callback_passthrough: false + 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_integrations.components.websearch.serperdev.websearch.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: + handler: haystack.tools.agent_tool.agent_result_to_string + parameters: null + type: haystack.tools.agent_tool.AgentTool + user_prompt: null + type: haystack.components.agents.agent.Agent +connection_type_validation: true +connections: [] +max_runs_per_component: 100 +metadata: {} +``` + ++
+
+
+
+```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-3.2-unstable/concepts/pipelines/visualizing-pipelines.mdx b/docs-website/versioned_docs/version-3.2-unstable/concepts/pipelines/visualizing-pipelines.mdx
new file mode 100644
index 00000000000..78e69675d5f
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/concepts/secret-management.mdx b/docs-website/versioned_docs/version-3.2-unstable/concepts/secret-management.mdx new file mode 100644 index 00000000000..ef1d99c8cbf --- /dev/null +++ b/docs-website/versioned_docs/version-3.2-unstable/concepts/secret-management.mdx @@ -0,0 +1,202 @@ +--- +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 = OpenAIChatGenerator(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 OpenAIChatGenerator) have a default value for `Secret.from_env_var` (in this case, `OPENAI_API_KEY`). This means that the `OpenAIChatGenerator` 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 = (
+ OpenAIChatGenerator()
+) # 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 = OpenAIChatGenerator(api_key=Secret.from_env_var("YOUR_ENV_VAR"))
+```
+
+When `OpenAIChatGenerator` 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: {}
+ http_client_kwargs: null
+ max_retries: null
+ model: gpt-5-mini
+ organization: null
+ streaming_callback: null
+ timeout: null
+ tools: null
+ tools_strict: false
+ type: haystack.components.generators.chat.openai.OpenAIChatGenerator
+ ...
+```
+
+### 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-3.2-unstable/development/deployment.mdx b/docs-website/versioned_docs/version-3.2-unstable/development/deployment.mdx
new file mode 100644
index 00000000000..30b21a02103
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/development/deployment.mdx
@@ -0,0 +1,37 @@
+---
+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:
+
+- [Haystack Enterprise Platform](deployment/haystack-enterprise-platform.mdx)
+- [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-3.2-unstable/development/deployment/docker.mdx b/docs-website/versioned_docs/version-3.2-unstable/development/deployment/docker.mdx
new file mode 100644
index 00000000000..f7907ab2104
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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 `3.0.0`, you can run the command:
+
+```shell
+docker pull deepset/haystack:base-v3.0.0
+```
+
+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-v3.0.0 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-v3.0.0
+
+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.23.0
+
+RUN pip install qdrant-haystack sentence-transformers-haystack
+
+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-3.2-unstable/development/deployment/haystack-enterprise-platform.mdx b/docs-website/versioned_docs/version-3.2-unstable/development/deployment/haystack-enterprise-platform.mdx
new file mode 100644
index 00000000000..16a682faef6
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/development/deployment/haystack-enterprise-platform.mdx
@@ -0,0 +1,22 @@
+---
+title: "Haystack Enterprise Platform"
+id: haystack-enterprise-platform
+slug: "/deployment-haystack-enterprise-platform"
+description: "Learn how to deploy your Haystack pipelines on Haystack Enterprise Platform, without managing your own infrastructure."
+---
+
+# Haystack Enterprise Platform
+
+Learn how to deploy your Haystack pipelines on [Haystack Enterprise Platform](https://www.deepset.ai/products-and-services/haystack-enterprise-platform), without managing your own infrastructure.
+
+## Bringing a Pipeline onto the Platform
+
+If you already have a Haystack pipeline defined in code, serialize it to YAML, create an empty pipeline in the platform's Pipeline Builder, switch to YAML view, and paste it in. See [Import a Pipeline](https://docs.cloud.deepset.ai/docs/import-a-pipeline) for the exact steps. You can also build a pipeline from scratch directly in the Builder.
+
+## Deploying a Pipeline
+
+Click **Deploy** on a pipeline to make it available for testing in the Playground. Deploys are zero-downtime: the version already running keeps serving queries until the new version deploys successfully, and Deploy always uses the latest saved version, so there's no draft-versus-version choice to make. See [Deploy a Pipeline](https://docs.cloud.deepset.ai/docs/deploy-a-pipeline) for details.
+
+## Scaling and Idle Resources
+
+You don't manage servers directly. In the pipeline's Settings tab, you configure a minimum and maximum number of replicas and an idle timeout, the time after which an unused pipeline enters standby mode to save resources; inactive pipelines don't consume the pipeline hours included in your plan. See [Pipelines](https://docs.cloud.deepset.ai/docs/about-pipelines) for details on hosting settings.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/development/deployment/kubernetes.mdx b/docs-website/versioned_docs/version-3.2-unstable/development/deployment/kubernetes.mdx
new file mode 100644
index 00000000000..53f246749d1
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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.23.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 `OpenAIChatGenerator` 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 = OpenAIChatGenerator(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 = OpenAIChatGenerator(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. + +
+
+| | |
+| --- | --- |
+| **Base classes** | `Tracer` and `Span` |
+| **How to enable** | Implement the `Tracer` interface, then `tracing.enable_tracing(your_tracer)` |
+| **Content tracing** | Optional. Set `HAYSTACK_CONTENT_TRACING_ENABLED` to `true` to trace component inputs and outputs |
+| **Package** | Built into Haystack |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/tracing/tracer.py |
+
+
+
+## Overview
+
+If your tracing backend isn't supported out of the box, you can connect it to Haystack by implementing the `Tracer` interface. This gives you full control over how spans are created and how tags are recorded.
+
+## Usage
+
+1. Implement the `Tracer` interface. The following code snippet provides an example using the OpenTelemetry package:
+
+ ```python
+ import contextlib
+ from collections.abc import Iterator
+ from typing import Any
+
+ from opentelemetry import trace
+ from opentelemetry.trace import NonRecordingSpan
+
+ from haystack.tracing import Tracer, Span
+ from haystack.tracing import utils as tracing_utils
+ import opentelemetry.trace
+
+
+ class OpenTelemetrySpan(Span):
+ def __init__(self, span: opentelemetry.trace.Span) -> None:
+ self._span = span
+
+ def set_tag(self, key: str, value: Any) -> None:
+ # Tracing backends usually don't support any tag value
+ # `coerce_tag_value` forces the value to either be a Python
+ # primitive (int, float, boolean, str) or tries to dump it as string.
+ coerced_value = tracing_utils.coerce_tag_value(value)
+ self._span.set_attribute(key, coerced_value)
+
+
+ class OpenTelemetryTracer(Tracer):
+ def __init__(self, tracer: opentelemetry.trace.Tracer) -> None:
+ self._tracer = tracer
+
+ @contextlib.contextmanager
+ def trace(
+ self,
+ operation_name: str,
+ tags: dict[str, Any] | None = None,
+ parent_span: Span | None = None,
+ ) -> Iterator[Span]:
+ with self._tracer.start_as_current_span(operation_name) as span:
+ span = OpenTelemetrySpan(span)
+ if tags:
+ span.set_tags(tags)
+
+ yield span
+
+ def current_span(self) -> Span | None:
+ current_span = trace.get_current_span()
+ if isinstance(current_span, NonRecordingSpan):
+ return None
+
+ return OpenTelemetrySpan(current_span)
+ ```
+
+2. Tell Haystack to use your custom tracer:
+
+ ```python
+ from haystack import tracing
+
+ haystack_tracer = OpenTelemetryTracer(tracer)
+ tracing.enable_tracing(haystack_tracer)
+ ```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/development/tracing/datadog.mdx b/docs-website/versioned_docs/version-3.2-unstable/development/tracing/datadog.mdx
new file mode 100644
index 00000000000..943f2d7ffda
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/development/tracing/datadog.mdx
@@ -0,0 +1,94 @@
+---
+title: "Datadog"
+id: datadog
+slug: "/tracing-datadog"
+description: "Learn how to trace your Haystack pipelines with Datadog."
+---
+
+# Datadog
+
+Learn how to trace your Haystack pipelines with Datadog.
+
+
+
+| | |
+| --- | --- |
+| **Tracer class** | `DatadogTracer` |
+| **How to enable** | Enable the tracer with `tracing.enable_tracing(DatadogTracer(ddtrace.tracer))`, or add the `DatadogConnector` component to your pipeline |
+| **Content tracing** | Set `HAYSTACK_CONTENT_TRACING_ENABLED` to `true` to trace component inputs and outputs |
+| **Package** | `datadog-haystack` |
+| **API reference** | [datadog](/reference/integrations-datadog) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/datadog |
+
+
+
+## Overview
+
+Trace your Haystack pipelines with [Datadog](https://www.datadoghq.com/) through [Datadog's tracing library `ddtrace`](https://ddtrace.readthedocs.io/en/stable/). Haystack captures detailed information about pipeline runs, like API calls, context data, and prompts, so you can see the complete trace of your pipeline execution in Datadog.
+
+## Installation
+
+Install the `datadog-haystack` package:
+
+```shell
+pip install datadog-haystack
+```
+
+## Prerequisites
+
+1. A way to receive traces, such as a running [Datadog Agent](https://docs.datadoghq.com/agent/). `ddtrace` sends traces to the Datadog Agent at `localhost:8126` by default.
+2. Configure `ddtrace` through the standard mechanisms, for example the `DD_SERVICE`, `DD_ENV`, and `DD_VERSION` environment variables, or by running your application with the `ddtrace-run` command. See the [ddtrace documentation](https://ddtrace.readthedocs.io/en/stable/) for more details.
+
+## Usage
+
+Enable the `DatadogTracer` directly to trace any Haystack pipeline, without adding a component to it. Make sure to set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable before importing any Haystack components.
+
+```python
+import os
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+import ddtrace
+
+from haystack import Pipeline, tracing
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.tracing.datadog import DatadogTracer
+
+# Enable the Datadog tracer
+tracing.enable_tracing(DatadogTracer(ddtrace.tracer))
+
+pipe = Pipeline()
+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])
+```
+
+Each pipeline run produces a trace that includes the entire execution context, including prompts, completions, and metadata. You can then view the traces in your Datadog dashboard.
+
+## Alternative: the DatadogConnector component
+
+If you prefer to manage tracing as part of your pipeline definition (for example, so it serializes to YAML), you can add the `DatadogConnector` component instead. It enables the same Datadog tracing as soon as it is initialized.
+
+:::info
+See the [`DatadogConnector` documentation page](../../pipeline-components/connectors/datadogconnector.mdx) for full usage examples, or check out the [integration page](https://haystack.deepset.ai/integrations/datadog).
+:::
diff --git a/docs-website/versioned_docs/version-3.2-unstable/development/tracing/haystack-enterprise-platform.mdx b/docs-website/versioned_docs/version-3.2-unstable/development/tracing/haystack-enterprise-platform.mdx
new file mode 100644
index 00000000000..2403d565298
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/development/tracing/haystack-enterprise-platform.mdx
@@ -0,0 +1,28 @@
+---
+title: "Haystack Enterprise Platform"
+id: haystack-enterprise-platform
+slug: "/tracing-haystack-enterprise-platform"
+description: "Learn how pipeline tracing works out of the box on Haystack Enterprise Platform."
+---
+
+# Haystack Enterprise Platform
+
+Learn how pipeline tracing works out of the box on [Haystack Enterprise Platform](https://www.deepset.ai/products-and-services/haystack-enterprise-platform).
+
+
+
+| | |
+| --- | --- |
+| **How to enable** | Built in — every deployed pipeline is traced automatically |
+| **Content tracing** | Captured automatically: query transformations, embeddings, retrieved documents, scoring decisions, latencies, and errors |
+| **Platform docs** | [Trace Your Pipelines](https://docs.cloud.deepset.ai/docs/trace-your-pipelines) |
+
+
+
+## Overview
+
+Haystack Enterprise Platform traces every pipeline you deploy without any setup: no tracer to enable, no content-tracing flag to flip. Traces capture the full journey of a query through your pipeline, including timestamps, query transformations, generated embeddings, retrieved documents, scoring and ranking decisions, and any errors or latency issues.
+
+## Built-in Tracing
+
+Open a pipeline in the Builder and check the **Analytics** tab to inspect traces for individual runs, alongside pipeline-level metrics like request volume and latency. See [Monitor Pipeline Performance](https://docs.cloud.deepset.ai/docs/monitor-pipeline-performance) for details on the available dashboards.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/development/tracing/langfuse.mdx b/docs-website/versioned_docs/version-3.2-unstable/development/tracing/langfuse.mdx
new file mode 100644
index 00000000000..46040144108
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/development/tracing/langfuse.mdx
@@ -0,0 +1,110 @@
+---
+title: "Langfuse"
+id: langfuse
+slug: "/tracing-langfuse"
+description: "Learn how to trace your Haystack pipelines with Langfuse."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# Langfuse
+
+Learn how to trace your Haystack pipelines with Langfuse.
+
+
+
+| | |
+| --- | --- |
+| **Tracer class** | `LangfuseTracer` |
+| **How to enable** | Enable the tracer with `tracing.enable_tracing(LangfuseTracer(langfuse))`, or add the `LangfuseConnector` component to your pipeline |
+| **Content tracing** | Required. Set `HAYSTACK_CONTENT_TRACING_ENABLED` to `true` |
+| **Package** | `langfuse-haystack` |
+| **API reference** | [langfuse](/reference/integrations-langfuse) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/langfuse |
+
+
+
+## Overview
+
+Trace your Haystack pipelines with the [Langfuse](https://langfuse.com/) UI. Langfuse captures detailed information about pipeline runs, like API calls, context data, prompts, and more. Use it to monitor model performance such as token usage and cost, find areas for improvement, and create datasets from your pipeline executions.
+
+## Installation
+
+Install the `langfuse-haystack` package:
+
+```shell
+pip install langfuse-haystack
+```
+
+## Prerequisites
+
+1. An active Langfuse [account](https://cloud.langfuse.com/).
+2. Set the `LANGFUSE_SECRET_KEY` and `LANGFUSE_PUBLIC_KEY` environment variables with your Langfuse secret and public keys, found in your account profile.
+3. Set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true` to enable tracing.
+
+:::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. An even better practice is to set these environment variables in your shell before running the script.
+:::
+
+## Usage
+
+Enable the `LangfuseTracer` directly to trace any Haystack pipeline, without adding a component to it.
+
+```python
+import os
+
+os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"
+os.environ["LANGFUSE_SECRET_KEY"] = "
+
+| | |
+| --- | --- |
+| **Tracer class** | `LoggingTracer` |
+| **How to enable** | `tracing.enable_tracing(LoggingTracer(...))` |
+| **Content tracing** | Required to log inputs and outputs. Set `tracing.tracer.is_content_tracing_enabled = True` |
+| **Package** | Built into Haystack |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/tracing/logging_tracer.py |
+
+
+
+## Overview
+
+Use Haystack's [`LoggingTracer`](https://github.com/deepset-ai/haystack/blob/main/haystack/tracing/logging_tracer.py) logs to inspect the data that's flowing through your pipeline in real time.
+
+This feature is particularly helpful during experimentation and prototyping, as you don’t need to set up any tracing backend beforehand.
+
+## Usage
+
+Here’s how you can enable this tracer. In this example, we are adding color tags (this is optional) to highlight the components' names and inputs:
+
+```python
+import logging
+from haystack import tracing
+from haystack.tracing.logging_tracer import LoggingTracer
+
+logging.basicConfig(
+ format="%(levelname)s - %(name)s - %(message)s",
+ level=logging.WARNING,
+)
+logging.getLogger("haystack").setLevel(logging.DEBUG)
+
+tracing.tracer.is_content_tracing_enabled = (
+ True # to enable tracing/logging content (inputs/outputs)
+)
+tracing.enable_tracing(
+ LoggingTracer(
+ tags_color_strings={
+ "haystack.component.input": "\x1b[1;31m",
+ "haystack.component.name": "\x1b[1;34m",
+ },
+ ),
+)
+```
+
+Here’s what the resulting log would look like when a pipeline is run:
+
+
+| | |
+| --- | --- |
+| **How to enable** | `mlflow.haystack.autolog()` |
+| **Content tracing** | Captured automatically, including latencies, token usage, cost, and exceptions |
+| **Package** | `mlflow` |
+| **Integration guide** | https://haystack.deepset.ai/integrations/mlflow |
+
+
+
+## Overview
+
+[MLflow](https://mlflow.org/) is an open-source platform for managing the end-to-end machine learning and AI lifecycle. MLflow provides native tracing support for Haystack, so you can capture traces from all your pipelines and components with a single line of code.
+
+## Installation
+
+Install MLflow:
+
+```shell
+pip install mlflow
+```
+
+## Usage
+
+Enable automatic tracing for all Haystack pipelines and components:
+
+```python
+import mlflow
+
+mlflow.haystack.autolog()
+# Optionally set an experiment name
+mlflow.set_experiment("Haystack")
+```
+
+This automatically captures traces from all Haystack pipelines and components, including latencies, token usage, cost, and any exceptions.
+
+:::info
+Check out the [MLflow Haystack integration guide](https://haystack.deepset.ai/integrations/mlflow) for a full walkthrough with examples.
+:::
diff --git a/docs-website/versioned_docs/version-3.2-unstable/development/tracing/opentelemetry.mdx b/docs-website/versioned_docs/version-3.2-unstable/development/tracing/opentelemetry.mdx
new file mode 100644
index 00000000000..de0ec4c2473
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/development/tracing/opentelemetry.mdx
@@ -0,0 +1,153 @@
+---
+title: "OpenTelemetry"
+id: opentelemetry
+slug: "/tracing-opentelemetry"
+description: "Learn how to trace your Haystack pipelines with OpenTelemetry."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# OpenTelemetry
+
+Learn how to trace your Haystack pipelines with OpenTelemetry.
+
+
+
+| | |
+| --- | --- |
+| **Tracer class** | `OpenTelemetryTracer` |
+| **How to enable** | Configure an OpenTelemetry `TracerProvider`, then enable the tracer with `tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer("my_application")))`, or add the `OpenTelemetryConnector` component to your pipeline |
+| **Content tracing** | Set `HAYSTACK_CONTENT_TRACING_ENABLED` to `true` to trace component inputs and outputs |
+| **Package** | `opentelemetry-haystack` |
+| **API reference** | [opentelemetry](/reference/integrations-opentelemetry) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opentelemetry |
+
+
+
+## Overview
+
+[OpenTelemetry](https://opentelemetry.io/) is an open-source observability framework for collecting traces, metrics, and logs. Haystack integrates with OpenTelemetry, so you can send traces of your pipeline runs to any OpenTelemetry-compatible backend.
+
+:::info[Provided by an integration]
+`OpenTelemetryTracer` lives in the `opentelemetry-haystack` package and is not part of Haystack core. Since Haystack 3.0, OpenTelemetry tracing is no longer auto-enabled when `opentelemetry-sdk` is installed. Install the integration and either enable the `OpenTelemetryTracer` directly or add the `OpenTelemetryConnector` component to your pipeline.
+:::
+
+## Installation
+
+Install the `opentelemetry-haystack` package:
+
+```shell
+pip install opentelemetry-haystack
+```
+
+To add traces to even deeper levels of your pipelines, we recommend you check out [OpenTelemetry integrations](https://opentelemetry.io/ecosystem/registry/?s=python), such as:
+
+- [`urllib3` instrumentation](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-urllib3) for tracing HTTP requests in your pipeline,
+- [OpenAI instrumentation](https://github.com/traceloop/openllmetry/tree/main/packages/opentelemetry-instrumentation-openai) for tracing OpenAI requests.
+
+## Prerequisites
+
+A configured OpenTelemetry `TracerProvider` with an exporter, for example an OTLP exporter that sends traces to a collector or a backend. Set up the provider before enabling the tracer.
+
+## Usage
+
+Enable the `OpenTelemetryTracer` directly to trace any Haystack pipeline, without adding a component to it. Configure your `TracerProvider` and set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable before importing any Haystack components.
+
+```python
+import os
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.semconv.resource import ResourceAttributes
+
+# Configure the OpenTelemetry SDK. A service name is required for most backends.
+resource = Resource(attributes={ResourceAttributes.SERVICE_NAME: "haystack"})
+tracer_provider = TracerProvider(resource=resource)
+tracer_provider.add_span_processor(
+ BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")),
+)
+trace.set_tracer_provider(tracer_provider)
+
+from haystack import tracing
+from haystack_integrations.tracing.opentelemetry import OpenTelemetryTracer
+
+# Enable the OpenTelemetry tracer
+tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer("my_application")))
+```
+
+Each pipeline run then produces a trace that includes the entire execution context, including prompts, completions, and metadata. You can view the traces in your OpenTelemetry-compatible backend.
+
+## Alternative: the OpenTelemetryConnector component
+
+If you prefer to manage tracing as part of your pipeline definition, you can add the `OpenTelemetryConnector` component instead. It enables the same OpenTelemetry tracing as soon as it is initialized.
+
+:::info
+See the [`OpenTelemetryConnector` documentation page](../../pipeline-components/connectors/opentelemetryconnector.mdx) for full usage examples, or check out the [integration page](https://haystack.deepset.ai/integrations/opentelemetry).
+:::
+
+## Visualizing Traces During Development
+
+Use [Jaeger](https://www.jaegertracing.io/docs/1.6/getting-started/) as a lightweight tracing backend for local pipeline development. This allows you to experiment with tracing without the need for a complex tracing backend.
+
+
+| | |
+| --- | --- |
+| **Tracer class** | `RhesisTracer` |
+| **How to enable** | Add the `RhesisConnector` component to your pipeline — constructing it enables the tracer. For applications that drive Haystack outside a pipeline, use `RhesisTracing` |
+| **Content tracing** | Required for prompts and completions. Set `HAYSTACK_CONTENT_TRACING_ENABLED` to `true` |
+| **Package** | `rhesis-haystack` |
+| **API reference** | [rhesis](/reference/integrations-rhesis) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/rhesis |
+
+
+
+## Overview
+
+Trace your Haystack pipelines, components and `Agent` runs in [Rhesis](https://rhesis.ai), an open-source platform for structured feedback and evaluation on LLM agents. Traces are exported over OpenTelemetry.
+
+Beyond viewing traces, the integration correlates them with evaluation data. Spans carry the identifiers of the test execution and the conversation turn they belong to — `rhesis.test.run_id`, `rhesis.test.id`, `rhesis.test.result_id`, and `rhesis.conversation.id` — so a pipeline can run under a Rhesis test run and have reviewer feedback land on the exact span tree that produced the answer.
+
+It also covers both Haystack span shapes: the 2.x batched `ToolInvoker` component span, and the 3.0 agent loop, where each step gets an `ai.llm.invoke` span, each tool call an `ai.tool.invoke` span, and a tool that runs another `Agent` is promoted to `ai.agent.handoff`.
+
+## Installation
+
+Install the `rhesis-haystack` package:
+
+```shell
+pip install rhesis-haystack
+```
+
+## Prerequisites
+
+1. A Rhesis [account](https://rhesis.ai), or a self-hosted backend that `RHESIS_BASE_URL` points at.
+2. Set the `RHESIS_API_KEY` environment variable with your Rhesis API key.
+3. Set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true` to capture prompts and completions.
+
+:::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. An even better practice is to set these environment variables in your shell before running the script.
+:::
+
+These are optional:
+
+| Variable | Description |
+| --- | --- |
+| `RHESIS_BASE_URL` | Backend URL. Defaults to `http://localhost:8080` |
+| `RHESIS_PROJECT_ID` | Project ID. Resolved from the API key when omitted |
+| `RHESIS_ENVIRONMENT` | Environment label. Defaults to `development` |
+| `RHESIS_FRONTEND_URL` | Frontend URL used to build `trace_url` deep links |
+| `HAYSTACK_RHESIS_ENFORCE_FLUSH` | Defaults to `true`, exporting once per pipeline run. Set to `false` to leave exporting to the batch processor |
+
+## Usage
+
+Add the `RhesisConnector` component to your pipeline without connecting it to anything else. Constructing it enables the tracer for every pipeline operation, and it returns the trace's `name`, `trace_url` and `trace_id` as outputs.
+
+```python
+import os
+
+os.environ["RHESIS_API_KEY"] = "
+
+| | |
+| --- | --- |
+| **Tracer class** | `WeaveTracer` |
+| **How to enable** | Enable the tracer with `tracing.enable_tracing(WeaveTracer(project_name="..."))`, or add the `WeaveConnector` component to your pipeline |
+| **Content tracing** | Required. Set `HAYSTACK_CONTENT_TRACING_ENABLED` to `true` |
+| **Package** | `weave-haystack` |
+| **API reference** | [Weave](/reference/integrations-weave) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/weave |
+
+
+
+## Overview
+
+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.
+
+## Installation
+
+Install the `weave-haystack` package:
+
+```shell
+pip install weave-haystack
+```
+
+## Prerequisites
+
+1. A Weave account. You can sign up for free on the [Weights & Biases website](https://wandb.ai/site).
+2. 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).
+3. Set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true`.
+
+## Usage
+
+Enable the `WeaveTracer` directly to trace any Haystack pipeline, without adding a component to it. The `project_name` is the name that will appear in your Weave project.
+
+```python
+import os
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+from haystack import Pipeline, tracing
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.tracing.weave import WeaveTracer
+
+# Enable the Weave tracer
+tracing.enable_tracing(WeaveTracer(project_name="test_pipeline"))
+
+pipe = Pipeline()
+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])
+```
+
+You can then see the complete trace for your pipeline at `https://wandb.ai/
+
+| | |
+| --- | --- |
+| API reference | [AlloyDB](/reference/integrations-alloydb) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/alloydb |
+
+
+
+[AlloyDB](https://cloud.google.com/alloydb) is a fully managed, PostgreSQL-compatible database service on Google Cloud. The `AlloyDBDocumentStore` uses the [pgvector extension](https://cloud.google.com/alloydb/docs/ai/work-with-embeddings) to perform vector similarity search.
+
+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.
+
+The `AlloyDBDocumentStore` supports embedding retrieval, keyword retrieval, and metadata filtering.
+
+## Installation
+
+Install the `alloydb-haystack` integration:
+
+```shell
+pip install alloydb-haystack
+```
+
+To set up an AlloyDB cluster and instance, follow the [AlloyDB quickstart](https://cloud.google.com/alloydb/docs/quickstart).
+
+## Usage
+
+### Authentication
+
+The `AlloyDBDocumentStore` uses [Secrets](../concepts/secret-management.mdx) and reads connection details from environment variables by default:
+
+- `ALLOYDB_INSTANCE_URI`: the AlloyDB instance URI in the format `projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE`.
+- `ALLOYDB_USER`: the database user. When using IAM database authentication, use the service account email (omitting `.gserviceaccount.com`) or the full IAM user email.
+- `ALLOYDB_PASSWORD`: the database password. Not required when `enable_iam_auth=True`.
+
+```shell
+export ALLOYDB_INSTANCE_URI="projects/MY_PROJECT/locations/MY_REGION/clusters/MY_CLUSTER/instances/MY_INSTANCE"
+export ALLOYDB_USER="my-db-user"
+export ALLOYDB_PASSWORD="my-db-password"
+```
+
+To authenticate with IAM instead of a password, set `enable_iam_auth=True` and grant the IAM principal the AlloyDB Client role. See the [AlloyDB IAM authentication documentation](https://cloud.google.com/alloydb/docs/manage-iam-authn) for details.
+
+## Initialization
+
+Initialize an `AlloyDBDocumentStore` and write Documents to it. Connection to AlloyDB is established lazily on first use, and the table that stores Haystack Documents is created automatically if it doesn't exist:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.alloydb import AlloyDBDocumentStore
+
+document_store = AlloyDBDocumentStore(
+ db="my-database",
+ embedding_dimension=768,
+ vector_function="cosine_similarity",
+ recreate_table=True,
+)
+
+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-alloydb#alloydbdocumentstore).
+
+To compute embeddings for your Documents, you can use a Document Embedder, such as the [`SentenceTransformersDocumentEmbedder`](../pipeline-components/embedders/sentencetransformersdocumentembedder.mdx).
+
+### Search Strategy
+
+The `AlloyDBDocumentStore` supports two search strategies for embedding retrieval:
+
+- `"exact_nearest_neighbor"` (default): provides perfect recall but can be slow on large numbers of documents.
+- `"hnsw"`: an approximate nearest neighbor search strategy that trades off some accuracy for speed. Recommended for large numbers of documents.
+
+When using `"hnsw"`, an index is created based on the `vector_function` you choose, so subsequent queries should keep using the same vector similarity function in order to take advantage of the index. You can tune index creation through `hnsw_index_creation_kwargs` (see the [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw)).
+
+### Metadata Filtering
+
+The `AlloyDBDocumentStore` fully supports comparison operators (`==`, `!=`, `>`, `>=`, `<`, `<=`, `in`, `not in`, `like`, `not like`) and the logical operators `AND` and `OR`. The `like` and `not like` operators are PostgreSQL-specific extensions to the standard Haystack filter syntax and map to the SQL `LIKE` / `NOT LIKE` pattern-matching operators.
+
+The `NOT` logical operator is **not** supported. Because every comparison operator already has a negated counterpart (`==`/`!=`, `in`/`not in`, `like`/`not like`), any filter expressible with `NOT` around a single condition can be rewritten by inverting the comparison operator instead. To negate a nested `AND`/`OR` group, apply De Morgan's laws — for example, `NOT (A AND B)` becomes `(NOT A) OR (NOT B)`, where each `NOT A` / `NOT B` is expressed via the inverted comparison.
+
+For more details on filter syntax, refer to [Metadata Filtering](../concepts/metadata-filtering.mdx).
+
+### Supported Retrievers
+
+- [`AlloyDBEmbeddingRetriever`](../pipeline-components/retrievers/alloydbembeddingretriever.mdx): An embedding-based Retriever that fetches Documents from the Document Store based on a query embedding.
+- [`AlloyDBKeywordRetriever`](../pipeline-components/retrievers/alloydbkeywordretriever.mdx): A keyword-based Retriever that fetches Documents matching a query using PostgreSQL full-text search.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/document-stores/arangodocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/arangodocumentstore.mdx
new file mode 100644
index 00000000000..6ed6630b4d3
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/document-stores/arangodocumentstore.mdx
@@ -0,0 +1,116 @@
+---
+title: "ArangoDocumentStore"
+id: arangodocumentstore
+slug: "/arangodocumentstore"
+description: "Use the ArangoDB multi-model database with Haystack for embedding retrieval and GraphRAG workloads."
+---
+
+# ArangoDocumentStore
+
+Use the ArangoDB multi-model database with Haystack for embedding retrieval and GraphRAG workloads.
+
+
+
+| | |
+| --- | --- |
+| API reference | [ArangoDB](/reference/integrations-arangodb) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/arangodb |
+
+
+
+ArangoDB is a multi-model database that combines documents, graphs, and key-value data in a single engine. The `ArangoDocumentStore` stores documents in an ArangoDB collection and runs vector similarity search using AQL (ArangoDB Query Language) vector functions. Because documents and their relationships live in the same database, ArangoDB is a good fit for GraphRAG pipelines that combine semantic search with graph traversal.
+
+Vector search requires **ArangoDB 3.12 or later** with the vector index feature enabled (the `--vector-index` startup flag).
+
+For more information, see the [ArangoDB documentation](https://docs.arangodb.com/).
+
+## Installation
+
+Run ArangoDB with Docker, enabling the vector index and setting a root password:
+
+```shell
+docker run -d -p 8529:8529 \
+ -e ARANGO_ROOT_PASSWORD=test-password \
+ arangodb:3.12 arangod --vector-index
+```
+
+Install the Haystack integration:
+
+```shell
+pip install arangodb-haystack
+```
+
+## Usage
+
+The store reads its credentials from the `ARANGO_USERNAME` and `ARANGO_PASSWORD` environment variables by default. `ARANGO_USERNAME` falls back to `root` if it is not set, so you typically only need to provide the password:
+
+```shell
+export ARANGO_PASSWORD=test-password
+```
+
+Initialize the document store and write documents:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.arangodb import ArangoDocumentStore
+
+document_store = ArangoDocumentStore(
+ host="http://localhost:8529",
+ database="haystack",
+ collection_name="documents",
+ embedding_dimension=768,
+ recreate_collection=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-arangodb#arangodocumentstore).
+
+To compute real embeddings for your documents, use a Document Embedder such as the [`SentenceTransformersDocumentEmbedder`](../pipeline-components/embedders/sentencetransformersdocumentembedder.mdx). The embedding dimension produced by the embedder must match the `embedding_dimension` configured on the store.
+
+### Authentication
+
+Credentials are passed as Haystack [`Secret`](../concepts/secret-management.mdx) objects. By default they are read from environment variables, but you can also pass them explicitly:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.document_stores.arangodb import ArangoDocumentStore
+
+document_store = ArangoDocumentStore(
+ host="http://localhost:8529",
+ database="haystack",
+ username=Secret.from_env_var("ARANGO_USERNAME", strict=False),
+ password=Secret.from_env_var("ARANGO_PASSWORD"),
+)
+```
+
+### Similarity Functions
+
+`ArangoDocumentStore` supports three similarity functions for vector search, configured at initialization with the `similarity_function` parameter:
+
+- `"cosine"` (default): cosine similarity, best for normalized embeddings.
+- `"dot_product"`: dot product, useful when embedding magnitude carries meaning.
+- `"l2"`: Euclidean (L2) distance.
+
+```python
+document_store = ArangoDocumentStore(
+ host="http://localhost:8529",
+ embedding_dimension=768,
+ similarity_function="dot_product",
+)
+```
+
+### Supported Retrievers
+
+- [`ArangoEmbeddingRetriever`](../pipeline-components/retrievers/arangoembeddingretriever.mdx): Retrieves documents from the `ArangoDocumentStore` based on vector similarity using ArangoDB's AQL vector functions.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/document-stores/arcadedbdocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/arcadedbdocumentstore.mdx
new file mode 100644
index 00000000000..12d251e2705
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/document-stores/arcadedbdocumentstore.mdx
@@ -0,0 +1,75 @@
+---
+title: "ArcadeDBDocumentStore"
+id: arcadedbdocumentstore
+slug: "/arcadedbdocumentstore"
+---
+
+# ArcadeDBDocumentStore
+
+
+
+| | |
+| --- | --- |
+| 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-3.2-unstable/document-stores/astradocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/astradocumentstore.mdx
new file mode 100644
index 00000000000..3292b32590f
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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 API endpoint and a generated token.
+
+You can additionally set a collection name and a namespace. The collection name defaults to `documents`, and you can set the embedding dimensions and the similarity metric alongside it with `embedding_dimension` and `similarity`. 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-3.2-unstable/document-stores/azureaisearchdocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/azureaisearchdocumentstore.mdx
new file mode 100644
index 00000000000..11710d5f9a4
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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:
+
+```shell
+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-3.2-unstable/document-stores/chromadocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/chromadocumentstore.mdx
new file mode 100644
index 00000000000..7f9df6a50a7
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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 two Retriever components. They both 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-3.2-unstable/document-stores/dynamodbdocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/dynamodbdocumentstore.mdx
new file mode 100644
index 00000000000..2ad66b2c2ce
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/document-stores/dynamodbdocumentstore.mdx
@@ -0,0 +1,95 @@
+---
+title: "DynamoDBDocumentStore"
+id: dynamodbdocumentstore
+slug: "/dynamodbdocumentstore"
+---
+
+# DynamoDBDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Amazon DynamoDB](/reference/integrations-dynamodb) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/dynamodb/ |
+
+
+
+[Amazon DynamoDB](https://aws.amazon.com/dynamodb/) is a serverless NoSQL database. Its native vector search stores embeddings in a vector index directly on a table, so documents and their embeddings live next to your operational data without a separate vector database.
+
+`DynamoDBDocumentStore` stores each document as an item in a DynamoDB table with a vector index and retrieves documents through DynamoDB's `SearchVectors` API using cosine similarity. It supports embedding retrieval and metadata filtering.
+
+## Installation
+
+To use DynamoDB with Haystack, install the `dynamodb-haystack` integration:
+
+```shell
+pip install dynamodb-haystack
+```
+
+DynamoDB's vector search requires `boto3 >= 1.43.66`, which the package installs for you. There is no local DynamoDB emulator with vector index support, so you need an AWS account.
+
+## Usage
+
+### Credentials
+
+The Document Store uses the standard AWS credential chain. Set your credentials and region as environment variables:
+
+```shell
+export AWS_ACCESS_KEY_ID=...
+export AWS_SECRET_ACCESS_KEY=...
+export AWS_DEFAULT_REGION=us-east-1
+```
+
+You can also pass them as [Secret](../concepts/secret-management.mdx) arguments (`aws_access_key_id`, `aws_secret_access_key`, `aws_session_token`) or rely on any other boto3 credential source, such as an IAM role.
+
+The credentials need permission for `DescribeTable`, the item-level operations (`PutItem`, `DeleteItem`, `Scan`) and `SearchVectors`. If you let the store create the table, it also needs `CreateTable`.
+
+## Initialization
+
+Initialize a `DynamoDBDocumentStore` object and write documents to it:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.dynamodb import DynamoDBDocumentStore
+
+document_store = DynamoDBDocumentStore(
+ table_name="haystack_documents",
+ index_name="haystack_vector_index",
+ embedding_dimension=768,
+ region_name="us-east-1",
+)
+
+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-dynamodb#dynamodbdocumentstore).
+
+:::note[Table creation]
+
+With `create_table_if_not_exists=True` (the default), the store creates the table and its vector index on first use and waits until the index is queryable, which takes about 20 seconds. The table has a single partition key `id`, and the vector index is declared together with the table because adding a vector index to an existing table triggers a backfill that blocks vector search for several minutes.
+
+If you point the store at an existing table, it must have a single partition key named `id` and a cosine vector index on the `embedding` attribute with matching `index_name` and `embedding_dimension`. The store validates this on first use and raises a `ValueError` on mismatch.
+
+:::
+
+:::info[Limitations]
+
+- `filter_documents`, `count_documents` and the filter-based bulk operations run a consistent full-table `Scan` and evaluate filters client-side, so their cost grows with the table size.
+- `SearchVectors` returns at most 100 candidates per request, so `top_k` cannot exceed 100. Metadata filters are applied to those candidates, so a selective filter can return fewer than `top_k` documents.
+- Only cosine similarity is supported. Scores are converted to Haystack's higher-is-better convention: `1.0` for an identical vector, `0.0` for an opposite one.
+- A DynamoDB item is limited to 400 KB, which bounds a document's content, metadata and embedding together.
+
+:::
+
+To properly compute embeddings for your documents, you can use a Document Embedder (for instance, the [`SentenceTransformersDocumentEmbedder`](../pipeline-components/embedders/sentencetransformersdocumentembedder.mdx)).
+
+### Supported Retrievers
+
+- [`DynamoDBEmbeddingRetriever`](../pipeline-components/retrievers/dynamodbembeddingretriever.mdx): An embedding-based Retriever that fetches documents from the Document Store based on a query embedding.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/document-stores/elasticsearch-document-store.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/elasticsearch-document-store.mdx
new file mode 100644
index 00000000000..9d95d10b9f8
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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.19.7
+docker run -p 9200:9200 -e "discovery.type=single-node" -e "ES_JAVA_OPTS=-Xms1024m -Xmx1024m" -e "xpack.security.enabled=false" docker.elastic.co/elasticsearch/elasticsearch:8.19.7
+```
+
+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-3.2-unstable/document-stores/faissdocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/faissdocumentstore.mdx
new file mode 100644
index 00000000000..fbaf4ba2007
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/document-stores/inmemorydocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/inmemorydocumentstore.mdx
new file mode 100644
index 00000000000..8e69b44e65f
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/document-stores/mariadbdocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/mariadbdocumentstore.mdx
new file mode 100644
index 00000000000..73c469598f4
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/document-stores/mariadbdocumentstore.mdx
@@ -0,0 +1,107 @@
+---
+title: "MariaDBDocumentStore"
+id: mariadbdocumentstore
+slug: "/mariadbdocumentstore"
+---
+
+# MariaDBDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [MariaDB](/reference/integrations-mariadb) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mariadb/ |
+
+
+
+MariaDB 11.7+ introduces a native `VECTOR` datatype with MHNSW indexing, enabling efficient vector similarity search directly in the database without any extensions.
+
+For more information, see the [MariaDB Vector documentation](https://mariadb.com/kb/en/vector/).
+
+MariaDB Document Store supports embedding retrieval, keyword retrieval, and metadata filtering.
+
+## Installation
+
+To quickly set up a MariaDB 11.7 instance, you can use Docker:
+
+```shell
+docker run -d -p 3306:3306 \
+ -e MARIADB_ROOT_PASSWORD=secret \
+ -e MARIADB_DATABASE=haystack \
+ -e MARIADB_USER=haystack \
+ -e MARIADB_PASSWORD=secret \
+ mariadb:11.7
+```
+
+The `mariadb` connector is a C extension built from source, so it needs the MariaDB Connector/C system library (`mariadb_config`):
+
+```shell
+# Ubuntu / Debian
+sudo apt-get install -y libmariadb-dev
+
+# macOS
+brew install mariadb-connector-c
+```
+
+To use MariaDB with Haystack, install the `mariadb-haystack` integration:
+
+```shell
+pip install mariadb-haystack
+```
+
+## Usage
+
+### Credentials
+
+Set the database credentials as environment variables:
+
+```shell
+export MARIADB_USER=haystack
+export MARIADB_PASSWORD=secret
+```
+
+## Initialization
+
+Initialize a `MariaDBDocumentStore` object and write documents to it:
+
+```python
+import os
+from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore
+from haystack import Document
+
+os.environ["MARIADB_USER"] = "haystack"
+os.environ["MARIADB_PASSWORD"] = "secret"
+
+document_store = MariaDBDocumentStore(
+ port=3306,
+ database="haystack",
+ embedding_dimension=768,
+ distance="cosine",
+)
+
+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-mariadb#mariadbdocumentstore).
+
+:::note[Table creation parameters]
+
+The `embedding_dimension`, `distance`, and `create_vector_index` parameters are only applied when the table is first created (or when `recreate_table=True`). Changing them later has no effect on an existing table.
+
+Setting `create_vector_index=True` at table creation enables a MHNSW vector index for fast approximate nearest neighbor search. However, this requires **every document to have a non-null embedding** — documents without embeddings will cause an error on write.
+
+:::
+
+To properly compute embeddings for your documents, you can use a Document Embedder (for instance, the [`SentenceTransformersDocumentEmbedder`](../pipeline-components/embedders/sentencetransformersdocumentembedder.mdx)).
+
+### Supported Retrievers
+
+- [`MariaDBEmbeddingRetriever`](../pipeline-components/retrievers/mariadbembeddingretriever.mdx): An embedding-based Retriever that fetches documents from the Document Store based on a query embedding.
+- [`MariaDBKeywordRetriever`](../pipeline-components/retrievers/mariadbkeywordretriever.mdx): A keyword-based Retriever that fetches documents matching a query using MariaDB's full-text search.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/document-stores/mongodbatlasdocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/mongodbatlasdocumentstore.mdx
new file mode 100644
index 00000000000..7f168be1b1d
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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:
+
+```shell
+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-3.2-unstable/document-stores/oracledocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/oracledocumentstore.mdx
new file mode 100644
index 00000000000..04e325fc775
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/document-stores/oracledocumentstore.mdx
@@ -0,0 +1,196 @@
+---
+title: "OracleDocumentStore"
+id: oracledocumentstore
+slug: "/oracledocumentstore"
+description: "Use Oracle AI Vector Search as a document store in Haystack, with vector similarity and keyword search powered by Oracle Database 23ai."
+---
+
+# OracleDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Oracle](/reference/integrations-oracle) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/oracle |
+
+
+
+`OracleDocumentStore` is a Document Store backed by [Oracle AI Vector Search](https://www.oracle.com/database/ai-vector-search/), available in Oracle Database 23ai and later.
+It stores documents alongside dense vector embeddings in a native `VECTOR` column, and supports both vector similarity search and keyword search via an automatically managed DBMS_SEARCH index.
+
+## Installation
+
+```shell
+pip install oracle-haystack
+```
+
+The examples on this page use Sentence Transformers embedders that have moved to the `sentence-transformers-haystack` package. Install it to run the examples:
+
+```shell
+pip install sentence-transformers-haystack
+```
+
+## Connection
+
+`OracleDocumentStore` connects to Oracle using the `OracleConnectionConfig` dataclass, which supports two connection modes:
+
+- **Thin mode** (default): connects directly over TCP. No Oracle Instant Client required.
+- **Thick mode**: activated automatically when `wallet_location` is provided. Used for Oracle Autonomous Database (ADB-S) connections.
+
+Set the connection parameters as environment variables:
+
+```shell
+export ORACLE_USER="haystack"
+export ORACLE_PASSWORD="secret"
+export ORACLE_DSN="localhost:1521/freepdb1"
+```
+
+## Initialization
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.document_stores.oracle import (
+ OracleDocumentStore,
+ OracleConnectionConfig,
+)
+
+document_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=768,
+)
+```
+
+To learn more about the initialization parameters, see the [API docs](/reference/integrations-oracle#oracledocumentstore).
+
+### Connecting to Oracle Autonomous Database
+
+For Oracle Autonomous Database (ADB-S), provide a wallet for authentication. The store automatically activates thick mode when `wallet_location` is set:
+
+```python
+document_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"),
+ wallet_location="/path/to/wallet",
+ wallet_password=Secret.from_env_var("WALLET_PASSWORD"),
+ ),
+ embedding_dim=1536,
+)
+```
+
+### HNSW Vector Index
+
+By default, the store performs exact vector search. To enable approximate nearest-neighbor search (faster on large datasets), create an HNSW index:
+
+```python
+document_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=768,
+ distance_metric="COSINE",
+ create_index=True, # creates the HNSW index on startup
+ hnsw_neighbors=32,
+ hnsw_ef_construction=200,
+ hnsw_accuracy=95,
+)
+```
+
+## Supported Retrievers
+
+- [`OracleEmbeddingRetriever`](../pipeline-components/retrievers/oracleembeddingretriever.mdx): Retrieves documents from `OracleDocumentStore` based on vector similarity to a query embedding.
+- [`OracleKeywordRetriever`](../pipeline-components/retrievers/oraclekeywordretriever.mdx): Retrieves documents matching a keyword query using Oracle's DBMS_SEARCH full-text index.
+
+## Example: RAG pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.types import DuplicatePolicy
+from haystack_integrations.components.embedders.sentence_transformers import (
+ SentenceTransformersDocumentEmbedder,
+ SentenceTransformersTextEmbedder,
+)
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+from haystack_integrations.document_stores.oracle import (
+ OracleDocumentStore,
+ OracleConnectionConfig,
+)
+from haystack_integrations.components.retrievers.oracle import OracleEmbeddingRetriever
+
+document_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=384,
+)
+
+# Index documents
+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 self-awareness.",
+ ),
+ Document(
+ content="In certain places, you can witness the phenomenon of bioluminescent waves.",
+ ),
+]
+
+doc_embedder = SentenceTransformersDocumentEmbedder(
+ model="sentence-transformers/all-MiniLM-L6-v2",
+)
+embedded_docs = doc_embedder.run(documents)["documents"]
+document_store.write_documents(embedded_docs, policy=DuplicatePolicy.OVERWRITE)
+
+# Build a RAG pipeline
+template = [
+ ChatMessage.from_user(
+ """
+ Given the following context, answer the question.
+ Context: {% for doc in documents %}{{ doc.content }}{% endfor %}
+ Question: {{ query }}
+ """,
+ ),
+]
+
+pipeline = Pipeline()
+pipeline.add_component(
+ "embedder",
+ SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"),
+)
+pipeline.add_component(
+ "retriever",
+ OracleEmbeddingRetriever(document_store=document_store, top_k=3),
+)
+pipeline.add_component("prompt_builder", ChatPromptBuilder(template=template))
+pipeline.add_component(
+ "llm",
+ OpenAIChatGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")),
+)
+
+pipeline.connect("embedder.embedding", "retriever.query_embedding")
+pipeline.connect("retriever.documents", "prompt_builder.documents")
+pipeline.connect("prompt_builder.prompt", "llm.messages")
+
+result = pipeline.run(
+ {
+ "embedder": {"text": "How many languages are there?"},
+ "prompt_builder": {"query": "How many languages are there?"},
+ },
+)
+
+print(result["llm"]["replies"][0].text)
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/document-stores/pgvectordocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/pgvectordocumentstore.mdx
new file mode 100644
index 00000000000..17f8a88cceb
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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 pgvector/pgvector:pg17
+```
+
+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/pgvectorkeywordretriever.mdx): A keyword-based Retriever that fetches documents matching a query from the Pgvector Document Store.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/document-stores/pinecone-document-store.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/pinecone-document-store.mdx
new file mode 100644
index 00000000000..dc67426f82d
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/document-stores/qdrant-document-store.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/qdrant-document-store.mdx
new file mode 100644
index 00000000000..0f8e56fed0e
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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). 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=5, # 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-3.2-unstable/document-stores/solrdocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/solrdocumentstore.mdx
new file mode 100644
index 00000000000..7511dafe9e7
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/document-stores/solrdocumentstore.mdx
@@ -0,0 +1,78 @@
+---
+title: "SolrDocumentStore"
+id: solrdocumentstore
+slug: "/solrdocumentstore"
+description: "A Document Store for storing and retrieval from Apache Solr."
+---
+
+# SolrDocumentStore
+
+A Document Store for storing and retrieval from Apache Solr.
+
+
+
+| | |
+| --- | --- |
+| API reference | [Solr](/reference/integrations-solr) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/solr |
+
+
+
+[Apache Solr](https://solr.apache.org/) is a widely used open source search server built on Apache Lucene. Since Solr 9, it ships a `DenseVectorField` type and the `{!knn}` query parser, so a single Solr core can serve both keyword (BM25) and dense vector retrieval. For more information, see the [Solr documentation](https://solr.apache.org/guide/solr/latest/).
+
+This Document Store is a good fit if your organization already runs Solr and you want to add semantic or hybrid retrieval on top of it without introducing a separate vector database.
+
+The Document Store requires Solr 9.6 or newer. Every operation is available both synchronously and asynchronously.
+
+### Initialization
+
+[Install](https://solr.apache.org/guide/solr/latest/deployment-guide/installing-solr.html) and run a Solr instance. If you have Docker set up, we recommend pulling the Docker image and running it with a precreated core:
+
+```shell
+docker run -d -p 8983:8983 solr:10 solr-precreate haystack
+```
+
+Once you have a running Solr instance, install the `solr-haystack` integration:
+
+```shell
+pip install solr-haystack
+```
+
+Then, initialize a `SolrDocumentStore` object that's connected to the Solr instance and write documents to it:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.solr import SolrDocumentStore
+
+document_store = SolrDocumentStore(
+ url="http://localhost:8983/solr",
+ core="haystack",
+ embedding_dim=768,
+)
+document_store.write_documents(
+ [Document(content="This is first"), Document(content="This is second")],
+)
+print(document_store.count_documents())
+```
+
+By default, the store manages the Solr schema itself: on first use, it creates the fields it needs and disables Solr's schemaless field guessing. Set `manage_schema=False` to manage the schema yourself.
+
+A few points to keep in mind:
+
+- `url` falls back to the `SOLR_URL` environment variable, then to `http://localhost:8983/solr`. Basic authentication credentials are read from the `SOLR_USERNAME` and `SOLR_PASSWORD` environment variables by default, so they never need to appear in code or serialized pipelines.
+- Solr fixes a vector field's dimension when the field is created, so `embedding_dim` cannot be changed for an existing core. The `similarity_function` can be `cosine` (default), `dot_product`, or `euclidean`.
+### Supported Retrievers
+
+[`SolrBM25Retriever`](../pipeline-components/retrievers/solrbm25retriever.mdx): A keyword-based Retriever that fetches documents matching a query from the Document Store.
+
+[`SolrEmbeddingRetriever`](../pipeline-components/retrievers/solrembeddingretriever.mdx): Compares the query and document embeddings and fetches the documents most relevant to the query.
+
+[`SolrHybridRetriever`](../pipeline-components/retrievers/solrhybridretriever.mdx): A SuperComponent that combines BM25 and embedding retrieval in a single component and fuses the results.
+
+### Extended Methods
+
+Beyond the standard Document Store protocol, `SolrDocumentStore` supports filter-based bulk operations and metadata introspection, each with an async twin:
+
+- `delete_by_filter` / `update_by_filter`: delete or update the metadata of all documents matching a filter.
+- `count_documents_by_filter` / `count_unique_metadata_by_filter`: count matching documents or the distinct values of metadata fields.
+- `get_metadata_fields_info`, `get_metadata_field_min_max`, `get_metadata_field_unique_values`: inspect which metadata fields exist, their types, and their value ranges.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/document-stores/supabasedocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/supabasedocumentstore.mdx
new file mode 100644
index 00000000000..bef8d2a8bcc
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/document-stores/supabasedocumentstore.mdx
@@ -0,0 +1,188 @@
+---
+title: "SupabaseDocumentStore"
+id: supabasedocumentstore
+slug: "/supabasedocumentstore"
+description: "Use Supabase as a document store in Haystack, with vector search (pgvector) or full-text search (PGroonga)."
+---
+
+# SupabaseDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Supabase](/reference/integrations-supabase) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/supabase/ |
+
+
+
+[Supabase](https://supabase.com/) is an open-source backend platform built on PostgreSQL. The Supabase integration for Haystack provides two document stores:
+
+- **`SupabasePgvectorDocumentStore`** — vector similarity search using the [pgvector](https://github.com/pgvector/pgvector) PostgreSQL extension, which comes pre-installed on Supabase.
+- **`SupabaseGroongaDocumentStore`** — multilingual full-text search using the [PGroonga](https://pgroonga.github.io/) PostgreSQL extension. No embeddings required.
+
+## Installation
+
+```shell
+pip install supabase-haystack
+```
+
+The examples on this page use Sentence Transformers embedders that have moved to the `sentence-transformers-haystack` package. Install it to run the examples:
+
+```shell
+pip install sentence-transformers-haystack
+```
+
+## SupabasePgvectorDocumentStore
+
+`SupabasePgvectorDocumentStore` is a thin wrapper around [`PgvectorDocumentStore`](./pgvectordocumentstore.mdx) 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
+
+Set the `SUPABASE_DB_URL` environment variable with your Supabase database connection string.
+
+:::tip[Use session mode (port 5432)]
+Supabase offers two pooler ports: transaction mode (port 6543) and session mode (port 5432). For best compatibility with pgvector operations, use session mode or a direct connection.
+:::
+
+```shell
+export SUPABASE_DB_URL="postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres"
+```
+
+### Initialization
+
+```python
+from haystack_integrations.document_stores.supabase import SupabasePgvectorDocumentStore
+
+document_store = SupabasePgvectorDocumentStore(
+ embedding_dimension=768,
+ vector_function="cosine_similarity",
+ recreate_table=True,
+)
+```
+
+To learn more about the initialization parameters, see the [API docs](/reference/integrations-supabase#supabasepgvectordocumentstore).
+
+### Supported Retrievers
+
+- [`SupabasePgvectorEmbeddingRetriever`](../pipeline-components/retrievers/supabasepgvectorembeddingretriever.mdx): Fetches documents from the store based on a query embedding.
+- [`SupabasePgvectorKeywordRetriever`](../pipeline-components/retrievers/supabasepgvectorkeywordretriever.mdx): Fetches documents matching a keyword query using PostgreSQL's `ts_rank_cd` ranking.
+
+### Example: RAG pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.types.policy import DuplicatePolicy
+from haystack_integrations.components.embedders.sentence_transformers import (
+ SentenceTransformersTextEmbedder,
+ SentenceTransformersDocumentEmbedder,
+)
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+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,
+)
+
+# Index documents
+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 self-awareness.",
+ ),
+ Document(
+ content="In certain places, you can witness the phenomenon of bioluminescent waves.",
+ ),
+]
+embedder = SentenceTransformersDocumentEmbedder()
+documents_with_embeddings = embedder.run(documents)
+document_store.write_documents(
+ documents_with_embeddings["documents"],
+ policy=DuplicatePolicy.OVERWRITE,
+)
+
+# Query pipeline
+prompt_template = [
+ ChatMessage.from_system("Answer the question based on the provided context."),
+ ChatMessage.from_user(
+ "Query: {{query}}\nDocuments:\n{% for doc in documents %}{{ doc.content }}\n{% endfor %}\nAnswer:",
+ ),
+]
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component(
+ "retriever",
+ SupabasePgvectorEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.add_component(
+ "prompt_builder",
+ ChatPromptBuilder(
+ template=prompt_template,
+ required_variables=["query", "documents"],
+ ),
+)
+query_pipeline.add_component("generator", OpenAIChatGenerator(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.prompt", "generator.messages")
+
+result = query_pipeline.run(
+ {
+ "text_embedder": {"text": "How many languages are there?"},
+ "prompt_builder": {"query": "How many languages are there?"},
+ },
+)
+```
+
+---
+
+## SupabaseGroongaDocumentStore
+
+`SupabaseGroongaDocumentStore` uses [PGroonga](https://pgroonga.github.io/), a PostgreSQL extension for fast, multilingual full-text search. Unlike the pgvector store, it works with plain text queries and requires no embeddings.
+
+### Prerequisites
+
+PGroonga must be enabled in your Supabase project. Run the following SQL in the Supabase SQL editor:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS pgroonga;
+```
+
+You also need to create a SQL function that PGroonga uses for search. See the [integration README](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/supabase/) for the required function definition.
+
+### Initialization
+
+```python
+from haystack_integrations.document_stores.supabase import SupabaseGroongaDocumentStore
+from haystack.utils import Secret
+
+document_store = SupabaseGroongaDocumentStore(
+ supabase_url="https://
+
+| | |
+| --- | --- |
+| 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
+```
+
+The examples on this page use Sentence Transformers embedders that have moved to the `sentence-transformers-haystack` package. Install it to run the examples:
+
+```shell
+pip install sentence-transformers-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_integrations.components.embedders.sentence_transformers 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_integrations.components.embedders.sentence_transformers 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.prompt", "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-3.2-unstable/document-stores/vespadocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/vespadocumentstore.mdx
new file mode 100644
index 00000000000..8955a65dd59
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/document-stores/vespadocumentstore.mdx
@@ -0,0 +1,115 @@
+---
+title: "VespaDocumentStore"
+id: vespadocumentstore
+slug: "/vespadocumentstore"
+---
+
+# VespaDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Vespa](/reference/integrations-vespa) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/vespa |
+
+
+
+[Vespa](https://vespa.ai/) is an open-source big data serving engine that supports structured, text, and vector search at scale. The `VespaDocumentStore` connects Haystack to an existing Vespa application through [pyvespa](https://vespa-engine.github.io/pyvespa/) and supports both lexical and dense vector retrieval as well as metadata filtering.
+
+Unlike most other Haystack Document Stores, the `VespaDocumentStore` does **not** create or deploy the Vespa application or schema for you. You configure Vespa with the fields and rank profiles you need, deploy it (either self-hosted or on [Vespa Cloud](https://cloud.vespa.ai/)), and then point the Document Store at the running endpoint.
+
+## Installation
+
+Install the `vespa-haystack` integration:
+
+```shell
+pip install vespa-haystack
+```
+
+To run Vespa locally, see the [Vespa quick start](https://docs.vespa.ai/en/vespa-quick-start.html). To deploy a managed Vespa application, see [Vespa Cloud](https://cloud.vespa.ai/en/getting-started).
+
+## Usage
+
+### Prerequisites: Vespa Schema
+
+Before using the `VespaDocumentStore`, you need a deployed Vespa application with a schema compatible with the fields you configure on the Document Store. By default, the integration expects:
+
+- A text field named `content` for the Document body.
+- A tensor field named `embedding` for dense vectors (when using embedding retrieval).
+- A rank profile named `bm25` for lexical retrieval (used by `VespaKeywordRetriever`).
+- A rank profile named `semantic` that ranks with `closeness(field, embedding)` (used by `VespaEmbeddingRetriever`).
+
+Field and rank profile names can be customized via the Document Store and Retriever constructors. See the [Vespa documentation](https://docs.vespa.ai/en/schemas.html) for details on writing schemas and rank profiles.
+
+### Authentication
+
+The `VespaDocumentStore` supports the authentication methods provided by `pyvespa`:
+
+- **No authentication** for local development against an unsecured Vespa endpoint.
+- **mTLS** with a data plane certificate and key (via the `cert` and `key` parameters as [Secrets](../concepts/secret-management.mdx)).
+- **Bearer token** for Vespa Cloud token endpoints (via `vespa_cloud_secret_token` or the `VESPA_CLOUD_SECRET_TOKEN` environment variable).
+
+The Vespa endpoint URL can be passed via the `url` parameter or the `VESPA_URL` environment variable:
+
+```shell
+export VESPA_URL="http://localhost"
+```
+
+For Vespa Cloud token authentication:
+
+```shell
+export VESPA_URL="https://my-app.my-tenant.aws-us-east-1c.z.vespa-app.cloud"
+export VESPA_CLOUD_SECRET_TOKEN="my-secret-token"
+```
+
+## Initialization
+
+Point the `VespaDocumentStore` at your deployed Vespa application and write Documents to it. The HTTP client is created lazily on first use:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.vespa import VespaDocumentStore
+
+document_store = VespaDocumentStore(
+ url="http://localhost",
+ schema="doc",
+ namespace="doc",
+ content_field="content",
+ embedding_field="embedding",
+ metadata_fields=["category"],
+)
+
+document_store.write_documents(
+ [
+ Document(
+ content="Haystack integrates with Vespa for search.",
+ meta={"category": "docs"},
+ ),
+ Document(
+ content="Vespa supports lexical and vector retrieval.",
+ meta={"category": "docs"},
+ ),
+ ],
+)
+print(document_store.count_documents())
+```
+
+To learn more about the initialization parameters, see our [API docs](/reference/integrations-vespa#vespadocumentstore).
+
+To compute embeddings for your Documents, you can use a Document Embedder, such as the [`SentenceTransformersDocumentEmbedder`](../pipeline-components/embedders/sentencetransformersdocumentembedder.mdx).
+
+### Metadata Fields
+
+Vespa is strictly schema-bound: every metadata field that you want to feed or read back from Vespa must exist as a field in the deployed schema. Use the `metadata_fields` parameter to declare an allowlist of metadata keys to send to Vespa on write and to request back on read. Metadata keys that are not in this allowlist are kept on Documents in memory but are not stored in Vespa.
+
+### Metadata Filtering
+
+The `VespaDocumentStore` supports comparison operators (`==`, `!=`, `>`, `>=`, `<`, `<=`, `in`, `not in`) and the logical operators `AND`, `OR`, and `NOT`. Filters are translated to Vespa's [YQL](https://docs.vespa.ai/en/query-language.html) where clauses whenever possible.
+
+Filters on date-typed values are evaluated client-side in Python when YQL cannot express the comparison directly. For more details on filter syntax, refer to [Metadata Filtering](../concepts/metadata-filtering.mdx).
+
+### Supported Retrievers
+
+- [`VespaEmbeddingRetriever`](../pipeline-components/retrievers/vespaembeddingretriever.mdx): A dense embedding-based Retriever that fetches Documents from Vespa using nearest-neighbor search and a configurable rank profile.
+- [`VespaKeywordRetriever`](../pipeline-components/retrievers/vespakeywordretriever.mdx): A lexical Retriever that fetches Documents from Vespa using a configurable rank profile (BM25 by default).
diff --git a/docs-website/versioned_docs/version-3.2-unstable/document-stores/weaviatedocumentstore.mdx b/docs-website/versioned_docs/version-3.2-unstable/document-stores/weaviatedocumentstore.mdx
new file mode 100644
index 00000000000..04cfd1586b7
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/document-stores/weaviatedocumentstore.mdx
@@ -0,0 +1,154 @@
+---
+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
+---
+services:
+ weaviate:
+ command:
+ - --host
+ - 0.0.0.0
+ - --port
+ - '8080'
+ - --scheme
+ - http
+ image: semitechnologies/weaviate:1.36.2
+ 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-3.2-unstable/intro.mdx b/docs-website/versioned_docs/version-3.2-unstable/intro.mdx
new file mode 100644
index 00000000000..7d46841cb9b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/memory-stores/cogneememorystore.mdx b/docs-website/versioned_docs/version-3.2-unstable/memory-stores/cogneememorystore.mdx
new file mode 100644
index 00000000000..b036758a9b6
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/memory-stores/cogneememorystore.mdx
@@ -0,0 +1,126 @@
+---
+title: "CogneeMemoryStore"
+id: cogneememorystore
+slug: "/cogneememorystore"
+description: "A persistent memory store backed by Cognee's knowledge graph API."
+---
+
+# CogneeMemoryStore
+
+`CogneeMemoryStore` is a persistent memory store backed by Cognee's knowledge graph API. It is the shared data layer used by [`CogneeRetriever`](../pipeline-components/retrievers/cogneeretriever.mdx) and [`CogneeWriter`](../pipeline-components/writers/cogneewriter.mdx).
+
+
+
+| | |
+| --- | --- |
+| **Used by** | [`CogneeRetriever`](../pipeline-components/retrievers/cogneeretriever.mdx), [`CogneeWriter`](../pipeline-components/writers/cogneewriter.mdx) |
+| **Optional init variables** | `search_type`, `top_k`, `dataset_name`, `session_id`, `self_improvement`, `timeout` |
+| **API reference** | [Cognee](/reference/integrations-cognee#cogneememorystore) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cognee |
+| **Package name** | `cognee-haystack` |
+
+
+
+## Overview
+
+`CogneeMemoryStore` wraps Cognee's V2 memory API:
+
+- `add_memories` → `cognee.remember`
+- `search_memories` → `cognee.recall`
+- `improve` → `cognee.improve`
+- `delete_all_memories` → `cognee.forget`
+
+Cognee supports two memory tiers. Set `session_id` to use the **session cache** — fast writes with no LLM extraction, session-aware recall. Leave `session_id` as `None` to write to the **permanent knowledge graph**, which uses LLM extraction during ingestion and supports richer graph-completion queries.
+
+Cognee configuration (LLM provider, database, vector store) is read from environment variables. See the [Cognee documentation](https://docs.cognee.ai) for setup instructions.
+
+### Parameters
+
+- `search_type` is *optional* and defaults to `"GRAPH_COMPLETION"`. Controls which Cognee recall strategy is used. Other useful values include `"CHUNKS"` for raw retrieval and `"SUMMARIES"` for summarized graph nodes.
+- `top_k` is *optional* and defaults to `5`. Sets the default maximum number of memories returned per search.
+- `dataset_name` is *optional* and defaults to `"haystack_memory"`. Names the Cognee dataset backing this store.
+- `session_id` is *optional* and defaults to `None`. When set, reads and writes target the session-cache tier. When `None`, the permanent knowledge graph is used.
+- `self_improvement` is *optional* and defaults to `True`. When `True`, Cognee runs graph improvement inline after every write. Set to `False` when you want `improve()` to be the sole improvement trigger.
+- `timeout` is *optional* and defaults to `300`. Per-call timeout in seconds for any Cognee operation.
+
+### Installation
+
+Install the Cognee integration:
+
+```bash
+pip install cognee-haystack
+```
+
+Set your LLM API key (used by Cognee for graph extraction and queries):
+
+```bash
+export LLM_API_KEY="your-llm-api-key"
+```
+
+Optionally, set a separate embedding API key (defaults to `LLM_API_KEY` when unset):
+
+```bash
+export EMBEDDING_API_KEY="your-embedding-api-key"
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.memory_stores.cognee import CogneeMemoryStore
+
+store = CogneeMemoryStore(search_type="GRAPH_COMPLETION", top_k=5)
+
+store.add_memories(
+ messages=[ChatMessage.from_user("Alice enjoys hiking and outdoor activities.")],
+ user_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+)
+
+memories = store.search_memories(
+ query="What does Alice like?",
+ user_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+)
+print([msg.text for msg in memories])
+```
+
+### Session tier vs permanent graph
+
+Use `session_id` to control which memory tier is targeted. A single store can serve both tiers — the writer's `session_id` overrides the store's `session_id` per call.
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.memory_stores.cognee import CogneeMemoryStore
+
+store = CogneeMemoryStore(dataset_name="my_agent_memory", self_improvement=False)
+
+# Write long-lived facts to the permanent graph (no session_id).
+store.add_memories(
+ messages=[ChatMessage.from_user("Alice is a senior data scientist at Acme Corp.")],
+)
+
+# Write transient session context to the session cache.
+store.add_memories(
+ messages=[
+ ChatMessage.from_user("Alice is currently debugging a vector store issue.")
+ ],
+ session_id="alice_session_1",
+)
+
+# Promote the session cache into the permanent graph.
+store.improve(session_id="alice_session_1")
+```
+
+### Delete all memories
+
+```python
+# Delete only this store's dataset (session cache is unaffected).
+store.delete_all_memories()
+
+# To wipe everything including the session cache, call cognee directly:
+import asyncio
+import cognee
+
+asyncio.run(cognee.forget(everything=True))
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/memory-stores/mem0memorystore.mdx b/docs-website/versioned_docs/version-3.2-unstable/memory-stores/mem0memorystore.mdx
new file mode 100644
index 00000000000..ce0537e0b4c
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/memory-stores/mem0memorystore.mdx
@@ -0,0 +1,105 @@
+---
+title: "Mem0MemoryStore"
+id: mem0memorystore
+slug: "/mem0memorystore"
+description: "A memory store backed by the Mem0 cloud API."
+---
+
+# Mem0MemoryStore
+
+`Mem0MemoryStore` is a memory store backed by the Mem0 cloud API. It is the shared data layer used by [`Mem0MemoryRetriever`](../pipeline-components/retrievers/mem0memoryretriever.mdx), [`Mem0MemoryWriter`](../pipeline-components/writers/mem0memorywriter.mdx), and the [Mem0 Memory Tools](../tools/ready-made-tools/mem0memorytools.mdx).
+
+
+
+| | |
+| --- | --- |
+| **Used by** | [`Mem0MemoryRetriever`](../pipeline-components/retrievers/mem0memoryretriever.mdx), [`Mem0MemoryWriter`](../pipeline-components/writers/mem0memorywriter.mdx), [`Mem0MemoryRetrieverTool`, `Mem0MemoryWriterTool`](../tools/ready-made-tools/mem0memorytools.mdx) |
+| **Optional init variables** | `api_key`: Defaults to `MEM0_API_KEY` environment variable |
+| **API reference** | [Mem0](/reference/integrations-mem0#mem0memorystore) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mem0 |
+| **Package name** | `mem0-haystack` |
+
+
+
+## Overview
+
+`Mem0MemoryStore` wraps the Mem0 cloud API and provides two core methods:
+
+- `add_memories` — stores a list of `ChatMessage` objects as memories in Mem0.
+- `search_memories` — retrieves memories from Mem0 that are relevant to a query.
+
+Scope memories with at least one Mem0 entity ID: `user_id`, `run_id`, `agent_id`, or `app_id`. These are runtime parameters, so a single store instance can serve multiple users or sessions.
+
+The `infer` parameter on `add_memories` controls how Mem0 processes incoming messages:
+
+- `infer=True` lets Mem0 extract memories from the messages automatically. This is useful when storing a full Agent turn.
+- `infer=False` stores the supplied message text as-is. This is useful when the exact memory text has already been selected upstream.
+
+### Installation
+
+Install the Mem0 integration:
+
+```bash
+pip install mem0-haystack
+```
+
+Set your Mem0 API key:
+
+```bash
+export MEM0_API_KEY="your-mem0-api-key"
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+
+store = Mem0MemoryStore()
+
+store.add_memories(
+ messages=[ChatMessage.from_user("Alice prefers concise Python examples.")],
+ user_id="alice",
+ infer=False,
+)
+
+memories = store.search_memories(
+ query="What does Alice prefer?",
+ user_id="alice",
+ top_k=3,
+)
+print([msg.text for msg in memories])
+```
+
+### Scoping with multiple entity IDs
+
+Mem0 supports narrowing the scope of reads and writes with `user_id`, `run_id`, `agent_id`, and `app_id`. Pass any combination at call time:
+
+```python
+store.add_memories(
+ messages=[
+ ChatMessage.from_user("Alice is working on a documentation search system.")
+ ],
+ user_id="alice",
+ run_id="docs-assistant-session-1",
+ infer=True,
+)
+
+memories = store.search_memories(
+ query="What project is Alice working on?",
+ user_id="alice",
+ run_id="docs-assistant-session-1",
+)
+print([msg.text for msg in memories])
+```
+
+### Retrieving all memories in scope
+
+Pass `query=None` to return all memories matching the provided scope without a relevance search:
+
+```python
+all_memories = store.search_memories(query=None, user_id="alice")
+print([msg.text for msg in all_memories])
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/optimization/advanced-rag-techniques.mdx b/docs-website/versioned_docs/version-3.2-unstable/optimization/advanced-rag-techniques.mdx
new file mode 100644
index 00000000000..4f4adcaf891
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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 RAG 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-3.2-unstable/optimization/advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx b/docs-website/versioned_docs/version-3.2-unstable/optimization/advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx
new file mode 100644
index 00000000000..9f442af74b0
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/optimization/advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx
@@ -0,0 +1,125 @@
+---
+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.
+
+
+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**
+
+The frameworks connect tools to the LLM differently. In Haystack, you only initialize the `ChatGenerator` component here: the tools are passed to the `Agent` in Step 3, which forwards them to the LLM. 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: Assemble the agent**
+
+This is where the frameworks diverge most. In Haystack, you create the `Agent` component from the chat generator and tools - the agentic loop is built in. The Agent accumulates the conversation (LLM replies and tool results) internally, executes the tool calls prepared by the LLM, and iterates until an exit condition is met. The default `exit_conditions=["text"]` stops the loop as soon as the LLM replies without tool calls; tool names can also be used to exit after a specific tool runs.
+
+In LangGraph, you build the loop explicitly: a node function (`llm_call`) that invokes the LLM on the accumulated `MessagesState`, a node function (`tool_node`) that executes tool calls and wraps the results in `ToolMessage` objects, and a conditional edge function (`should_continue`) that decides whether to continue the loop or finish. You then wire nodes and edges together in a `StateGraph` and compile the graph into an executable agent.
+
+
+ {`from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+
+# Initialize the LLM; the tools are passed to the Agent in Step 3
+tools = [add, multiply, divide]
+model = AnthropicChatGenerator(
+ model="claude-sonnet-4-5-20250929",
+ generation_kwargs={"temperature": 0},
+)`}
+
+
+ {`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: Run the agent**
+
+Finally, we execute the agent with a user message. Haystack calls `.run()` on the Agent with initial messages, while LangGraph calls `.invoke()` on the compiled agent. Both return the conversation history.
+
+
+ {`from haystack.components.agents import Agent
+
+# Create the agent - the agentic loop (LLM calls,
+# tool execution, iteration) is built in
+agent = Agent(
+ chat_generator=model,
+ tools=tools,
+ system_prompt="You are a helpful assistant tasked with performing arithmetic on a set of inputs.",
+ exit_conditions=["text"], # default
+)`}
+
+
+ {`from typing import Literal
+from langgraph.graph import MessagesState, StateGraph, START, END
+from langchain.messages import SystemMessage, ToolMessage
+
+# Node: the LLM decides whether to call a tool or not
+def llm_call(state: MessagesState):
+ return {
+ "messages": [
+ llm_with_tools.invoke(
+ [
+ SystemMessage(
+ content="You are a helpful assistant tasked with performing arithmetic on a set of inputs."
+ )
+ ]
+ + state["messages"]
+ )
+ ]
+ }
+
+# Node: performs the tool calls
+def tool_node(state: dict):
+ 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}
+
+# Conditional edge: 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]:
+ last_message = state["messages"][-1]
+ if last_message.tool_calls:
+ return "tool_node"
+ return END
+
+# 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 stepped through the agent loop piece by piece. In Haystack, the high-level `Agent` class 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. Here are the complete examples side by side:
+
+
+ {`from haystack.dataclasses import ChatMessage
+
+# Run the agent
+result = agent.run(messages=[
+ ChatMessage.from_user(text="Add 3 and 4.")
+])
+print(result["last_message"].text)`}
+
+
+ {`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-haystack
+
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.sentence_transformers 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_integrations.components.embedders.sentence_transformers 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-3.2-unstable/overview/migration.mdx b/docs-website/versioned_docs/version-3.2-unstable/overview/migration.mdx
new file mode 100644
index 00000000000..797e6333de0
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/overview/migration.mdx
@@ -0,0 +1,329 @@
+---
+title: "Migration Guide"
+id: migration
+slug: "/migration"
+description: "Learn how to make the move to Haystack 3.x from Haystack 2.x."
+---
+
+# Migration Guide
+
+Learn how to make the move to Haystack 3.x from Haystack 2.x.
+
+This guide is designed for those with previous experience with Haystack 2.x who want to upgrade to Haystack 3.x. It walks through every breaking change and shows how to adapt your code. If you're new to Haystack, skip this page and proceed directly to the [Get Started](get-started.mdx) guide.
+
+Haystack 3.x is an evolution of Haystack 2.x, not a rewrite: components, pipelines, and the `Agent` work as before. Most applications only need import updates and small, mechanical changes. The complete list of breaking changes with extended examples is maintained in [MIGRATION.md](https://github.com/deepset-ai/haystack/blob/main/MIGRATION.md) in the Haystack repository.
+
+:::tip[Migrate with a coding agent]
+Want help migrating with a coding agent? [Fill out this form](https://landing.deepset.ai/haystack-v3-migration-skill) to get access to the Haystack v3 migration skill.
+:::
+
+## Update Your Installation
+
+The package name is unchanged:
+
+```bash
+pip install --upgrade haystack-ai
+```
+
+Two dependency changes to be aware of:
+
+- **`haystack-experimental` is no longer installed automatically.** The package is now archived and unmaintained: `0.19.0.post1` is its final release. If your code still imports from `haystack_experimental`, install it explicitly and pin it with `pip install "haystack-experimental==0.19.0.post1"`. Most experiments graduated into `haystack-ai` itself, so prefer migrating your imports to the core equivalents.
+- **Several components moved to dedicated integration packages** and now require an extra `pip install`. See [Components Moved to Integration Packages](#components-moved-to-integration-packages) below.
+
+## Removed and Renamed Components
+
+### Legacy Generators removed
+
+`OpenAIGenerator`, `AzureOpenAIGenerator`, `HuggingFaceAPIGenerator`, and `HuggingFaceLocalGenerator` have been removed. Their chat counterparts are the replacement: `OpenAIChatGenerator` and `AzureOpenAIChatGenerator` in Haystack core, `HuggingFaceAPIChatGenerator` in the `huggingface-api-haystack` integration, and `TransformersChatGenerator` (the renamed `HuggingFaceLocalChatGenerator`) in the `transformers-haystack` integration (see [Components Moved to Integration Packages](#components-moved-to-integration-packages)). All [ChatGenerators](../pipeline-components/generators.mdx) now also accept a plain `str` as input, so simple text-in/text-out use cases rarely require structural changes.
+
+Before (v2.x):
+
+```python
+from haystack.components.generators import OpenAIGenerator
+
+gen = OpenAIGenerator()
+result = gen.run("What is NLP?")
+text = result["replies"][0] # str
+meta = result["meta"][0] # dict with model metadata
+```
+
+After (v3.0):
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+gen = OpenAIChatGenerator()
+result = gen.run("What is NLP?") # str input accepted directly
+reply = result["replies"][0] # ChatMessage
+text = reply.text # str
+meta = reply.meta # dict with model metadata (now on the message)
+```
+
+Pipelines that connected a `PromptBuilder` (output: `str`) to a legacy Generator keep working unchanged when you swap in a ChatGenerator: the pipeline type system automatically converts `str` to `list[ChatMessage]` at the connection edge. Two follow-up points:
+
+- The legacy Generators' separate `meta` output socket is gone. Remove any `pipeline.connect("llm.meta", ...)` calls; per-reply metadata now lives in each `ChatMessage.meta`, and `AnswerBuilder` reads it from there automatically.
+- To set a system prompt, prepend `ChatMessage.from_system(...)` to the messages instead of using the removed `system_prompt` init parameter.
+
+### `ToolInvoker` removed
+
+Tool execution is now owned by the [`Agent`](../pipeline-components/agents-1/agent.mdx) component. Instead of wiring a ChatGenerator to a `ToolInvoker`, pass the tools to an `Agent`: it forwards the tool definitions to the chat generator, executes requested tool calls, appends tool results to the conversation, and loops until an exit condition is reached.
+
+Before (v2.x):
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.tools import ToolInvoker
+from haystack.dataclasses import ChatMessage
+
+chat_generator = OpenAIChatGenerator(tools=[weather])
+tool_invoker = ToolInvoker(tools=[weather])
+
+llm_result = chat_generator.run(
+ messages=[ChatMessage.from_user("What is the weather in Berlin?")],
+)
+tool_result = tool_invoker.run(messages=llm_result["replies"])
+```
+
+After (v3.0):
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+agent = Agent(chat_generator=OpenAIChatGenerator(), tools=[weather])
+result = agent.run(messages=[ChatMessage.from_user("What is the weather in Berlin?")])
+```
+
+The `tool_invoker_kwargs` parameter is gone from `Agent`; the relevant options are now top-level constructor parameters:
+
+- `max_workers` → `tool_concurrency_limit`
+- `enable_streaming_callback_passthrough` → `tool_streaming_callback_passthrough`
+- `convert_result_to_json_string` has been removed: non-string tool results are now always serialized with `json.dumps`.
+
+If you need to execute a prepared tool call outside an `Agent`, call `Tool.invoke` directly and send the result back to the model as a `ChatMessage.from_tool` message.
+
+### Other removals and renames
+
+| v2.x | v3.0 replacement |
+| --- | --- |
+| `TransformersSimilarityRanker` | `SentenceTransformersSimilarityRanker` (accepts the same parameters, adds async support) |
+| `DALLEImageGenerator` | [`OpenAIImageGenerator`](../pipeline-components/generators/openaiimagegenerator.mdx) (same API; renamed after OpenAI retired the DALL-E family) |
+| `AsyncPipeline` | `Pipeline` (see [Pipeline changes](#asyncpipeline-merged-into-pipeline)) |
+
+## Components Moved to Integration Packages
+
+Some components moved out of Haystack core into dedicated integration packages hosted in the [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations) repository. This keeps the core lean and lets fixes ship independently of the Haystack release cycle.
+
+To migrate, install the new package (`pip install
+ {`# 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())`}
+
+
+
+| | |
+| --- | --- |
+| **API reference** | Agent Pack |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/agent_pack |
+| **Package name** | `agent-pack-haystack` |
+
+
+
+## Overview
+
+Language Models and Tools are the core building blocks of agents.
+
+However, building a robust agent often requires more: an architecture that splits the work across sub-agents, techniques for keeping context small but focused, and ways to influence and interact with the agent loop.
+
+Agent Pack combines these techniques into working agents. Each one is a complete architecture built from Haystack primitives ([`Agent`](./agent.mdx), [Tools](../../tools/tool.mdx), [hooks](./hooks.mdx), [`State`](./state.mdx), and Pipelines), exposed behind a single `create_*` entry point.
+
+There are three ways to use an agent from the pack:
+- **Run it as is.** Each agent has a factory that builds a ready-to-run agent with defaults chosen to work out of the box. For example, `create_deep_research_agent()` returns an agent that takes a question and produces a report.
+- **Customize it.** Each entry point exposes a set of parameters for the choices specific to that agent, such as which LLMs to use. For everything else, such as adding tools or hooks, use [`clone()`](./agent.mdx#cloning-and-modifying-an-agent) on the returned agent.
+- **Copy it.** Read the implementation and take inspiration for your agents. These agents are built with this use case in mind, so individual parts should be easy to adapt.
+
+In other words, you can use the agents in Agent Pack as either ready-made solutions or reference architectures.
+
+## Installation
+
+```shell
+pip install agent-pack-haystack
+```
+
+Each agent has its own additional runtime dependencies and may require API keys. See its documentation page for these details.
+
+## Available agents
+
+| Agent | Description |
+| --- | --- |
+| [Deep Research Agent](agent-pack/deep-research-agent.mdx) | Researches a question on the web and produces a structured Markdown report with citations. |
+| [Advanced RAG Agent](agent-pack/advanced-rag-agent.mdx) | Inspects document-store metadata and builds Haystack filters to retrieve precisely, then answers with citations. |
+
+## Experimental
+
+:::warning
+Agent Pack is experimental for the moment. Its APIs and agent architectures can change in any release, without following the usual deprecation policy.
+:::
+
+Agent Pack is distributed separately from `haystack-ai` and its code lives in `haystack-core-integrations`.
+
+Agentic architectures are evolving fast. Keeping it outside `haystack-ai` allows us to improve these agents rapidly, release updates independently, and avoid committing to stability before these patterns have settled.
+
+Developing complex agents also helps us identify missing capabilities in Haystack. When a gap shows up, we can implement it in the pack first, and then, if it turns out to be generally useful, refine it and move it into Haystack.
+
+## Feedback
+
+If you find a bug or have an idea for a complex agent that could belong in the pack, [open an issue](https://github.com/deepset-ai/haystack-core-integrations/issues).
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/agent-pack/advanced-rag-agent.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/agent-pack/advanced-rag-agent.mdx
new file mode 100644
index 00000000000..d9b8952a2ea
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/agent-pack/advanced-rag-agent.mdx
@@ -0,0 +1,238 @@
+---
+title: "Advanced RAG Agent"
+id: advanced-rag-agent
+slug: "/advanced-rag-agent"
+description: "A metadata-aware RAG agent: it inspects the document store and can construct Haystack filters to narrow its retrieval."
+---
+
+# Advanced RAG Agent
+
+A metadata-aware RAG agent: instead of guessing which metadata fields exist, it inspects the document store (fields, values, ranges) and can construct Haystack filters to narrow its retrieval.
+
+
+
+| | |
+| --- | --- |
+| **Mandatory init variables** | `document_store`: The document store to inspect and fetch from
`retriever`: A relevance-scoring retriever or retrieval `Pipeline` | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../../concepts/data-classes/chatmessage.mdx)s | +| **Output variables** | `last_message`: The answer, citing documents as `[doc]`
`documents`: Every document the agent retrieved, deduplicated | +| **API reference** | [Agent Pack](/reference/integrations-agent-pack) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/agent_pack/src/haystack_integrations/agent_pack/advanced_rag | +| **Package name** | `agent-pack-haystack` | + +
+
+:::warning
+Part of [Agent Pack](../agent-pack.mdx), which is experimental for the moment. Its APIs and agent architectures can change in any release, without following the usual deprecation policy.
+:::
+
+## When to use this agent
+
+Use the advanced RAG agent when:
+
+- You have a large, heterogeneous corpus (many topics, sources, or document types mixed together) with well-structured metadata. The agent uses that metadata to narrow retrieval, making results more precise than relevance ranking alone.
+- You need to retrieve exact or complete subsets of documents by metadata ("all pages of this file", "everything from source X"), not just the most relevant matches.
+
+It's less useful when:
+
+- There's no metadata, or the metadata isn't useful for narrowing retrieval.
+- The corpus is small and homogeneous, so plain top-k retrieval already returns the right documents.
+
+## Installation
+
+```shell
+pip install agent-pack-haystack arrow
+```
+
+`arrow` (required with the default system prompt) renders today's date so the agent can build filters for relative dates like "the last 5 years".
+
+Set `OPENAI_API_KEY` in the environment.
+
+## Usage
+
+Index a corpus with varied metadata and ask a question the agent can only answer well by inspecting the metadata, building a filter, and retrieving with it:
+
+```python
+from haystack import Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.agent_pack import create_advanced_rag_agent
+
+document_store = InMemoryDocumentStore()
+document_store.write_documents(
+ [
+ Document(
+ content="CRISPR gene editing corrected a hereditary blindness mutation in a clinical trial.",
+ meta={"category": "science", "year": 2021, "rating": 4.6},
+ ),
+ Document(
+ content="A quantum computer demonstrated error-corrected logical qubits.",
+ meta={"category": "science", "year": 2023, "rating": 4.8},
+ ),
+ Document(
+ content="Dolly the sheep became the first mammal cloned from an adult somatic cell.",
+ meta={"category": "science", "year": 1996, "rating": 4.2},
+ ),
+ Document(
+ content="The Berlin Wall fell, a decisive moment in the end of the Cold War.",
+ meta={"category": "history", "year": 1989, "rating": 4.7},
+ ),
+ Document(
+ content="Argentina won the FIFA World Cup final against France on penalties.",
+ meta={"category": "sports", "year": 2022, "rating": 4.9},
+ ),
+ ],
+)
+
+agent = create_advanced_rag_agent(
+ document_store=document_store,
+ retriever=InMemoryBM25Retriever(document_store=document_store, top_k=5),
+)
+
+result = agent.run(
+ messages=[ChatMessage.from_user("What science advances happened after 2015?")],
+)
+
+print(result["last_message"].text) # the answer, citing documents as [doc `retriever`: A relevance-scoring retriever or retrieval `Pipeline` | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../../concepts/data-classes/chatmessage.mdx)s | +| **Output variables** | `last_message`: The answer, citing documents as `[doc
`documents`: Every document the agent retrieved, deduplicated | +| **API reference** | [Agent Pack](/reference/integrations-agent-pack) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/agent_pack/src/haystack_integrations/agent_pack/advanced_rag | +| **Package name** | `agent-pack-haystack` | + +
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../../concepts/data-classes/chatmessage.mdx)s |
+| **Output variables** | `report`: The final cited Markdown report
`brief`, `notes`: The intermediate research brief and collected summaries | +| **API reference** | [Agent Pack](/reference/integrations-agent-pack) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/agent_pack/src/haystack_integrations/agent_pack/deep_research | +| **Package name** | `agent-pack-haystack` | + +
+
+:::warning
+Part of [Agent Pack](../agent-pack.mdx), which is experimental for the moment. Its APIs and agent architectures can change in any release, without following the usual deprecation policy.
+:::
+
+## When to use this agent
+
+Use the deep research agent when you need more than a quick answer. It's designed for questions that require gathering information from many web sources, evaluating them, and producing a structured report with citations.
+
+Typical use cases include:
+
+- Researching a broad topic across many sources.
+- Comparing products, companies, technologies, or scientific findings.
+- Preparing a literature review or market overview.
+- Answering complex questions that benefit from investigating several sub-topics in parallel.
+
+It's less useful when:
+
+- A single web search or RAG lookup is enough. The multi-agent workflow adds latency and cost.
+- The information lives in a private knowledge base rather than on the public web. For that, use the [Advanced RAG Agent](./advanced-rag-agent.mdx).
+
+## Installation
+
+```shell
+pip install agent-pack-haystack tavily-haystack trafilatura pypdf arrow
+```
+
+`trafilatura`, `pypdf`, and `arrow` are separate installs the deep research agent needs at runtime (HTML and PDF parsing, and date rendering). `tavily-haystack` is only needed for the default `search_tool`.
+
+Set `OPENAI_API_KEY` and `TAVILY_API_KEY` in the environment.
+
+## Usage
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.agent_pack import create_deep_research_agent
+
+agent = create_deep_research_agent()
+result = agent.run(messages=[ChatMessage.from_user("your research question")])
+print(result["report"])
+```
+
+`agent.run(...)` returns a dictionary whose main output is `report`, the final Markdown report. The dictionary also carries the intermediate `brief` (a `str`) and `notes` (a `list[str]`), plus the standard [`Agent`](../agent.mdx) outputs `messages`, `last_message`, `step_count`, `token_usage`, and `tool_call_counts`.
+
+## Configuration
+
+Everything is configured through keyword arguments to `create_deep_research_agent`. All parameters are keyword-only and optional.
+
+### Main agent
+
+The main agent is the orchestrator: it plans the investigation and delegates the sub-questions.
+
+- `llm` is the LLM that drives the orchestrator's loop. Defaults to `OpenAIResponsesChatGenerator("gpt-5.4")`.
+- `system_prompt` overrides the pre-made orchestrator prompt. The placeholder `{{ max_subtopics }}` is replaced with the value of `max_subtopics`.
+- `max_agent_steps` is the maximum number of steps for the orchestrator's agent loop (reflect and delegate rounds). Defaults to `8`.
+- `max_subtopics` is the maximum number of sub-questions the orchestrator may delegate (breadth). Defaults to `5`.
+- `max_concurrent_researchers` is the maximum number of sub-researchers that run at the same time. Defaults to `5`.
+
+### Sub-researchers
+
+- `researcher_llm` is the LLM that drives each sub-researcher's search, read, and think loop. Defaults to `OpenAIResponsesChatGenerator("gpt-5.4-mini")`.
+- `search_tool` is the web search tool each sub-researcher uses. Defaults to `TavilyWebSearchTool(top_k=10)`, which requires `tavily-haystack`. The pre-made researcher prompt refers to this tool as `web_search`, so name a custom tool the same way or adapt the prompt.
+- `page_summary_llm` is the LLM used inside the `read_url` tool to summarize a fetched page toward the question. Defaults to `OpenAIResponsesChatGenerator("gpt-5.4-mini")`.
+- `max_researcher_steps` is the maximum number of steps for each sub-researcher's agent loop. Defaults to `20`.
+- `max_page_chars` is the maximum number of raw page characters fed to `page_summary_llm`, before summarization. Defaults to `50000`.
+
+### Brief and report
+
+The Scope and Write phases are single LLM calls, each with its own ChatGenerator, so you can mix models by cost and capability or swap in a different provider.
+
+- `brief_llm` is the LLM that rewrites the user query into a focused research brief. Defaults to `OpenAIResponsesChatGenerator("gpt-5.4")`.
+- `report_llm` is the LLM that turns the brief plus collected notes into the final report. Defaults to `OpenAIResponsesChatGenerator("gpt-5.4")`.
+
+### Further customization
+
+To change anything else, such as adding tools or [hooks](../hooks.mdx), use [`clone()`](../agent.mdx#cloning-and-modifying-an-agent) on the returned agent. Unpack the existing values to keep the built-in tools, state entries, and the Scope and Write hooks:
+
+```python
+agent = create_deep_research_agent()
+
+customized = agent.clone(
+ tools=[*agent.tools, my_tool],
+ hooks={**agent.hooks, "before_llm": [my_hook]},
+)
+```
+
+## How it works
+
+The architecture is built around a single top-level Haystack [`Agent`](../agent.mdx), which acts as the orchestrator. Two [hooks](../hooks.mdx) run before and after its loop, creating three logical phases: Scope, Research, and Write. During the Research phase, the orchestrator invokes isolated sub-researcher agents, each its own `Agent`, through a tool:
+
+- **Scope.** The user question is rewritten into a focused research brief.
+- **Research.** The orchestrator splits the brief into focused sub-questions, delegates each to a sub-researcher, and collects their summaries.
+- **Write.** The brief and the collected summaries become the final report: Markdown with inline `[text](url)` citations.
+
+Scope and Write are plain LLM calls (a [`ChatPromptBuilder`](../../builders/chatpromptbuilder.mdx) and an [`OpenAIResponsesChatGenerator`](../../generators/openairesponseschatgenerator.mdx)), wrapped as serializable hook classes (`ScopeHook`, `WriteHook`):
+
+- Scope runs as a `before_run` hook: before the orchestrator's loop starts, it turns the user query into a brief, stored on the agent's [`State`](../state.mdx).
+- Write runs as an `after_run` hook: when the orchestrator's loop finishes, it turns the brief plus collected `notes` into the final report.
+
+`brief`, `notes`, and `report` are declared in the agent's `state_schema`, so they come back as outputs of a single `agent.run(...)` call.
+
+### The agents
+
+The Research phase uses two nested agents. Each one is a Haystack `Agent`: an LLM that loops, calling tools, until it decides to answer.
+
+#### Orchestrator
+
+The orchestrator is the lead agent: it receives the research brief and coordinates the whole investigation.
+
+- **Job:** split the brief into a few focused, non-overlapping sub-questions, delegate each one, check coverage, and stop when there's enough.
+- **Parallelism:** it emits several delegation calls in a single turn, and they run concurrently (bounded by `max_concurrent_researchers`).
+- **Memory:** the summaries returned by sub-researchers are appended to a shared `notes` list (the agent's `State`), which the writer later turns into the report.
+- **Stops when:** it replies with plain text (research complete) or hits `max_agent_steps`.
+
+The orchestrator's tools:
+
+| Tool | What it is | What it does |
+| --- | --- | --- |
+| `research_subtopic` | The sub-researcher agent, exposed as an [`AgentTool`](../../../tools/agenttool.mdx) | Researches a single sub-question in an isolated context and returns a compressed, cited summary. Only that summary is shown to the orchestrator; the summary is also appended to `notes`. |
+| `think_tool` | A no-op reflection tool | Lets the orchestrator pause to plan sub-questions and assess coverage between rounds. |
+
+#### Sub-researcher
+
+The sub-researcher is a reusable agent that answers a single sub-question. The orchestrator runs it many times in parallel, each in its own isolated context. This is the key idea: each sub-researcher processes the raw search results privately and returns only a concise summary, so the orchestrator's context stays small and the final report stays coherent.
+
+- **Job:** search the web, optionally read promising pages, reflect, then write a compressed summary with inline citations to the exact source URLs.
+- **Returns:** its final text message *is* the summary (it exits as soon as it writes plain text).
+- **Bounded by:** `max_researcher_steps`.
+
+The sub-researcher's tools:
+
+| Tool | What it is | What it does |
+| --- | --- | --- |
+| `web_search` | [`TavilyWebSearchTool`](../../../tools/ready-made-tools/tavilywebsearchtool.mdx) from the Tavily integration by default, or the `search_tool` you pass | Runs a web search and returns the top results as title, exact URL, and snippet. |
+| `read_url` | [`PipelineTool`](../../../tools/pipelinetool.mdx) over a fetch, route, convert-to-text, and summarize pipeline | Fetches a page (`LinkContentFetcher`), routes by MIME type (`FileTypeRouter`) to `HTMLToDocument` (Trafilatura) or `PyPDFToDocument` so PDFs are parsed too, and summarizes the page toward a question the agent passes, so only the relevant text enters the agent's context, not the full page. Used only when a search snippet is too shallow. |
+| `think_tool` | A no-op reflection tool | "What did I learn? What's missing? Stop or continue?" between searches. |
+
+### Context management
+
+The core challenge in a deep research agent is keeping each context window small and focused. Raw web content (search results, full pages, PDFs) is large and noisy. If it all accumulated in a single context, the model's output quality would degrade. We avoid that with isolation and compression:
+
+- Each sub-researcher runs as its own agent with its own `State`, so all the messy intermediate content (every search result, every fetched page) stays in *its* private context.
+- It finishes by writing one short summary (its final message). Only that summary leaves the sub-researcher: the raw content never reaches the orchestrator or the writer.
+
+The `AgentTool` default output handling and one setting on `research_subtopic` decide where that summary goes:
+
+| Behavior or setting | Controls | Effect |
+| --- | --- | --- |
+| `AgentTool` default output handling | What the orchestrator's LLM sees as the tool result | The text of the sub-researcher's final reply comes back by default, not its full message history. Keeps the orchestrator's context clean. |
+| `outputs_to_state={"notes": {...}}` | What gets saved for the writer | The same summary is appended (as text) to the shared `notes` list, which becomes the writer's input. |
+
+So each summary travels two ways, into the orchestrator's reasoning (so it can decide whether to dig further) and into the `notes` accumulator (so the writer can use it), while the bulky raw research stays isolated and is not propagated beyond the sub-researcher:
+
+```
+sub-researcher (private context: searches, pages, reflections)
+ │ writes one short summary
+ ├─ AgentTool default output → orchestrator's LLM (decide: done, or dig more?)
+ └─ outputs_to_state → notes → writer (final report)
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/agent.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/agent.mdx
new file mode 100644
index 00000000000..8d5eeec5746
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/agent.mdx
@@ -0,0 +1,563 @@
+---
+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`.
+
+`brief`, `notes`: The intermediate research brief and collected summaries | +| **API reference** | [Agent Pack](/reference/integrations-agent-pack) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/agent_pack/src/haystack_integrations/agent_pack/deep_research | +| **Package name** | `agent-pack-haystack` | + +
+
+| | |
+| --- | --- |
+| **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
`last_message`: The final `ChatMessage` of the run
`step_count`, `token_usage`, `tool_call_counts`, `exit_reason`: Run metadata
Plus one output per key defined in `state_schema` | +| **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,
+- `step_count`: the number of steps the agent ran,
+- `token_usage`: aggregated token usage summed across every LLM call in the run,
+- `tool_call_counts`: how many times each tool was invoked, keyed by tool name,
+- `exit_reason`: why the agent stopped, useful for routing its output downstream,
+- Additional dynamic keys based on `state_schema`.
+
+### Run Metadata
+
+The `step_count`, `token_usage`, `tool_call_counts`, and `exit_reason` outputs are populated automatically during a run. They are added to the agent's `state_schema` behind the scenes, so tools registered with `inputs_from_state` and [hooks](./hooks.mdx) can read them from the live `State`. They are outputs only — they cannot be passed as inputs to `run()` or `run_async()`, and using them as keys in your own `state_schema` raises a `ValueError`. See [State](./state.mdx#schema-definition) for details.
+
+```python
+response = agent.run(messages=[ChatMessage.from_user("What is 7 * (4 + 2)?")])
+
+print(response["step_count"]) # 2
+print(
+ response["token_usage"],
+) # {"prompt_tokens": 512, "completion_tokens": 86, ...}
+print(response["tool_call_counts"]) # {"calculator": 1}
+print(response["exit_reason"]) # "text"
+```
+
+### Exit reason
+
+The `exit_reason` output tells you why the agent stopped, which makes it easy to route the agent's output downstream — for example, with a [`ConditionalRouter`](../routers/conditionalrouter.mdx). It is one of:
+
+- `"text"`: the model returned a complete reply with no tool calls.
+- `"length"`: the model reached its output-token limit. `last_message` may contain a partial response.
+- `"content_filter"`: a content filter stopped the model response. `last_message` may contain a partial response.
+- the name of the tool that satisfied a tool exit condition. In this case `last_message` is that tool's result — a tool-result `ChatMessage` whose `text` is empty — so `exit_reason` tells you how to consume it.
+- `"max_agent_steps"`: the agent reached `max_agent_steps` before meeting an exit condition.
+- a custom reason set by a hook through the `stop_run` state key, such as `"token_budget_exceeded"` from the [`TokenBudgetHook`](./token-budget.mdx).
+
+The Agent stops by default on `"length"` and `"content_filter"` so it does not repeatedly submit an unchanged request. These reasons do not make recovery impossible: an `on_exit` hook can inspect the reason, rewrite the messages, and set `continue_run` to `True`. Alternatively, route the result downstream to retry with different generation settings or request human review.
+
+Because `exit_reason` is available on the live `State`, an `after_run` [hook](./hooks.mdx) can read it to react to how the run ended — for example, appending a fallback answer when the step budget is exhausted before the agent finished:
+
+```python
+from haystack.components.agents.state import State
+from haystack.dataclasses import ChatMessage
+from haystack.hooks import hook
+
+
+@hook
+def fallback_on_max_steps(state: State) -> None:
+ if state.get("exit_reason") == "max_agent_steps":
+ state.set(
+ "messages",
+ [ChatMessage.from_assistant("Sorry, I ran out of steps before finishing.")],
+ )
+```
+
+For example, this hook requests one shorter continuation after an output-limit exit. The Agent's existing `max_agent_steps` setting still bounds the run.
+
+```python
+@hook
+def recover_from_output_limit(state: State) -> None:
+ recovery_prompt = "Continue with a shorter answer."
+ recovery_attempted = any(
+ message.text == recovery_prompt for message in state.get("messages", [])
+ )
+ if state.get("exit_reason") == "length" and not recovery_attempted:
+ state.set(
+ "messages",
+ [ChatMessage.from_user(recovery_prompt)],
+ )
+ state.set("continue_run", True)
+```
+
+## 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), [`AgentTool`](../../tools/agenttool.mdx), [`MCPTool`](../../tools/mcptool.mdx), [`Toolset`](../../tools/toolset.mdx), [`MCPToolset`](../../tools/mcptoolset.mdx), [`SearchableToolset`](../../tools/searchabletoolset.mdx). Tool names must be unique; duplicate names are detected at the start of each agent step, before the chat generator is called.
+- `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"]`. Exit conditions are evaluated at runtime rather than validated at initialization, so a condition can name a tool that is only loaded later — for example, a tool passed at runtime via `run(tools=...)` or one discovered by a [`SearchableToolset`](../../tools/searchabletoolset.mdx).
+- `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.
+- `hooks`: A dict mapping a hook point (`"before_run"`, `"before_llm"`, `"before_tool"`, `"after_tool"`, `"on_exit"`, `"after_run"`) to a list of hooks the agent runs at that point. Hooks receive the live `State` and influence the run by mutating it — for example, to build run-time context or require human confirmation of tool calls. See [Hooks](./hooks.mdx) and [Human in the Loop](./human-in-the-loop.mdx).
+- `tool_concurrency_limit`: Maximum number of tool calls to execute at the same time. Defaults to `4`; set to `1` to disable parallel tool execution.
+- `tool_streaming_callback_passthrough`: If `True`, passes the streaming callback to tools that accept it.
+
+### 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 chat generator (e.g. `{"temperature": 0.2}`). They are merged per key with the `generation_kwargs` set at the chat generator's initialization: keys passed here take precedence, keys set only at initialization are kept.
+- `hook_context`: A dict of request-scoped resources made available to [hooks](./hooks.mdx) via `state.data["hook_context"]` — for example, a user ID or a WebSocket connection.
+
+:::info
+For the full parameter reference, see the [Agents API Documentation](/reference/agents-api).
+:::
+
+### Cloning and modifying an agent
+
+Agent attributes are not meant to be reassigned after initialization: several parameters are processed at init time, so setting an attribute on a built agent does not reliably take effect. The recommended way to get a modified version of an existing agent is `clone()`.
+
+`clone()` returns a new agent with the same configuration, optionally replacing some init parameters. This is useful for creating a variant of an agent you did not build yourself, such as one returned by a factory function of the [Agent Pack](./agent-pack.mdx).
+
+```python
+variant = agent.clone(system_prompt="Answer in German.", max_agent_steps=20)
+```
+
+Overrides replace the original values. To extend a list or dictionary instead, unpack the existing value and add your entries:
+
+```python
+extended = agent.clone(
+ tools=[*agent.tools, my_new_tool],
+ state_schema={**agent.state_schema, "notes": {"type": str}},
+ hooks={**agent.hooks, "before_llm": [my_hook]},
+)
+```
+
+## 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.
+
+`last_message`: The final `ChatMessage` of the run
`step_count`, `token_usage`, `tool_call_counts`, `exit_reason`: Run metadata
Plus one output per key defined in `state_schema` | +| **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` | + +
+
+
+## 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 Agent's tool execution 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.
+
+The simplest way is [`AgentTool`](../../tools/agenttool.mdx), which wraps an `Agent` and delegates a task to it as a single user message, returning only its final reply.
+
+See [Multi-Agent Systems](../../concepts/agents/multi-agent-systems.mdx) for a full guide.
+
+## 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
+- [Hooks](./hooks.mdx) — running custom logic at defined points of the run loop
+- [Human in the Loop](./human-in-the-loop.mdx) — intercepting tool calls for human review
+- [Tool Result Offloading](./tool-result-offloading.mdx) — keeping large tool results out of the context window
+
+📚 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-3.2-unstable/pipeline-components/agents-1/compaction.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction.mdx
new file mode 100644
index 00000000000..c9aa5259a84
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction.mdx
@@ -0,0 +1,163 @@
+---
+title: "Context Compaction"
+id: compaction
+slug: "/compaction"
+description: "Context compaction shortens an Agent's conversation so long runs do not exhaust the model's context window."
+---
+
+# Context Compaction
+
+Context compaction shortens an Agent's conversation so long runs do not exhaust the model's context window. It rewrites older history into a smaller representation while preserving the context the Agent needs to continue working.
+
+Compaction is lossy. After it runs, the Agent works from a shorter record of the conversation. What survives and what is discarded depends on the compaction strategy.
+
+## How context compaction works
+
+Context compaction separates three responsibilities:
+
+| Responsibility | Abstraction | Purpose |
+| --- | --- | --- |
+| Decide when to compact | [`CompactionHook`](compaction/compaction-hook.mdx) | Monitors the Agent's context before LLM calls and invokes a compactor after a configured threshold is reached. |
+| Decide how to compact | `Compactor` protocol | Defines how a conversation is rewritten. Haystack includes [`SlidingWindowCompactor`](compaction/sliding-window-compactor.mdx), [`SummarizationCompactor`](compaction/summarization-compactor.mdx), and [`ToolResultPruningCompactor`](compaction/tool-result-pruning-compactor.mdx). |
+| Measure the conversation | [`TokenCounter`](../../token-counters.mdx) protocol | Estimates the size of messages and tool schemas before they are sent to a model. |
+
+This separation lets you combine a standard trigger with different compaction strategies and token counters. For example, a local sliding window can remove old history without making an additional model call, while a summarization compactor can condense the same history with an LLM.
+
+## Basic setup
+
+The following example registers a `CompactionHook` under the Agent's `before_llm` [hook point](./hooks.mdx). It starts compacting at 70% of the model's context window and asks the compactor to reduce the context to approximately 40%.
+
+
+```python
+from typing import Annotated
+
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor
+from haystack.tools import tool
+
+
+@tool
+def fetch_page(url: Annotated[str, "The URL to fetch"]) -> str:
+ """Fetch a web page and return its text."""
+ return "Fusion startups reported net-energy-gain milestones this year. " * 500
+
+
+compaction_hook = CompactionHook(
+ compactor=SlidingWindowCompactor(),
+ context_window=400_000, # gpt-5.4-nano's context window
+ compact_at=0.7,
+ compact_to=0.4,
+)
+
+agent = Agent(
+ chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
+ tools=[fetch_page],
+ system_prompt="You are a research assistant. Fetch pages as needed and cite what you used.",
+ hooks={"before_llm": [compaction_hook]},
+)
+
+result = agent.run(
+ messages=[ChatMessage.from_user("Summarize recent fusion energy milestones.")],
+)
+print(result["last_message"].text)
+```
+
+See [`CompactionHook`](compaction/compaction-hook.mdx) for threshold configuration, context measurement, lifecycle, and serialization.
+
+## Compaction strategies
+
+Compactors receive the current messages, a target token count, and the same token counter used to measure the context. They return a shorter replacement conversation or `None` when there is nothing useful to change.
+
+| Compactor | Strategy | Trade-off |
+| --- | --- | --- |
+| [`SlidingWindowCompactor`](compaction/sliding-window-compactor.mdx) | Preserves the Agent's instructions and latest user task, keeps complete historical turns while they fit, and trims the current task's own Agent steps only when that is not enough. | Fast and local, but discarded information is not summarized. |
+| [`SummarizationCompactor`](compaction/summarization-compactor.mdx) | Progressively replaces historical turns and current-task steps with LLM-generated summaries, then combines older summaries only as needed. | Preserves a condensed record of earlier work, but adds model cost and latency and remains lossy. |
+| [`ToolResultPruningCompactor`](compaction/tool-result-pruning-compactor.mdx) | Replaces older, large tool results with short placeholders while preserving tool-call/result structure. | Retains the shape of the run and recent results, but removes the content of pruned results. |
+
+## Combining compaction strategies
+
+Register multiple `CompactionHook` instances at `before_llm` to apply progressively more aggressive strategies. Hooks run in list order against the same Agent state, so each hook measures the messages left by the previous one.
+
+For example, prune large tool results first and use a sliding window as a fallback:
+
+```python
+from haystack.hooks.compaction import (
+ CompactionHook,
+ SlidingWindowCompactor,
+ ToolResultPruningCompactor,
+)
+
+prune_tool_results = CompactionHook(
+ compactor=ToolResultPruningCompactor(),
+ context_window=400_000,
+ compact_at=0.7,
+ compact_to=0.4,
+)
+drop_old_steps = CompactionHook(
+ compactor=SlidingWindowCompactor(),
+ context_window=400_000,
+ compact_at=0.7,
+ compact_to=0.4,
+)
+
+agent = Agent(
+ chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
+ tools=[fetch_page],
+ hooks={"before_llm": [prune_tool_results, drop_old_steps]},
+)
+```
+
+If pruning brings the updated context below `compact_at`, the sliding-window hook does nothing. If pruning returns `None` because no eligible results remain, or it shortens the context without getting below the trigger, the sliding window removes historical turns and then, if needed, the current task's oldest Agent steps. A result the pruning compactor already replaced with a placeholder stays with the historical turn it belongs to, so its tool call keeps an answer. Configure both hooks for the same model context window and compatible token counters so they make decisions from comparable estimates.
+
+### Creating a custom compactor
+
+Implement the `Compactor` protocol when you need a different strategy, such as preserving application-specific messages or selectively shortening content using custom metadata.
+
+```python
+from typing import Any
+
+from haystack.core.serialization import default_to_dict
+from haystack.dataclasses import ChatMessage
+from haystack.hooks.compaction import Compactor
+from haystack.token_counters import TokenCounter
+
+
+class CustomCompactor(Compactor):
+ def compact(
+ self,
+ messages: list[ChatMessage],
+ target_tokens: int,
+ token_counter: TokenCounter,
+ ) -> list[ChatMessage] | None:
+ # Return a shorter, valid conversation or None when nothing should change.
+ ...
+
+ def to_dict(self) -> dict[str, Any]:
+ return default_to_dict(self)
+```
+
+A compactor must follow these rules:
+
+1. Return `None` unless the conversation actually gets smaller.
+2. Return a new list without modifying the input `messages` list.
+3. Keep tool calls together with all their result messages. Chat-completion APIs reject incomplete tool-call exchanges.
+
+The `target_tokens` value is a goal rather than a guarantee. When the target conflicts with context the Agent must retain, preserve the required context and get as close to the target as possible.
+
+`compact_async()` calls `compact()` by default. Override it when compaction performs I/O, such as calling an LLM, so asynchronous Agent runs are not blocked. Use `to_dict()` to serialize constructor settings. The protocol's default `from_dict()` handles plain constructor values; override it when serialized values must be reconstructed first, such as a `Secret` or nested component.
+
+## Token counters
+
+The default `ApproximateTokenCounter` estimates tokens from text length and needs no extra dependency. You can configure another built-in or custom [`TokenCounter`](../../token-counters.mdx) when you need a model- or provider-specific estimate.
+
+Token counters can also include tool schemas and non-text content in the estimate. Consult the page for the counter you use to understand how it handles images and files.
+
+## Context compaction and tool result offloading
+
+[Tool result offloading](./tool-result-offloading.mdx) solves an adjacent problem: it writes large tool results to a store and leaves a pointer in the conversation. The two approaches work well together — offloading keeps individual results small as they arrive, while compaction bounds the conversation as a whole.
+
+An offloaded result is represented by a reference to the stored content. If a compactor removes or rewrites that message, the model loses the reference it needs to read the content again.
+
+`ToolResultPruningCompactor` skips results marked as offloaded by default, preserving their stored-content references.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction/compaction-hook.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction/compaction-hook.mdx
new file mode 100644
index 00000000000..36e4c9fa24e
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction/compaction-hook.mdx
@@ -0,0 +1,103 @@
+---
+title: "CompactionHook"
+id: compaction-hook
+slug: "/compaction-hook"
+description: "Use CompactionHook to shorten an Agent's conversation before it exceeds the model's context window."
+---
+
+# CompactionHook
+
+`CompactionHook` monitors an Agent's conversation before each LLM call. When the estimated context reaches a configured threshold, the hook passes the messages to a `Compactor` and writes the shorter conversation back to the Agent's state.
+
+:::warning[Experimental]
+
+`CompactionHook` is experimental and may change without a deprecation cycle.
+:::
+
+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 + exit_conditions: + - text + hooks: null + 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_concurrency_limit: 4 + tool_streaming_callback_passthrough: false + 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_integrations.components.websearch.serperdev.websearch.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 under the `before_llm` [hook point](../hooks.mdx) |
+| **Mandatory init variables** | `compactor`: The strategy used to shorten the messages
`context_window`: The model's context-window size in tokens | +| **Import path** | `haystack.hooks.compaction.CompactionHook` | +| **API reference** | [Hooks](/reference/hooks-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/hooks/compaction/hooks.py | +| **Package name** | `haystack-ai` | + +
+
+## Usage
+
+Register the hook under `before_llm` and configure the context window of the Agent's model:
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor
+
+compaction_hook = CompactionHook(
+ compactor=SlidingWindowCompactor(),
+ context_window=400_000, # gpt-5.4-nano's context window
+ compact_at=0.7,
+ compact_to=0.4,
+)
+
+agent = Agent(
+ chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
+ tools=[],
+ hooks={"before_llm": [compaction_hook]},
+ max_agent_steps=50,
+)
+```
+
+`CompactionHook` can only be registered under `before_llm`. The Agent raises a `ValueError` if you register it at another hook point.
+
+## Configuration
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `compactor` | No default | A `Compactor` implementation that decides how to shorten the messages. |
+| `context_window` | No default | The model's full context-window size in tokens. It must be greater than zero. |
+| `compact_at` | `0.7` | The fraction of the context window at which compaction starts. Leave enough space above it for the next model response and tool results. |
+| `compact_to` | `0.4` | The fraction of the context window that compaction targets. A lower value compacts less often but removes more context each time. |
+| `token_counter` | `ApproximateTokenCounter()` | The counter used to estimate messages not yet included in provider-reported usage. |
+
+The thresholds must satisfy `0 < compact_to < compact_at <= 1`. A target at or above the trigger would leave the conversation ready to compact again on the next step, so the hook rejects that configuration.
+
+## How the hook measures context
+
+After an LLM call, the Agent stores the generator's reported prompt-plus-completion usage in `state.data["context_tokens"]`. This count includes the system prompt, tool schemas, and provider-specific chat-template overhead. Messages appended since that call, typically tool results, are measured locally with the configured [`TokenCounter`](../../../token-counters.mdx).
+
+If the generator does not report usage and `context_tokens` remains `0`, the hook estimates the complete conversation and tool schemas locally. The default `ApproximateTokenCounter` needs no extra dependency. You can provide another built-in or custom counter:
+
+```python
+from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor
+from haystack.token_counters import TiktokenCounter
+
+compaction_hook = CompactionHook(
+ compactor=SlidingWindowCompactor(),
+ context_window=128_000,
+ token_counter=TiktokenCounter(encoding="o200k_base"),
+)
+```
+
+The hook subtracts estimated non-message overhead from the target passed to the compactor. This prevents the compactor from treating tool schemas or provider formatting as message tokens it can remove.
+
+## Choosing a compactor
+
+The compactor controls what information survives:
+
+| Compactor | Strategy |
+| --- | --- |
+| [`SlidingWindowCompactor`](sliding-window-compactor.mdx) | Keeps the current task and as much complete recent conversation as fits, removing complete historical turns before it trims the task's own steps. |
+| [`SummarizationCompactor`](summarization-compactor.mdx) | Progressively summarizes historical turns before the current task, preserving the newest configured Agent steps. |
+| [`ToolResultPruningCompactor`](tool-result-pruning-compactor.mdx) | Replaces older, large tool results with short placeholders while keeping recent results intact. |
+
+You can also implement the `Compactor` protocol for a custom strategy. See [Context Compaction](../compaction.mdx#creating-a-custom-compactor) for its requirements.
+
+## Lifecycle and serialization
+
+The hook warms up its token counter and compactor when they provide a `warm_up` method, and delegates `close` to the compactor when supported. Its asynchronous lifecycle methods prefer the compactor's async implementation when one exists.
+
+`to_dict()` serializes the hook together with its compactor and token counter. `from_dict()` reconstructs both nested objects, so an Agent configured with the hook can be serialized and restored.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction/sliding-window-compactor.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction/sliding-window-compactor.mdx
new file mode 100644
index 00000000000..e66e5c915fe
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction/sliding-window-compactor.mdx
@@ -0,0 +1,90 @@
+---
+title: "SlidingWindowCompactor"
+id: sliding-window-compactor
+slug: "/sliding-window-compactor"
+description: "Use SlidingWindowCompactor to remove older Agent history while preserving the current task and as much recent complete conversation as fits."
+---
+
+# SlidingWindowCompactor
+
+`SlidingWindowCompactor` removes older conversation history while preserving the Agent's instructions, current task, and as much complete recent conversation as the token target allows. It removes complete historical turns first, and only trims the current task's own Agent steps when removing every historical turn is not enough.
+
+:::warning[Experimental]
+
+`SlidingWindowCompactor` is experimental and may change without a deprecation cycle. Compaction is lossy: messages removed by this strategy cannot be recovered or summarized.
+:::
+
+`context_window`: The model's context-window size in tokens | +| **Import path** | `haystack.hooks.compaction.CompactionHook` | +| **API reference** | [Hooks](/reference/hooks-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/hooks/compaction/hooks.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Used by** | [`CompactionHook`](compaction-hook.mdx) |
+| **Mandatory init variables** | None |
+| **Import path** | `haystack.hooks.compaction.SlidingWindowCompactor` |
+| **API reference** | [Hooks](/reference/hooks-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/hooks/compaction/sliding_window.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Usage
+
+Pass the compactor to a `CompactionHook`:
+
+```python
+from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor
+
+compaction_hook = CompactionHook(
+ compactor=SlidingWindowCompactor(
+ min_keep_steps=1,
+ omission_note=(
+ "[{num_removed} earlier messages were removed to free up context.]"
+ ),
+ ),
+ context_window=200_000,
+ compact_at=0.7,
+ compact_to=0.4,
+)
+```
+
+`CompactionHook` determines when compaction runs and provides the target token count. `SlidingWindowCompactor` determines which messages to retain.
+
+## How the sliding window is selected
+
+The compactor divides a conversation into protected context, historical turns, and the current task's Agent steps:
+
+1. It preserves all leading system messages as the Agent's instructions.
+2. It preserves the latest user message as the current task.
+3. It groups the history before that task into complete historical turns, each running from one user message up to the next.
+4. It groups each assistant message and all immediately following tool-result messages into one complete Agent step.
+5. Working backwards from the newest, it keeps as many complete historical turns as fit within the target.
+6. Only when the current task alone still exceeds the target does it begin removing that task's own steps, oldest first.
+7. It replaces what it removed with an omission note, unless the note is disabled.
+
+Keeping complete steps ensures that an assistant tool call is not separated from its results, including batches of parallel tool calls. Incomplete tool-call exchanges are rejected by chat-completion providers. Historical turns are kept or removed in full for the same reason: an assistant reply is never retained without the user message it answers.
+
+The target is a goal rather than a guarantee, and the conversation can end up above it rather than below. Leading system messages and the current task are never removed, and `min_keep_steps` holds on to the newest Agent steps whatever their size, so a long system prompt or a single large tool result can leave the conversation well over the target.
+
+## Configuration
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `min_keep_steps` | `1` | The minimum number of complete recent Agent steps to preserve, even if they exceed the target. Set it to `0` to allow all completed steps to be removed. |
+| `omission_note` | `"[{num_removed} earlier messages were removed from this conversation to free up context and cannot be recovered.]"` | A user message inserted where history was removed. Use `{num_removed}` to include the number of removed messages, provide custom text without the placeholder, or set it to `None` to remove history silently. |
+
+`min_keep_steps` cannot be negative.
+
+### Omission notes
+
+An omission note tells the model that earlier context is missing. Without one, the shortened conversation can appear complete and the model may repeat work or behave as though it still has the removed information.
+
+The note is left where the removed messages used to sit: directly after the leading system messages when only historical turns were removed, and directly after the latest user message when the current task's own steps were removed. Repeated compactions fold an earlier note into the new one, so the conversation carries at most one.
+
+Compaction metadata is stored on the note, including the strategy name and the numbers of removed and retained messages.
+
+## When the conversation is unchanged
+
+The compactor returns `None` without changing the conversation when:
+
+- The conversation already fits within `target_tokens`.
+- There is no removable history outside the protected messages and the history it retained.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction/summarization-compactor.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction/summarization-compactor.mdx
new file mode 100644
index 00000000000..3c1a366b23a
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/compaction/summarization-compactor.mdx
@@ -0,0 +1,147 @@
+---
+title: "SummarizationCompactor"
+id: summarization-compactor
+slug: "/summarization-compactor"
+description: "Use SummarizationCompactor to progressively replace older Agent context with LLM-generated summaries."
+---
+
+# SummarizationCompactor
+
+`SummarizationCompactor` reduces an Agent's context by progressively replacing older conversation turns and Agent steps with LLM-generated summaries. Unlike strategies that discard content, it preserves a condensed account of earlier objectives, decisions, completed work, identifiers, and unresolved work.
+
+:::warning[Experimental]
+
+`SummarizationCompactor` is experimental and may change without a deprecation cycle. Summarization is lossy, and its quality depends on the Chat Generator and instructions you configure.
+:::
+
+
+
+| | |
+| --- | --- |
+| **Used by** | [`CompactionHook`](compaction-hook.mdx) |
+| **Mandatory init variables** | `chat_generator`: The Chat Generator that writes conversation summaries |
+| **Import path** | `haystack.hooks.compaction.SummarizationCompactor` |
+| **API reference** | [Hooks](/reference/hooks-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/hooks/compaction/summarization.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Usage
+
+Create a separate Chat Generator for summaries and pass the compactor to a `CompactionHook`:
+
+```python
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.hooks.compaction import CompactionHook, SummarizationCompactor
+
+summary_generator = OpenAIResponsesChatGenerator(model="gpt-5.4-nano")
+
+compaction_hook = CompactionHook(
+ compactor=SummarizationCompactor(
+ chat_generator=summary_generator,
+ min_keep_steps=2,
+ approximate_summary_tokens=1_024,
+ ),
+ context_window=400_000,
+ compact_at=0.7,
+ compact_to=0.4,
+)
+```
+
+Register `compaction_hook` under the Agent's `before_llm` [hook point](../hooks.mdx). `CompactionHook` decides when to compact and derives the target from `context_window` and `compact_to`. `SummarizationCompactor` decides which part of the conversation to summarize.
+
+## How progressive summarization works
+
+The compactor divides the conversation into two regions:
+
+- **History** starts after the leading system messages and ends before the latest real user message.
+- **Current task** starts with the latest real user message and continues to the end.
+
+It always spends history before the current task. Each round uses the first applicable tier below and selects only enough of its oldest content to reach the target:
+
+1. **Historical turns:** Summarize complete historical user turns, oldest first.
+2. **Historical summaries:** Once no complete historical turns remain, combine the oldest historical summaries. At least two summaries are selected so a model call never merely rewrites one summary.
+3. **Current-task steps:** Summarize the oldest eligible Agent steps while preserving the `min_keep_steps` newest steps. An Agent step contains an assistant message and all immediately following tool results.
+4. **Current-task summaries:** When no more steps may be summarized, combine the oldest summaries already created for the current task.
+
+After each successful model call, the resulting summary replaces the selected messages. If the measured conversation is still above the target, the compactor plans another round.
+
+Leading system messages and the latest user message are always retained.
+
+## Summary prompt
+
+The default instruction asks the model to produce terse sections for:
+
+- Objective
+- Decisions and constraints
+- Work completed
+- Identifiers
+- Unresolved work
+
+Only the messages being replaced are sent to the summary generator. The latest request and other retained messages stay in the conversation but are not included in that model call. For example, a selected portion containing an earlier summary, attachments, and a tool interaction is rendered as:
+
+```text
+
+
+| | |
+| --- | --- |
+| **Used by** | [`CompactionHook`](compaction-hook.mdx) |
+| **Mandatory init variables** | None |
+| **Import path** | `haystack.hooks.compaction.ToolResultPruningCompactor` |
+| **API reference** | [Hooks](/reference/hooks-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/hooks/compaction/tool_result_pruning.py |
+| **Package name** | `haystack-ai` |
+
+
+
+## Usage
+
+Pass the compactor to a `CompactionHook`:
+
+```python
+from haystack.hooks.compaction import CompactionHook, ToolResultPruningCompactor
+
+compaction_hook = CompactionHook(
+ compactor=ToolResultPruningCompactor(
+ min_keep_steps=1,
+ min_tokens=200,
+ ),
+ context_window=200_000,
+ compact_at=0.7,
+ compact_to=0.4,
+)
+```
+
+`CompactionHook` determines when compaction runs and provides the target token count. `ToolResultPruningCompactor` replaces only as many eligible results as needed to reach that target.
+
+## How pruning works
+
+The compactor processes tool results from oldest to newest:
+
+1. It leaves the conversation unchanged when it already fits within the target.
+2. It protects results from at least the configured number of recent tool-calling Agent steps. Since at least one step must be kept, the current result batch remains intact until the model has acted on it.
+3. It skips results already marked by context compaction, results below the token threshold, and results carrying protected metadata such as an offloaded-result reference.
+4. It replaces eligible results with the configured placeholder until the estimated conversation size reaches the target.
+
+The replacement preserves the originating tool call, error flag, and message metadata. This keeps the tool-call exchange valid for chat-completion providers while discarding the expensive result content.
+
+The target is a goal rather than a guarantee. Protected recent results and results that do not meet the pruning rules can leave the conversation above the requested target.
+
+## Configuration
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `min_keep_steps` | `1` | The minimum number of recent tool-calling Agent steps whose results remain intact regardless of the target. Parallel results from one step are protected together. |
+| `min_tokens` | `200` | Only prune a tool-result message when it uses more than this many tokens, as measured by the configured token counter. |
+| `placeholder` | ``"[Tool result removed to free up context. Call `{tool_name}` again if you need it.]"`` | Text that replaces a pruned result. Use `{tool_name}` to insert the originating tool's name. Other braces are preserved literally. |
+| `skip_meta_keys` | `("tool_result_offloaded",)` | Leave a result unchanged when its metadata contains any listed key. The default protects pointers created by `ToolResultOffloadHook`. |
+
+`min_keep_steps` must be at least `1`, and `min_tokens` cannot be negative.
+
+### Custom placeholders
+
+Keep custom placeholders short so replacing a result saves context. If a placeholder costs at least as many tokens as the original result, the compactor leaves that result unchanged.
+
+```python
+compactor = ToolResultPruningCompactor(
+ placeholder="Previous output from {tool_name} was removed. Call the tool again if needed.",
+)
+```
+
+The compactor records `context_compaction` metadata on each rewritten result with the strategy name and the original tool-result message's token count.
+
+## Token counting
+
+The compactor uses the [`TokenCounter`](../../../token-counters.mdx) supplied by `CompactionHook` to determine whether a result exceeds `min_tokens` and whether replacing it saves context.
+
+The complete conversation is counted once. For each eligible result, the counter then measures only the original result message and its short replacement. The compactor updates its running total using the difference between those two counts.
+
+## Interaction with tool result offloading
+
+[`ToolResultOffloadHook`](../tool-result-offloading.mdx) stores a tool result outside the conversation and replaces it with a reference. Pruning that reference would prevent the model from retrieving the stored content.
+
+By default, `ToolResultPruningCompactor` skips messages with `tool_result_offloaded` metadata. These pointer messages are already small, so pruning them would save little context while removing the model's only reference to the full stored result. Add other metadata keys to `skip_meta_keys` when another hook or application feature leaves references that must remain available.
+
+## When the conversation is unchanged
+
+The compactor returns `None` without changing the conversation when:
+
+- The conversation already fits within `target_tokens`.
+- There are no results older than the protected steps.
+- Every older result is already compacted, protected by metadata, or no larger than `min_tokens`.
+- A replacement would not reduce the result's measured token count.
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/hooks.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/hooks.mdx
new file mode 100644
index 00000000000..7795ebe00af
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/hooks.mdx
@@ -0,0 +1,209 @@
+---
+title: "Hooks"
+id: hooks
+slug: "/hooks"
+description: "Hooks let you run custom logic at defined points of an Agent's run loop — at the start and end of a run, before each LLM call, before and after tool execution, and on exit."
+---
+
+# Hooks
+
+Hooks let you run custom logic at defined points of an [`Agent`](./agent.mdx)'s run loop — at the start and end of a run, before each LLM call, before and after tool execution, and on exit.
+
+
+
+| | |
+| --- | --- |
+| **Configured on** | The [`Agent`](./agent.mdx) component via the `hooks` parameter |
+| **Key classes** | `hook` (decorator), `FunctionHook`, `Hook` (protocol) |
+| **Import path** | `haystack.hooks` |
+| **API reference** | [Hooks](/reference/hooks-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/hooks/ |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+Pass `hooks` to the `Agent` as a dictionary mapping a *hook point* to a list of hooks the Agent runs at that point. Each hook receives the live [`State`](./state.mdx) and influences the run by mutating it in place. Hooks for a hook point run in list order, and the same hook can be registered under multiple hook points.
+
+This enables patterns such as building run-time system context, retrieving memories before the first LLM call, auditing or intercepting tool calls, and requiring a condition to hold before the Agent is allowed to finish.
+
+### Hook points
+
+- `before_run`: Runs once per run, after the state is initialized and before the first chat-generator call. Use it to rewrite the initial messages or seed state — for example, to turn the user query into a task brief — without re-running on every step like `before_llm` does.
+- `before_llm`: Runs before each chat-generator call.
+- `before_tool`: Runs after the model requests tool calls, before any tools run. After these hooks run, the Agent re-reads the current last message from `state.data["messages"]`. If that message contains tool calls, those calls are executed. If it does not, no tools run for that step, no tool-based exit condition is triggered, and the Agent loops back to the next LLM call unless `max_agent_steps` has been reached.
+- `after_tool`: Runs after tools execute, once their result messages are in `state.data["messages"]`, before the exit-condition check and the next LLM call. Use it to rewrite the freshly produced tool-result messages — for example, to offload, redact, truncate, or summarize results. It does not run on the plain-text exit step. It does still run when a `before_tool` hook removed the pending tool calls: no tools executed on that step, so don't assume the last message is a fresh tool result.
+- `on_exit`: Runs when the Agent is about to stop on an exit condition. An `on_exit` hook can keep the Agent running by setting the `continue_run` control flag (`state.set("continue_run", True)`), usually alongside a message telling the model what to do next. `on_exit` hooks run when the Agent stops on an exit condition, but not when it stops because `max_agent_steps` is reached — use `after_run` for logic that must run however the run ends.
+- `after_run`: Runs once per run, after the step loop has ended and before the Agent builds its return value — regardless of whether the run stopped on an exit condition or because `max_agent_steps` was reached (unlike `on_exit`). Mutations to the state, such as appending a final message, are reflected in the returned `messages` / `last_message` and `state_schema` outputs. Setting `continue_run` here has no effect.
+
+Registering a hook under an unknown hook point raises a `ValueError` at construction. A hook class can declare an `allowed_hook_points` attribute listing the hook points it supports; the Agent validates it and fails fast if the hook is registered somewhere it doesn't belong.
+
+### State keys for hooks
+
+The Agent manages a few state keys that hooks interact with. Like the run-metadata keys (`step_count`, `token_usage`, `tool_call_counts`), they are reserved — using any of them in your own `state_schema` raises a `ValueError`. See [State](./state.mdx#schema-definition) for the full list:
+
+- `continue_run`: Set by an `on_exit` hook to keep the Agent running.
+- `stop_run`: Set by any hook to stop the run, read before each LLM call and used as the `exit_reason`.
+- `tools`: The tools available in the current step, for hooks to inspect.
+- `hook_context`: Request-scoped resources passed to `Agent.run(hook_context={...})` / `run_async(hook_context={...})`. Hooks read it with `state.data["hook_context"]` or `state.data.get("hook_context")` — use it for per-request resources such as a user ID, a WebSocket, or a database client. Avoid the plain `state.get("hook_context")` here: `State.get` returns a deep copy of the value, which often fails for the kinds of resources stored in this dict (such as a WebSocket or a database client).
+- `context_tokens`: An approximate count of the tokens currently in the context window, refreshed after each LLM call with that reply's prompt-plus-completion tokens (read it with `state.get("context_tokens")`). Unlike `token_usage`, which accumulates over the run, this is replaced on every call. It's `0` until the first reply that reports usage and doesn't count messages appended after the latest call. A `before_llm` hook can read it to trigger context compaction once it crosses a threshold.
+
+Hooks can also read the automatically tracked run metadata: `step_count`, `token_usage`, and `tool_call_counts`.
+
+## Creating hooks
+
+### With the `@hook` decorator
+
+The `@hook` decorator wraps a function taking a single `State` argument into a hook. A regular function becomes the hook's sync path, a coroutine function its async path. To give a single hook both paths, construct a `FunctionHook` directly with both `function` and `async_function`.
+
+The example below registers a hook at each of `before_llm`, `before_tool`, and `on_exit` to show what hooks can do:
+
+```python
+from datetime import datetime, timezone
+from typing import Annotated
+
+from haystack.components.agents import Agent
+from haystack.components.agents.state import State, replace_values
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.hooks import hook
+from haystack.tools import tool
+
+
+@tool
+def search(query: Annotated[str, "The search query"]) -> str:
+ """Search the web."""
+ # Placeholder: would call a real search API
+ return "Fusion startups reported net-energy-gain milestones this year."
+
+
+@hook
+def build_context(state: State) -> None:
+ # before_llm: build run-time system context once, before the first model call.
+ if state.get("step_count") == 0:
+ now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+ system = ChatMessage.from_system(
+ f"You are a research assistant. The current time is {now}.",
+ )
+ state.set(
+ "messages",
+ [system, *state.data["messages"]],
+ handler_override=replace_values,
+ )
+
+
+@hook
+def audit_tool_calls(state: State) -> None:
+ # before_tool: see which tools the model is about to run.
+ pending = state.data["messages"][-1].tool_calls
+ print(f"about to run: {[tc.tool_name for tc in pending]}")
+
+
+@hook
+def require_search(state: State) -> None:
+ # on_exit: keep going until the agent has actually searched.
+ if state.get("tool_call_counts", {}).get("search", 0) == 0:
+ state.set("messages", [ChatMessage.from_system("Search before answering.")])
+ state.set("continue_run", True)
+
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[search],
+ hooks={
+ "before_llm": [build_context],
+ "before_tool": [audit_tool_calls],
+ "on_exit": [require_search],
+ },
+)
+
+result = agent.run(
+ messages=[
+ ChatMessage.from_user("What are the latest developments in fusion energy?"),
+ ],
+)
+print(result["last_message"].text)
+```
+
+### Class-based hooks
+
+A hook is any object with a `run(state)` method; it may additionally define `run_async(state)` for true async behavior. Class-based hooks may also implement the optional lifecycle methods `warm_up` / `warm_up_async` and `close` / `close_async`. The Agent calls them from its own `warm_up` / `close`, so a hook can defer opening clients or reading credentials until warm-up and release them on close. Because warm-up runs before every Agent run, a hook should not repeat expensive initialization: return early if the work is already done, as in `if self._client is not None: return`.
+
+When a class-based hook should be serializable (so an Agent using it can be serialized), implement `to_dict` / `from_dict`: store serializable constructor arguments on the hook and rebuild runtime clients from those values.
+
+The example below is an `on_exit` hook that grades the Agent's answer with its own LLM and asks the Agent to improve a weak answer before finishing:
+
+```python
+from typing import Any
+
+from haystack.components.agents import Agent
+from haystack.components.agents.state import State
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.core.serialization import default_from_dict, default_to_dict
+from haystack.dataclasses import ChatMessage
+
+
+class GradeFinalAnswer:
+ """Grade the Agent's answer with an LLM and ask it to improve a weak answer before finishing."""
+
+ def __init__(self, model: str = "gpt-5.4-nano"):
+ self.model = model
+ self._judge = OpenAIChatGenerator(model=self.model)
+
+ def warm_up(self) -> None:
+ # The Agent calls this before every run, but OpenAIChatGenerator.warm_up
+ # creates its client only on the first call, so repeating it is safe and cheap.
+ self._judge.warm_up()
+
+ def close(self) -> None:
+ # Release the judge's client during the Agent's close.
+ self._judge.close()
+
+ def run(self, state: State) -> None:
+ answer = state.data["messages"][-1].text or ""
+ verdict = (
+ self._judge.run(
+ messages=[
+ ChatMessage.from_user(
+ f"Reply with only PASS or FAIL. Is this answer complete?\n\n{answer}",
+ ),
+ ],
+ )["replies"][0].text
+ or ""
+ )
+ if "FAIL" in verdict.upper():
+ state.set(
+ "messages",
+ [
+ ChatMessage.from_user(
+ "Your answer was incomplete. Please improve it.",
+ ),
+ ],
+ )
+ state.set("continue_run", True)
+
+ def to_dict(self) -> dict[str, Any]:
+ return default_to_dict(self, model=self.model)
+
+ @classmethod
+ def from_dict(cls, data: dict[str, Any]) -> "GradeFinalAnswer":
+ return default_from_dict(cls, data)
+
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ hooks={"on_exit": [GradeFinalAnswer()]},
+)
+result = agent.run(messages=[ChatMessage.from_user("Explain how vaccines work.")])
+print(result["last_message"].text)
+```
+
+## Ready-made hooks
+
+Haystack ships several ready-made hooks, each in its own submodule of `haystack.hooks`:
+
+- `CompactionHook` (from `haystack.hooks.compaction`): A `before_llm` hook that shortens an Agent's conversation when it reaches a configured fraction of the model's context window. A `Compactor` determines how the conversation is shortened. See [Context Compaction](./compaction.mdx).
+- `ConfirmationHook` (from `haystack.hooks.human_in_the_loop`): A `before_tool` hook that applies Human-in-the-Loop confirmation strategies to pending tool calls — a human can confirm, modify, or reject the tool calls the model requested before they run. See [Human in the Loop](./human-in-the-loop.mdx).
+- `ToolResultOffloadHook` (from `haystack.hooks.tool_result_offloading`): An `after_tool` hook that offloads tool results to a `ToolResultStore` (such as `FileSystemToolResultStore`) and replaces them in the conversation with a compact pointer, so the next LLM call sees a reference instead of the full result. Per-tool policies (`AlwaysOffload`, `NeverOffload`, `OffloadOverChars`) control which results are offloaded. See [Tool Result Offloading](./tool-result-offloading.mdx).
+- `TokenBudgetHook` (from `haystack.hooks.budget`): A `before_llm` hook that ends the run once its cumulative token usage reaches a configured budget, reporting `"token_budget_exceeded"` as the `exit_reason`. See [Token Budget](./token-budget.mdx).
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/human-in-the-loop.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/human-in-the-loop.mdx
new file mode 100644
index 00000000000..ee56a5f8f5d
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/human-in-the-loop.mdx
@@ -0,0 +1,324 @@
+---
+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.
+
+
+
+| | |
+| --- | --- |
+| **Configured on** | The [`Agent`](./agent.mdx) component, as a `ConfirmationHook` registered under the `before_tool` [hook point](./hooks.mdx) |
+| **Key classes** | `ConfirmationHook`, `BlockingConfirmationStrategy`, `AlwaysAskPolicy`, `AskOncePolicy`, `NeverAskPolicy`, `RichConsoleUI`, `SimpleConsoleUI` |
+| **Import path** | `haystack.hooks.human_in_the_loop` |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/hooks/human_in_the_loop/ |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+HITL is one application of the Agent's general [hooks](./hooks.mdx) mechanism: a `ConfirmationHook` registered under the `before_tool` hook point intercepts the tool calls the model requested before they run, and confirms, modifies, or rejects them by rewriting the conversation in the Agent's `State`.
+
+The HITL system is composed of these layers:
+
+- **`ConfirmationHook`** - the `before_tool` hook that applies your confirmation strategies to pending tool calls. Its `confirmation_strategies` mapping accepts a single tool name, a tuple of tool names, or the wildcard `"*"` that applies to any tool without a more specific entry.
+- **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.
+
+:::info
+Strategies see only the arguments the model produced for a tool call. Values injected from [`State`](./state.mdx) via a tool's `inputs_from_state` mapping are not included in what is presented for confirmation — that injection happens at tool execution time.
+:::
+
+## 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.hooks.human_in_the_loop import (
+ AlwaysAskPolicy,
+ BlockingConfirmationStrategy,
+ ConfirmationHook,
+ 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],
+ hooks={
+ "before_tool": [
+ ConfirmationHook(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.hooks.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, share one strategy across a group of tools using a tuple key, or set a default for all tools with the wildcard `"*"` (applied to any tool without a more specific entry):
+
+```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(),
+)
+
+confirmation_hook = ConfirmationHook(
+ 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
+ },
+)
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-mini"),
+ tools=[send_email, delete_record, update_record, search],
+ hooks={"before_tool": [confirmation_hook]},
+)
+```
+
+### 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.hooks.human_in_the_loop.types`:
+
+```python
+from haystack.hooks.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.hooks.human_in_the_loop.types import ConfirmationPolicy
+from haystack.hooks.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 receives per-request resources - a Redis client and an async event queue - at runtime. Pass such resources via the generic `hook_context` run argument (`agent.run(messages=[...], hook_context={"redis": client})`). `ConfirmationHook` reads this dict from state with `state.data["hook_context"]` (not `state.get`, which returns a deep copy that fails for live resources like clients and queues - see [Hooks](./hooks.mdx)) and passes it to each strategy's `run()` as the `confirmation_strategy_context` keyword argument, which is how a custom strategy receives the Redis client and event queue:
+
+- 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.hooks.human_in_the_loop.types` to build your own interface - for example, a web-based approval queue:
+
+```python
+from haystack.hooks.human_in_the_loop.types import ConfirmationUI
+from haystack.hooks.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-3.2-unstable/pipeline-components/agents-1/state.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/state.mdx
new file mode 100644
index 00000000000..cf3af513e0c
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/state.mdx
@@ -0,0 +1,424 @@
+---
+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.
+
+:::info Reserved keys
+The `Agent` manages some state keys itself and rejects them in a user-provided `state_schema` with a `ValueError`:
+
+- The run-metadata keys `step_count`, `token_usage`, `tool_call_counts`, and `exit_reason`, which the Agent populates automatically during a run: tools and hooks can read them from the live `State`, and they are returned in the result dictionary. `exit_reason` reports why the Agent stopped (`"text"`, `"length"`, `"content_filter"`, the name of the tool that triggered a tool exit condition, `"max_agent_steps"`, or a custom reason a hook set through `stop_run`).
+- The hook-facing keys `continue_run` (set by an `on_exit` hook to keep the Agent running), `stop_run` (set by any hook to stop the run, read before each LLM call and used as the `exit_reason`), `tools` (the tools available in the current step, for hooks to inspect), `hook_context` (the request-scoped resources passed to `Agent.run(hook_context={...})`), and `context_tokens` (an approximate count of the tokens currently in the context window, refreshed after each LLM call for hooks to read — for example, to trigger context compaction). Unlike the run-metadata keys, these are not returned in the result dictionary.
+
+If one of your state keys clashes, rename it (for example, `my_token_usage`).
+:::
+
+### 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 Agent 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-3.2-unstable/pipeline-components/agents-1/token-budget.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/token-budget.mdx
new file mode 100644
index 00000000000..e95b1a7cb13
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/token-budget.mdx
@@ -0,0 +1,118 @@
+---
+title: "Token Budget"
+id: token-budget
+slug: "/token-budget"
+description: "Use TokenBudgetHook to stop an Agent run when its cumulative token usage reaches a configured threshold."
+---
+
+# Token Budget
+
+`TokenBudgetHook` lets you limit the token usage of an Agent run. When the configured threshold is reached, the Agent stops before its next LLM call. The messages collected up to that point remain available.
+
+
+
+| | |
+| --- | --- |
+| **Configured on** | The [`Agent`](./agent.mdx) component, as a `TokenBudgetHook` registered under the `before_llm` [hook point](./hooks.mdx) |
+| **Key classes** | `TokenBudgetHook` |
+| **Import path** | `haystack.hooks.budget` |
+| **API reference** | [Hooks](/reference/hooks-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/hooks/budget/ |
+| **Package name** | `haystack-ai` |
+
+
+
+:::warning
+`TokenBudgetHook` is experimental. Its API can change in any release, without following the usual deprecation policy.
+:::
+
+## Overview
+
+A token budget is one use of the Agent's general [hooks](./hooks.mdx) mechanism. Registered under `before_llm`, `TokenBudgetHook` compares the cumulative `token_usage` in the Agent's [`State`](./state.mdx) with the configured threshold before every LLM call.
+
+When usage reaches or exceeds the threshold, the hook sets `stop_run`. The Agent ends the run without making another LLM call and sets `exit_reason` to `"token_budget_exceeded"`.
+
+## What the budget covers
+
+The budget applies to the `token_usage` accumulated from the Agent's chat generator replies. Calls made by tools or other hooks are not counted. For example, if a tool makes its own LLM call, the tokens used by that call do not count toward the Agent's budget.
+
+Because the hook checks usage before each LLM call, the call that takes the total past the threshold has already completed. The final usage can therefore exceed `max_total_tokens` by the cost of one LLM call.
+
+## Usage
+
+### Basic setup
+
+Register the hook under `before_llm` and set the token threshold with `max_total_tokens`. The threshold below is low enough to stop the research task before the Agent completes its report:
+
+```python
+import random
+from typing import Annotated
+
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.hooks.budget import TokenBudgetHook
+from haystack.tools import tool
+
+FACTS = [
+ "Capybaras are the largest living rodents, weighing up to 65 kg. ",
+ "Capybaras are highly social and live in groups of ten to twenty. ",
+ "Capybaras are excellent swimmers and can stay underwater for five minutes. ",
+ "Capybaras are famously relaxed and often share space with birds and monkeys. ",
+]
+
+
+@tool
+def search(query: Annotated[str, "The search query"]) -> str:
+ """Search the web."""
+ # Placeholder: would call a real search API
+ # Repeat the result to simulate a longer search response
+ return random.choice(FACTS) * 20
+
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5-mini"),
+ tools=[search],
+ system_prompt="You are a research assistant. Search one aspect at a time before answering.",
+ hooks={"before_llm": [TokenBudgetHook(max_total_tokens=3_000)]},
+)
+agent.warm_up()
+
+result = agent.run(
+ messages=[
+ ChatMessage.from_user(
+ "Research capybaras: size, social life, swimming and temperament."
+ )
+ ]
+)
+
+print(result["exit_reason"])
+# >> token_budget_exceeded
+```
+
+The Agent stops partway through its research and preserves the messages collected so far. With a higher threshold, it can complete the report and return `"text"` as its `exit_reason`.
+
+### Adding a final message
+
+When the budget stops a run, the last message may be a tool result rather than a final answer. Set `add_final_message=True` to append an assistant message explaining why the run ended. This message then becomes `last_message`:
+
+```python
+TokenBudgetHook(max_total_tokens=3_000, add_final_message=True)
+```
+
+To customize the message or handle other exit reasons such as `max_agent_steps`, use an `after_run` hook. It runs after the Agent ends, regardless of its exit reason:
+
+```python
+from haystack.components.agents.state import State
+from haystack.dataclasses import ChatMessage
+from haystack.hooks import hook
+
+
+@hook
+def explain_stop(state: State) -> None:
+ if state.get("exit_reason") == "token_budget_exceeded":
+ state.set(
+ "messages",
+ [ChatMessage.from_assistant("I ran out of budget before finishing.")],
+ )
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/tool-result-offloading.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/tool-result-offloading.mdx
new file mode 100644
index 00000000000..8a140a33f92
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/agents-1/tool-result-offloading.mdx
@@ -0,0 +1,254 @@
+---
+title: "Tool Result Offloading"
+id: tool-result-offloading
+slug: "/tool-result-offloading"
+description: "Tool result offloading writes large tool results to a store and replaces them in the conversation with a compact pointer, keeping the Agent's context window small."
+---
+
+# Tool Result Offloading
+
+Tool result offloading writes selected tool results to a store and replaces them in the conversation with a compact pointer — a reference plus a short preview — so the next LLM call sees a reference instead of the full result.
+This keeps the context window small when tools return large outputs (web pages, file contents, query results), and it is a step towards letting an Agent operate on offloaded results with follow-up tools, such as a file-reading tool that opens the referenced files.
+
+
+
+| | |
+| --- | --- |
+| **Configured on** | The [`Agent`](./agent.mdx) component, as a `ToolResultOffloadHook` registered under the `after_tool` [hook point](./hooks.mdx) |
+| **Key classes** | `ToolResultOffloadHook`, `FileSystemToolResultStore`, `AlwaysOffload`, `NeverOffload`, `OffloadOverChars` |
+| **Import path** | `haystack.hooks.tool_result_offloading` |
+| **API reference** | [Hooks](/reference/hooks-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/hooks/tool_result_offloading/ |
+| **Package name** | `haystack-ai` |
+
+
+
+## Overview
+
+Tool result offloading is one application of the Agent's general [hooks](./hooks.mdx) mechanism: a `ToolResultOffloadHook` registered under the `after_tool` hook point runs after each step's tools execute and rewrites the freshly produced tool-result messages in the Agent's [`State`](./state.mdx). It only considers the current step's results; earlier conversation history is left untouched.
+
+The system is composed of these layers:
+
+- **`ToolResultOffloadHook`** - the `after_tool` hook that applies your offload strategies to fresh tool results. Its `offload_strategies` mapping accepts a single tool name, a tuple of tool names, or the wildcard `"*"` that applies to any tool without a more specific entry.
+- **Policy** - decides *whether* a given result is offloaded. Built-in policies: `AlwaysOffload`, `NeverOffload`, `OffloadOverChars`.
+- **Store** - decides *where* the full result lives. The built-in `FileSystemToolResultStore` writes results to the local file system.
+
+When a result is offloaded, the hook writes each part of it to the store and rebuilds the message with a compact pointer in its place. For example:
+
+```
+Tool result offloaded to text (18234 characters) at '/abs/path/tool_results/2_search_call-123.txt'. Preview: Fusion startups reported...
+```
+
+The pointer carries the store reference, the original size, and, for text, a preview of the first `preview_chars` characters (200 by default, configurable on the hook), so the model knows roughly what was offloaded and where to find it.
+
+A result made of several parts — any mix of text, images, and files — gets one store entry and one pointer line per part:
+
+```
+Tool result offloaded to 3 files:
+1. text (412 characters) at '/abs/path/tool_results/2_fetch_call-123_0.txt'. Preview: Quarterly report attached...
+2. image/png (48210 bytes) at '/abs/path/tool_results/2_fetch_call-123_1.png'
+3. application/pdf named 'q3.pdf' (1048576 bytes) at '/abs/path/tool_results/2_fetch_call-123_2.pdf'
+```
+
+Images and files are stored as raw bytes, decoded from their base64 payload. A base64 payload is a costly way to carry a file through a conversation, so moving one out can free up a substantial part of the context window.
+
+## Usage
+
+### Basic setup
+
+The example below offloads any tool result longer than 4,000 characters to files under a local `tool_results` directory:
+
+```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.hooks.tool_result_offloading import (
+ FileSystemToolResultStore,
+ OffloadOverChars,
+ ToolResultOffloadHook,
+)
+from haystack.tools import tool
+
+
+@tool
+def search(query: Annotated[str, "The search query"]) -> str:
+ """Search the web and return the (potentially large) results."""
+ # Placeholder: would call a real search API
+ return f"... large result for {query} ..."
+
+
+offload_hook = ToolResultOffloadHook(
+ store=FileSystemToolResultStore(root="tool_results"),
+ offload_strategies={"*": OffloadOverChars(4000)},
+)
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+ tools=[search],
+ hooks={"after_tool": [offload_hook]},
+)
+
+result = agent.run(messages=[ChatMessage.from_user("Summarize today's tech news")])
+```
+
+### Configuring what gets offloaded per tool
+
+Each key in `offload_strategies` may be a single tool name, a tuple of tool names sharing one policy, or the wildcard `"*"`. More specific keys win over `"*"`, and a tool with no matching key (and no `"*"`) is never offloaded:
+
+```python
+from haystack.hooks.tool_result_offloading import (
+ AlwaysOffload,
+ FileSystemToolResultStore,
+ NeverOffload,
+ OffloadOverChars,
+ ToolResultOffloadHook,
+)
+
+offload_hook = ToolResultOffloadHook(
+ store=FileSystemToolResultStore(root="tool_results"),
+ offload_strategies={
+ "web_search": AlwaysOffload(), # force offload
+ "get_time": NeverOffload(), # opt out of the wildcard default
+ ("read_file", "list_dir"): OffloadOverChars(4000), # tuple key: shared policy
+ "*": OffloadOverChars(8000), # default for any unlisted tool
+ },
+)
+```
+
+### What is offloaded
+
+The hook only offloads **successful** tool results:
+
+- Error results — including rejections produced by a `before_tool` [Human-in-the-Loop](./human-in-the-loop.mdx) hook — are always left in context, so the model sees what went wrong.
+- Text, image, and file results are all offloaded. Each part of a result gets its own store entry, so every text, image, and file stays usable on its own.
+- Image and file content only goes to a store that declares `supports_binary_content`. With a text-only store, a result carrying an image or a file stays in context and a warning is logged.
+- The file extension of an image or file comes from its `filename` when it has one, and from its `mime_type` otherwise (falling back to `.bin` when neither yields an extension).
+- Policies see the result as the text and base64 payloads of all its parts joined together.
+- Each result is offloaded at most once, even though the hook runs on every tool step. This also means two offload hooks registered under `after_tool` won't offload each other's pointers.
+
+## Policies
+
+Policies control *whether* a result is offloaded.
+
+| Policy | Behavior |
+| --- | --- |
+| `AlwaysOffload` | Offload every result of the tool it is assigned to |
+| `NeverOffload` | Never offload - keep the full result in context (useful to opt a tool out of a wildcard default) |
+| `OffloadOverChars(threshold)` | Offload only when the result is longer than `threshold` characters |
+
+### Custom policy
+
+Subclass the `OffloadPolicy` protocol from `haystack.hooks.tool_result_offloading` for custom conditions. A policy needs a `should_offload` method, which receives the tool name, the result text, and the Agent's live [`State`](./state.mdx), so it can also decide based on run context:
+
+```python
+from haystack.components.agents.state import State
+from haystack.hooks.tool_result_offloading import OffloadPolicy
+
+
+class OffloadLateSteps(OffloadPolicy):
+ """Offload results only once the run is several steps deep and context pressure builds up."""
+
+ def should_offload(self, tool_name: str, result: str, state: State) -> bool:
+ return state.data.get("step_count", 0) >= 3 and len(result) > 1000
+```
+
+The protocol provides default `to_dict` / `from_dict` implementations, so a policy like this one, whose constructor takes no arguments, is serializable as-is. A policy with constructor arguments should implement both methods itself, following `OffloadOverChars` as an example.
+
+## Stores
+
+### `FileSystemToolResultStore`
+
+`FileSystemToolResultStore(root=...)` writes each offloaded result to a file under its root directory and returns the absolute file path as the reference. The directory is created on first write. Store keys are derived from the step count, tool name, and tool call ID (for example `2_search_call-123.txt`), plus the position of the part within the result when it spans several entries (`2_search_call-123_1.png`), so results from different tools and steps do not collide. A key that would resolve outside the root directory is rejected.
+
+Text is written UTF-8 encoded and read back as a string; images and files are written as raw bytes and read back as `bytes`.
+
+### Custom store
+
+Subclass the `ToolResultStore` protocol to target other backends, such as object storage or an isolated sandbox file system. A store needs two methods: `write(key=..., content=...)` persists the content and returns a reference string, and `read(reference)` resolves that reference back to the content. Only the store interprets a reference — everyone else passes it back to `read` unchanged:
+
+```python
+from haystack.hooks.tool_result_offloading import ToolResultStore
+
+
+class InMemoryToolResultStore(ToolResultStore):
+ """Keep offloaded results in a dict - useful for tests."""
+
+ def __init__(self) -> None:
+ self._data: dict[str, str] = {}
+
+ def write(self, *, key: str, content: str) -> str:
+ self._data[key] = content
+ return key
+
+ def read(self, reference: str) -> str:
+ return self._data[reference]
+```
+
+A store like this one only ever receives text: `supports_binary_content` defaults to `False`, so the hook leaves image and file results in context rather than handing it bytes it cannot write. A store that can hold bytes sets the flag and widens both signatures:
+
+```python
+class BinaryCapableStore(ToolResultStore):
+ supports_binary_content = True
+
+ def write(self, *, key: str, content: str | bytes) -> str: ...
+
+ def read(self, reference: str) -> str | bytes: ...
+```
+
+Like `OffloadPolicy`, the protocol provides default `to_dict` / `from_dict` implementations covering stores whose constructor takes no arguments; implement both methods for stores with constructor arguments.
+
+### Per-run stores via `hook_context`
+
+The constructor `store` is shared by every run - fine for single-user or local use. In a multi-user server, give each run its own isolated store (for example, a per-session directory) by passing it in the Agent's generic `hook_context` run argument under the key `RESULT_STORE_CONTEXT_KEY`. It overrides the constructor store for that run:
+
+```python
+from haystack.hooks.tool_result_offloading import (
+ RESULT_STORE_CONTEXT_KEY,
+ FileSystemToolResultStore,
+)
+
+per_request_store = FileSystemToolResultStore(root=f"tool_results/{session_id}")
+result = agent.run(
+ messages=[ChatMessage.from_user("...")],
+ hook_context={RESULT_STORE_CONTEXT_KEY: per_request_store},
+)
+```
+
+Isolating the store per run keeps concurrent users from colliding on store keys or reading each other's offloaded results — especially important when a file-reading tool is scoped to the store. The hook itself keeps no mutable state, so a single instance is safe to share across concurrent runs.
+
+## Letting the Agent read offloaded results back
+
+The pointer left in the conversation tells the model where the full result lives, but the model can only act on it if the Agent has a tool that can read from the store. With `FileSystemToolResultStore`, that can be a simple file-reading tool:
+
+```python
+from typing import Annotated
+
+from haystack.tools import tool
+
+
+@tool
+def read_offloaded_result(
+ path: Annotated[str, "Absolute path of an offloaded tool result"],
+) -> str:
+ """Read back the full content of an offloaded tool result."""
+ content = FileSystemToolResultStore(root="tool_results").read(path)
+ if isinstance(content, bytes):
+ return f"'{path}' holds {len(content)} bytes of binary content and cannot be read as text."
+ return content
+```
+
+With this tool available, the Agent can work with a compact conversation and selectively re-read only the offloaded results it actually needs — instead of carrying every full result in context on every LLM call. An offloaded image or file comes back as `bytes`; to put one back in front of the model, a tool can return it as an `ImageContent` or `FileContent` block instead of as text.
+
+## Serialization
+
+`ToolResultOffloadHook` implements `to_dict` / `from_dict`, so an Agent using it can be serialized as long as the configured store and policies are serializable too. The built-in store and policies all are; for custom ones, see the notes in [Policies](#custom-policy) and [Stores](#custom-store) above.
+
+## Additional References
+
+📖 Related docs:
+
+- [Hooks](./hooks.mdx) — the general mechanism behind this feature, including the `after_tool` hook point
+- [Human in the Loop](./human-in-the-loop.mdx) — another ready-made hook, intercepting tool calls for human review
+- [State](./state.mdx) — the live run state hooks and policies receive
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/audio.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/audio.mdx
new file mode 100644
index 00000000000..f125672fa1c
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/audio.mdx
@@ -0,0 +1,16 @@
+---
+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 |
+| --- | --- |
+| [FunASRTranscriber](audio/funasrtranscriber.mdx) | Transcribe audio files using FunASR — a local, open-source speech recognition toolkit supporting 50+ languages. |
+| [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-3.2-unstable/pipeline-components/audio/external-integrations-audio.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/audio/external-integrations-audio.mdx
new file mode 100644
index 00000000000..c1ac4ce8945
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/audio/funasrtranscriber.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/audio/funasrtranscriber.mdx
new file mode 100644
index 00000000000..194bdc184ec
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/audio/funasrtranscriber.mdx
@@ -0,0 +1,66 @@
+---
+title: "FunASRTranscriber"
+id: funasrtranscriber
+slug: "/funasrtranscriber"
+description: "Transcribe audio files to Documents using FunASR — a local, open-source speech recognition toolkit supporting 50+ languages."
+---
+
+# FunASRTranscriber
+
+Transcribe audio files to Haystack Documents using FunASR — a local, open-source speech recognition toolkit supporting 50+ languages.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | As the first component in an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of audio file paths (`str` or `Path`) or `ByteStream` objects |
+| **Output variables** | `documents`: A list of Haystack Documents, one per source, with transcript text in `content` |
+| **API reference** | [FunASR integration](/reference/integrations-funasr) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/funasr/src/haystack_integrations/components/audio/funasr/transcriber.py |
+
+
+
+## Overview
+
+`FunASRTranscriber` uses [FunASR](https://github.com/modelscope/FunASR), an open-source speech recognition toolkit from Alibaba DAMO Academy, to transcribe audio files into Haystack `Document` objects. It runs entirely locally — no API key required.
+
+The default model is `iic/SenseVoiceSmall`, a multilingual model supporting 50+ languages that is 5–10x faster than Whisper. Models are downloaded from ModelScope on first use and cached in `~/.cache/modelscope`.
+
+The component accepts audio file paths (`str` or `Path`) as well as `ByteStream` objects. The model is loaded into memory automatically the first time the component runs.
+
+## Usage
+
+### On its own
+
+```python
+from haystack_integrations.components.audio.funasr import FunASRTranscriber
+
+transcriber = FunASRTranscriber()
+
+result = transcriber.run(sources=["speech.wav"])
+print(result["documents"][0].content)
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.fetchers import LinkContentFetcher
+from haystack_integrations.components.audio.funasr import FunASRTranscriber
+
+pipe = Pipeline()
+pipe.add_component("fetcher", LinkContentFetcher())
+pipe.add_component("transcriber", FunASRTranscriber())
+
+pipe.connect("fetcher", "transcriber")
+
+result = pipe.run(
+ data={
+ "fetcher": {
+ "urls": ["https://example.com/interview.wav"],
+ },
+ },
+)
+print(result["transcriber"]["documents"][0].content)
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/audio/localwhispertranscriber.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/audio/localwhispertranscriber.mdx
new file mode 100644
index 00000000000..5e4550e2a45
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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** | [Whisper](/reference/integrations-whisper) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/whisper |
+| **Package name** | `whisper-haystack` |
+
+
+
+## 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/integrations-whisper).
+
+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.
+
+The `LocalWhisperTranscriber` is part of the `whisper-haystack` integration package. To work with it, install the package along with [Whisper](https://github.com/openai/whisper) (which also pulls in torch) using the following commands:
+
+```shell
+pip install whisper-haystack
+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_integrations.components.audio.whisper 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_integrations.components.audio.whisper 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-3.2-unstable/pipeline-components/audio/remotewhispertranscriber.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/audio/remotewhispertranscriber.mdx
new file mode 100644
index 00000000000..7f61d2c17e4
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/audio/remotewhispertranscriber.mdx
@@ -0,0 +1,104 @@
+---
+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** | [Whisper](/reference/integrations-whisper) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/whisper |
+| **Package name** | `whisper-haystack` |
+
+
+
+## Overview
+
+The `RemoteWhisperTranscriber` is part of the `whisper-haystack` integration package. Install it with:
+
+```shell
+pip install whisper-haystack
+```
+
+`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-to-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_integrations.components.audio.whisper 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/integrations-whisper).
+
+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_integrations.components.audio.whisper 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_integrations.components.audio.whisper 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-3.2-unstable/pipeline-components/builders.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/builders.mdx
new file mode 100644
index 00000000000..49b72d883c2
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/builders/answerbuilder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/builders/answerbuilder.mdx
new file mode 100644
index 00000000000..6b4d38ae897
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/builders/chatpromptbuilder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/builders/chatpromptbuilder.mdx
new file mode 100644
index 00000000000..ae32324b02b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/builders/chatpromptbuilder.mdx
@@ -0,0 +1,478 @@
+---
+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. By default, `required_variables` is set to `"*"`, so all variables in the template are required: if any of them is missing at runtime, the component raises an error and halts execution.
+
+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:
+ - Use `"*"` (the default) to mark all variables in the template as required, or
+ - Pass a list of required variable names (such as `["name"]`) to make only those required; the remaining variables are optional, or
+ - Pass an empty list (`[]`) or `None` to make all variables optional. Setting `None` explicitly logs a warning, since missing variables are then silently replaced with empty strings, which can lead to unintended behavior, especially in complex pipelines.
+
+- `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")
+# >> "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.
+
+#### The `insert` Tag
+
+String templates also support an `{% insert %}` tag. It is a placeholder that evaluates an expression to a `ChatMessage` or a list of `ChatMessage` objects and expands it into the prompt, so messages provided at runtime can be interleaved with literal `{% message %}` blocks. For example, you can wrap the runtime messages with a system message above and a templated user message below, then pass the messages (and any template variables) at run time:
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = """
+{% message role="system" %}You are a helpful assistant.{% endmessage %}
+{% insert messages %}
+{% message role="user" %}{{ query }}{% endmessage %}
+"""
+
+builder = ChatPromptBuilder(template=template)
+result = builder.run(
+ messages=[ChatMessage.from_user("Hi"), ChatMessage.from_assistant("Hello!")],
+ query="What's the weather?",
+)
+# result["prompt"] -> [system, user "Hi", assistant "Hello!", user "What's the weather?"]
+```
+
+All content types (tool calls, tool call results, images, reasoning, `name`, and `meta`) round trip without loss. A missing or empty value expands to nothing.
+
+The expression can be a plain variable (`{% insert messages %}`), a slice or index (`{% insert messages[-1:] %}`, `{% insert messages[-1] %}`), or a combination of variables (`{% insert previous + current %}`). Multiple `{% insert %}` tags can be used in a single template, so the runtime messages can be split, reordered, or repeated across different positions.
+
+### Jinja2 Time Extension
+
+`ChatPromptBuilder` 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: '*'
+ 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-3.2-unstable/pipeline-components/builders/promptbuilder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/builders/promptbuilder.mdx
new file mode 100644
index 00000000000..d29656a5b2e
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/builders/promptbuilder.mdx
@@ -0,0 +1,312 @@
+---
+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. By default, `required_variables` is set to `"*"`, so all variables in the template are required: if any of them is missing at runtime, the component raises an error and halts execution.
+
+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:
+ - Use `"*"` (the default) to mark all variables in the template as required, or
+ - Pass a list of required variable names (such as `["query"]`) to make only those required; the remaining variables are optional, or
+ - Pass an empty list (`[]`) or `None` to make all variables optional. Setting `None` explicitly logs a warning, since missing variables are then silently replaced with empty strings, which can lead to unintended behavior, especially in complex pipelines.
+
+- `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 required (the default, equivalent to required_variables="*")
+builder = PromptBuilder(
+ template="Hello {{name}}! {{greeting}}",
+)
+
+# Some variables required
+builder = PromptBuilder(
+ template="Hello {{name}}! {{greeting}}",
+ required_variables=["name"], # 'greeting' becomes optional
+)
+
+# All variables optional (missing ones default to empty string)
+builder = PromptBuilder(
+ template="Hello {{name}}! {{greeting}}",
+ required_variables=[], # explicit None also works but logs a warning
+)
+```
+
+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.chat import OpenAIChatGenerator
+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=OpenAIChatGenerator(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
+ timeout: null
+ tools: null
+ tools_strict: false
+ type: haystack.components.generators.chat.openai.OpenAIChatGenerator
+ prompt_builder:
+ init_parameters:
+ required_variables: '*'
+ 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.messages
+ 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-3.2-unstable/pipeline-components/caching/cachechecker.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/caching/cachechecker.mdx
new file mode 100644
index 00000000000..ae74b8efded
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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** | [Langdetect](/reference/integrations-langdetect) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/langdetect |
+| **Package name** | `langdetect-haystack` |
+
+
+
+## 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-haystack` package to use the `DocumentLanguageClassifier` component:
+
+```shell
+pip install langdetect-haystack
+```
+
+### On its own
+
+Below, we are using the `DocumentLanguageClassifier` to classify English and German documents:
+
+The examples on this page use Sentence Transformers embedders from the `sentence-transformers-haystack` package. Install it to run the examples:
+
+```shell
+pip install sentence-transformers-haystack
+```
+
+```python
+from haystack_integrations.components.classifiers.langdetect 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_integrations.components.classifiers.langdetect import (
+ DocumentLanguageClassifier,
+)
+from haystack_integrations.components.embedders.sentence_transformers 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-3.2-unstable/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx
new file mode 100644
index 00000000000..7a067ba0c49
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx
@@ -0,0 +1,115 @@
+---
+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** | [Transformers](/reference/integrations-transformers) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/transformers | +| **Package name** | `transformers-haystack` | + +
+
+## 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
+
+Install the `transformers-haystack` package to use the `TransformersZeroShotDocumentClassifier`:
+
+```shell
+pip install transformers-haystack
+```
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.classifiers.transformers 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_integrations.components.classifiers.transformers 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(name="retriever", instance=retriever)
+pipeline.add_component(name="document_classifier", instance=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-3.2-unstable/pipeline-components/connectors.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors.mdx
new file mode 100644
index 00000000000..3ffb6ecd69c
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors.mdx
@@ -0,0 +1,27 @@
+---
+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 |
+| --- | --- |
+| [DatadogConnector](connectors/datadogconnector.mdx) | Enables tracing in Haystack pipelines using Datadog. |
+| [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. |
+| [OAuthTokenResolver](connectors/oauthtokenresolver.mdx) | Resolves an OAuth access token at runtime and emits it for downstream components. |
+| [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. |
+| [OpenTelemetryConnector](connectors/opentelemetryconnector.mdx) | Enables tracing in Haystack pipelines using OpenTelemetry. |
+| [WeaveConnector](connectors/weaveconnector.mdx) | Connects you to Weights & Biases Weave framework for tracing and monitoring your pipeline components. |
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/datadogconnector.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/datadogconnector.mdx
new file mode 100644
index 00000000000..eaabbd1dc68
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/datadogconnector.mdx
@@ -0,0 +1,202 @@
+---
+title: "DatadogConnector"
+id: datadogconnector
+slug: "/datadogconnector"
+description: "Learn how to work with Datadog in Haystack."
+---
+
+# DatadogConnector
+
+Learn how to work with Datadog in Haystack.
+
+`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** | [Transformers](/reference/integrations-transformers) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/transformers | +| **Package name** | `transformers-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Anywhere, as it’s not connected to other components |
+| **Mandatory init variables** | None. The connection to the Datadog backend is created at initialization time |
+| **Output variables** | `name`: The name of the tracing component |
+| **API reference** | [datadog](/reference/integrations-datadog) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/datadog |
+| **Package name** | `datadog-haystack` |
+
+
+
+## Overview
+
+`DatadogConnector` integrates tracing capabilities into Haystack pipelines using [Datadog](https://www.datadoghq.com/), through [Datadog's tracing library `ddtrace`](https://ddtrace.readthedocs.io/en/stable/). It captures detailed information about pipeline runs, like API calls, context data, prompts, and more, so you can see the complete trace of your pipeline execution in Datadog.
+
+Datadog tracing is enabled as soon as the `DatadogConnector` is initialized, so you only need to add it to your pipeline – it does not need to be connected to other components or to run to take effect.
+
+You can optionally pass a `name` to identify this tracing component (it defaults to `datadog`).
+
+### Prerequisites
+
+These are the things that you need before working with the `DatadogConnector`:
+
+1. A way to receive traces, such as a running [Datadog Agent](https://docs.datadoghq.com/agent/). `ddtrace` sends traces to the Datadog Agent at `localhost:8126` by default.
+2. Set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true` – this will enable content tracing (inputs and outputs) in your pipelines.
+3. Configure `ddtrace` through the standard mechanisms, for example the `DD_SERVICE`, `DD_ENV`, and `DD_VERSION` environment variables, or by running your application with the `ddtrace-run` command. See the [ddtrace documentation](https://ddtrace.readthedocs.io/en/stable/) for more details.
+
+### Installation
+
+First, install the `datadog-haystack` package to use the `DatadogConnector`:
+
+```shell
+pip install datadog-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 environment 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 `DatadogConnector` to the pipeline as a _tracer_. Each pipeline run will produce a trace that includes the entire execution context, including prompts, completions, and metadata. You can then view the traces in your Datadog dashboard. + +```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.datadog import DatadogConnector + +pipe = Pipeline() +pipe.add_component("tracer", DatadogConnector("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]) +``` + +### With an Agent + +```python +import os + +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.datadog import DatadogConnector + + +@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" + result = a / b + else: + return f"Error: Unknown operation '{operation}'" + + return f"The result of {a} {operation} {b} is {result}" + + +# Create the chat generator +chat_generator = OpenAIChatGenerator() + +# Create the agent with tools +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"], +) + +# Create the DatadogConnector for tracing +datadog_connector = DatadogConnector("Agent Example") + +# Build the pipeline +pipe = Pipeline() +pipe.add_component("tracer", datadog_connector) +pipe.add_component("agent", agent) + +# Run the pipeline +response = pipe.run( + data={ + "agent": { + "messages": [ + ChatMessage.from_user( + "What's the weather in Berlin and calculate 15 + 27?", + ), + ], + }, + "tracer": {}, + }, +) + +# Display results +print("Agent Response:") +print(response["agent"]["last_message"].text) +``` + +### Configuring the tracing backend directly + +Instead of using the `DatadogConnector`, you can configure the Datadog tracing backend directly by enabling a `DatadogTracer`. Make sure to set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable before importing any Haystack components. + +```python +import ddtrace + +from haystack import tracing +from haystack_integrations.tracing.datadog import DatadogTracer + +tracing.enable_tracing(DatadogTracer(ddtrace.tracer)) +``` diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/external-integrations-connectors.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/external-integrations-connectors.mdx new file mode 100644 index 00000000000..cb22c9473e9 --- /dev/null +++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/connectors/githubfileeditor.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/githubfileeditor.mdx new file mode 100644 index 00000000000..fc80a5c2430 --- /dev/null +++ b/docs-website/versioned_docs/version-3.2-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. + +
+
+| | |
+| --- | --- |
+| **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-3.2-unstable/pipeline-components/connectors/githubissuecommenter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/githubissuecommenter.mdx
new file mode 100644
index 00000000000..f23acda1433
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/connectors/githubissueviewer.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/githubissueviewer.mdx
new file mode 100644
index 00000000000..4758b2a7bed
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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.
+
+Pass the token during initialization via the `github_token` parameter, for example `github_token=Secret.from_env_var("GITHUB_TOKEN")`. This component has no default environment variable for the token.
+
+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-3.2-unstable/pipeline-components/connectors/githubprcreator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/githubprcreator.mdx
new file mode 100644
index 00000000000..e80841cc12f
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/connectors/githubrepoforker.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/githubrepoforker.mdx
new file mode 100644
index 00000000000..6f8f9d26346
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/connectors/githubrepoviewer.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/githubrepoviewer.mdx
new file mode 100644
index 00000000000..c4cc9c306b1
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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.
+
+Pass the token during initialization via the `github_token` parameter, for example `github_token=Secret.from_env_var("GITHUB_TOKEN")`. This component has no default environment variable for the token.
+
+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
+reader = JinaReaderConnector(mode="read", 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
`trace_id`: The ID of the trace | +| **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
`trace_id`: The ID of the trace | +| **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.components.connectors.langfuse import LangfuseConnector +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 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( + "Custom Handler Example", span_handler=CustomSpanHandler() +) +``` diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/oauthtokenresolver.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/oauthtokenresolver.mdx new file mode 100644 index 00000000000..ac1ec63fdc0 --- /dev/null +++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/oauthtokenresolver.mdx @@ -0,0 +1,155 @@ +--- +title: "OAuthTokenResolver" +id: oauthtokenresolver +slug: "/oauthtokenresolver" +description: "Resolves an OAuth access token at pipeline runtime and emits it for downstream components such as the SharePoint and Google Drive retrievers and fetchers." +--- + +# OAuthTokenResolver + +Resolves an OAuth access token at pipeline runtime and emits it for downstream components such as the SharePoint and Google Drive retrievers and fetchers. + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | At the start of a pipeline, feeding `access_token` into downstream components such as [`MSSharePointRetriever`](../retrievers/mssharepointretriever.mdx) or [`GoogleDriveRetriever`](../retrievers/googledriveretriever.mdx) |
+| **Mandatory init variables** | `token_source`: The strategy that resolves the access token, for example `OAuthRefreshTokenSource` |
+| **Mandatory run variables** | None for config-only sources. `subject_token`: a controller-injected per-request credential, mandatory only when the source requires it (for example `OAuthTokenExchangeSource`) |
+| **Output variables** | `access_token`: A bearer token string |
+| **API reference** | [OAuth](/reference/integrations-oauth) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/oauth |
+| **Package name** | `oauth-haystack` |
+
+
+
+## Overview
+
+`OAuthTokenResolver` resolves an OAuth access token when the pipeline runs and emits it on the `access_token` output socket. Downstream components – such as [`MSSharePointRetriever`](../retrievers/mssharepointretriever.mdx), [`MSSharePointFetcher`](../fetchers/mssharepointfetcher.mdx), [`GoogleDriveRetriever`](../retrievers/googledriveretriever.mdx), and [`GoogleDriveFetcher`](../fetchers/googledrivefetcher.mdx) – consume the token through a normal connection and never need to know how it was obtained.
+
+The resolver itself is a thin wrapper. The actual work of getting a token is delegated to a pluggable **token source** that decides *where* the token comes from. This separation lets you swap authentication strategies (refresh-token grant, per-request token exchange, or a static long-lived token) without changing the rest of your pipeline.
+
+### Token sources
+
+You pass a token source to the resolver through the `token_source` parameter. All sources are importable from `haystack_integrations.utils.oauth`.
+
+| Source | Use it when | Per-request input |
+| --- | --- | --- |
+| `OAuthRefreshTokenSource` | You have a single, fixed identity backed by a stored refresh token and want the source to exchange it for short-lived access tokens and cache them. | None |
+| `OAuthTokenExchangeSource` | You serve multiple users (or run multiple replicas) and want to exchange an incoming per-request user assertion for a downstream token, with no persistent storage. Implements RFC 8693 token exchange and Microsoft's on-behalf-of flow. | `subject_token` |
+| `OAuthStaticTokenSource` | Your provider issues a non-expiring token that you manage out of band (for example Slack or Notion). | None |
+
+When the configured source needs a per-request credential (`OAuthTokenExchangeSource` sets `requires_subject_token = True`), the resolver declares a **mandatory** `subject_token` run input. This is a controller-injected credential – for example an incoming user assertion – not a value chosen by an end user. For config-only sources (`OAuthRefreshTokenSource`, `OAuthStaticTokenSource`), the resolver declares no run input and acts as a source node.
+
+:::info[Scopes are provider-specific]
+
+The OAuth scopes you request depend on the downstream service. For Microsoft Graph, that means scopes such as `https://graph.microsoft.com/Files.Read.All`; for Google Drive, scopes such as `https://www.googleapis.com/auth/drive.readonly`. Always consult your identity provider's documentation for the exact scope values.
+
+:::
+
+### Installation
+
+Install the OAuth integration with:
+
+```shell
+pip install oauth-haystack
+```
+
+## Usage
+
+### On its own
+
+Resolve a token with a stored refresh token using `OAuthRefreshTokenSource`. The refresh token is read from an environment variable through the [Secret API](../../concepts/secret-management.mdx):
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.connectors.oauth import OAuthTokenResolver
+from haystack_integrations.utils.oauth import OAuthRefreshTokenSource
+
+resolver = OAuthTokenResolver(
+ token_source=OAuthRefreshTokenSource(
+ token_url="https://login.microsoftonline.com/common/oauth2/v2.0/token",
+ client_id="aaa-bbb-ccc",
+ refresh_token=Secret.from_env_var("MS_REFRESH_TOKEN"),
+ scopes=[
+ "https://graph.microsoft.com/Files.Read.All",
+ "offline_access",
+ ],
+ ),
+)
+
+access_token = resolver.run()["access_token"]
+```
+
+For a provider that issues long-lived, non-expiring tokens, use `OAuthStaticTokenSource` instead:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.connectors.oauth import OAuthTokenResolver
+from haystack_integrations.utils.oauth import OAuthStaticTokenSource
+
+resolver = OAuthTokenResolver(
+ token_source=OAuthStaticTokenSource(token=Secret.from_env_var("SERVICE_TOKEN")),
+)
+
+access_token = resolver.run()["access_token"]
+```
+
+For multi-user backends, use `OAuthTokenExchangeSource`. The resolver then requires a per-request `subject_token`:
+
+```python
+from haystack_integrations.components.connectors.oauth import OAuthTokenResolver
+from haystack_integrations.utils.oauth import OAuthTokenExchangeSource
+
+resolver = OAuthTokenResolver(
+ token_source=OAuthTokenExchangeSource(
+ token_url="https://login.microsoftonline.com/
+
+| | |
+| --- | --- |
+| **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** | [OpenAPI](/reference/integrations-openapi) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/openapi |
+| **Package name** | `openapi-haystack` |
+
+
+
+## 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-haystack` package installed:
+
+```shell
+pip install openapi-haystack
+```
+
+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_integrations.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_integrations.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-3.2-unstable/pipeline-components/connectors/openapiserviceconnector.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/openapiserviceconnector.mdx
new file mode 100644
index 00000000000..b63f5af118b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/openapiserviceconnector.mdx
@@ -0,0 +1,150 @@
+---
+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.
+
+:::tip[Consider using MCP instead]
+
+These OpenAPI components are a legacy way to connect Haystack to external APIs. For most use cases, we recommend the [`MCPTool`](../../tools/mcptool.mdx) instead: it is the modern, standardized way to give your pipelines and agents access to external tools and 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** | [OpenAPI](/reference/integrations-openapi) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/openapi | +| **Package name** | `openapi-haystack` | + +
+
+## 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 `openapi-haystack` package with:
+
+```shell
+pip install openapi-haystack
+```
+
+`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.converters import OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.connectors.openapi import OpenAPIServiceConnector
+from haystack_integrations.components.converters.openapi import (
+ OpenAPIServiceToFunctions,
+)
+
+
+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-3.2-unstable/pipeline-components/connectors/opentelemetryconnector.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/opentelemetryconnector.mdx
new file mode 100644
index 00000000000..6cbf9f85cf5
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/opentelemetryconnector.mdx
@@ -0,0 +1,126 @@
+---
+title: "OpenTelemetryConnector"
+id: opentelemetryconnector
+slug: "/opentelemetryconnector"
+description: "Learn how to work with OpenTelemetry in Haystack."
+---
+
+# OpenTelemetryConnector
+
+Learn how to work with OpenTelemetry in Haystack.
+
+`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** | [OpenAPI](/reference/integrations-openapi) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/openapi | +| **Package name** | `openapi-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Anywhere, as it’s not connected to other components |
+| **Mandatory init variables** | None. The tracer is created at initialization time |
+| **Output variables** | `name`: The name of the tracing component |
+| **API reference** | [opentelemetry](/reference/integrations-opentelemetry) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opentelemetry |
+| **Package name** | `opentelemetry-haystack` |
+
+
+
+## Overview
+
+`OpenTelemetryConnector` integrates tracing capabilities into Haystack pipelines using [OpenTelemetry](https://opentelemetry.io/), through the [OpenTelemetry SDK](https://opentelemetry.io/docs/languages/python/). It captures detailed information about pipeline runs, like API calls, context data, prompts, and more, so you can see the complete trace of your pipeline execution in any OpenTelemetry-compatible backend.
+
+OpenTelemetry tracing is enabled as soon as the `OpenTelemetryConnector` is initialized, so you only need to add it to your pipeline – it does not need to be connected to other components or to run to take effect.
+
+You can optionally pass a `name` to identify this tracing component (it defaults to `opentelemetry`).
+
+### Prerequisites
+
+These are the things that you need before working with the `OpenTelemetryConnector`:
+
+1. A configured OpenTelemetry `TracerProvider` with an exporter (for example, an OTLP exporter that sends traces to a collector or a backend). Set up the provider before initializing the connector.
+2. Set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true` – this will enable content tracing (inputs and outputs) in your pipelines.
+3. To add traces at even deeper levels, check out the available [OpenTelemetry instrumentations](https://opentelemetry.io/ecosystem/registry/?s=python), such as `opentelemetry-instrumentation-openai-v2` for tracing OpenAI requests.
+
+### Installation
+
+First, install the `opentelemetry-haystack` package to use the `OpenTelemetryConnector`:
+
+```shell
+pip install opentelemetry-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 environment 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 `OpenTelemetryConnector` to the pipeline as a _tracer_. Each pipeline run will produce a trace that includes the entire execution context, including prompts, completions, and metadata. You can then view the traces in your OpenTelemetry backend. + +```python +import os + +os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true" + +from opentelemetry import trace +from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter +from opentelemetry.sdk.resources import Resource +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import BatchSpanProcessor +from opentelemetry.semconv.resource import ResourceAttributes + +# Configure the OpenTelemetry SDK. A service name is required for most backends. +resource = Resource(attributes={ResourceAttributes.SERVICE_NAME: "haystack"}) +tracer_provider = TracerProvider(resource=resource) +tracer_provider.add_span_processor( + BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")), +) +trace.set_tracer_provider(tracer_provider) + +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.opentelemetry import ( + OpenTelemetryConnector, +) + +pipe = Pipeline() +pipe.add_component("tracer", OpenTelemetryConnector("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]) +``` + +### Configuring the tracing backend directly + +Instead of using the `OpenTelemetryConnector`, you can configure the OpenTelemetry tracing backend directly by enabling an `OpenTelemetryTracer`. Make sure to set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable and configure your `TracerProvider` before importing any Haystack components. + +```python +from opentelemetry import trace + +from haystack import tracing +from haystack_integrations.tracing.opentelemetry import OpenTelemetryTracer + +tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer("my_application"))) +``` diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/weaveconnector.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/connectors/weaveconnector.mdx new file mode 100644 index 00000000000..e54eee950bc --- /dev/null +++ b/docs-website/versioned_docs/version-3.2-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. + +
+
+| | |
+| --- | --- |
+| **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** | AWS credentials are resolved via `Secret` parameters or the default boto3 credential chain (environment variables, AWS config files, IAM roles). |
+| **Mandatory run variables** | `sources`: A list of file paths or `ByteStream` objects |
+| **Output variables** | `documents`: A list of documents
`raw_textract_response`: A list of raw responses from the Textract API | +| **API reference** | [Amazon Textract](/reference/integrations-amazon_textract) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_textract | +| **Package name** | `amazon-textract-haystack` | + +
+
+## Overview
+
+`AmazonTextractConverter` takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and uses AWS Textract to extract text from images and single-page PDFs. Optionally, metadata can be attached to the documents through the `meta` input parameter. You need an active AWS account with access to the Textract service to use this integration. Refer to the [AWS Textract documentation](https://docs.aws.amazon.com/textract/latest/dg/getting-started.html) to set up your AWS credentials and ensure Textract is available in your selected region.
+
+Supported input formats: JPEG, PNG, TIFF, BMP, and single-page PDF (up to 10 MB).
+
+By default, the component uses the standard AWS environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_DEFAULT_REGION`, `AWS_PROFILE`) for authentication. You can also pass these as `Secret` objects at initialization. The component falls back to the default boto3 credential chain if no explicit credentials are provided, which makes it work with IAM roles when running on AWS infrastructure.
+
+### Operation modes
+
+The component switches between two Textract APIs depending on how you configure it:
+
+- **Plain text OCR (`DetectDocumentText`)** – Used when `feature_types` is not set. This is the fastest and cheapest option, extracting raw text from the document.
+- **Structured analysis (`AnalyzeDocument`)** – Used when `feature_types` is set. You can pass any combination of `"TABLES"`, `"FORMS"`, `"SIGNATURES"`, and `"LAYOUT"` to extract richer structural information from the document.
+
+### Natural-language queries
+
+You can pass a list of natural-language questions through the `queries` parameter on `run()`. When queries are provided, the `QUERIES` feature type is added automatically and Textract returns the extracted answers in the raw response. This is useful for pulling specific fields out of forms, invoices, or receipts without writing custom parsing logic.
+
+## Usage
+
+You need to install the `amazon-textract-haystack` integration to use `AmazonTextractConverter`:
+
+```shell
+pip install amazon-textract-haystack
+```
+
+### On its own
+
+Basic usage with plain text OCR:
+
+```python
+from haystack_integrations.components.converters.amazon_textract import (
+ AmazonTextractConverter,
+)
+
+converter = AmazonTextractConverter()
+result = converter.run(sources=["document.png"])
+documents = result["documents"]
+```
+
+Extracting tables and forms with `AnalyzeDocument`:
+
+```python
+from haystack_integrations.components.converters.amazon_textract import (
+ AmazonTextractConverter,
+)
+
+converter = AmazonTextractConverter(feature_types=["TABLES", "FORMS"])
+result = converter.run(sources=["invoice.pdf"])
+documents = result["documents"]
+raw_responses = result["raw_textract_response"]
+```
+
+Using natural-language queries to extract specific fields:
+
+```python
+from haystack_integrations.components.converters.amazon_textract import (
+ AmazonTextractConverter,
+)
+
+converter = AmazonTextractConverter()
+result = converter.run(
+ sources=["receipt.png"],
+ queries=["What is the patient name?", "What is the total due?"],
+)
+documents = result["documents"]
+raw_responses = result["raw_textract_response"]
+```
+
+Passing AWS credentials explicitly:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.converters.amazon_textract import (
+ AmazonTextractConverter,
+)
+
+converter = AmazonTextractConverter(
+ aws_access_key_id=Secret.from_env_var("AWS_ACCESS_KEY_ID"),
+ aws_secret_access_key=Secret.from_env_var("AWS_SECRET_ACCESS_KEY"),
+ aws_region_name=Secret.from_token("us-east-1"),
+)
+result = converter.run(sources=["document.png"])
+```
+
+### In a pipeline
+
+Here's an example of an indexing pipeline that uses Textract to extract text from images and writes the resulting documents to a Document Store:
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.preprocessors import DocumentCleaner, DocumentSplitter
+from haystack.components.writers import DocumentWriter
+from haystack_integrations.components.converters.amazon_textract import (
+ AmazonTextractConverter,
+)
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", AmazonTextractConverter())
+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")
+
+file_names = ["document.png", "invoice.pdf"]
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/azuredocumentintelligenceconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/azuredocumentintelligenceconverter.mdx
new file mode 100644
index 00000000000..d141aefb85b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/azuredocumentintelligenceconverter.mdx
@@ -0,0 +1,109 @@
+---
+title: "AzureDocumentIntelligenceConverter"
+id: azuredocumentintelligenceconverter
+slug: "/azuredocumentintelligenceconverter"
+description: "`AzureDocumentIntelligenceConverter` converts files to Documents using Azure's Document Intelligence service with GitHub Flavored Markdown output for better LLM/RAG integration. It supports PDF, JPEG, PNG, BMP, TIFF, DOCX, XLSX, PPTX, and HTML."
+---
+
+# AzureDocumentIntelligenceConverter
+
+`AzureDocumentIntelligenceConverter` converts files to Documents using Azure's Document Intelligence service with GitHub Flavored Markdown output for better LLM/RAG integration. It supports the following file formats: PDF (both searchable and image-only), JPEG, PNG, BMP, TIFF, DOCX, XLSX, PPTX, and HTML.
+
+`raw_textract_response`: A list of raw responses from the Textract API | +| **API reference** | [Amazon Textract](/reference/integrations-amazon_textract) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_textract | +| **Package name** | `amazon-textract-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 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](/reference/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-3.2-unstable/pipeline-components/converters/azureocrdocumentconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/azureocrdocumentconverter.mdx
new file mode 100644
index 00000000000..48f1b0017b6
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/azureocrdocumentconverter.mdx
@@ -0,0 +1,97 @@
+---
+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](/reference/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** | [Azure Form Recognizer](/reference/integrations-azure_form_recognizer) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_form_recognizer | +| **Package name** | `azure-form-recognizer-haystack` | + +
+
+## 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 leave tables inline in the page text. It creates a separate `Document` for each table, with the table rendered as CSV in the document content and `preceding_context`, `following_context`, and `page` added to its metadata.
+
+## Usage
+
+The `AzureOCRDocumentConverter` is part of the `azure-form-recognizer-haystack` integration package. Install it with:
+
+```shell
+pip install azure-form-recognizer-haystack
+```
+
+### On its own
+
+```python
+from pathlib import Path
+
+from haystack_integrations.components.converters.azure_form_recognizer 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** | [Azure Form Recognizer](/reference/integrations-azure_form_recognizer) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_form_recognizer | +| **Package name** | `azure-form-recognizer-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 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\nrow1,row1\nrow2,row2\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-3.2-unstable/pipeline-components/converters/doclingconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/doclingconverter.mdx
new file mode 100644
index 00000000000..95ee303725f
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/doclingconverter.mdx
@@ -0,0 +1,141 @@
+---
+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://docling-project.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.MARKDOWN`** (default): 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.DOC_CHUNKS`**: 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.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: full document as Markdown
+converter = DoclingConverter()
+result = converter.run(sources=["report.pdf", "notes.docx"])
+documents = result["documents"]
+print(documents[0].content)
+
+# One document per chunk
+converter = DoclingConverter(export_type=ExportType.DOC_CHUNKS)
+result = converter.run(sources=["report.pdf"])
+documents = result["documents"]
+```
+
+### 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"]}})
+```
+
+When you set `export_type=ExportType.DOC_CHUNKS`, `DoclingConverter` already chunks the documents, so 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. The `chunker` parameter only takes effect with `ExportType.DOC_CHUNKS`:
+
+```python
+from docling.chunking import HybridChunker
+from haystack_integrations.components.converters.docling import (
+ DoclingConverter,
+ ExportType,
+)
+
+chunker = HybridChunker(tokenizer="BAAI/bge-small-en-v1.5", max_tokens=256)
+converter = DoclingConverter(export_type=ExportType.DOC_CHUNKS, 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-3.2-unstable/pipeline-components/converters/doclingserveconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/doclingserveconverter.mdx
new file mode 100644
index 00000000000..c042198a943
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/documenttoimagecontent.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/documenttoimagecontent.mdx
new file mode 100644
index 00000000000..559e4e5e948
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/filetofilecontent.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/filetofilecontent.mdx
new file mode 100644
index 00000000000..9dbf0da49fd
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/htmltodocument.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/htmltodocument.mdx
new file mode 100644
index 00000000000..fa8e1676b70
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/imagefiletodocument.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/imagefiletodocument.mdx
new file mode 100644
index 00000000000..1f09af93e16
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/imagefiletodocument.mdx
@@ -0,0 +1,110 @@
+---
+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 `SentenceTransformersDocumentImageEmbedder` 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 `SentenceTransformersDocumentImageEmbedder` 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.
+
+The examples on this page use Sentence Transformers embedders from the `sentence-transformers-haystack` package. Install it to run the examples:
+
+```shell
+pip install sentence-transformers-haystack
+```
+
+```python
+from haystack import Pipeline
+from haystack.components.converters.image import ImageFileToDocument
+from haystack_integrations.components.embedders.sentence_transformers 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-3.2-unstable/pipeline-components/converters/imagefiletoimagecontent.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/imagefiletoimagecontent.mdx
new file mode 100644
index 00000000000..aea9181718b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/imagefiletoimagecontent.mdx
@@ -0,0 +1,128 @@
+---
+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="iVBORw0KGgo...", 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](/reference/converters-api#jsonconverter) 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-3.2-unstable/pipeline-components/converters/kreuzbergconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/kreuzbergconverter.mdx
new file mode 100644
index 00000000000..c3c1b19fae3
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/libreofficefileconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/libreofficefileconverter.mdx
new file mode 100644
index 00000000000..aaea2dd84b5
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/markdowntodocument.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/markdowntodocument.mdx
new file mode 100644
index 00000000000..177798feb27
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/markdowntodocument.mdx
@@ -0,0 +1,105 @@
+---
+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.
+
+If your Markdown files start with YAML frontmatter, set `extract_frontmatter=True` to move that data into `Document.meta` and remove it from the converted document content. Metadata passed through the `meta` input takes precedence over frontmatter keys.
+
+## Usage
+
+You need to install the `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")])
+```
+
+### With YAML frontmatter
+
+Given `equity_note.md`:
+
+```markdown
+---
+ticker: AAPL
+source: earnings_call
+date: 2026-06-12
+---
+
+# Thesis
+Revenue guidance improved.
+```
+
+```python
+from haystack.components.converters import MarkdownToDocument
+
+converter = MarkdownToDocument(extract_frontmatter=True)
+
+docs = converter.run(sources=["equity_note.md"])["documents"]
+print(docs[0].meta["ticker"])
+print(docs[0].content)
+```
+
+### 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-3.2-unstable/pipeline-components/converters/markitdownconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/markitdownconverter.mdx
new file mode 100644
index 00000000000..3680d460365
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/mistralocrdocumentconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/mistralocrdocumentconverter.mdx
new file mode 100644
index 00000000000..84b3a98823f
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/msgtodocument.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/msgtodocument.mdx
new file mode 100644
index 00000000000..7c38ca4c1d3
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/multifileconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/multifileconverter.mdx
new file mode 100644
index 00000000000..36e532d5879
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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 file paths or byte streams whose MIME type isn't supported
`failed`: A list of file paths or byte streams that couldn't be processed, for example a path that doesn't exist | +| **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-sig` by default, which decodes plain UTF-8 identically and additionally strips a byte order mark (BOM) if the file has one. 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 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-3.2-unstable/pipeline-components/converters/openapiservicetofunctions.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/openapiservicetofunctions.mdx
new file mode 100644
index 00000000000..ed03a5b9ce6
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/openapiservicetofunctions.mdx
@@ -0,0 +1,148 @@
+---
+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.
+
+:::tip[Consider using MCP instead]
+
+These OpenAPI components are a legacy way to connect Haystack to external APIs. For most use cases, we recommend the [`MCPTool`](../../tools/mcptool.mdx) instead: it is the modern, standardized way to give your pipelines and agents access to external tools and services.
+
+:::
+
+`unclassified`: A list of file paths or byte streams whose MIME type isn't supported
`failed`: A list of file paths or byte streams that couldn't be processed, for example a path that doesn't exist | +| **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** | [OpenAPI](/reference/integrations-openapi) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/openapi | +| **Package name** | `openapi-haystack` | + +
+
+## 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 the `openapi-haystack` package with:
+
+```shell
+pip install openapi-haystack
+```
+
+`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.converters import OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.connectors.openapi import OpenAPIServiceConnector
+from haystack_integrations.components.converters.openapi import (
+ OpenAPIServiceToFunctions,
+)
+
+
+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-3.2-unstable/pipeline-components/converters/opendataloaderconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/opendataloaderconverter.mdx
new file mode 100644
index 00000000000..d5cb9bb0bd8
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/opendataloaderconverter.mdx
@@ -0,0 +1,132 @@
+---
+title: "OpenDataLoaderConverter"
+id: opendataloaderconverter
+slug: "/opendataloaderconverter"
+description: "`OpenDataLoaderConverter` converts PDF files to Haystack Documents using OpenDataLoader PDF, a local PDF parser that extracts layout-aware Markdown, text, HTML, or JSON."
+---
+
+# OpenDataLoaderConverter
+
+`OpenDataLoaderConverter` converts PDF files to Haystack Documents using [OpenDataLoader PDF](https://opendataloader.org/), a local PDF parser that extracts layout-aware Markdown, text, HTML, or JSON.
+
+`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** | [OpenAPI](/reference/integrations-openapi) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/openapi | +| **Package name** | `openapi-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 PDF file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Opendataloader Pdf](/reference/integrations-opendataloader-pdf) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opendataloader_pdf |
+| **Package name** | `opendataloader-pdf-haystack` |
+
+
+
+## Overview
+
+`OpenDataLoaderConverter` takes a list of PDF file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects and runs OpenDataLoader PDF over them. Everything is processed locally, with no external API calls.
+
+OpenDataLoader analyzes the layout of a PDF (headings, paragraphs, lists, and tables) and serializes it into the format you pick with `output_format`:
+
+- `"markdown"` (default): structured Markdown with headings, lists, and tables
+- `"text"`: plain text
+- `"html"`: HTML markup
+- `"json"`: the full structured representation, including layout information
+
+The component returns one [`Document`](../../concepts/data-classes.mdx#document) per source. Each document's metadata contains the `file_path` of the source and the `output_format` that produced its content, plus any metadata you pass through the `meta` run variable. For `ByteStream` sources, the metadata of the stream is preserved as well.
+
+Only PDFs are supported. Passing a file with another extension, or a `ByteStream` whose MIME type is not `application/pdf`, raises a `ValueError`.
+
+:::info
+OpenDataLoader PDF runs on a Java engine, so Java 11 or newer must be installed and `java` must be available on your `PATH`. The component checks for this when it runs and raises a `RuntimeError` if no usable Java runtime is found.
+:::
+
+Image extraction is turned off by default so that documents contain text only. To turn it back on, pass `image_output` (and, if needed, `image_format` and `image_dir`) through `convert_kwargs`. See the [OpenDataLoader convert options](https://opendataloader.org/docs/quick-start-python#convert-options) for the accepted values.
+
+## Usage
+
+Install the OpenDataLoader PDF integration:
+
+```shell
+pip install opendataloader-pdf-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.converters.opendataloader_pdf import (
+ OpenDataLoaderConverter,
+)
+
+converter = OpenDataLoaderConverter()
+result = converter.run(sources=["report.pdf", "invoice.pdf"])
+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
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", OpenDataLoaderConverter())
+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"]}})
+```
+
+## Additional Features
+
+### Choosing an Output Format
+
+Set `output_format` to control what the content of the resulting documents looks like:
+
+```python
+converter = OpenDataLoaderConverter(output_format="json")
+```
+
+### Extraction Settings
+
+Pass any [OpenDataLoader PDF option](https://opendataloader.org/docs/quick-start-python#convert-options) through `convert_kwargs`. For example, to convert a page range of an encrypted PDF, keep page separators in the Markdown output, and redact sensitive data:
+
+```python
+converter = OpenDataLoaderConverter(
+ output_format="markdown",
+ convert_kwargs={
+ "pages": "1,3,5-7",
+ "password": "secret",
+ "markdown_page_separator": "--- page %page-number% ---",
+ "sanitize": True,
+ },
+)
+```
+
+Other frequently used options are `table_method="cluster"` for table-heavy PDFs, `use_struct_tree=True` to follow the structure tree of a tagged PDF, and `include_header_footer=True` to keep page headers and footers.
+
+### Converting ByteStreams
+
+Sources coming from a fetcher or a file store can be passed as `ByteStream` objects, optionally together with metadata:
+
+```python
+from pathlib import Path
+
+from haystack.dataclasses import ByteStream
+
+stream = ByteStream.from_file_path(
+ Path("report.pdf"), mime_type="application/pdf", meta={"file_path": "report.pdf"}
+)
+
+converter = OpenDataLoaderConverter()
+result = converter.run(sources=[stream], meta={"source": "internal-reports"})
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/outputadapter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/outputadapter.mdx
new file mode 100644
index 00000000000..68b7e8eb0a8
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/outputadapter.mdx
@@ -0,0 +1,134 @@
+---
+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.
+
+
+
+| | |
+| --- | --- |
+| **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-3.2-unstable/pipeline-components/converters/paddleocrvldocumentconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/paddleocrvldocumentconverter.mdx
new file mode 100644
index 00000000000..4a58753854b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/pdftoimagecontent.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/pdftoimagecontent.mdx
new file mode 100644
index 00000000000..850e437a0b1
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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='image/jpeg',
+# detail=None,
+# meta={'file_path': 'file.pdf', 'page_number': 1}),
+# ...]
+```
+
+### In a pipeline
+
+Use `PDFToImageContent` to supply page images 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["llm"]["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-3.2-unstable/pipeline-components/converters/pptxtodocument.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/pptxtodocument.mdx
new file mode 100644
index 00000000000..c1d33120f5f
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/pypdftodocument.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/pypdftodocument.mdx
new file mode 100644
index 00000000000..b1ad0075ffb
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/textfiletodocument.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/textfiletodocument.mdx
new file mode 100644
index 00000000000..9ac34f8817d
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-sig"` by default, which decodes plain UTF-8 identically and additionally strips a byte order mark (BOM) if the file has one. 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-3.2-unstable/pipeline-components/converters/tikadocumentconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/tikadocumentconverter.mdx
new file mode 100644
index 00000000000..329dd6daad7
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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** | [Tika](/reference/integrations-tika) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/tika |
+| **Package name** | `tika-haystack` |
+
+
+
+## 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
+
+Install the `tika-haystack` package to use the `TikaDocumentConverter` component:
+
+```shell
+pip install tika-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.converters.tika 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_integrations.components.converters.tika 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-3.2-unstable/pipeline-components/converters/twelvelabsvideoconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/twelvelabsvideoconverter.mdx
new file mode 100644
index 00000000000..0ab0e5df4dd
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/twelvelabsvideoconverter.mdx
@@ -0,0 +1,128 @@
+---
+title: "TwelveLabsVideoConverter"
+id: twelvelabsvideoconverter
+slug: "/twelvelabsvideoconverter"
+description: "`TwelveLabsVideoConverter` converts videos to Haystack Documents using the TwelveLabs Pegasus video-language model. Pegasus analyzes each video on the fly — its visuals and its own audio (via ASR) — and returns text, so each video becomes a Document whose content is the analysis."
+---
+
+# TwelveLabsVideoConverter
+
+`TwelveLabsVideoConverter` converts videos to Haystack Documents using the TwelveLabs Pegasus video-language model. Pegasus analyzes each video on the fly — its visuals **and** its own audio (via ASR) — and returns text, so each source video becomes one Document whose content is Pegasus's analysis (for example, a description plus a transcript). There is no frame extraction or separate transcription step.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | At the beginning of an indexing pipeline, before [PreProcessors](../preprocessors.mdx) or an embedder |
+| **Mandatory init variables** | `api_key`: The TwelveLabs API key. Can be set with `TWELVELABS_API_KEY` env var. |
+| **Mandatory run variables** | `sources`: A list of video URLs or local file paths |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [TwelveLabs](/reference/integrations-twelvelabs) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/twelvelabs |
+| **Package name** | `twelvelabs-haystack` |
+
+
+
+## Overview
+
+The `TwelveLabsVideoConverter` takes a list of video sources and produces one [`Document`](../../concepts/data-classes.mdx#document) per source, with the Document content set to Pegasus's text analysis. Sources may be publicly accessible direct video URLs or local file paths (uploaded to TwelveLabs, up to 200 MB). Sources that fail to process are skipped with a warning logged, so one bad source does not fail the whole batch.
+
+Each produced Document carries metadata about the request, including `source`, `asset_id`, `analysis_id`, `model`, and `provider`. The default model is `pegasus1.5`.
+
+You can steer the analysis with a custom `prompt` and tune `temperature` and `max_tokens`.
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install twelvelabs-haystack
+```
+
+The component uses a `TWELVELABS_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`. To get an API key, head to [playground.twelvelabs.io](https://playground.twelvelabs.io).
+
+## Usage
+
+### On its own
+
+```python
+from haystack_integrations.components.converters.twelvelabs import (
+ TwelveLabsVideoConverter,
+)
+
+converter = TwelveLabsVideoConverter()
+result = converter.run(sources=["https://example.com/clip.mp4"])
+
+document = result["documents"][0]
+print(document.content) # Pegasus's description + transcript of the video
+print(document.meta) # includes source, asset_id, analysis_id, model, provider
+```
+
+:::info
+We recommend setting `TWELVELABS_API_KEY` as an environment variable instead of setting it as a parameter.
+:::
+
+### With a custom prompt
+
+```python
+from haystack_integrations.components.converters.twelvelabs import (
+ TwelveLabsVideoConverter,
+)
+
+converter = TwelveLabsVideoConverter(
+ prompt="Summarize this video in three bullet points and list any products shown.",
+ temperature=0.2,
+ max_tokens=1024,
+)
+result = converter.run(sources=["https://example.com/clip.mp4"])
+print(result["documents"][0].content)
+```
+
+### In a pipeline
+
+This indexing pipeline analyzes videos with Pegasus, embeds the resulting analysis with the [`TwelveLabsDocumentEmbedder`](../embedders/twelvelabsdocumentembedder.mdx), and writes the documents to a document store:
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.writers import DocumentWriter
+from haystack_integrations.components.converters.twelvelabs import (
+ TwelveLabsVideoConverter,
+)
+from haystack_integrations.components.embedders.twelvelabs import (
+ TwelveLabsDocumentEmbedder,
+)
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("converter", TwelveLabsVideoConverter())
+indexing_pipeline.add_component("embedder", TwelveLabsDocumentEmbedder())
+indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+indexing_pipeline.connect("converter", "embedder")
+indexing_pipeline.connect("embedder", "writer")
+
+indexing_pipeline.run({"converter": {"sources": ["https://example.com/clip.mp4"]}})
+```
+
+### 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.twelvelabs import (
+ TwelveLabsVideoConverter,
+)
+
+converter = TwelveLabsVideoConverter()
+
+# Same metadata for all sources
+result = converter.run(
+ sources=["https://example.com/a.mp4", "https://example.com/b.mp4"],
+ meta={"campaign": "demo"},
+)
+
+# Per-source metadata
+result = converter.run(
+ sources=["https://example.com/a.mp4", "https://example.com/b.mp4"],
+ meta=[{"title": "Clip A"}, {"title": "Clip B"}],
+)
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/unstructuredfileconverter.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/unstructuredfileconverter.mdx
new file mode 100644
index 00000000000..07b00ca2aea
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/converters/xlsxtodocument.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/converters/xlsxtodocument.mdx
new file mode 100644
index 00000000000..525f1461303
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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 pandas, 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-3.2-unstable/pipeline-components/downloaders/s3downloader.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/downloaders/s3downloader.mdx
new file mode 100644
index 00000000000..2261e0bf51b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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.
+
+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`, and `cohere.embed-v4:0`. To find all supported models, see the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html), filter for "embedding", and select models from the Amazon Titan and Cohere series.
+
+:::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 `AmazonBedrockDocumentEmbedder`:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import os
+from haystack import Document
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentEmbedder,
+)
+
+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 = embedder.run(documents=[doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack import Document, 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
+from haystack.components.writers import DocumentWriter
+
+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-3.2-unstable/pipeline-components/embedders/amazonbedrockdocumentimageembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/amazonbedrockdocumentimageembedder.mdx
new file mode 100644
index 00000000000..da4e7c8dbfa
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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.
+
+Amazon Titan and Cohere multimodal embedding models are supported, for example `amazon.titan-embed-image-v1`, `cohere.embed-english-v3`, `cohere.embed-multilingual-v3`, and `cohere.embed-v4:0`.
+
+`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-3.2-unstable/pipeline-components/embedders/amazonbedrocktextembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/amazonbedrocktextembedder.mdx
new file mode 100644
index 00000000000..cec7e4f9b65
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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.
+
+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`, and `cohere.embed-v4:0`. To find all supported models, see the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html), filter for "embedding", and select models from the Amazon Titan and Cohere series.
+
+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-3.2-unstable/pipeline-components/embedders/azureopenaidocumentembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/azureopenaidocumentembedder.mdx
new file mode 100644
index 00000000000..aacd67c2b21
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/azureopenaidocumentembedder.mdx
@@ -0,0 +1,127 @@
+---
+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-v4.0"`, `"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-v4.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
+from haystack.utils import Secret
+from haystack_integrations.components.embedders.cohere import CohereDocumentEmbedder
+
+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
+from haystack.utils import Secret
+from haystack_integrations.components.embedders.cohere import (
+ CohereDocumentImageEmbedder,
+)
+
+embedder = CohereDocumentImageEmbedder(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-v4.0"`, `"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-v4.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 init variables** | `api_key`: The Eden AI API key. Can be set with `EDENAI_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** | [Eden AI](/reference/integrations-edenai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/edenai | +| **Package name** | `edenai-haystack` | + +
+
+This component should be used to embed a list of Documents. To embed a string, use the [`EdenAITextEmbedder`](edenaitextembedder.mdx).
+
+## Overview
+
+`EdenAIDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses Eden AI's OpenAI-compatible API. Models are selected using Eden AI's `provider/model` naming convention, for example `openai/text-embedding-3-small` (default) or `mistral/mistral-embed`. For the full list of available models, see the [Eden AI models catalog](https://www.edenai.co/models).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install edenai-haystack
+```
+
+`EdenAIDocumentEmbedder` needs an Eden AI API key to work. It uses an `EDENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.embedders.edenai import EdenAIDocumentEmbedder
+
+embedder = EdenAIDocumentEmbedder(
+ api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Eden AI](/reference/integrations-edenai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/edenai | +| **Package name** | `edenai-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The Eden AI API key. Can be set with `EDENAI_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** | [Eden AI](/reference/integrations-edenai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/edenai | +| **Package name** | `edenai-haystack` | + +
+
+Use `EdenAITextEmbedder` to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [`EdenAIDocumentEmbedder`](edenaidocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+## Overview
+
+`EdenAITextEmbedder` transforms a string into a vector that captures its semantics using an Eden AI embedding model. Models are selected using Eden AI's `provider/model` naming convention, for example `openai/text-embedding-3-small` (default) or `mistral/mistral-embed`. For the full list of available models, see the [Eden AI models catalog](https://www.edenai.co/models).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install edenai-haystack
+```
+
+`EdenAITextEmbedder` needs an Eden AI API key to work. It uses an `EDENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.embedders.edenai import EdenAITextEmbedder
+
+embedder = EdenAITextEmbedder(
+ api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Eden AI](/reference/integrations-edenai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/edenai | +| **Package name** | `edenai-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 import Document
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedDocumentEmbedder,
+)
+
+doc = Document(
+ content="some text",
+ meta={"title": "relevant title", "page number": 18},
+)
+
+embedder = FastembedDocumentEmbedder(
+ model="BAAI/bge-small-en-v1.5",
+ batch_size=256,
+ meta_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-3.2-unstable/pipeline-components/embedders/fastembedsparsedocumentembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/fastembedsparsedocumentembedder.mdx
new file mode 100644
index 00000000000..ee822bc68a7
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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 import Document
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedSparseDocumentEmbedder,
+)
+
+doc = Document(
+ content="some text",
+ meta={"title": "relevant title", "page number": 18},
+)
+
+embedder = FastembedSparseDocumentEmbedder(
+ model="prithivida/Splade_PP_en_v1",
+ meta_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 (
+ FastembedSparseDocumentEmbedder,
+ FastembedSparseTextEmbedder,
+)
+
+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-3.2-unstable/pipeline-components/embedders/fastembedsparsetextembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/fastembedsparsetextembedder.mdx
new file mode 100644
index 00000000000..27ef5150f7c
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/embedders/fastembedtextembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/fastembedtextembedder.mdx
new file mode 100644
index 00000000000..d3473f6239f
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/fastembedtextembedder.mdx
@@ -0,0 +1,144 @@
+---
+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-3.2-unstable/pipeline-components/embedders/googlegenaidocumentembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/googlegenaidocumentembedder.mdx
new file mode 100644
index 00000000000..15f96766f32
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/googlegenaidocumentembedder.mdx
@@ -0,0 +1,183 @@
+---
+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`. | +| **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** | [Hugging Face API](/reference/integrations-huggingface-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api | +| **Package name** | `huggingface-api-haystack` | + +
+
+## 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
+
+Install the `huggingface-api-haystack` package to use the `HuggingFaceAPIDocumentEmbedder`:
+
+```shell
+pip install huggingface-api-haystack
+```
+
+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/integrations-huggingface-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_integrations.components.embedders.huggingface_api 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`. | +| **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** | [Hugging Face API](/reference/integrations-huggingface-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api | +| **Package name** | `huggingface-api-haystack` | + +
+
+| | |
+| --- | --- |
+| **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`. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers | +| **API reference** | [Hugging Face API](/reference/integrations-huggingface-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api | +| **Package name** | `huggingface-api-haystack` | + +
+
+## 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
+
+Install the `huggingface-api-haystack` package to use the `HuggingFaceAPITextEmbedder`:
+
+```shell
+pip install huggingface-api-haystack
+```
+
+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/integrations-huggingface-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_integrations.components.embedders.huggingface_api 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`. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers | +| **API reference** | [Hugging Face API](/reference/integrations-huggingface-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api | +| **Package name** | `huggingface-api-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 |
+| **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-v3`.
+
+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 |
+| **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-v3`.
+
+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 `MistralTextEmbedder` 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** | In place of a real Document Embedder, in tests and prototypes |
+| **Mandatory init variables** | None |
+| **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/mock_document_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`MockDocumentEmbedder` is a deterministic, zero-cost drop-in replacement for real Document Embedders such as `OpenAIDocumentEmbedder`. It implements `run`, `run_async`, and serialization like any other embedder but never contacts an external service, which makes it ideal for unit tests, smoke tests, and quick prototypes.
+
+The embedding is selected based on how the component is configured:
+
+- **Deterministic (default)**: With no configuration, each document's embedding is derived from a stable hash of its prepared text. The same text always yields the same unit-length embedding, and different texts yield different embeddings, so the mock works in retrieval pipelines and is reproducible across runs and processes.
+- **Fixed embedding**: Pass an `embedding` vector. The same vector is assigned to every document.
+- **Dynamic embedding**: Pass an `embedding_fn` callable that receives the prepared text of a document and returns the embedding. To support serialization, pass a named function.
+
+`embedding` and `embedding_fn` are mutually exclusive.
+
+Further optional parameters:
+
+- `dimension`: The number of dimensions of the deterministic embedding. Defaults to `768`. Ignored when `embedding` or `embedding_fn` is provided, since their length is determined by the value or callable.
+- `model`: The model name reported in the metadata. Defaults to `"mock-model"`.
+- `meta`: Additional metadata merged into the output `meta`.
+- `prefix` / `suffix`: Strings added to the beginning and end of each text before embedding, mirroring real embedders.
+- `meta_fields_to_embed` / `embedding_separator`: Like real Document Embedders, the metadata fields listed in `meta_fields_to_embed` are concatenated with the document content before embedding, so the deterministic embedding reflects the embedded metadata.
+- `progress_bar`: Accepted for interface compatibility with real Document Embedders and ignored.
+
+:::info
+The deterministic embeddings are derived from a hash: identical texts get identical vectors and the similarity between different texts is stable but arbitrary. For exact-match retrieval in tests this is exactly what you want. Do not expect semantically similar texts to end up close together.
+:::
+
+Use `MockDocumentEmbedder` for documents and its counterpart [`MockTextEmbedder`](mocktextembedder.mdx) for queries. With the default deterministic mode, a query whose text matches a document's content produces the same vector, so the document is retrieved as the top hit.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.embedders import MockDocumentEmbedder
+
+embedder = MockDocumentEmbedder(dimension=8)
+result = embedder.run([Document(content="I love pizza!")])
+print(result["documents"][0].embedding) # a deterministic list of 8 floats
+```
+
+### In a pipeline
+
+Use it in an indexing pipeline exactly like a real Document Embedder — no API key needed:
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.embedders import MockDocumentEmbedder
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("embedder", MockDocumentEmbedder(dimension=8))
+indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+indexing_pipeline.connect("embedder.documents", "writer.documents")
+
+indexing_pipeline.run(
+ {
+ "embedder": {
+ "documents": [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ ],
+ },
+ },
+)
+print(document_store.count_documents()) # 2
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/mocktextembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/mocktextembedder.mdx
new file mode 100644
index 00000000000..d19f19e88cc
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/mocktextembedder.mdx
@@ -0,0 +1,94 @@
+---
+title: "MockTextEmbedder"
+id: mocktextembedder
+slug: "/mocktextembedder"
+description: "A Text Embedder that returns deterministic embeddings without calling any API, for tests and quick prototypes."
+---
+
+# MockTextEmbedder
+
+A Text Embedder that returns deterministic embeddings without calling any API, for tests and quick prototypes.
+
+`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/mock_document_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In place of a real Text Embedder, in tests and prototypes |
+| **Mandatory init variables** | None |
+| **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/mock_text_embedder.py | +| **Package name** | `haystack-ai` | + +
+
+## Overview
+
+`MockTextEmbedder` is a deterministic, zero-cost drop-in replacement for real Text Embedders such as `OpenAITextEmbedder`. It implements `run`, `run_async`, and serialization like any other embedder but never contacts an external service, which makes it ideal for unit tests, smoke tests, and quick prototypes.
+
+The embedding is selected based on how the component is configured:
+
+- **Deterministic (default)**: With no configuration, the embedding is derived from a stable hash of the input text. The same text always yields the same unit-length embedding, and different texts yield different embeddings, so the mock works in retrieval pipelines and is reproducible across runs and processes.
+- **Fixed embedding**: Pass an `embedding` vector. The same vector is returned for every input.
+- **Dynamic embedding**: Pass an `embedding_fn` callable that receives the prepared text (after `prefix`/`suffix` are applied) and returns the embedding. To support serialization, pass a named function.
+
+`embedding` and `embedding_fn` are mutually exclusive.
+
+Further optional parameters:
+
+- `dimension`: The number of dimensions of the deterministic embedding. Defaults to `768`. Ignored when `embedding` or `embedding_fn` is provided, since their length is determined by the value or callable.
+- `model`: The model name reported in the metadata. Defaults to `"mock-model"`.
+- `meta`: Additional metadata merged into the output `meta`.
+- `prefix` / `suffix`: Strings added to the beginning and end of the text before embedding, mirroring real embedders.
+
+:::info
+The deterministic embeddings are derived from a hash: identical texts get identical vectors and the similarity between different texts is stable but arbitrary. For exact-match retrieval in tests this is exactly what you want. Do not expect semantically similar texts to end up close together.
+:::
+
+Use `MockTextEmbedder` for queries and its counterpart [`MockDocumentEmbedder`](mockdocumentembedder.mdx) for documents. With the default deterministic mode, a query whose text matches a document's content produces the same vector, so the document is retrieved as the top hit.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.embedders import MockTextEmbedder
+
+embedder = MockTextEmbedder(dimension=8)
+result = embedder.run("I love pizza!")
+print(result["embedding"]) # a deterministic list of 8 floats
+```
+
+### In a pipeline
+
+A retrieval pipeline built with mock embedders runs without any API key and always returns the same result for the same input:
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.embedders import MockDocumentEmbedder, MockTextEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+]
+
+indexed = MockDocumentEmbedder(dimension=8).run(documents=documents)
+document_store.write_documents(indexed["documents"])
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", MockTextEmbedder(dimension=8))
+query_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store),
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+result = query_pipeline.run(
+ {"text_embedder": {"text": "I saw a black horse running"}},
+)
+print(result["retriever"]["documents"][0].content) # "I saw a black horse running"
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/nvidiadocumentembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/nvidiadocumentembedder.mdx
new file mode 100644
index 00000000000..ca23fb68418
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/nvidiadocumentembedder.mdx
@@ -0,0 +1,154 @@
+---
+title: "NvidiaDocumentEmbedder"
+id: nvidiadocumentembedder
+slug: "/nvidiadocumentembedder"
+description: "This component computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document."
+---
+
+# NvidiaDocumentEmbedder
+
+This component computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document.
+
+`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/mock_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`: 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 [NIM for Embedding](https://docs.nvidia.com/nim/nemo-retriever/text-embedding/latest/index.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 [NIM for Embedding](https://docs.nvidia.com/nim/nemo-retriever/text-embedding/latest/index.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.com/library). To load your own custom model, follow the [instructions](https://docs.ollama.com/modelfile) 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://docs.ollama.com/modelfile#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-3.2-unstable/pipeline-components/embedders/ollamatextembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/ollamatextembedder.mdx
new file mode 100644
index 00000000000..651b7bd496a
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/ollamatextembedder.mdx
@@ -0,0 +1,112 @@
+---
+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` | + +
+
+`OllamaTextEmbedder` computes the embeddings of a string and returns the obtained vector. It uses embedding models compatible with the Ollama Library.
+
+When you perform embedding retrieval, use this component first to transform your query into a vector. Then, the embedding Retriever uses that vector to search for 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.com/library). To load your own custom model, follow the [instructions](https://docs.ollama.com/modelfile) 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://docs.ollama.com/modelfile#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 haystack_integrations.components.embedders.ollama import (
+ OllamaDocumentEmbedder,
+ OllamaTextEmbedder,
+)
+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-3.2-unstable/pipeline-components/embedders/openaidocumentembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/openaidocumentembedder.mdx
new file mode 100644
index 00000000000..1252f2d64b7
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/openaidocumentembedder.mdx
@@ -0,0 +1,121 @@
+---
+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). 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). 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)
+
+results = pipeline.run({"embedder": {"documents": documents}})
+
+print(results["embedder"]["documents"][0].embedding)
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/optimumtextembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/optimumtextembedder.mdx
new file mode 100644
index 00000000000..f6ca51b4176
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/embedders/perplexitydocumentembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/perplexitydocumentembedder.mdx
new file mode 100644
index 00000000000..62d1d6d643c
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/perplexitydocumentembedder.mdx
@@ -0,0 +1,123 @@
+---
+title: "PerplexityDocumentEmbedder"
+id: perplexitydocumentembedder
+slug: "/perplexitydocumentembedder"
+description: "`PerplexityDocumentEmbedder` computes embeddings for a list of documents using Perplexity embedding models and stores the vectors in each document's `embedding` field."
+---
+
+# PerplexityDocumentEmbedder
+
+`PerplexityDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the `embedding` field of each document. It uses Perplexity 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.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: A Perplexity API key. Can be set with `PERPLEXITY_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** | [Integrations](/reference/integrations-perplexity) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/perplexity/src/haystack_integrations/components/embedders/perplexity/document_embedder.py | +| **Package name** | `perplexity-haystack` | + +
+
+## Overview
+
+`PerplexityDocumentEmbedder` supports the following embedding models:
+
+- `pplx-embed-v1-0.6b` (default)
+- `pplx-embed-v1-4b`
+
+Use this component to embed a list of documents. To embed a single string (such as a query), use [PerplexityTextEmbedder](perplexitytextembedder.mdx).
+
+The component uses a `PERPLEXITY_API_KEY` environment variable by default. You can also pass an API key directly at initialization:
+
+```python
+from haystack_integrations.components.embedders.perplexity import (
+ PerplexityDocumentEmbedder,
+)
+from haystack.utils import Secret
+
+embedder = PerplexityDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Integrations](/reference/integrations-perplexity) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/perplexity/src/haystack_integrations/components/embedders/perplexity/document_embedder.py | +| **Package name** | `perplexity-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: A Perplexity API key. Can be set with `PERPLEXITY_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** | [Integrations](/reference/integrations-perplexity) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/perplexity/src/haystack_integrations/components/embedders/perplexity/text_embedder.py | +| **Package name** | `perplexity-haystack` | + +
+
+## Overview
+
+`PerplexityTextEmbedder` supports the following embedding models:
+
+- `pplx-embed-v1-0.6b` (default)
+- `pplx-embed-v1-4b`
+
+Use `PerplexityTextEmbedder` to embed a single string, such as a query. For embedding lists of documents, use [PerplexityDocumentEmbedder](perplexitydocumentembedder.mdx).
+
+The component uses a `PERPLEXITY_API_KEY` environment variable by default. You can also pass an API key directly at initialization:
+
+```python
+from haystack_integrations.components.embedders.perplexity import PerplexityTextEmbedder
+from haystack.utils import Secret
+
+embedder = PerplexityTextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Integrations](/reference/integrations-perplexity) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/perplexity/src/haystack_integrations/components/embedders/perplexity/text_embedder.py | +| **Package name** | `perplexity-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** | [Sentence Transformers](/reference/integrations-sentence-transformers) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/sentence_transformers |
+| **Package name** | `sentence-transformers-haystack` |
+
+
+
+## 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** | None |
+| **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** | [Sentence Transformers](/reference/integrations-sentence-transformers) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/sentence_transformers |
+| **Package name** | `sentence-transformers-haystack` |
+
+
+
+## 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` parameter: `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
+
+Install the `sentence-transformers-haystack` package to use the `SentenceTransformersDocumentImageEmbedder`:
+
+```shell
+pip install sentence-transformers-haystack
+```
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.sentence_transformers 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_integrations.components.embedders.sentence_transformers import (
+ SentenceTransformersTextEmbedder,
+ 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-3.2-unstable/pipeline-components/embedders/sentencetransformerssparsedocumentembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/sentencetransformerssparsedocumentembedder.mdx
new file mode 100644
index 00000000000..f730cd3df83
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/sentencetransformerssparsedocumentembedder.mdx
@@ -0,0 +1,197 @@
+---
+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** | [Sentence Transformers](/reference/integrations-sentence-transformers) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/sentence_transformers |
+| **Package name** | `sentence-transformers-haystack` |
+
+
+
+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_integrations.components.embedders.sentence_transformers 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** | [Sentence Transformers](/reference/integrations-sentence-transformers) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/sentence_transformers |
+| **Package name** | `sentence-transformers-haystack` |
+
+
+
+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_integrations.components.embedders.sentence_transformers 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** | [Sentence Transformers](/reference/integrations-sentence-transformers) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/sentence_transformers |
+| **Package name** | `sentence-transformers-haystack` |
+
+
+
+## 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/products/data-and-ai/ai-model-serving/basics/available-shared-models/).
+
+Optionally, you can change the default `api_base_url`, which is `"https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1"`.
+
+Other optional parameters include `prefix` and `suffix` (added to each text before embedding), `batch_size`, `meta_fields_to_embed`, `embedding_separator`, and `dimensions`.
+
+The 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 import Document
+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-3.2-unstable/pipeline-components/embedders/stackittextembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/stackittextembedder.mdx
new file mode 100644
index 00000000000..fee137473d5
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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/products/data-and-ai/ai-model-serving/basics/available-shared-models/).
+
+Optionally, you can change the default `api_base_url`, which is `"https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1"`.
+
+Other optional parameters include `prefix` and `suffix` (added to the text before embedding) and `dimensions`.
+
+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-3.2-unstable/pipeline-components/embedders/twelvelabsdocumentembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/twelvelabsdocumentembedder.mdx
new file mode 100644
index 00000000000..b2bcae6398b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/twelvelabsdocumentembedder.mdx
@@ -0,0 +1,134 @@
+---
+title: "TwelveLabsDocumentEmbedder"
+id: twelvelabsdocumentembedder
+slug: "/twelvelabsdocumentembedder"
+description: "This component computes the embeddings of a list of documents using the TwelveLabs Marengo multimodal embedding model and stores the obtained vectors in the embedding field of each document. The vectors are necessary to perform embedding retrieval on a collection of documents."
+---
+
+# TwelveLabsDocumentEmbedder
+
+This component computes the embeddings of a list of documents using the TwelveLabs Marengo multimodal embedding model and stores the obtained vectors in the embedding field of each document. 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 TwelveLabs API key. Can be set with `TWELVELABS_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** | [TwelveLabs](/reference/integrations-twelvelabs) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/twelvelabs | +| **Package name** | `twelvelabs-haystack` | + +
+
+## Overview
+
+`TwelveLabsDocumentEmbedder` enriches each document with an embedding of its content. To embed a string, use the [`TwelveLabsTextEmbedder`](twelvelabstextembedder.mdx). The default model is `marengo3.0`.
+
+Because Marengo embeds text, images, audio, and video into a single shared space, these embeddings support cross-modal retrieval.
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install twelvelabs-haystack
+```
+
+The component uses a `TWELVELABS_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.embedders.twelvelabs import (
+ TwelveLabsDocumentEmbedder,
+)
+
+embedder = TwelveLabsDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [TwelveLabs](/reference/integrations-twelvelabs) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/twelvelabs | +| **Package name** | `twelvelabs-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The TwelveLabs API key. Can be set with `TWELVELABS_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** | [TwelveLabs](/reference/integrations-twelvelabs) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/twelvelabs | +| **Package name** | `twelvelabs-haystack` | + +
+
+## Overview
+
+`TwelveLabsTextEmbedder` embeds a simple string (such as a query) into a vector. For embedding lists of documents, use the [`TwelveLabsDocumentEmbedder`](twelvelabsdocumentembedder.mdx), which enriches each document with the computed embedding. The default model is `marengo3.0`.
+
+Because Marengo embeds into a single shared space, embeddings produced from text are directly comparable (cosine similarity) with embeddings of images, audio, and video from the same model.
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install twelvelabs-haystack
+```
+
+The component uses a `TWELVELABS_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.embedders.twelvelabs import TwelveLabsTextEmbedder
+
+embedder = TwelveLabsTextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [TwelveLabs](/reference/integrations-twelvelabs) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/twelvelabs | +| **Package name** | `twelvelabs-haystack` | + +
+
+| | |
+| --- | --- |
+| **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-3.2-unstable/pipeline-components/embedders/vertexaitextembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/vertexaitextembedder.mdx
new file mode 100644
index 00000000000..e7919844c1a
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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]
+
+The `google-vertex-haystack` integration is archived and no longer maintained. It builds on a deprecated Google SDK.
+
+We recommend switching to the [GoogleGenAITextEmbedder](googlegenaitextembedder.mdx) from the `google-genai-haystack` package 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-3.2-unstable/pipeline-components/embedders/vllmdocumentembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/vllmdocumentembedder.mdx
new file mode 100644
index 00000000000..65106b64ed8
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/embedders/vllmtextembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/vllmtextembedder.mdx
new file mode 100644
index 00000000000..ad41d3ef59c
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/embedders/watsonxdocumentembedder.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/embedders/watsonxdocumentembedder.mdx
new file mode 100644
index 00000000000..47c04029fac
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-v2` and similar. The default model is `ibm/slate-30m-english-rtrvr-v2`. 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-v2`. 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]
+# [1.0, 0.5174766182899475]
+
+for evaluator in result:
+ print(result[evaluator]["score"])
+# 0.5
+# 0.7587383091449738
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/contextrelevanceevaluator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/contextrelevanceevaluator.mdx
new file mode 100644
index 00000000000..a3acdd05fcf
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/contextrelevanceevaluator.mdx
@@ -0,0 +1,133 @@
+---
+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 context relevance score over all input questions
- `individual_scores`: A list of the individual context relevance scores, each either 0 or 1, for each input pair of a question and a list of contexts
- `results`: A list of dictionaries with keys `relevant_statements`, `score`, and `status`. They contain the statements that an LLM found relevant in each context, the binary score for that context, and `evaluated` for valid results or `error` for failed evaluations. | +| **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 score for each context is binary: 1 if the LLM found at least one relevant statement in it, 0 otherwise. The overall `score` is the mean of these binary scores over all input questions, so it is a number from 0.0 to 1.0.
+
+### Parameters
+
+The default model for this Evaluator is `gpt-5-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 `relevant_statements`.
+Here is the 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."],
+ },
+ },
+]
+```
+
+## 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 because it finds a statement in the context that 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
+print(result["individual_scores"])
+# [1]
+print(result["results"])
+# [{'relevant_statements': ['Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language.'], 'status': 'evaluated', 'score': 1}]
+```
+
+### 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.",
+ ],
+]
+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"])
+# [1]
+# [0.5]
+for evaluator in result:
+ print(result[evaluator]["score"])
+# 1
+# 0.5
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/deepevalevaluator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/deepevalevaluator.mdx
new file mode 100644
index 00000000000..f67782456fb
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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 context relevance score over all input questions
- `individual_scores`: A list of the individual context relevance scores, each either 0 or 1, for each input pair of a question and a list of contexts
- `results`: A list of dictionaries with keys `relevant_statements`, `score`, and `status`. They contain the statements that an LLM found relevant in each context, the binary score for that context, and `evaluated` for valid results or `error` for failed evaluations. | +| **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-4o-mini"},
+)
+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`, a list of `contexts`, and a list of `responses`. 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-3.2-unstable/pipeline-components/evaluators/documentmapevaluator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/documentmapevaluator.mdx
new file mode 100644
index 00000000000..1cf8a7b0d0e
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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, 0.8333333333333333]
+# [1.0, 1.0]
+for evaluator in result:
+ print(result[evaluator]["score"])
+# 0.9166666666666666
+# 1.0
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/documentmrrevaluator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/documentmrrevaluator.mdx
new file mode 100644
index 00000000000..90a9cf4050b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/evaluators/documentndcgevaluator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/documentndcgevaluator.mdx
new file mode 100644
index 00000000000..2f7f4a30453
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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.9502344167898356]
+print(result["score"])
+# 0.9502344167898356
+```
+
+### 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"])
+# 1.0
+# 0.9502344167898356
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/documentrecallevaluator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/documentrecallevaluator.mdx
new file mode 100644
index 00000000000..8b3041a1aff
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/evaluators/external-integrations-evaluators.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/external-integrations-evaluators.mdx
new file mode 100644
index 00000000000..e90faec7aaf
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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-3.2-unstable/pipeline-components/evaluators/faithfulnessevaluator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/faithfulnessevaluator.mdx
new file mode 100644
index 00000000000..d6acd482127
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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`, `statement_scores`, `score`, and `status` keys. They contain the statements extracted by an LLM from each predicted answer, the corresponding faithfulness scores per statement (either 0 or 1), the mean score for that answer, and `evaluated` for valid results or `error` for failed evaluations. | +| **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-5-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], 'status': 'evaluated', '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-3.2-unstable/pipeline-components/evaluators/llmevaluator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/llmevaluator.mdx
new file mode 100644
index 00000000000..b8454dac339
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/llmevaluator.mdx
@@ -0,0 +1,138 @@
+---
+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`, `statement_scores`, `score`, and `status` keys. They contain the statements extracted by an LLM from each predicted answer, the corresponding faithfulness scores per statement (either 0 or 1), the mean score for that answer, and `evaluated` for valid results or `error` for failed evaluations. | +| **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** | A dictionary containing:
- `results`: A list of dictionaries whose keys are the ones you declared in the `outputs` parameter, such as `score`
- `meta`: The metadata returned by the Chat Generator for each evaluated input, or `None` if there is none | +| **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-5-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` takes the following parameters for initialization. The first four are required, the last two have defaults:
+
+- `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. True is the default.
+
+Each example must be a dictionary with keys `inputs` and `outputs`.
+`inputs` must be a dictionary whose keys are the input names you declared in the `inputs` parameter.
+`outputs` must be a dictionary whose keys are the names you declared in the `outputs` parameter.
+
+Here is the expected format for an Evaluator declared with `inputs=[("responses", list[str])]` and `outputs=["score"]`:
+
+```python
+[
+ {
+ "inputs": {"responses": "Damn, this is straight outta hell!!!"},
+ "outputs": {"score": 1},
+ },
+ {
+ "inputs": {"responses": "Football is the most popular sport."},
+ "outputs": {"score": 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}],
+# 'meta': [{'model': 'gpt-5-mini-2025-08-07', 'index': 0, 'finish_reason': 'stop', 'usage': {...}},
+# {'model': 'gpt-5-mini-2025-08-07', 'index': 0, 'finish_reason': 'stop', 'usage': {...}}]}
+```
+
+### 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-3.2-unstable/pipeline-components/evaluators/ragasevaluator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/ragasevaluator.mdx
new file mode 100644
index 00000000000..a38c883253b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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** | A dictionary containing:
- `results`: A list of dictionaries whose keys are the ones you declared in the `outputs` parameter, such as `score`
- `meta`: The metadata returned by the Chat Generator for each evaluated input, or `None` if there is none | +| **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-3.2-unstable/pipeline-components/evaluators/sasevaluator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/evaluators/sasevaluator.mdx
new file mode 100644
index 00000000000..9a111eb44a0
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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** | None |
+| **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"])
+# [1.0, 0.5174766182899475]
+print(result["score"])
+# 0.7587383091449738
+```
+
+### 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]
+# [1.0, 0.5174766182899475]
+
+for evaluator in result:
+ print(result[evaluator]["score"])
+# 0.5
+# 0.7587383091449738
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Prompt Optimization with DSPy](https://haystack.deepset.ai/cookbook/prompt_optimization_with_dspy)
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors.mdx
new file mode 100644
index 00000000000..2490daf34dc
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors.mdx
@@ -0,0 +1,16 @@
+---
+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. |
+| [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. |
+| [SpacyNamedEntityExtractor](extractors/spacynamedentityextractor.mdx) | Extracts predefined entities out of a piece of text and writes them into documents' meta field. Uses a spaCy model. |
+| [TransformersNamedEntityExtractor](extractors/transformersnamedentityextractor.mdx) | Extracts predefined entities out of a piece of text and writes them into documents' meta field. Uses a Hugging Face model. |
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors/llmdocumentcontentextractor.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors/llmdocumentcontentextractor.mdx
new file mode 100644
index 00000000000..ed7f43d6b8a
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-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 |
+| **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-3.2-unstable/pipeline-components/extractors/llmmetadataextractor.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors/llmmetadataextractor.mdx
new file mode 100644
index 00000000000..a6a527d76bc
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors/llmmetadataextractor.mdx
@@ -0,0 +1,146 @@
+---
+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.
+
+`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. It must contain exactly one variable, called `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 must have exactly one variable, called `document`, that points 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 raises a `ValueError` at initialization if the prompt has no variables, more than one variable, or a variable with a different name.
+
+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.
+
+`chat_generator` accepts any Haystack Chat Generator configured to return a JSON object, for example:
+
+- [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** | 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://data-privacy-stack.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://data-privacy-stack.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://data-privacy-stack.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-3.2-unstable/pipeline-components/extractors/regextextextractor.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors/regextextextractor.mdx
new file mode 100644
index 00000000000..fe18d0689b1
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors/regextextextractor.mdx
@@ -0,0 +1,128 @@
+---
+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
+
+When the pattern doesn't match, the component returns `captured_text` as an empty string:
+
+```python
+from haystack.components.extractors import RegexTextExtractor
+
+extractor = RegexTextExtractor(regex_pattern=r"
+
+| | |
+| --- | --- |
+| **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** | `model`: Name or path of the spaCy model to use |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Spacy](/reference/integrations-spacy) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/spacy |
+| **Package name** | `spacy-haystack` |
+
+
+
+## Overview
+
+`SpacyNamedEntityExtractor` 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.
+
+`SpacyNamedEntityExtractor` 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 and the start and end of the span, for example: `NamedEntityAnnotation(entity='PERSON', start=11, end=16, score=None)`.
+
+When the `SpacyNamedEntityExtractor` is initialized, you need to set a `model`. Optionally, you can set `pipeline_kwargs`, which are then passed on to the spaCy pipeline. You can additionally set the `device` that is used to run the component.
+
+## Usage
+
+Install the `spacy-haystack` package to use the `SpacyNamedEntityExtractor`:
+
+```shell
+pip install spacy-haystack
+```
+
+The component works with any [spaCy model](https://spacy.io/models) that contains an NER component.
+
+`SpacyNamedEntityExtractor` 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_integrations.components.extractors.spacy import (
+ SpacyNamedEntityExtractor,
+)
+
+extractor = SpacyNamedEntityExtractor(model="en_core_web_sm")
+
+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."),
+]
+
+result = extractor.run(documents)
+print(result["documents"])
+```
+
+Here is the example result:
+
+```text
+[Document(id=aec840d1b6c85609f4f16c3e222a5a25fd8c4c53bd981a40c1268ab9c72cee10, content: 'My name is Clara and I live in Berkeley, California.', meta: {'named_entities': [NamedEntityAnnotation(entity='PERSON', start=11, end=16, score=None), NamedEntityAnnotation(entity='GPE', start=31, end=39, score=None), NamedEntityAnnotation(entity='GPE', start=41, end=51, score=None)]}),
+Document(id=98f1dc5d0ccd9d9950cd191d1076db0f7af40c401dd7608f11c90cb3fc38c0c2, content: 'I'm Merlin, the happy pig!', meta: {'named_entities': [NamedEntityAnnotation(entity='PERSON', start=4, end=10, score=None)]}),
+Document(id=44948ea0eec018b33aceaaedde4616eb9e93ce075e0090ec1613fc145f84b4a9, content: 'New York State is home to the Empire State Building.', meta: {'named_entities': [NamedEntityAnnotation(entity='GPE', start=0, end=14, score=None), NamedEntityAnnotation(entity='ORG', start=26, end=51, score=None)]})]
+```
+
+### 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_integrations.components.extractors.spacy import (
+ SpacyNamedEntityExtractor,
+)
+
+extractor = SpacyNamedEntityExtractor(model="en_core_web_sm")
+
+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."),
+]
+
+result = extractor.run(documents)
+
+annotations = [
+ SpacyNamedEntityExtractor.get_stored_annotations(doc) for doc in result["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 SpacyNamedEntityExtractor.get_stored_annotations(new_doc) is None
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors/transformersnamedentityextractor.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors/transformersnamedentityextractor.mdx
new file mode 100644
index 00000000000..7c33c0e4794
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/extractors/transformersnamedentityextractor.mdx
@@ -0,0 +1,103 @@
+---
+title: "TransformersNamedEntityExtractor"
+id: transformersnamedentityextractor
+slug: "/transformersnamedentityextractor"
+description: "This component extracts predefined entities out of a piece of text and writes them into documents’ meta field."
+---
+
+# TransformersNamedEntityExtractor
+
+This component extracts predefined entities out of a piece of text and writes them into documents’ meta field.
+
+
+
+| | |
+| --- | --- |
+| **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** | `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** | [Transformers](/reference/integrations-transformers) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/transformers |
+| **Package name** | `transformers-haystack` |
+
+
+
+## Overview
+
+`TransformersNamedEntityExtractor` 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.
+
+`TransformersNamedEntityExtractor` 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 `TransformersNamedEntityExtractor` is initialized, you need to set a `model`. Optionally, you can set `pipeline_kwargs`, which are then passed on to the Hugging Face pipeline. You can additionally set the `device` that is used to run the component.
+
+Authentication with a Hugging Face API token is only required to access private or gated models. You can pass the token at initialization with `token`, or set the `HF_API_TOKEN` or `HF_TOKEN` environment variable.
+
+## Usage
+
+Install the `transformers-haystack` package to use the `TransformersNamedEntityExtractor`:
+
+```shell
+pip install transformers-haystack
+```
+
+The component works with any Hugging Face model that supports token classification or NER.
+
+`TransformersNamedEntityExtractor` 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_integrations.components.extractors.transformers import (
+ TransformersNamedEntityExtractor,
+)
+
+extractor = TransformersNamedEntityExtractor(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."),
+]
+
+result = extractor.run(documents)
+print(result["documents"])
+```
+
+Here is the example result:
+
+```text
+[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=np.float32(0.99641764)), NamedEntityAnnotation(entity='LOC', start=31, end=39, score=np.float32(0.996198)), NamedEntityAnnotation(entity='LOC', start=41, end=51, score=np.float32(0.9990196))]}),
+Document(id=98f1dc5d0ccd9d9950cd191d1076db0f7af40c401dd7608f11c90cb3fc38c0c2, content: 'I'm Merlin, the happy pig!', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=4, end=10, score=np.float32(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=np.float32(0.9989541)), NamedEntityAnnotation(entity='LOC', start=30, end=51, score=np.float32(0.9574631))]})]
+```
+
+### 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_integrations.components.extractors.transformers import (
+ TransformersNamedEntityExtractor,
+)
+
+extractor = TransformersNamedEntityExtractor(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."),
+]
+
+result = extractor.run(documents)
+
+annotations = [
+ TransformersNamedEntityExtractor.get_stored_annotations(doc)
+ for doc in result["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 TransformersNamedEntityExtractor.get_stored_annotations(new_doc) is None
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers.mdx
new file mode 100644
index 00000000000..6496e694d1b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers.mdx
@@ -0,0 +1,18 @@
+---
+title: "Fetchers"
+id: fetchers
+slug: "/fetchers"
+description: "Fetchers retrieve content from external sources – URLs, web crawls, or cloud storage such as SharePoint and Google Drive – so you can use it as data for your pipelines."
+---
+
+# Fetchers
+
+Fetchers retrieve content from external sources – URLs, web crawls, or cloud storage such as SharePoint and Google Drive – so you can use it as data for your pipelines.
+
+| Component | Description |
+| --- | --- |
+| [FirecrawlCrawler](fetchers/firecrawlcrawler.mdx) | Crawls websites with Firecrawl, following links to discover subpages, and returns them as Documents. |
+| [GoogleDriveFetcher](fetchers/googledrivefetcher.mdx) | Fetches the full content of Google Drive files via the Drive API v3 and returns it as ByteStreams. |
+| [LinkContentFetcher](fetchers/linkcontentfetcher.mdx) | Fetches the contents of the URLs you give it so you can use them as data for your pipelines. |
+| [MSSharePointFetcher](fetchers/mssharepointfetcher.mdx) | Fetches the full content of Microsoft SharePoint and OneDrive items via the Microsoft Graph API and returns it as ByteStreams. |
+| [TavilyFetcher](fetchers/tavilyfetcher.mdx) | Extracts and parses the content of the URLs you give it with the Tavily Extract API and returns it as Documents. |
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/external-integrations-fetchers.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/external-integrations-fetchers.mdx
new file mode 100644
index 00000000000..63d3630be1e
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/external-integrations-fetchers.mdx
@@ -0,0 +1,17 @@
+---
+title: "External Integrations"
+id: external-integrations-fetchers
+slug: "/external-integrations-fetchers"
+description: "External integrations that enable data extraction from different sources."
+---
+
+# External Integrations
+
+External integrations that enable data extraction from different sources.
+
+| Name | Description |
+| --- | --- |
+| [Apify](https://haystack.deepset.ai/integrations/apify) | Extract data from e-commerce websites, social media platforms (such as Facebook, Instagram, and TikTok), search engines, online maps, and more, while automating web tasks. |
+| [Bright Data](https://haystack.deepset.ai/integrations/bright-data) | Extract data from 45+ websites, get search engine results, and access geo-restricted content using Bright Data's web scraping services. |
+| [Mastodon](https://haystack.deepset.ai/integrations/mastodon-fetcher) | Fetch a Mastodon username's latest posts. |
+| [Notion](https://haystack.deepset.ai/integrations/notion-extractor) | Extract pages from Notion to Haystack Documents. |
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/firecrawlcrawler.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/firecrawlcrawler.mdx
new file mode 100644
index 00000000000..69da316d0a8
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/firecrawlcrawler.mdx
@@ -0,0 +1,109 @@
+---
+title: "FirecrawlCrawler"
+id: firecrawlcrawler
+slug: "/firecrawlcrawler"
+description: "Use Firecrawl to crawl websites and return the content as Haystack Documents. Unlike single-page fetchers, FirecrawlCrawler follows links and discovers subpages."
+---
+
+# FirecrawlCrawler
+
+Use Firecrawl to crawl websites and return the content as Haystack Documents. Unlike single-page fetchers, FirecrawlCrawler follows links and discovers subpages.
+
+
+
+| | |
+| --- | --- |
+| **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** | After [`GoogleDriveRetriever`](../retrievers/googledriveretriever.mdx), before a Router or File Converters |
+| **Mandatory init variables** | None |
+| **Mandatory run variables** | `access_token`: A delegated Google OAuth bearer token, typically wired from an upstream `OAuthTokenResolver`
`targets`: A list of `Document`s (from `GoogleDriveRetriever`) or raw Google Drive file ids / URLs | +| **Output variables** | `streams`: A list of [ByteStreams](../../concepts/data-classes.mdx) holding the fetched content | +| **API reference** | [Google Drive](/reference/integrations-google-drive) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_drive | +| **Package name** | `google-drive-haystack` | + +
+
+## Overview
+
+`GoogleDriveFetcher` downloads the full content of Google Drive files through the [Drive API v3](https://developers.google.com/drive/api/reference/rest/v3) and returns `ByteStream` objects, ready for a downstream converter.
+
+It complements [`GoogleDriveRetriever`](../retrievers/googledriveretriever.mdx), which returns only metadata (and optionally exported text). Wire the retriever's `documents` (or a list of file ids / Drive URLs) into the fetcher to download the underlying content. The fetcher dispatches on each file's mime type:
+
+- **Binary files** (PDF, DOCX, images, ...) are downloaded as-is via `files.get?alt=media`.
+- **Native Google Docs/Sheets/Slides** are exported with `files.export`, by default to the Office formats (DOCX/XLSX/PPTX), configurable via `export_mime_types`.
+- **Folders** and other non-downloadable Google types (Forms, Sites, ...) are skipped.
+
+Each `ByteStream`'s `meta` carries `file_id`, `web_url`, `file_name`, and `content_type`. Because the output is a list of `ByteStream`s of mixed types, the typical next step is a [`FileTypeRouter`](../routers/filetyperouter.mdx) that dispatches each stream to the right converter ([`PyPDFToDocument`](../converters/pypdftodocument.mdx), [`DOCXToDocument`](../converters/docxtodocument.mdx), [`XLSXToDocument`](../converters/xlsxtodocument.mdx), or [`PPTXToDocument`](../converters/pptxtodocument.mdx)).
+
+### Authentication
+
+The fetcher takes a per-user `access_token` as a run input. The token must carry a delegated Google OAuth scope that allows reading file content, for example `https://www.googleapis.com/auth/drive.readonly`. Typically you wire it from an upstream [`OAuthTokenResolver`](../connectors/oauthtokenresolver.mdx), which emits a plain string. A `Secret` is also accepted and resolved internally.
+
+### Error handling and concurrency
+
+- `raise_on_failure` (default `True`): when `False`, a failed fetch is logged and the file is skipped, so the remaining files are still returned.
+- `max_retries` (default `3`): retries on throttled (HTTP 429) and transient server errors.
+- `max_concurrent_requests` (default `5`): bounds the number of files fetched concurrently by `run_async` to avoid tripping Drive rate limits. It has no effect on the synchronous `run`, which fetches files one at a time.
+- `export_mime_types`: overrides the default native-Google-to-Office export mapping. Drive caps a single export at 10 MB.
+
+### Installation
+
+Install the Google Drive integration with:
+
+```shell
+pip install google-drive-haystack
+```
+
+## Usage
+
+### On its own
+
+`access_token` below is a per-user delegated Google OAuth bearer token. You can pass either raw file ids / Drive URLs or the `Document`s produced by `GoogleDriveRetriever`.
+
+```python
+from haystack_integrations.components.fetchers.google_drive import GoogleDriveFetcher
+
+fetcher = GoogleDriveFetcher()
+
+result = fetcher.run(
+ access_token="my-delegated-google-token",
+ targets=[
+ "https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/view",
+ ],
+)
+
+for stream in result["streams"]:
+ print(stream.meta["file_name"], stream.meta["content_type"])
+```
+
+### In a pipeline
+
+The following query pipeline ties the whole integration together: an [`OAuthTokenResolver`](../connectors/oauthtokenresolver.mdx) provides a token, [`GoogleDriveRetriever`](../retrievers/googledriveretriever.mdx) searches Drive, `GoogleDriveFetcher` downloads the matching files, and a [`FileTypeRouter`](../routers/filetyperouter.mdx) sends each `ByteStream` to the right converter. Note that the resolver's single `access_token` output feeds both the retriever and the fetcher.
+
+```python
+from haystack import Pipeline
+from haystack.utils import Secret
+from haystack.components.routers import FileTypeRouter
+from haystack.components.converters import PyPDFToDocument, DOCXToDocument
+
+from haystack_integrations.components.connectors.oauth import OAuthTokenResolver
+from haystack_integrations.utils.oauth import OAuthRefreshTokenSource
+from haystack_integrations.components.retrievers.google_drive import (
+ GoogleDriveRetriever,
+)
+from haystack_integrations.components.fetchers.google_drive import GoogleDriveFetcher
+
+pipeline = Pipeline()
+pipeline.add_component(
+ "resolver",
+ OAuthTokenResolver(
+ token_source=OAuthRefreshTokenSource(
+ token_url="https://oauth2.googleapis.com/token",
+ client_id="aaa-bbb-ccc",
+ refresh_token=Secret.from_env_var("GOOGLE_REFRESH_TOKEN"),
+ scopes=["https://www.googleapis.com/auth/drive.readonly"],
+ ),
+ ),
+)
+pipeline.add_component("retriever", GoogleDriveRetriever(top_k=5))
+pipeline.add_component("fetcher", GoogleDriveFetcher())
+pipeline.add_component(
+ "router",
+ FileTypeRouter(
+ mime_types=[
+ "application/pdf",
+ "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+ ],
+ ),
+)
+pipeline.add_component("pdf_converter", PyPDFToDocument())
+pipeline.add_component("docx_converter", DOCXToDocument())
+
+# The same token feeds both the retriever and the fetcher.
+pipeline.connect("resolver.access_token", "retriever.access_token")
+pipeline.connect("resolver.access_token", "fetcher.access_token")
+
+# The retrieved documents become the fetcher's targets.
+pipeline.connect("retriever.documents", "fetcher.targets")
+
+# Route each fetched ByteStream to the matching converter.
+pipeline.connect("fetcher.streams", "router.sources")
+pipeline.connect("router.application/pdf", "pdf_converter.sources")
+pipeline.connect(
+ "router.application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+ "docx_converter.sources",
+)
+
+result = pipeline.run({"retriever": {"query": "quarterly roadmap"}})
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/linkcontentfetcher.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/linkcontentfetcher.mdx
new file mode 100644
index 00000000000..2359e068095
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/linkcontentfetcher.mdx
@@ -0,0 +1,130 @@
+---
+title: "LinkContentFetcher"
+id: linkcontentfetcher
+slug: "/linkcontentfetcher"
+description: "With LinkContentFetcher, you can use the contents of several URLs as the data for your pipeline. You can use it in indexing and query pipelines to fetch the contents of the URLs you give it."
+---
+
+# LinkContentFetcher
+
+With LinkContentFetcher, you can use the contents of several URLs as the data for your pipeline. You can use it in indexing and query pipelines to fetch the contents of the URLs you give it.
+
+`targets`: A list of `Document`s (from `GoogleDriveRetriever`) or raw Google Drive file ids / URLs | +| **Output variables** | `streams`: A list of [ByteStreams](../../concepts/data-classes.mdx) holding the fetched content | +| **API reference** | [Google Drive](/reference/integrations-google-drive) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_drive | +| **Package name** | `google-drive-haystack` | + +
+
+| | |
+| --- | --- |
+| **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-3.2-unstable/pipeline-components/fetchers/mssharepointfetcher.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/mssharepointfetcher.mdx
new file mode 100644
index 00000000000..3989d6bc041
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/mssharepointfetcher.mdx
@@ -0,0 +1,147 @@
+---
+title: "MSSharePointFetcher"
+id: mssharepointfetcher
+slug: "/mssharepointfetcher"
+description: "Fetches the full content of Microsoft SharePoint and OneDrive items via the Microsoft Graph API and returns it as ByteStreams."
+---
+
+# MSSharePointFetcher
+
+Fetches the full content of Microsoft SharePoint and OneDrive items via the Microsoft Graph API and returns it as ByteStreams.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After [`MSSharePointRetriever`](../retrievers/mssharepointretriever.mdx), before a Router or File Converters |
+| **Mandatory init variables** | None |
+| **Mandatory run variables** | `access_token`: A delegated Microsoft Graph bearer token, typically wired from an upstream `OAuthTokenResolver`
`targets`: A list of `Document`s (from `MSSharePointRetriever`) or raw SharePoint/OneDrive `web_url` strings | +| **Output variables** | `streams`: A list of [ByteStreams](../../concepts/data-classes.mdx) holding the fetched content | +| **API reference** | [Microsoft SharePoint](/reference/integrations-microsoft-sharepoint) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/microsoft_sharepoint | +| **Package name** | `microsoft-sharepoint-haystack` | + +
+
+## Overview
+
+`MSSharePointFetcher` downloads the full content of Microsoft SharePoint and OneDrive items through the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/use-the-api) and returns `ByteStream` objects, ready for a downstream converter.
+
+It complements [`MSSharePointRetriever`](../retrievers/mssharepointretriever.mdx), which returns only Search snippets and metadata. Wire the retriever's `documents` (or a list of `web_url`s) into the fetcher to download the underlying content. The fetcher dispatches on the entity type of each hit:
+
+- **Files** (`driveItem`) are downloaded as their raw bytes (PDF, DOCX, ...).
+- **List items** (`listItem`) are returned as a JSON `ByteStream` of the item's column values (`fields`).
+- **SharePoint pages** (`sitePage`) are returned as an HTML `ByteStream` built from the page's web parts.
+
+Each `ByteStream`'s `meta` carries `url`, `file_name`, `content_type`, and a normalized `entity_type` (`driveItem`, `listItem`, or `sitePage`). Everything is resolved through the Microsoft Graph `shares` endpoint (plus the Pages API for pages), so only the `web_url` already exposed by the retriever is needed.
+
+Because the output is a list of `ByteStream`s of mixed types, the typical next step is a [`FileTypeRouter`](../routers/filetyperouter.mdx) that dispatches each stream to the right converter ([`PyPDFToDocument`](../converters/pypdftodocument.mdx), [`DOCXToDocument`](../converters/docxtodocument.mdx), [`HTMLToDocument`](../converters/htmltodocument.mdx), or a JSON converter).
+
+### Authentication
+
+The fetcher takes a per-user `access_token` as a run input. The token must carry **delegated** Microsoft Graph permissions (for example `Files.Read.All` for files and `Sites.Read.All` for list items and pages). Typically you wire it from an upstream [`OAuthTokenResolver`](../connectors/oauthtokenresolver.mdx), which emits a plain string. A `Secret` is also accepted and resolved internally.
+
+### Error handling and concurrency
+
+- `raise_on_failure` (default `True`): when `False`, a failed fetch is logged and the item is skipped, so the remaining items are still returned.
+- `max_retries` (default `3`): retries on throttled (HTTP 429) and transient server errors.
+- `max_concurrent_requests` (default `5`): bounds the number of items fetched concurrently by `run_async` to avoid tripping Microsoft Graph rate limits. It has no effect on the synchronous `run`, which fetches items one at a time.
+
+### Installation
+
+Install the Microsoft SharePoint integration with:
+
+```shell
+pip install microsoft-sharepoint-haystack
+```
+
+## Usage
+
+### On its own
+
+`access_token` below is a per-user delegated Microsoft Graph bearer token. You can pass either raw `web_url` strings or the `Document`s produced by `MSSharePointRetriever`.
+
+```python
+from haystack_integrations.components.fetchers.microsoft_sharepoint import (
+ MSSharePointFetcher,
+)
+
+fetcher = MSSharePointFetcher()
+
+result = fetcher.run(
+ access_token="my-delegated-graph-token",
+ targets=[
+ "https://contoso.sharepoint.com/sites/contoso-team/contoso-designs.docx",
+ ],
+)
+
+for stream in result["streams"]:
+ print(stream.meta["file_name"], stream.meta["content_type"])
+```
+
+### In a pipeline
+
+The following query pipeline ties the whole integration together: an [`OAuthTokenResolver`](../connectors/oauthtokenresolver.mdx) provides a token, [`MSSharePointRetriever`](../retrievers/mssharepointretriever.mdx) searches SharePoint, `MSSharePointFetcher` downloads the matching items, and a [`FileTypeRouter`](../routers/filetyperouter.mdx) sends each `ByteStream` to the right converter. Note that the resolver's single `access_token` output feeds both the retriever and the fetcher.
+
+```python
+from haystack import Pipeline
+from haystack.utils import Secret
+from haystack.components.routers import FileTypeRouter
+from haystack.components.converters import PyPDFToDocument, DOCXToDocument
+
+from haystack_integrations.components.connectors.oauth import OAuthTokenResolver
+from haystack_integrations.utils.oauth import OAuthRefreshTokenSource
+from haystack_integrations.components.retrievers.microsoft_sharepoint import (
+ MSSharePointRetriever,
+)
+from haystack_integrations.components.fetchers.microsoft_sharepoint import (
+ MSSharePointFetcher,
+)
+
+pipeline = Pipeline()
+pipeline.add_component(
+ "resolver",
+ OAuthTokenResolver(
+ token_source=OAuthRefreshTokenSource(
+ token_url="https://login.microsoftonline.com/common/oauth2/v2.0/token",
+ client_id="aaa-bbb-ccc",
+ refresh_token=Secret.from_env_var("MS_REFRESH_TOKEN"),
+ scopes=[
+ "https://graph.microsoft.com/Files.Read.All",
+ "https://graph.microsoft.com/Sites.Read.All",
+ "offline_access",
+ ],
+ ),
+ ),
+)
+pipeline.add_component("retriever", MSSharePointRetriever(top_k=5))
+pipeline.add_component("fetcher", MSSharePointFetcher())
+pipeline.add_component(
+ "router",
+ FileTypeRouter(
+ mime_types=[
+ "application/pdf",
+ "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+ ],
+ ),
+)
+pipeline.add_component("pdf_converter", PyPDFToDocument())
+pipeline.add_component("docx_converter", DOCXToDocument())
+
+# The same token feeds both the retriever and the fetcher.
+pipeline.connect("resolver.access_token", "retriever.access_token")
+pipeline.connect("resolver.access_token", "fetcher.access_token")
+
+# The retrieved documents become the fetcher's targets.
+pipeline.connect("retriever.documents", "fetcher.targets")
+
+# Route each fetched ByteStream to the matching converter.
+pipeline.connect("fetcher.streams", "router.sources")
+pipeline.connect("router.application/pdf", "pdf_converter.sources")
+pipeline.connect(
+ "router.application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+ "docx_converter.sources",
+)
+
+result = pipeline.run({"retriever": {"query": "quarterly roadmap"}})
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/tavilyfetcher.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/tavilyfetcher.mdx
new file mode 100644
index 00000000000..cab3571c019
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/fetchers/tavilyfetcher.mdx
@@ -0,0 +1,138 @@
+---
+title: "TavilyFetcher"
+id: tavilyfetcher
+slug: "/tavilyfetcher"
+description: "Use Tavily Extract to fetch and parse content from URLs as Haystack Documents. Unlike web search, it retrieves content from the URLs you provide rather than discovering them via a query."
+---
+
+# TavilyFetcher
+
+Use Tavily Extract to fetch and parse content from URLs as Haystack Documents. Unlike web search, it retrieves content from the URLs you provide rather than discovering them via a query.
+
+`targets`: A list of `Document`s (from `MSSharePointRetriever`) or raw SharePoint/OneDrive `web_url` strings | +| **Output variables** | `streams`: A list of [ByteStreams](../../concepts/data-classes.mdx) holding the fetched content | +| **API reference** | [Microsoft SharePoint](/reference/integrations-microsoft-sharepoint) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/microsoft_sharepoint | +| **Package name** | `microsoft-sharepoint-haystack` | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing or query pipelines as the data fetching step |
+| **Mandatory init variables** | `api_key`: The Tavily API key. Can be set with the `TAVILY_API_KEY` env var. |
+| **Mandatory run variables** | `urls`: A list of URLs (strings) to extract content from (max 20 per request) |
+| **Output variables** | `documents`: A list of [Documents](../../concepts/data-classes.mdx)
`meta`: Request-level metadata (`response_time`, `usage`, `request_id`, `failed_results`) | +| **API reference** | [Tavily](/reference/integrations-tavily) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/tavily | +| **Package name** | `tavily-haystack` | + +
+
+## Overview
+
+`TavilyFetcher` wraps the [Tavily Extract API](https://docs.tavily.com/documentation/api-reference/endpoint/extract) to retrieve and parse web page content from one or more specified URLs. PDF URLs are also supported. Each successful URL becomes a Haystack `Document` with page content in `content` and metadata such as `url` (and optionally `images`) in `meta`.
+
+This component is complementary to [`TavilyWebSearch`](../websearch/tavilywebsearch.mdx): search discovers URLs from a query, while `TavilyFetcher` extracts full content from URLs you already have.
+
+### Extract parameters
+
+You can control extraction behavior at initialization:
+
+- `extract_depth`: `"basic"` (fast, lower cost) or `"advanced"` (more data including tables; higher latency and cost). Defaults to `"basic"`.
+- `include_images`: When `True`, image URLs are stored on each Document under `meta["images"]`. Defaults to `False`.
+- `extract_params`: Extra kwargs forwarded to the Tavily Extract API (for example `format`, `include_favicon`, `query`, `chunks_per_source`). See the [Tavily Extract API reference](https://docs.tavily.com/documentation/api-reference/endpoint/extract).
+
+Of these, only `extract_params` can also be passed to `run()` to override it for a single call. Note that an `extract_params` dictionary passed to `run()` fully replaces the one set at initialization instead of being merged with it.
+
+### Authorization
+
+`TavilyFetcher` uses the `TAVILY_API_KEY` environment variable by default. You can also pass the key explicitly:
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.fetchers.tavily import TavilyFetcher
+
+fetcher = TavilyFetcher(api_key=Secret.from_token("`meta`: Request-level metadata (`response_time`, `usage`, `request_id`, `failed_results`) | +| **API reference** | [Tavily](/reference/integrations-tavily) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/tavily | +| **Package name** | `tavily-haystack` | + +
+
+| | |
+| --- | --- |
+| **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 |
+| **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`, `tool`), 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", parameters=..., function=...
+)
+news_tool = Tool(
+ name="news", description="Get latest news", parameters=..., function=...
+)
+
+# 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
+from haystack_integrations.components.generators.aimlapi import AIMLAPIChatGenerator
+
+# 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=
+
+| | |
+| --- | --- |
+| **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 | +| **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 AmazonBedrockChatGenerator 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", parameters=..., function=...
+)
+news_tool = Tool(
+ name="news", description="Get latest news", parameters=..., function=...
+)
+
+# 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="global.anthropic.claude-sonnet-4-6",
+ 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="global.anthropic.claude-sonnet-4-6",
+)
+
+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="global.anthropic.claude-sonnet-4-6",
+ 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="global.anthropic.claude-sonnet-4-6")
+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="global.anthropic.claude-sonnet-4-6")
+
+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="global.anthropic.claude-sonnet-4-6")
+)
+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-3.2-unstable/pipeline-components/generators/anthropicchatgenerator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/anthropicchatgenerator.mdx
new file mode 100644
index 00000000000..fda8eba7fa5
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/anthropicchatgenerator.mdx
@@ -0,0 +1,226 @@
+---
+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** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) instances | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **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 |
+| **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`, `tool`), and optional metadata.
+
+Both text and image input modalities are supported.
+
+### 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", parameters=..., function=...
+)
+news_tool = Tool(
+ name="news", description="Get latest news", parameters=..., function=...
+)
+
+# 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
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+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-3.2-unstable/pipeline-components/generators/anthropicfoundrychatgenerator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/anthropicfoundrychatgenerator.mdx
new file mode 100644
index 00000000000..a3cfe4f2739
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/anthropicfoundrychatgenerator.mdx
@@ -0,0 +1,187 @@
+---
+title: "AnthropicFoundryChatGenerator"
+id: anthropicfoundrychatgenerator
+slug: "/anthropicfoundrychatgenerator"
+description: "This component enables chat completions using Anthropic models served through Azure Foundry."
+---
+
+# AnthropicFoundryChatGenerator
+
+This component enables chat completions using Anthropic models served through Azure Foundry.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: Your Azure Foundry API key. Can be set with the `ANTHROPIC_FOUNDRY_API_KEY` env var. Alternatively, pass an `azure_ad_token_provider` callable.
`resource`: Your Azure Foundry resource name. Can be set with the `ANTHROPIC_FOUNDRY_RESOURCE` env var. Alternatively, pass a full `endpoint` URL. | +| **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** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | +| **Package name** | `anthropic-haystack` | + +
+
+## Overview
+
+`AnthropicFoundryChatGenerator` lets you call Anthropic's Claude models through an [Azure Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/) deployment. It is a thin subclass of [`AnthropicChatGenerator`](anthropicchatgenerator.mdx) — the request and response shapes match the Anthropic Messages API, but the traffic flows through your Azure resource instead of `api.anthropic.com`.
+
+Use this generator when your organization standardizes on Azure for model hosting (billing, networking, compliance) but still wants to work against Claude. If you don't need Azure, prefer `AnthropicChatGenerator`.
+
+The default model is `claude-sonnet-4-5`. Other models known to work include `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-opus-4-5`, `claude-opus-4-1`, and `claude-haiku-4-5`. This list is not exhaustive — the actual catalog depends on what is deployed in your Foundry resource. See the [Anthropic model overview](https://docs.anthropic.com/en/docs/about-claude/models) for guidance on picking a model.
+
+### Parameters
+
+`AnthropicFoundryChatGenerator` needs two things to talk to Azure: credentials and an endpoint.
+
+**Credentials.** Pick one of:
+
+- The `ANTHROPIC_FOUNDRY_API_KEY` environment variable (recommended).
+- The `api_key` init parameter using the Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`.
+- A callable passed as `azure_ad_token_provider` that returns a fresh Azure AD token on demand. Use this for Entra ID / managed-identity setups where a static key isn't appropriate.
+
+**Endpoint.** Pick one of:
+
+- The `resource` init parameter (or the `ANTHROPIC_FOUNDRY_RESOURCE` environment variable) — the short Foundry resource name, used to derive the URL.
+- The `endpoint` init parameter — a full URL, useful for custom domains or non-standard routes.
+
+Once configured, pass any text-generation parameter supported by the Anthropic [Messages API](https://docs.anthropic.com/en/api/messages) through `generation_kwargs`, either at init or per call. Common keys include `system`, `max_tokens`, `temperature`, `top_p`, `top_k`, `stop_sequences`, `metadata`, and `extra_headers`. You can also tune `timeout` and `max_retries` to control client-side resilience.
+
+The component takes a list of `ChatMessage` objects. `ChatMessage` is a data class that holds a message, a role (`user`, `assistant`, `system`, or `tool`), and optional metadata. Only text input is supported.
+
+### Tool Support
+
+`AnthropicFoundryChatGenerator` supports function calling through the `tools` parameter, which accepts:
+
+- **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.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.anthropic import (
+ AnthropicFoundryChatGenerator,
+)
+
+weather_tool = Tool(
+ name="weather", description="Get weather info", parameters=..., function=...
+)
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+generator = AnthropicFoundryChatGenerator(
+ resource="my-resource",
+ tools=[math_toolset, weather_tool],
+)
+```
+
+Tools passed to `run()` override any tools set at init time. For more details, 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`. The built-in `print_streaming_chunk` prints text tokens and tool events to stdout.
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.anthropic import (
+ AnthropicFoundryChatGenerator,
+)
+
+generator = AnthropicFoundryChatGenerator(
+ resource="my-resource",
+ streaming_callback=print_streaming_chunk,
+)
+generator.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 [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) for how `StreamingChunk` works and how to write a custom callback. Prefer `print_streaming_chunk` unless you need a specific transport (such as SSE or WebSocket) or custom UI formatting.
+
+### Async
+
+`run_async` mirrors `run` and is wired up automatically — useful inside an async pipeline or web handler.
+
+```python
+import asyncio
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.anthropic import (
+ AnthropicFoundryChatGenerator,
+)
+
+
+async def main():
+ generator = AnthropicFoundryChatGenerator(resource="my-resource")
+ result = await generator.run_async([ChatMessage.from_user("Hello!")])
+ print(result["replies"][0].text)
+
+
+asyncio.run(main())
+```
+
+## Usage
+
+Install the `anthropic-haystack` package to use the `AnthropicFoundryChatGenerator`:
+
+```shell
+pip install anthropic-haystack
+```
+
+### On its own
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack_integrations.components.generators.anthropic import (
+ AnthropicFoundryChatGenerator,
+)
+
+generator = AnthropicFoundryChatGenerator(
+ model="claude-sonnet-4-5",
+ api_key=Secret.from_env_var("ANTHROPIC_FOUNDRY_API_KEY"),
+ resource="my-resource",
+)
+
+response = generator.run([ChatMessage.from_user("What's Natural Language Processing?")])
+print(response)
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.anthropic import (
+ AnthropicFoundryChatGenerator,
+)
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component(
+ "llm",
+ AnthropicFoundryChatGenerator(resource="my-resource"),
+)
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+messages = [
+ ChatMessage.from_system(
+ "You are an assistant giving out valuable information to language learners.",
+ ),
+ 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-3.2-unstable/pipeline-components/generators/anthropicvertexchatgenerator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/anthropicvertexchatgenerator.mdx
new file mode 100644
index 00000000000..0e651e76fbf
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/anthropicvertexchatgenerator.mdx
@@ -0,0 +1,183 @@
+---
+title: "AnthropicVertexChatGenerator"
+id: anthropicvertexchatgenerator
+slug: "/anthropicvertexchatgenerator"
+description: "This component enables chat completions using AnthropicVertex API."
+---
+
+# AnthropicVertexChatGenerator
+
+This component enables chat completions using AnthropicVertex API.
+
+`resource`: Your Azure Foundry resource name. Can be set with the `ANTHROPIC_FOUNDRY_RESOURCE` env var. Alternatively, pass a full `endpoint` URL. | +| **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** | [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 [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **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 Anthropic's Claude models through the Anthropic Vertex AI API.
+A variety of Claude models (Opus, Sonnet, Haiku, and others) 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 pass your GCP `project_id` and `region` as init parameters. If you pass `None` for both, the component falls back to the `PROJECT_ID` and `REGION` environment variables.
+
+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`, `tool`), 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-sonnet-4@20250514",
+ 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-3.2-unstable/pipeline-components/generators/azureopenaichatgenerator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/azureopenaichatgenerator.mdx
new file mode 100644
index 00000000000..c5c1d096689
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/azureopenaichatgenerator.mdx
@@ -0,0 +1,225 @@
+---
+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 [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **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 or a plain string | +| **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-4.1-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 or a plain string | +| **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 [`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 or a plain string | +| **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. If a string is passed, it is converted into a list containing a single `ChatMessage` with the `user` role. 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 or a plain string | +| **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 |
+| **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-a-03-2025` (the default), `command-a-plus-05-2026`, and `command-r-plus-08-2024`. 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`, `tool`), 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", parameters=..., function=...
+)
+news_tool = Tool(
+ name="news", description="Get latest news", parameters=..., function=...
+)
+
+# 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-3.2-unstable/pipeline-components/generators/cometapichatgenerator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/cometapichatgenerator.mdx
new file mode 100644
index 00000000000..76961cb37d1
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/cometapichatgenerator.mdx
@@ -0,0 +1,320 @@
+---
+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.
+
+
+
+| | |
+| --- | --- |
+| **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 |
+| **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, xAI, DeepSeek, 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-5-mini` (default), `gpt-4o`, `gpt-4o-mini`, and more
+- Anthropic models: `claude-sonnet-4-5`, `claude-opus-4-5-20251101`, and more
+- Google models: `gemini-2.5-pro`, `gemini-2.5-flash`, and more
+- xAI models: `grok-4.3`, and more
+- DeepSeek models: `deepseek-chat`, 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`, `tool`), 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", parameters=..., function=...
+)
+news_tool = Tool(
+ name="news", description="Get latest news", parameters=..., function=...
+)
+
+# 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
+from haystack_integrations.components.generators.cometapi import CometAPIChatGenerator
+
+# 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=
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Eden AI API key. Can be set with `EDENAI_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** | [Eden AI](/reference/integrations-edenai) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/edenai |
+| **Package name** | `edenai-haystack` |
+
+
+
+## Overview
+
+`EdenAIChatGenerator` connects Haystack to [Eden AI](https://www.edenai.co/), a unified, OpenAI-compatible API that gives access to 500+ models from many providers (OpenAI, Anthropic, Mistral, Google, Cohere, and more) through a single API key, with EU data residency.
+
+`EdenAIChatGenerator` needs an Eden AI API key to work. You can write this key in:
+
+- The `api_key` init parameter using [Secret API](../../concepts/secret-management.mdx)
+- The `EDENAI_API_KEY` environment variable (recommended)
+
+Models are selected using Eden AI's `provider/model` naming convention, for example:
+
+- `openai/gpt-4o-mini` (default)
+- `anthropic/claude-sonnet-4-5`
+- `mistral/mistral-large-latest`
+- `google/gemini-2.5-flash`
+
+For the full list of available models, see the [Eden AI models catalog](https://www.edenai.co/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`, `tool`), and optional metadata.
+
+Refer to the [Eden AI documentation](https://docs.edenai.co/) for more details on the parameters supported by the API, which you can provide with `generation_kwargs` when running the component.
+
+### Tool Support
+
+`EdenAIChatGenerator` supports function calling through the `tools` parameter, which accepts a list of `Tool` objects, a single `Toolset`, or a mix of both. This lets you organize related tools into logical groups while also including standalone tools as needed.
+
+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 `edenai-haystack` package to use the `EdenAIChatGenerator`:
+
+```shell
+pip install edenai-haystack
+```
+
+#### On its own
+
+```python
+from haystack_integrations.components.generators.edenai import EdenAIChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+generator = EdenAIChatGenerator(
+ api_key=Secret.from_env_var("EDENAI_API_KEY"),
+ model="mistral/mistral-large-latest",
+ streaming_callback=print_streaming_chunk,
+)
+message = ChatMessage.from_user("What's Natural Language Processing? Be brief.")
+print(generator.run([message]))
+```
+
+#### In a Pipeline
+
+Below is an example RAG Pipeline where we answer questions based on the contents of a URL. We add the contents of the URL into our `messages` in the `ChatPromptBuilder` and generate an answer with the `EdenAIChatGenerator`.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.fetchers import LinkContentFetcher
+from haystack.components.converters import HTMLToDocument
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.components.generators.edenai import EdenAIChatGenerator
+
+fetcher = LinkContentFetcher()
+converter = HTMLToDocument()
+prompt_builder = ChatPromptBuilder(variables=["documents"])
+llm = EdenAIChatGenerator(model="mistral/mistral-large-latest")
+
+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 is Eden AI?"
+
+result = rag_pipeline.run(
+ {
+ "fetcher": {"urls": ["https://www.edenai.co/"]},
+ "prompt_builder": {
+ "template_variables": {"query": question},
+ "template": messages,
+ },
+ },
+)
+
+print(result["llm"]["replies"][0].text)
+```
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/external-integrations-generators.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/external-integrations-generators.mdx
new file mode 100644
index 00000000000..f1fa662645b
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/external-integrations-generators.mdx
@@ -0,0 +1,17 @@
+---
+title: "External Integrations"
+id: external-integrations-generators
+slug: "/external-integrations-generators"
+description: "External integrations that enable RAG pipeline creation."
+---
+
+# External Integrations
+
+External integrations that enable RAG pipeline creation.
+
+| Name | Description |
+| --- | --- |
+| [DeepL](https://haystack.deepset.ai/integrations/deepl) | Translate your text and documents using DeepL services. |
+| [fastRAG](https://haystack.deepset.ai/integrations/fastrag/) | Enables the creation of efficient and optimized retrieval augmented generative pipelines. |
+| [LM Format Enforcer](https://haystack.deepset.ai/integrations/lmformatenforcer) | Enforce JSON Schema / Regex output of your local models with `LMFormatEnforcerLocalGenerator`. |
+| [Titan](https://haystack.deepset.ai/integrations/titanml-takeoff) | Run local open-source LLMs from Meta, Mistral and Alphabet directly in your computer. |
diff --git a/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/fallbackchatgenerator.mdx b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/fallbackchatgenerator.mdx
new file mode 100644
index 00000000000..6a66aaaf03e
--- /dev/null
+++ b/docs-website/versioned_docs/version-3.2-unstable/pipeline-components/generators/fallbackchatgenerator.mdx
@@ -0,0 +1,242 @@
+---
+title: "FallbackChatGenerator"
+id: fallbackchatgenerator
+slug: "/fallbackchatgenerator"
+description: "A ChatGenerator wrapper that tries multiple Chat Generators sequentially until one succeeds."
+---
+
+# FallbackChatGenerator
+
+A ChatGenerator wrapper that tries multiple Chat Generators sequentially until one succeeds.
+
+
+
+| | |
+| --- | --- |
+| **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 or a plain string |
+| **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. If a string is passed to `messages`, it is converted into a list containing a single `ChatMessage` with the `user` role before forwarding.
+
+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 models such as `gemini-3.8-flash` (the default), `gemini-3.7-flash`, `gemini-2.5-pro`, and `gemini-2.5-flash`.
+
+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 models such as `gemini-3.8-flash` (the default), `gemini-3.7-flash`, `gemini-2.5-pro`, and `gemini-2.5-flash`.
+
+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.8-flash`, `gemini-3.7-flash`, `gemini-3.6-flash`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, and `gemini-2.5-flash-lite`. `gemini-3.8-flash` is the default.
+
+### 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", parameters=..., function=...
+)
+news_tool = Tool(
+ name="news", description="Get latest news", parameters=..., function=...
+)
+
+# 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
+chat_generator = GoogleGenAIChatGenerator(api_key=Secret.from_token("