chore: import upstream snapshot with attribution

docs-website/reference/integrations-api/aimlapi.md

@@ -0,0 +1,119 @@
+---
+title: "AIMLAPI"
+id: integrations-aimlapi
+description: "AIMLAPI integration for Haystack"
+slug: "/integrations-aimlapi"
+---
+
+<a id="haystack_integrations.components.generators.aimlapi.chat.chat_generator"></a>
+
+## Module haystack\_integrations.components.generators.aimlapi.chat.chat\_generator
+
+<a id="haystack_integrations.components.generators.aimlapi.chat.chat_generator.AIMLAPIChatGenerator"></a>
+
+### AIMLAPIChatGenerator
+
+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=<ChatRole.ASSISTANT: 'assistant'>, _name=None,
+>>_meta={'model': 'openai/gpt-5-chat-latest', 'index': 0, 'finish_reason': 'stop',
+>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]}
+```
+
+<a id="haystack_integrations.components.generators.aimlapi.chat.chat_generator.AIMLAPIChatGenerator.__init__"></a>
+
+#### AIMLAPIChatGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+             api_key: Secret = Secret.from_env_var("AIMLAPI_API_KEY"),
+             model: str = "openai/gpt-5-chat-latest",
+             streaming_callback: StreamingCallbackT | None = None,
+             api_base_url: str | None = "https://api.aimlapi.com/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)
+```
+
+Creates an instance of AIMLAPIChatGenerator. Unless specified otherwise,
+
+the default model is `openai/gpt-5-chat-latest`.
+
+**Arguments**:
+
+- `api_key`: The AIMLAPI API key.
+- `model`: The name of the AIMLAPI chat completion model to use.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+The callback function accepts StreamingChunk as an argument.
+- `api_base_url`: The AIMLAPI API Base url.
+For more details, see AIMLAPI documentation.
+- `generation_kwargs`: 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`: 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`: The timeout for the AIMLAPI API call.
+- `extra_headers`: Additional HTTP headers to include in requests to the AIMLAPI API.
+- `max_retries`: 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`: 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`).
+
+<a id="haystack_integrations.components.generators.aimlapi.chat.chat_generator.AIMLAPIChatGenerator.to_dict"></a>
+
+#### AIMLAPIChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns**:
+
+The serialized component as a dictionary.
+

docs-website/reference/integrations-api/alloydb.md

@@ -0,0 +1,601 @@
+---
+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** (<code>AlloyDBDocumentStore</code>) – An instance of `AlloyDBDocumentStore` to use as the document store.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved documents.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – 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** (<code>str | FilterPolicy</code>) – 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:**
+
+- <code>ValueError</code> – 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** (<code>list\[float\]</code>) – A vector representation of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved documents.
+  The `filter_policy` set at initialization determines how these are combined with the init filters.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return. Overrides the `top_k` set at initialization.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – The similarity function to use when searching for similar embeddings.
+  Overrides the `vector_function` set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AlloyDBEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AlloyDBEmbeddingRetriever</code> – Deserialized component.
+
+## haystack_integrations.components.retrievers.alloydb.keyword_retriever
+
+### AlloyDBKeywordRetriever
+
+Retrieves documents from the `AlloyDBDocumentStore` by keyword search.
+
+Uses PostgreSQL full-text search (`to_tsvector` / `plainto_tsquery`) to find documents.
+Must be connected to the `AlloyDBDocumentStore`.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: AlloyDBDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create the `AlloyDBKeywordRetriever` component.
+
+**Parameters:**
+
+- **document_store** (<code>AlloyDBDocumentStore</code>) – An instance of `AlloyDBDocumentStore` to use as the document store.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved documents.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – 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:**
+
+- <code>ValueError</code> – 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** (<code>str</code>) – A keyword query to search for.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved documents.
+  The `filter_policy` set at initialization determines how these are combined with the init filters.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return. Overrides the `top_k` set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AlloyDBKeywordRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AlloyDBKeywordRetriever</code> – Deserialized component.
+
+## haystack_integrations.document_stores.alloydb.document_store
+
+### AlloyDBDocumentStore
+
+Bases: <code>DocumentStore</code>
+
+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** (<code>Secret</code>) – 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** (<code>Secret</code>) – 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** (<code>Secret</code>) – The database password. Read from the `ALLOYDB_PASSWORD` environment variable by default.
+  Not required when `enable_iam_auth=True`.
+- **db** (<code>str</code>) – The name of the database to connect to. Defaults to `"postgres"`.
+- **enable_iam_auth** (<code>bool</code>) – 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** (<code>Literal['PRIVATE', 'PUBLIC', 'PSC']</code>) – 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** (<code>bool</code>) – 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** (<code>str</code>) – The name of the schema the table is created in. The schema must already exist.
+- **table_name** (<code>str</code>) – The name of the table to use to store Haystack documents.
+- **language** (<code>str</code>) – 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** (<code>int</code>) – The dimension of the embedding.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance']</code>) – 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** (<code>bool</code>) – Whether to recreate the table if it already exists.
+- **search_strategy** (<code>Literal['exact_nearest_neighbor', 'hnsw']</code>) – 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** (<code>bool</code>) – Whether to recreate the HNSW index if it already exists.
+  Only used if search_strategy is set to `"hnsw"`.
+- **hnsw_index_creation_kwargs** (<code>dict\[str, int\] | None</code>) – 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** (<code>str</code>) – Index name for the HNSW index.
+- **hnsw_ef_search** (<code>int | None</code>) – 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** (<code>str</code>) – Index name for the keyword GIN index.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AlloyDBDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AlloyDBDocumentStore</code> – Deserialized component.
+
+#### close
+
+```python
+close() -> None
+```
+
+Closes the database connection and the AlloyDB connector.
+
+Call this when you are done using the document store to release resources.
+For long-lived applications the connector runs a background refresh thread;
+calling `close()` ensures that thread is stopped cleanly.
+
+#### delete_table
+
+```python
+delete_table() -> None
+```
+
+Deletes the table used to store Haystack documents.
+
+The name of the schema (`schema_name`) and the name of the table (`table_name`)
+are defined when initializing the `AlloyDBDocumentStore`.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are in the document store.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+**Raises:**
+
+- <code>TypeError</code> – If `filters` is not a dictionary.
+- <code>ValueError</code> – 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** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` contains objects that are not of type `Document`.
+- <code>DuplicateDocumentError</code> – If a document with the same id already exists in the document store
+  and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+- <code>DocumentStoreError</code> – 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** (<code>list\[str\]</code>) – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names to count unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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** (<code>str</code>) – The metadata field name (with or without the "meta." prefix).
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with `min` and `max` keys. Returns
+  `{"min": None, "max": None}` when the field has no values or the
+  store is empty.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    field: str, filters: dict[str, Any] | None = None
+) -> list[Any]
+```
+
+Returns a list of unique values for a metadata field.
+
+**Parameters:**
+
+- **field** (<code>str</code>) – The metadata field name (with or without the "meta." prefix).
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- <code>list\[Any\]</code> – A list of unique values for the given field.

docs-website/reference/integrations-api/amazon_sagemaker.md

@@ -0,0 +1,150 @@
+---
+title: "Amazon Sagemaker"
+id: integrations-amazon-sagemaker
+description: "Amazon Sagemaker integration for Haystack"
+slug: "/integrations-amazon-sagemaker"
+---
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker"></a>
+
+## Module haystack\_integrations.components.generators.amazon\_sagemaker.sagemaker
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker.SagemakerGenerator"></a>
+
+### 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': [{}]}
+```
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker.SagemakerGenerator.__init__"></a>
+
+#### SagemakerGenerator.\_\_init\_\_
+
+```python
+def __init__(
+        model: str,
+        aws_access_key_id: Secret | None = Secret.from_env_var(
+            ["AWS_ACCESS_KEY_ID"], strict=False),
+        aws_secret_access_key: Secret
+    | None = Secret.from_env_var(  # noqa: B008
+        ["AWS_SECRET_ACCESS_KEY"], strict=False),
+        aws_session_token: Secret | None = Secret.from_env_var(
+            ["AWS_SESSION_TOKEN"], strict=False),
+        aws_region_name: Secret | None = Secret.from_env_var(
+            ["AWS_DEFAULT_REGION"], strict=False),
+        aws_profile_name: Secret | None = Secret.from_env_var(["AWS_PROFILE"],
+                                                              strict=False),
+        aws_custom_attributes: dict[str, Any] | None = None,
+        generation_kwargs: dict[str, Any] | None = None)
+```
+
+Instantiates the session with SageMaker.
+
+**Arguments**:
+
+- `aws_access_key_id`: The `Secret` for AWS access key ID.
+- `aws_secret_access_key`: The `Secret` for AWS secret access key.
+- `aws_session_token`: The `Secret` for AWS session token.
+- `aws_region_name`: The `Secret` for AWS region name. If not provided, the default region will be used.
+- `aws_profile_name`: The `Secret` for AWS profile name. If not provided, the default profile will be used.
+- `model`: The name for SageMaker Model Endpoint.
+- `aws_custom_attributes`: Custom attributes to be passed to SageMaker, for example `{"accept_eula": True}`
+in case of Llama-2 models.
+- `generation_kwargs`: Additional keyword arguments for text generation. For a list of supported parameters
+see your model's documentation page, for example here for HuggingFace models:
+https://huggingface.co/blog/sagemaker-huggingface-llm#4-run-inference-and-chat-with-our-model
+
+Specifically, Llama-2 models support the following inference payload parameters:
+
+- `max_new_tokens`: Model generates text until the output length (excluding the input context length)
+    reaches `max_new_tokens`. If specified, it must be a positive integer.
+- `temperature`: Controls the randomness in the output. Higher temperature results in output sequence with
+    low-probability words and lower temperature results in output sequence with high-probability words.
+    If `temperature=0`, it results in greedy decoding. If specified, it must be a positive float.
+- `top_p`: In each step of text generation, sample from the smallest possible set of words with cumulative
+    probability `top_p`. If specified, it must be a float between 0 and 1.
+- `return_full_text`: If `True`, input text will be part of the output generated text. If specified, it must
+    be boolean. The default value for it is `False`.
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker.SagemakerGenerator.to_dict"></a>
+
+#### SagemakerGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker.SagemakerGenerator.from_dict"></a>
+
+#### SagemakerGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "SagemakerGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker.SagemakerGenerator.run"></a>
+
+#### SagemakerGenerator.run
+
+```python
+@component.output_types(replies=list[str], meta=list[dict[str, Any]])
+def run(
+    prompt: str,
+    generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Invoke the text generation inference based on the provided prompt and generation parameters.
+
+**Arguments**:
+
+- `prompt`: The string prompt to use for text generation.
+- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will
+potentially override the parameters passed in the `__init__` method.
+
+**Raises**:
+
+- `ValueError`: If the model response type is not a list of dictionaries or a single dictionary.
+- `SagemakerNotReadyError`: If the SageMaker model is not ready to accept requests.
+- `SagemakerInferenceError`: If the SageMaker Inference returns an error.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list of strings containing the generated responses
+- `meta`: A list of dictionaries containing the metadata for each response.
+

docs-website/reference/integrations-api/amazon_textract.md

@@ -0,0 +1,151 @@
+---
+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** (<code>Secret | None</code>) – AWS access key ID.
+- **aws_secret_access_key** (<code>Secret | None</code>) – AWS secret access key.
+- **aws_session_token** (<code>Secret | None</code>) – AWS session token.
+- **aws_region_name** (<code>Secret | None</code>) – AWS region name. Must be a region that supports Textract.
+- **aws_profile_name** (<code>Secret | None</code>) – AWS profile name from the credentials file.
+- **feature_types** (<code>list\[str\] | None</code>) – 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** (<code>bool</code>) – If True, stores the complete file path in Document metadata.
+  If False, stores only the filename (default).
+- **boto3_config** (<code>dict\[str, Any\] | None</code>) – 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.
+
+#### 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** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths or ByteStream objects to convert.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – 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** (<code>list\[str\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AmazonTextractConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AmazonTextractConverter</code> – The deserialized component.

docs-website/reference/integrations-api/anthropic.md

@@ -0,0 +1,689 @@
+---
+title: "Anthropic"
+id: integrations-anthropic
+description: "Anthropic integration for Haystack"
+slug: "/integrations-anthropic"
+---
+
+
+## haystack_integrations.components.generators.anthropic.chat.chat_generator
+
+### AnthropicChatGenerator
+
+Completes chats using Anthropic's large language models (LLMs).
+
+It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage)
+format in input and output. Supports multimodal inputs including text and images.
+
+You can customize how the text is generated by passing parameters to the
+Anthropic API. Use the `**generation_kwargs` argument when you initialize
+the component or when you run it. Any parameter that works with
+`anthropic.Message.create` will work here too.
+
+For details on Anthropic API parameters, see
+[Anthropic documentation](https://docs.anthropic.com/en/api/messages).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.anthropic import (
+    AnthropicChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+
+generator = AnthropicChatGenerator(
+    generation_kwargs={
+        "max_tokens": 1000,
+        "temperature": 0.7,
+    },
+)
+
+messages = [
+    ChatMessage.from_system(
+        "You are a helpful, respectful and honest assistant"
+    ),
+    ChatMessage.from_user("What's Natural Language Processing?"),
+]
+print(generator.run(messages=messages))
+```
+
+Usage example with images:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+
+image_content = ImageContent.from_file_path("path/to/image.jpg")
+messages = [
+    ChatMessage.from_user(
+        content_parts=["What's in this image?", image_content]
+    )
+]
+generator = AnthropicChatGenerator()
+result = generator.run(messages)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "claude-opus-4-6",
+    "claude-sonnet-4-6",
+    "claude-haiku-4-5-20251001",
+    "claude-sonnet-4-5-20250929",
+    "claude-opus-4-5-20251101",
+    "claude-opus-4-1-20250805",
+    "claude-sonnet-4-20250514",
+    "claude-opus-4-20250514",
+    "claude-3-haiku-20240307",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component. See
+https://platform.claude.com/docs/en/about-claude/models/overview for the full list.
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("ANTHROPIC_API_KEY"),
+    model: str = "claude-sonnet-4-5",
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    ignore_tools_thinking_messages: bool = True,
+    tools: ToolsType | None = None,
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None
+) -> None
+```
+
+Creates an instance of AnthropicChatGenerator.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Anthropic API key
+- **model** (<code>str</code>) – The name of the model to use.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Other parameters to use for the model. These parameters are all sent directly to
+  the Anthropic endpoint. See Anthropic [documentation](https://docs.anthropic.com/claude/reference/messages_post)
+  for more details.
+
+Supported generation_kwargs parameters are:
+
+- `system`: The system message to be passed to the model.
+- `max_tokens`: The maximum number of tokens to generate.
+- `metadata`: A dictionary of metadata to be passed to the model.
+- `stop_sequences`: A list of strings that the model should stop generating at.
+- `temperature`: The temperature to use for sampling.
+- `top_p`: The top_p value to use for nucleus sampling.
+- `top_k`: The top_k value to use for top-k sampling.
+- `extra_headers`: A dictionary of extra headers to be passed to the model (i.e. for beta features).
+- `thinking`: A dictionary of thinking parameters to be passed to the model.
+  The `budget_tokens` passed for thinking should be less than `max_tokens`.
+  For more details and supported models, see: [Anthropic Extended Thinking](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking)
+- `output_config`: A dictionary of output configuration options to be passed to the model.
+- **ignore_tools_thinking_messages** (<code>bool</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>float | None</code>) – Timeout for Anthropic client calls. If not set, it defaults to the default set by the Anthropic client.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by
+  the Anthropic client.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnthropicChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>AnthropicChatGenerator</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Anthropic generation endpoint.
+- **tools** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Anthropic generation endpoint.
+- **tools** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `replies`: The responses from the model
+
+## haystack_integrations.components.generators.anthropic.chat.foundry_chat_generator
+
+### AnthropicFoundryChatGenerator
+
+Bases: <code>AnthropicChatGenerator</code>
+
+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=<ChatRole.ASSISTANT: 'assistant'>, _content=[TextContent(text=
+>> "Natural Language Processing (NLP) is a field of artificial intelligence that
+>> focuses on enabling computers to understand, interpret, and generate human language. It involves developing
+>> techniques and algorithms to analyze and process text or speech data, allowing machines to comprehend and
+>> communicate in natural languages like English, Spanish, or Chinese.")],
+>> _name=None, _meta={'model': 'claude-sonnet-4-5', 'index': 0, 'finish_reason': 'end_turn',
+>> 'usage': {'input_tokens': 15, 'output_tokens': 64}})]}
+```
+
+For more details on supported models and their capabilities, refer to the Anthropic
+[documentation](https://docs.anthropic.com/claude/docs/intro-to-claude).
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "claude-opus-4-6",
+    "claude-sonnet-4-6",
+    "claude-sonnet-4-5",
+    "claude-opus-4-5",
+    "claude-opus-4-1",
+    "claude-haiku-4-5",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+The actual availability depends on your Azure Foundry resource configuration.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret | None = Secret.from_env_var(
+        "ANTHROPIC_FOUNDRY_API_KEY", strict=True
+    ),
+    resource: str | None = None,
+    endpoint: str | None = None,
+    model: str = "claude-sonnet-4-5",
+    streaming_callback: Callable[[StreamingChunk], None] | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    ignore_tools_thinking_messages: bool = True,
+    tools: ToolsType | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    azure_ad_token_provider: Callable[[], str] | None = None
+) -> None
+```
+
+Creates an instance of AnthropicFoundryChatGenerator.
+
+**Parameters:**
+
+- **api_key** (<code>Secret | None</code>) – 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** (<code>str | None</code>) – The Foundry resource name. Can also be set via the `ANTHROPIC_FOUNDRY_RESOURCE`
+  environment variable. Either `resource` or `endpoint` must be provided.
+- **endpoint** (<code>str | None</code>) – The full Foundry endpoint URL (e.g.,
+  "https://your-resource.openai.azure.com/anthropic").
+  Either `resource` or `endpoint` must be provided.
+- **model** (<code>str</code>) – The name of the model to use (deployment name in Foundry).
+- **streaming_callback** (<code>Callable\\[[StreamingChunk\], None\] | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Other parameters to use for the model. These parameters are all sent directly to
+  the AnthropicFoundry endpoint. See Anthropic [documentation](https://docs.anthropic.com/claude/reference/messages_post)
+  for more details.
+  Supported generation_kwargs parameters are:
+- `system`: The system message to be passed to the model.
+- `max_tokens`: The maximum number of tokens to generate.
+- `metadata`: A dictionary of metadata to be passed to the model.
+- `stop_sequences`: A list of strings that the model should stop generating at.
+- `temperature`: The temperature to use for sampling.
+- `top_p`: The top_p value to use for nucleus sampling.
+- `top_k`: The top_k value to use for top-k sampling.
+- `extra_headers`: A dictionary of extra headers to be passed to the model (i.e. for beta features).
+- **ignore_tools_thinking_messages** (<code>bool</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>float | None</code>) – Timeout for Anthropic client calls. If not set, it defaults to the default set by the Anthropic client.
+- **max_retries** (<code>int | None</code>) – 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** (<code>Callable\[[], str\] | None</code>) – A function that returns an Azure AD token for authentication.
+  Can be used instead of `api_key` for enhanced security.
+  See [Azure Identity documentation](https://learn.microsoft.com/en-us/azure/developer/python/sdk/authentication/overview)
+  for more details.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the AnthropicFoundry clients.
+
+This method is idempotent — it only creates clients once.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage] | str,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    tools: ToolsType | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Invokes the AnthropicFoundry API with the given messages and generation kwargs.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Anthropic generation endpoint.
+- **tools** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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 AnthropicFoundry API with the given messages and generation kwargs.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Anthropic generation endpoint.
+- **tools** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `replies`: The responses from the model
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnthropicFoundryChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>AnthropicFoundryChatGenerator</code> – The deserialized component instance.
+
+## haystack_integrations.components.generators.anthropic.chat.vertex_chat_generator
+
+### AnthropicVertexChatGenerator
+
+Bases: <code>AnthropicChatGenerator</code>
+
+Enables text generation using Anthropic's Claude models via the Anthropic Vertex AI API.
+
+A variety of Claude models (Opus, Sonnet, Haiku, and others) are available through the Vertex AI API endpoint.
+
+To use AnthropicVertexChatGenerator, you must have a GCP project with Vertex AI enabled.
+Additionally, ensure that the desired Anthropic model is activated in the Vertex AI Model Garden.
+Before making requests, you may need to authenticate with GCP using `gcloud auth login`.
+For more details, refer to the [guide] (https://docs.anthropic.com/en/api/claude-on-vertex-ai).
+
+Any valid text generation parameters for the Anthropic messaging API can be passed to
+the AnthropicVertex API. Users can provide these parameters directly to the component via
+the `generation_kwargs` parameter in `__init__` or the `run` method.
+
+For more details on the parameters supported by the Anthropic API, refer to the
+Anthropic Message API [documentation](https://docs.anthropic.com/en/api/messages).
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicVertexChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+client = AnthropicVertexChatGenerator(
+            model="claude-sonnet-4@20250514",
+            project_id="your-project-id", region="your-region"
+        )
+response = client.run(messages)
+print(response)
+
+>> {'replies': [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _content=[TextContent(text=
+>> "Natural Language Processing (NLP) is a field of artificial intelligence that
+>> focuses on enabling computers to understand, interpret, and generate human language. It involves developing
+>> techniques and algorithms to analyze and process text or speech data, allowing machines to comprehend and
+>> communicate in natural languages like English, Spanish, or Chinese.")],
+>> _name=None, _meta={'model': 'claude-sonnet-4@20250514', 'index': 0, 'finish_reason': 'end_turn',
+>> 'usage': {'input_tokens': 15, 'output_tokens': 64}})]}
+```
+
+For more details on supported models and their capabilities, refer to the Anthropic
+[documentation](https://docs.anthropic.com/claude/docs/intro-to-claude).
+
+For a list of available model IDs when using Claude on Vertex AI, see
+[Claude on Vertex AI - model availability](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai#model-availability).
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "claude-opus-4-6",
+    "claude-sonnet-4-6",
+    "claude-sonnet-4-5@20250929",
+    "claude-sonnet-4@20250514",
+    "claude-opus-4-5@20251101",
+    "claude-opus-4-1@20250805",
+    "claude-opus-4@20250514",
+    "claude-haiku-4-5@20251001",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component. See
+https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai#model-availability for the full list.
+
+#### __init__
+
+```python
+__init__(
+    region: str,
+    project_id: str,
+    model: str = "claude-sonnet-4@20250514",
+    streaming_callback: Callable[[StreamingChunk], None] | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    ignore_tools_thinking_messages: bool = True,
+    tools: ToolsType | None = None,
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None
+) -> None
+```
+
+Creates an instance of AnthropicVertexChatGenerator.
+
+**Parameters:**
+
+- **region** (<code>str</code>) – The region where the Anthropic model is deployed. Defaults to "us-central1".
+- **project_id** (<code>str</code>) – The GCP project ID where the Anthropic model is deployed.
+- **model** (<code>str</code>) – The name of the model to use.
+- **streaming_callback** (<code>Callable\\[[StreamingChunk\], None\] | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Other parameters to use for the model. These parameters are all sent directly to
+  the AnthropicVertex endpoint. See Anthropic [documentation](https://docs.anthropic.com/claude/reference/messages_post)
+  for more details.
+
+Supported generation_kwargs parameters are:
+
+- `system`: The system message to be passed to the model.
+- `max_tokens`: The maximum number of tokens to generate.
+- `metadata`: A dictionary of metadata to be passed to the model.
+- `stop_sequences`: A list of strings that the model should stop generating at.
+- `temperature`: The temperature to use for sampling.
+- `top_p`: The top_p value to use for nucleus sampling.
+- `top_k`: The top_k value to use for top-k sampling.
+- `extra_headers`: A dictionary of extra headers to be passed to the model (i.e. for beta features).
+- **ignore_tools_thinking_messages** (<code>bool</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>float | None</code>) – Timeout for Anthropic client calls. If not set, it defaults to the default set by the Anthropic client.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by
+  the Anthropic client.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnthropicVertexChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>AnthropicVertexChatGenerator</code> – The deserialized component instance.
+
+## haystack_integrations.components.generators.anthropic.generator
+
+### AnthropicGenerator
+
+Enables text generation using Anthropic large language models (LLMs). It supports the Claude family of models.
+
+Although Anthropic natively supports a much richer messaging API, we have intentionally simplified it in this
+component so that the main input/output interface is string-based.
+For more complete support, consider using the AnthropicChatGenerator.
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicGenerator
+
+client = AnthropicGenerator(model="claude-sonnet-4-20250514")
+response = client.run("What's Natural Language Processing? Be brief.")
+print(response)
+>>{'replies': ['Natural language processing (NLP) is a branch of artificial intelligence focused on enabling
+>>computers to understand, interpret, and manipulate human language. The goal of NLP is to read, decipher,
+>> understand, and make sense of the human languages in a manner that is valuable.'], 'meta': {'model':
+>> 'claude-2.1', 'index': 0, 'finish_reason': 'end_turn', 'usage': {'input_tokens': 18, 'output_tokens': 58}}}
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("ANTHROPIC_API_KEY"),
+    model: str = "claude-sonnet-4-5",
+    streaming_callback: Callable[[StreamingChunk], None] | None = None,
+    system_prompt: str | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None
+) -> None
+```
+
+Initialize the AnthropicGenerator.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Anthropic API key.
+- **model** (<code>str</code>) – The name of the Anthropic model to use.
+- **streaming_callback** (<code>Callable\\[[StreamingChunk\], None\] | None</code>) – An optional callback function to handle streaming chunks.
+- **system_prompt** (<code>str | None</code>) – An optional system prompt to use for generation.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for generation.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnthropicGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>AnthropicGenerator</code> – The deserialized component instance.
+
+#### run
+
+```python
+run(
+    prompt: str,
+    generation_kwargs: dict[str, Any] | None = None,
+    streaming_callback: Callable[[StreamingChunk], None] | None = None,
+) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Generate replies using the Anthropic API.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – The input prompt for generation.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for generation.
+- **streaming_callback** (<code>Callable\\[[StreamingChunk\], None\] | None</code>) – An optional callback function to handle streaming chunks.
+
+**Returns:**
+
+- <code>dict\[str, list\[str\] | list\[dict\[str, Any\]\]\]</code> – A dictionary containing:
+- `replies`: A list of generated replies.
+- `meta`: A list of metadata dictionaries for each reply.

docs-website/reference/integrations-api/arangodb.md

@@ -0,0 +1,244 @@
+---
+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** (<code>ArangoDocumentStore</code>) – The `ArangoDocumentStore` to retrieve documents from.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>list\[float\]</code>) – The query vector.
+- **top_k** (<code>int | None</code>) – Overrides the instance-level `top_k` for this call.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Overrides the instance-level `filters` for this call.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ArangoEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ArangoEmbeddingRetriever</code> – Deserialized component.
+
+## 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** (<code>str</code>) – ArangoDB server URL, e.g. `http://localhost:8529`.
+- **database** (<code>str</code>) – Name of the ArangoDB database to use. Created if it does not exist.
+- **username** (<code>Secret</code>) – ArangoDB username as a `Secret`. Defaults to `ARANGO_USERNAME` env var,
+  falling back to `root` if the variable is not set.
+- **password** (<code>Secret</code>) – ArangoDB password as a `Secret`. Defaults to `ARANGO_PASSWORD` env var.
+- **collection_name** (<code>str</code>) – Name of the collection to store documents in.
+- **embedding_dimension** (<code>int</code>) – Dimensionality of document embeddings.
+- **recreate_collection** (<code>bool</code>) – If `True`, drop and recreate the collection on startup.
+- **similarity_function** (<code>Literal['cosine', 'dot_product', 'l2']</code>) – 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:**
+
+- <code>int</code> – Document count.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Haystack metadata filters. If `None`, all documents are returned.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>list\[Document\]</code>) – Documents to write.
+- **policy** (<code>DuplicatePolicy</code>) – How to handle duplicates — `OVERWRITE`, `SKIP`, or `FAIL` (default).
+
+**Returns:**
+
+- <code>int</code> – Number of documents written.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` contains non-`Document` objects.
+- <code>DuplicateDocumentError</code> – 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** (<code>list\[str\]</code>) – List of document IDs to delete.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ArangoDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ArangoDocumentStore</code> – Deserialized component.

docs-website/reference/integrations-api/arcadedb.md

@@ -0,0 +1,391 @@
+---
+title: "ArcadeDB"
+id: integrations-arcadedb
+description: "ArcadeDB integration for Haystack"
+slug: "/integrations-arcadedb"
+---
+
+
+## haystack_integrations.components.retrievers.arcadedb.embedding_retriever
+
+### ArcadeDBEmbeddingRetriever
+
+Retrieve documents from ArcadeDB using vector similarity (LSM_VECTOR / HNSW index).
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack_integrations.components.retrievers.arcadedb import ArcadeDBEmbeddingRetriever
+from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore
+
+store = ArcadeDBDocumentStore(database="mydb")
+retriever = ArcadeDBEmbeddingRetriever(document_store=store, top_k=5)
+
+# Add documents to DocumentStore
+documents = [
+    Document(text="My name is Carla and I live in Berlin"),
+    Document(text="My name is Paul and I live in New York"),
+    Document(text="My name is Silvano and I live in Matera"),
+    Document(text="My name is Usagi Tsukino and I live in Tokyo"),
+]
+document_store.write_documents(documents)
+
+embedder = SentenceTransformersTextEmbedder()
+query_embeddings = embedder.run("Who lives in Berlin?")["embedding"]
+
+result = retriever.run(query=query_embeddings)
+for doc in result["documents"]:
+    print(doc.content)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: ArcadeDBDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create an ArcadeDBEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>ArcadeDBDocumentStore</code>) – An instance of `ArcadeDBDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Default filters applied to every retrieval call.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+- **filter_policy** (<code>FilterPolicy</code>) – 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** (<code>list\[float\]</code>) – The embedding vector to search with.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional filters to narrow results.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ArcadeDBEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ArcadeDBEmbeddingRetriever</code> – 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** (<code>str</code>) – ArcadeDB HTTP endpoint.
+- **database** (<code>str</code>) – Database name.
+- **username** (<code>Secret</code>) – HTTP Basic Auth username (default: `ARCADEDB_USERNAME` env var).
+- **password** (<code>Secret</code>) – HTTP Basic Auth password (default: `ARCADEDB_PASSWORD` env var).
+- **type_name** (<code>str</code>) – Vertex type name for documents.
+- **embedding_dimension** (<code>int</code>) – Vector dimension for the HNSW index.
+- **similarity_function** (<code>str</code>) – Distance metric — `"cosine"`, `"euclidean"`, or `"dot"`.
+- **recreate_type** (<code>bool</code>) – If `True`, drop and recreate the type on initialization.
+- **create_database** (<code>bool</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ArcadeDBDocumentStore
+```
+
+Deserializes the DocumentStore from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ArcadeDBDocumentStore</code> – The deserialized DocumentStore.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\] | None</code>) – Haystack filter dictionary.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – List of matching documents.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to the store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of Haystack Documents to write.
+- **policy** (<code>DuplicatePolicy</code>) – How to handle duplicate document IDs.
+
+**Returns:**
+
+- <code>int</code> – Number of documents written.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents by their IDs.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the documents
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+- **metadata_fields** (<code>list\[str\]</code>) – Metadata fields for which to count unique values.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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** (<code>str</code>) – The metadata field to inspect.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with `min` and `max` keys and their corresponding values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a field matching a search term or all possible values
+if no search term is given.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to inspect.
+- **search_term** (<code>str | None</code>) – Optional case-insensitive substring search term.
+- **from\_** (<code>int</code>) – The starting index for pagination.
+- **size** (<code>int</code>) – The number of values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing the paginated values and the total count.

docs-website/reference/integrations-api/astra.md

@@ -0,0 +1,520 @@
+---
+title: "Astra"
+id: integrations-astra
+description: "Astra integration for Haystack"
+slug: "/integrations-astra"
+---
+
+
+## haystack_integrations.components.retrievers.astra.retriever
+
+### AstraEmbeddingRetriever
+
+A component for retrieving documents from an AstraDocumentStore.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.astra import AstraDocumentStore
+from haystack_integrations.components.retrievers.astra import AstraEmbeddingRetriever
+
+document_store = AstraDocumentStore(
+    api_endpoint=api_endpoint,
+    token=token,
+    collection_name=collection_name,
+    duplicates_policy=DuplicatePolicy.SKIP,
+    embedding_dim=384,
+)
+
+retriever = AstraEmbeddingRetriever(document_store=document_store)
+```
+
+#### __init__
+
+```python
+__init__(
+    document_store: AstraDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Initialize the AstraEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>AstraDocumentStore</code>) – An instance of AstraDocumentStore.
+- **filters** (<code>dict\[str, Any\] | None</code>) – a dictionary with filters to narrow down the search space.
+- **top_k** (<code>int</code>) – the maximum number of documents to retrieve.
+- **filter_policy** (<code>str | FilterPolicy</code>) – 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** (<code>list\[float\]</code>) – floats representing the query embedding
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – the maximum number of documents to retrieve.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>list\[float\]</code>) – floats representing the query embedding
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – the maximum number of documents to retrieve.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AstraEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AstraEmbeddingRetriever</code> – 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** (<code>Secret</code>) – the Astra DB API endpoint.
+- **token** (<code>Secret</code>) – the Astra DB application token.
+- **collection_name** (<code>str</code>) – the current collection in the keyspace in the current Astra DB.
+- **embedding_dimension** (<code>int</code>) – dimension of embedding vector.
+- **duplicates_policy** (<code>DuplicatePolicy</code>) – 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** (<code>str</code>) – the similarity function used to compare document vectors.
+
+**Raises:**
+
+- <code>ValueError</code> – 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** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AstraDocumentStore</code> – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Indexes documents for later queries.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – a list of Haystack Document objects.
+- **policy** (<code>DuplicatePolicy</code>) – 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:**
+
+- <code>int</code> – number of documents written.
+
+**Raises:**
+
+- <code>ValueError</code> – if the documents are not of type Document or dict.
+- <code>DuplicateDocumentError</code> – if a document with the same ID already exists and policy is set to FAIL.
+- <code>Exception</code> – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\] | None</code>) – filters to apply.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – matching documents.
+
+**Raises:**
+
+- <code>AstraDocumentStoreFilterError</code> – 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** (<code>list\[str\]</code>) – the IDs of the documents to retrieve.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>str</code>) – the ID to filter by
+
+**Returns:**
+
+- <code>Document</code> – the found document
+
+**Raises:**
+
+- <code>MissingDocumentError</code> – 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** (<code>list\[float\]</code>) – a list of query embeddings.
+- **top_k** (<code>int</code>) – the number of results to return.
+- **filters** (<code>dict\[str, Any\] | None</code>) – filters to apply during search.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – matching documents.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents from the document store.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – IDs of the documents to delete.
+
+**Raises:**
+
+- <code>MissingDocumentError</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to find documents to delete.
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+**Raises:**
+
+- <code>AstraDocumentStoreFilterError</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to find documents to update.
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+**Raises:**
+
+- <code>AstraDocumentStoreFilterError</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+- **metadata_fields** (<code>list\[str\]</code>) – The metadata fields to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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** (<code>str</code>) – The metadata field to inspect.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with `min` and `max`.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a field matching a search term or all possible values if no search term is given.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to inspect.
+- **search_term** (<code>str | None</code>) – Optional case-insensitive substring search term.
+- **from\_** (<code>int</code>) – The starting index for pagination.
+- **size** (<code>int</code>) – The number of values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing the paginated values and the total count.
+
+## haystack_integrations.document_stores.astra.errors
+
+### AstraDocumentStoreError
+
+Bases: <code>DocumentStoreError</code>
+
+Parent class for all AstraDocumentStore errors.
+
+### AstraDocumentStoreFilterError
+
+Bases: <code>FilterError</code>
+
+Raised when an invalid filter is passed to AstraDocumentStore.
+
+### AstraDocumentStoreConfigError
+
+Bases: <code>AstraDocumentStoreError</code>
+
+Raised when an invalid configuration is passed to AstraDocumentStore.

docs-website/reference/integrations-api/azure_ai_search.md

@@ -0,0 +1,463 @@
+---
+title: "Azure AI Search"
+id: integrations-azure_ai_search
+description: "Azure AI Search integration for Haystack"
+slug: "/integrations-azure_ai_search"
+---
+
+
+## haystack_integrations.components.retrievers.azure_ai_search.embedding_retriever
+
+### AzureAISearchEmbeddingRetriever
+
+Retrieves documents from the AzureAISearchDocumentStore using a vector similarity metric.
+
+Must be connected to the AzureAISearchDocumentStore to run.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: AzureAISearchDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+    **kwargs: Any
+) -> None
+```
+
+Create the AzureAISearchEmbeddingRetriever component.
+
+**Parameters:**
+
+- **document_store** (<code>AzureAISearchDocumentStore</code>) – An instance of AzureAISearchDocumentStore to use with the Retriever.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied when fetching documents from the Document Store.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+- **kwargs** (<code>Any</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureAISearchEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AzureAISearchEmbeddingRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the AzureAISearchDocumentStore.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – A list of floats representing the query embedding.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – The maximum number of documents to retrieve.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>Secret</code>) – The URL endpoint of an Azure AI Search service.
+- **api_key** (<code>Secret</code>) – The API key to use for authentication.
+- **index_name** (<code>str</code>) – Name of index in Azure AI Search, if it doesn't exist it will be created.
+- **embedding_dimension** (<code>int</code>) – Dimension of the embeddings.
+- **metadata_fields** (<code>dict\[str, SearchField | type\] | None</code>) – 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** (<code>VectorSearch | None</code>) – Configuration option related to vector search.
+  Default configuration uses the HNSW algorithm with cosine similarity to handle vector searches.
+- **include_search_metadata** (<code>bool</code>) – 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** (<code>TokenCredential | None</code>) – An Azure `TokenCredential` instance used to authenticate requests.
+  When provided, this takes priority over `api_key`.
+- **index_creation_kwargs** (<code>Any</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureAISearchDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AzureAISearchDocumentStore</code> – Deserialized component.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the search index.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents.
+- **metadata_fields** (<code>list\[str\]</code>) – List of field names to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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** (<code>str</code>) – The metadata field to get the minimum and maximum values for.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the keys "min" and "max".
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a metadata field with optional search and pagination.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get unique values for.
+- **search_term** (<code>str | None</code>) – Optional search term to filter unique values.
+- **from\_** (<code>int</code>) – Starting offset for pagination.
+- **size** (<code>int</code>) – Number of values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – Tuple of (list of unique values, total count of matching values).
+
+#### query_sql
+
+```python
+query_sql(query: str) -> Any
+```
+
+Executes an SQL query if supported by the document store backend.
+
+Azure AI Search does not support SQL queries.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes the provided documents to search index.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – documents to write to the index.
+- **policy** (<code>DuplicatePolicy</code>) – Policy to determine how duplicates are handled.
+
+**Returns:**
+
+- <code>int</code> – the number of documents added to index.
+
+**Raises:**
+
+- <code>ValueError</code> – If the documents are not of type Document.
+- <code>TypeError</code> – 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** (<code>list\[str\]</code>) – 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** (<code>bool</code>) – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The fields to update. These fields must exist in the index schema.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>list\[str\]</code>) – IDs of the documents to retrieve.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>str</code>) – the text to search for in the Document list.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>dict\[str, Any\] | None</code>) – the filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+## haystack_integrations.document_stores.azure_ai_search.filters

docs-website/reference/integrations-api/azure_doc_intelligence.md

@@ -0,0 +1,155 @@
+---
+title: "Azure Document Intelligence"
+id: integrations-azure_doc_intelligence
+description: "Azure Document Intelligence integration for Haystack"
+slug: "/integrations-azure_doc_intelligence"
+---
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter"></a>
+
+## Module haystack\_integrations.components.converters.azure\_doc\_intelligence.converter
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter"></a>
+
+### 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)
+```
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter.__init__"></a>
+
+#### AzureDocumentIntelligenceConverter.\_\_init\_\_
+
+```python
+def __init__(endpoint: str,
+             *,
+             api_key: Secret = Secret.from_env_var("AZURE_DI_API_KEY"),
+             model_id: str = "prebuilt-document",
+             store_full_path: bool = False)
+```
+
+Creates an AzureDocumentIntelligenceConverter component.
+
+**Arguments**:
+
+- `endpoint`: The endpoint URL of your Azure Document Intelligence resource.
+Example: "https://YOUR_RESOURCE.cognitiveservices.azure.com/"
+- `api_key`: API key for Azure authentication. Can use Secret.from_env_var()
+to load from AZURE_DI_API_KEY environment variable.
+- `model_id`: Azure model to use for analysis. Options:
+- "prebuilt-document": General document analysis (default)
+- "prebuilt-read": Fast OCR for text extraction
+- "prebuilt-layout": Enhanced layout analysis with better table/structure detection
+- Custom model IDs from your Azure resource
+- `store_full_path`: If True, stores complete file path in metadata.
+If False, stores only the filename (default).
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter.warm_up"></a>
+
+#### AzureDocumentIntelligenceConverter.warm\_up
+
+```python
+def warm_up()
+```
+
+Initializes the Azure Document Intelligence client.
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter.run"></a>
+
+#### AzureDocumentIntelligenceConverter.run
+
+```python
+@component.output_types(documents=list[Document],
+                        raw_azure_response=list[dict])
+def run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, list[Document] | list[dict]]
+```
+
+Convert a list of files to Documents using Azure's Document Intelligence service.
+
+**Arguments**:
+
+- `sources`: List of file paths or ByteStream objects.
+- `meta`: Optional metadata to attach to the Documents.
+This value can be either a list of dictionaries or a single dictionary.
+If it's a single dictionary, its content is added to the metadata of all produced Documents.
+If it's a list, the length of the list must match the number of sources, because the two lists will be
+zipped. If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `documents`: List of created Documents
+- `raw_azure_response`: List of raw Azure responses used to create the Documents
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter.to_dict"></a>
+
+#### AzureDocumentIntelligenceConverter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter.from_dict"></a>
+
+#### AzureDocumentIntelligenceConverter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str,
+                              Any]) -> "AzureDocumentIntelligenceConverter"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+

docs-website/reference/integrations-api/azure_form_recognizer.md

@@ -0,0 +1,134 @@
+---
+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** (<code>str</code>) – The endpoint of your Azure resource.
+- **api_key** (<code>Secret</code>) – The API key of your Azure resource.
+- **model_id** (<code>str</code>) – 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** (<code>int</code>) – Number of lines before a table to include as preceding context
+  (this will be added to the metadata).
+- **following_context_len** (<code>int</code>) – Number of lines after a table to include as subsequent context (
+  this will be added to the metadata).
+- **merge_multiple_column_headers** (<code>bool</code>) – If `True`, merges multiple column header rows into a single row.
+- **page_layout** (<code>Literal['natural', 'single_column']</code>) – 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** (<code>float | None</code>) – 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** (<code>bool</code>) – If True, the full path of the file is stored in the metadata of the document.
+  If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, Any]
+```
+
+Convert a list of files to Documents using Azure's Document Intelligence service.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths or ByteStream objects.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureOCRDocumentConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AzureOCRDocumentConverter</code> – The deserialized component.

docs-website/reference/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** (<code>Secret</code>) – Brave Search API key. Defaults to the `BRAVE_API_KEY` environment variable.
+- **top_k** (<code>int | None</code>) – Maximum number of results to return. Maps to the `count` parameter in the Brave API.
+- **country** (<code>str | None</code>) – 2-letter country code to bias search results (e.g. `"US"`, `"DE"`).
+- **search_lang** (<code>str | None</code>) – Language code for search results (e.g. `"en"`, `"de"`).
+- **extra_params** (<code>dict\[str, Any\] | None</code>) – Additional query parameters passed directly to the Brave Search API.
+- **timeout** (<code>int</code>) – Timeout in seconds for the HTTP request. Defaults to 10.
+- **max_retries** (<code>int</code>) – 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** (<code>str</code>) – Search query string.
+- **top_k** (<code>int | None</code>) – Optional per-run override of the maximum number of results.
+  If not provided, the init-time `top_k` is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – Search query string.
+- **top_k** (<code>int | None</code>) – Optional per-run override of the maximum number of results.
+  If not provided, the init-time `top_k` is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with:
+- `documents`: List of Documents containing search result content.
+- `links`: List of URLs from the search results.

docs-website/reference/integrations-api/chonkie.md

@@ -0,0 +1,394 @@
+---
+title: "Chonkie"
+id: integrations-chonkie
+description: "Chonkie integration for Haystack"
+slug: "/integrations-chonkie"
+---
+
+
+## haystack_integrations.components.preprocessors.chonkie.recursive_splitter
+
+### ChonkieRecursiveDocumentSplitter
+
+A Document Splitter that uses Chonkie's RecursiveChunker to split documents.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.chonkie import ChonkieRecursiveDocumentSplitter
+
+chunker = ChonkieRecursiveDocumentSplitter(chunk_size=512)
+documents = [Document(content="Hello world. This is a test.")]
+result = chunker.run(documents=documents)
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    tokenizer: str = "character",
+    chunk_size: int = 2048,
+    min_characters_per_chunk: int = 24,
+    rules: RecursiveRules | dict[str, Any] | None = None,
+    skip_empty_documents: bool = True,
+    page_break_character: str = "\x0c"
+) -> None
+```
+
+Initializes the ChonkieRecursiveDocumentSplitter.
+
+**Parameters:**
+
+- **tokenizer** (<code>str</code>) – 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** (<code>int</code>) – The maximum number of tokens per chunk. The actual length depends on the chosen tokenizer.
+- **min_characters_per_chunk** (<code>int</code>) – The minimum number of characters per chunk.
+- **rules** (<code>RecursiveRules | dict\[str, Any\] | None</code>) – 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** (<code>bool</code>) – Whether to skip empty documents.
+- **page_break_character** (<code>str</code>) – The character to use for page breaks.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Splits a list of documents into smaller chunks.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – The list of documents to split.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChonkieRecursiveDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ChonkieRecursiveDocumentSplitter</code> – 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** (<code>Any</code>) – The embedding model to use for semantic similarity.
+  See the [Chonkie documentation](https://docs.chonkie.ai/) for more information on supported models.
+- **threshold** (<code>float</code>) – The semantic similarity threshold.
+- **chunk_size** (<code>int</code>) – The maximum number of tokens per chunk. The actual length depends on the
+  embedding model's tokenizer.
+- **similarity_window** (<code>int</code>) – The window size for similarity calculations.
+- **min_sentences_per_chunk** (<code>int</code>) – The minimum number of sentences per chunk.
+- **min_characters_per_sentence** (<code>int</code>) – The minimum number of characters per sentence.
+- **delim** (<code>Any</code>) – Delimiters to use for splitting. If None, default delimiters are used.
+- **include_delim** (<code>str</code>) – Whether to include the delimiter in the chunks.
+- **skip_window** (<code>int</code>) – The skip window for similarity calculations.
+- **filter_window** (<code>int</code>) – The filter window for similarity calculations.
+- **filter_polyorder** (<code>int</code>) – The polynomial order for similarity filtering.
+- **filter_tolerance** (<code>float</code>) – The tolerance for similarity filtering.
+- **skip_empty_documents** (<code>bool</code>) – Whether to skip empty documents.
+- **page_break_character** (<code>str</code>) – 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** (<code>list\[Document\]</code>) – The list of documents to split.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChonkieSemanticDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ChonkieSemanticDocumentSplitter</code> – 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** (<code>str</code>) – 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** (<code>int</code>) – The maximum number of tokens per chunk. The actual length depends on the chosen tokenizer.
+- **chunk_overlap** (<code>int</code>) – The overlap between consecutive chunks.
+- **min_sentences_per_chunk** (<code>int</code>) – The minimum number of sentences per chunk.
+- **min_characters_per_sentence** (<code>int</code>) – The minimum number of characters per sentence.
+- **approximate** (<code>bool</code>) – Whether to use approximate chunking.
+- **delim** (<code>Any</code>) – Delimiters to use for splitting. If None, default delimiters are used.
+- **include_delim** (<code>str</code>) – Whether to include the delimiter in the chunks ("prev" or "next").
+- **skip_empty_documents** (<code>bool</code>) – Whether to skip empty documents.
+- **page_break_character** (<code>str</code>) – The character to use for page breaks.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Splits a list of documents into smaller sentence-based chunks.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – The list of documents to split.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChonkieSentenceDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ChonkieSentenceDocumentSplitter</code> – 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** (<code>str</code>) – 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** (<code>int</code>) – The maximum number of tokens per chunk. The actual length depends on the chosen tokenizer.
+- **chunk_overlap** (<code>int</code>) – The overlap between consecutive chunks.
+- **skip_empty_documents** (<code>bool</code>) – Whether to skip empty documents.
+- **page_break_character** (<code>str</code>) – The character to use for page breaks.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Splits a list of documents into smaller token-based chunks.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – The list of documents to split.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChonkieTokenDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ChonkieTokenDocumentSplitter</code> – Deserialized component.

docs-website/reference/integrations-api/chroma.md

@@ -0,0 +1,986 @@
+---
+title: "Chroma"
+id: integrations-chroma
+description: "Chroma integration for Haystack"
+slug: "/integrations-chroma"
+---
+
+
+## haystack_integrations.components.retrievers.chroma.retriever
+
+### ChromaQueryTextRetriever
+
+A component for retrieving documents from a [Chroma database](https://docs.trychroma.com/) using the `query` API.
+
+Example usage:
+
+```python
+from haystack import Pipeline
+from haystack.components.converters import TextFileToDocument
+from haystack.components.writers import DocumentWriter
+
+from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+from haystack_integrations.components.retrievers.chroma import ChromaQueryTextRetriever
+
+file_paths = ...
+
+# Chroma is used in-memory so we use the same instances in the two pipelines below
+document_store = ChromaDocumentStore()
+
+indexing = Pipeline()
+indexing.add_component("converter", TextFileToDocument())
+indexing.add_component("writer", DocumentWriter(document_store))
+indexing.connect("converter", "writer")
+indexing.run({"converter": {"sources": file_paths}})
+
+querying = Pipeline()
+querying.add_component("retriever", ChromaQueryTextRetriever(document_store))
+results = querying.run({"retriever": {"query": "Variable declarations", "top_k": 3}})
+
+for d in results["retriever"]["documents"]:
+    print(d.meta, d.score)
+```
+
+#### __init__
+
+```python
+__init__(
+    document_store: ChromaDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Initialize the ChromaQueryTextRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>ChromaDocumentStore</code>) – an instance of `ChromaDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – filters to narrow down the search space.
+- **top_k** (<code>int</code>) – the maximum number of documents to retrieve.
+- **filter_policy** (<code>str | FilterPolicy</code>) – 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** (<code>str</code>) – The input data for the retriever. In this case, a plain-text query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – The maximum number of documents to retrieve.
+  If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+**Raises:**
+
+- <code>ValueError</code> – 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** (<code>str</code>) – The input data for the retriever. In this case, a plain-text query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – The maximum number of documents to retrieve.
+  If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+**Raises:**
+
+- <code>ValueError</code> – If the specified document store is not found or is not a MemoryDocumentStore instance.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChromaQueryTextRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ChromaQueryTextRetriever</code> – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>ChromaDocumentStore</code>) – an instance of `ChromaDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – filters to narrow down the search space.
+- **top_k** (<code>int</code>) – the maximum number of documents to retrieve.
+- **filter_policy** (<code>str | FilterPolicy</code>) – 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** (<code>list\[float\]</code>) – the query embeddings.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – the maximum number of documents to retrieve.
+  If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>list\[float\]</code>) – the query embeddings.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – the maximum number of documents to retrieve.
+  If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – a dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChromaEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ChromaEmbeddingRetriever</code> – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – the name of the collection to use in the database.
+- **embedding_function** (<code>str</code>) – the name of the embedding function to use to embed the query
+- **persist_path** (<code>str | None</code>) – 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** (<code>str | None</code>) – The host address for the remote Chroma HTTP client connection. Cannot be used with `persist_path`.
+- **port** (<code>int | None</code>) – The port number for the remote Chroma HTTP client connection. Cannot be used with `persist_path`.
+- **distance_function** (<code>Literal['l2', 'cosine', 'ip']</code>) – 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** (<code>dict | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>Any</code>) – additional parameters to pass to the embedding function.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\] | None</code>) – the filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>dict\[str, Any\] | None</code>) – the filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>list\[Document\]</code>) – A list of documents to write into the document store.
+- **policy** (<code>DuplicatePolicy</code>) – 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:**
+
+- <code>int</code> – The number of documents written.
+
+**Raises:**
+
+- <code>ValueError</code> – When input is not valid.
+- <code>DuplicateDocumentError</code> – 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** (<code>list\[Document\]</code>) – A list of documents to write into the document store.
+- **policy** (<code>DuplicatePolicy</code>) – 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:**
+
+- <code>int</code> – The number of documents written.
+
+**Raises:**
+
+- <code>ValueError</code> – When input is not valid.
+- <code>DuplicateDocumentError</code> – 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** (<code>list\[str\]</code>) – 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** (<code>list\[str\]</code>) – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>bool</code>) – 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** (<code>bool</code>) – 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** (<code>list\[str\]</code>) – the list of queries to search for.
+- **top_k** (<code>int</code>) – top_k documents to return for each query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- <code>list\[list\[Document\]\]</code> – 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** (<code>list\[str\]</code>) – the list of queries to search for.
+- **top_k** (<code>int</code>) – top_k documents to return for each query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- <code>list\[list\[Document\]\]</code> – 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** (<code>list\[list\[float\]\]</code>) – a list of embeddings to use as queries.
+- **top_k** (<code>int</code>) – the maximum number of documents to retrieve.
+- **filters** (<code>dict\[str, Any\] | None</code>) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- <code>list\[list\[Document\]\]</code> – 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** (<code>list\[list\[float\]\]</code>) – a list of embeddings to use as queries.
+- **top_k** (<code>int</code>) – the maximum number of documents to retrieve.
+- **filters** (<code>dict\[str, Any\] | None</code>) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- <code>list\[list\[Document\]\]</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (<code>list\[str\]</code>) – List of field names to calculate unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (<code>list\[str\]</code>) – List of field names to calculate unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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** (<code>str</code>) – The metadata field to get the minimum and maximum values for.
+  Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – The metadata field to get the minimum and maximum values for.
+  Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the keys "min" and "max", where each value is
+  the minimum or maximum value of the metadata field across all documents.
+  Returns:
+
+```python
+  {"min": None, "max": None}
+```
+
+if field doesn't exist or has no values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Return unique metadata field values, optionally filtered by a content search term, with pagination.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get unique values for.
+  Can include or omit the "meta." prefix.
+- **search_term** (<code>str | None</code>) – Optional search term to filter documents by matching
+  in the content field.
+- **from\_** (<code>int</code>) – The offset to start returning values from (for pagination).
+- **size** (<code>int</code>) – The maximum number of unique values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing list of unique values and total count of unique values.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously return unique metadata field values, optionally filtered by content, with pagination.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get unique values for.
+  Can include or omit the "meta." prefix.
+- **search_term** (<code>str | None</code>) – Optional search term to filter documents by matching
+  in the content field.
+- **from\_** (<code>int</code>) – The offset to start returning values from (for pagination).
+- **size** (<code>int</code>) – The maximum number of unique values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing list of unique values and total count of unique values.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChromaDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ChromaDocumentStore</code> – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.document_stores.chroma.errors
+
+### ChromaDocumentStoreError
+
+Bases: <code>DocumentStoreError</code>
+
+Parent class for all ChromaDocumentStore exceptions.
+
+### ChromaDocumentStoreFilterError
+
+Bases: <code>FilterError</code>, <code>ValueError</code>
+
+Raised when a filter is not valid for a ChromaDocumentStore.
+
+### ChromaDocumentStoreConfigError
+
+Bases: <code>ChromaDocumentStoreError</code>
+
+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** (<code>str</code>) – the name of the embedding function.
+- **kwargs** (<code>Any</code>) – additional arguments to pass to the embedding function.
+
+**Returns:**
+
+- <code>EmbeddingFunction</code> – the loaded embedding function.
+
+**Raises:**
+
+- <code>ChromaDocumentStoreConfigError</code> – if the function name is invalid.

docs-website/reference/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** (<code>CogneeMemoryStore</code>) – Backing `CogneeMemoryStore` to query.
+- **top_k** (<code>int | None</code>) – 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** (<code>str</code>) – Natural-language query.
+- **top_k** (<code>int | None</code>) – Per-call override; falls back to init `top_k`, then the store's default.
+- **user_id** (<code>str | None</code>) – 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** (<code>CogneeMemoryStore</code>) – Backing `CogneeMemoryStore` to write into.
+- **session_id** (<code>str | None</code>) – 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** (<code>list\[ChatMessage\]</code>) – Messages to persist.
+- **user_id** (<code>str | None</code>) – 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, implementing the haystack-experimental `MemoryStore` protocol.
+
+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** (<code>CogneeSearchType</code>) – Cognee search strategy used by `search_memories`.
+- **top_k** (<code>int</code>) – Default max results for `search_memories`.
+- **dataset_name** (<code>str</code>) – Cognee dataset backing this store.
+- **session_id** (<code>str | None</code>) – When set, use the session-cache tier; otherwise the permanent graph.
+- **self_improvement** (<code>bool</code>) – Forwarded to `cognee.remember` (default `True`, matches cognee).
+  Set to `False` when `improve()` should be the only improve trigger.
+- **timeout** (<code>float</code>) – 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** (<code>list\[ChatMessage\]</code>) – Messages to store.
+- **user_id** (<code>str | None</code>) – Cognee user UUID; `None` uses cognee's default user.
+- **session_id** (<code>str | None</code>) – 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** (<code>str | None</code>) – Natural-language query. Empty/`None` returns `[]`.
+- **top_k** (<code>int | None</code>) – Per-call override of the store's default.
+- **user_id** (<code>str | None</code>) – 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** (<code>str | None</code>) – Session to promote; defaults to the store's `session_id`.
+- **user_id** (<code>str | None</code>) – 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`.

docs-website/reference/integrations-api/cometapi.md

@@ -0,0 +1,37 @@
+---
+title: "Comet API"
+id: integrations-cometapi
+description: "Comet API integration for Haystack"
+slug: "/integrations-cometapi"
+---
+
+<a id="haystack_integrations.components.generators.cometapi.chat.chat_generator"></a>
+
+## Module haystack\_integrations.components.generators.cometapi.chat.chat\_generator
+
+<a id="haystack_integrations.components.generators.cometapi.chat.chat_generator.CometAPIChatGenerator"></a>
+
+### CometAPIChatGenerator
+
+A chat generator that uses the CometAPI for generating chat responses.
+
+This class extends Haystack's OpenAIChatGenerator to specifically interact with the CometAPI.
+It sets the `api_base_url` to the CometAPI endpoint and allows for all the
+standard configurations available in the OpenAIChatGenerator.
+
+**Arguments**:
+
+- `api_key`: The API key for authenticating with the CometAPI. Defaults to
+loading from the "COMET_API_KEY" environment variable.
+- `model`: The name of the model to use for chat generation (e.g., "gpt-5-mini", "grok-3-mini").
+Defaults to "gpt-5-mini".
+- `streaming_callback`: An optional callable that will be called with each chunk of
+a streaming response.
+- `generation_kwargs`: Optional keyword arguments to pass to the underlying generation
+API call.
+- `timeout`: The maximum time in seconds to wait for a response from the API.
+- `max_retries`: The maximum number of times to retry a failed API request.
+- `tools`: An optional list of tool definitions that the model can use.
+- `tools_strict`: If True, the model is forced to use one of the provided tools if a tool call is made.
+- `http_client_kwargs`: Optional keyword arguments to pass to the HTTP client.
+

docs-website/reference/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** (<code>str</code>) – 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:**
+
+- <code>dict\[str, str\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DatadogConnector
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>DatadogConnector</code> – The deserialized component instance.
+
+## haystack_integrations.tracing.datadog.tracer
+
+### DatadogSpan
+
+Bases: <code>Span</code>
+
+#### __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** (<code>str</code>) – the name of the tag.
+- **value** (<code>Any</code>) – the value of the tag.
+
+#### raw_span
+
+```python
+raw_span() -> Any
+```
+
+Provides access to the underlying span object of the tracer.
+
+**Returns:**
+
+- <code>Any</code> – 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: <code>Tracer</code>
+
+#### __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

docs-website/reference/integrations-api/deepeval.md

@@ -0,0 +1,193 @@
+---
+title: "DeepEval"
+id: integrations-deepeval
+description: "DeepEval integration for Haystack"
+slug: "/integrations-deepeval"
+---
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator"></a>
+
+## Module haystack\_integrations.components.evaluators.deepeval.evaluator
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator.DeepEvalEvaluator"></a>
+
+### 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"])
+```
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator.DeepEvalEvaluator.__init__"></a>
+
+#### 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.
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator.DeepEvalEvaluator.run"></a>
+
+#### 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.
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator.DeepEvalEvaluator.to_dict"></a>
+
+#### 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.
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator.DeepEvalEvaluator.from_dict"></a>
+
+#### 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.
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics"></a>
+
+## Module haystack\_integrations.components.evaluators.deepeval.metrics
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric"></a>
+
+### 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.
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.ANSWER_RELEVANCY"></a>
+
+#### ANSWER\_RELEVANCY
+
+Answer relevancy.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]`
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.FAITHFULNESS"></a>
+
+#### FAITHFULNESS
+
+Faithfulness.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]`
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.CONTEXTUAL_PRECISION"></a>
+
+#### 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.
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.CONTEXTUAL_RECALL"></a>
+
+#### 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.\
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.CONTEXTUAL_RELEVANCE"></a>
+
+#### CONTEXTUAL\_RELEVANCE
+
+Contextual relevance.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]`
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.from_str"></a>
+
+#### 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.
+

docs-website/reference/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: <code>str</code>, <code>Enum</code>
+
+Enumeration of available export types.
+
+### BaseMetaExtractor
+
+Bases: <code>ABC</code>
+
+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: <code>BaseMetaExtractor</code>
+
+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** (<code>DocumentConverter | None</code>) – The Docling `DocumentConverter` to use; if not set, a system
+  default is used.
+- **convert_kwargs** (<code>dict\[str, Any\] | None</code>) – Any parameters to pass to Docling conversion; if not set, a
+  system default is used.
+- **export_type** (<code>ExportType</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Any parameters to pass to Markdown export (applicable in
+  case of `ExportType.MARKDOWN`).
+- **chunker** (<code>BaseChunker | None</code>) – The Docling chunker instance to use; if not set, a system default
+  is used.
+- **meta_extractor** (<code>BaseMetaExtractor | None</code>) – 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** (<code>dict\[str, Any\]</code>) – Dictionary with keys `type` and `init_parameters`, as produced by `to_dict`.
+
+**Returns:**
+
+- <code>DoclingConverter</code> – 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** (<code>list\[str | Path\] | None</code>) – Deprecated. Use `sources` instead.
+- **sources** (<code>list\[str | Path | ByteStream\] | None</code>) – List of file paths, URLs, or ByteStream objects to convert.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with key `"documents"` containing the output Haystack Documents.
+
+**Raises:**
+
+- <code>ValueError</code> – If `meta` is a list whose length does not match the number of sources.
+- <code>RuntimeError</code> – If an unexpected `export_type` is encountered.

docs-website/reference/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: <code>str</code>, <code>Enum</code>
+
+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: <code>str</code>, <code>Enum</code>
+
+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: <code>Exception</code>
+
+Raised when DoclingServe reports an async task or conversion failure.
+
+### DoclingServeTimeoutError
+
+Bases: <code>DoclingServeConversionError</code>
+
+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** (<code>str</code>) – Base URL of the DoclingServe instance. Defaults to `"http://localhost:5001"`.
+- **export_type** (<code>ExportType</code>) – The output format for converted documents. One of `ExportType.MARKDOWN` (default),
+  `ExportType.TEXT`, or `ExportType.JSON`.
+- **convert_options** (<code>dict\[str, Any\] | None</code>) – 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** (<code>float</code>) – HTTP request timeout in seconds. Defaults to `120.0`.
+- **api_key** (<code>Secret | None</code>) – 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** (<code>ConversionMode | str</code>) – Conversion mode. `sync` uses DoclingServe's synchronous endpoints. `async` submits
+  conversion jobs to DoclingServe's async endpoints and polls until completion.
+- **poll_interval** (<code>float</code>) – 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** (<code>float</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – A dictionary representation of the component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DoclingServeConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary representation of the component.
+
+**Returns:**
+
+- <code>DoclingServeConverter</code> – 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** (<code>list\[str | Path | ByteStream\]</code>) – 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** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>list\[str | Path | ByteStream\]</code>) – 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** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the output Documents.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with key `"documents"` containing the converted Haystack Documents.

docs-website/reference/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: <code>Tool</code>
+
+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** (<code>E2BSandbox</code>) – 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** (<code>Secret</code>) – E2B API key.
+- **sandbox_template** (<code>str</code>) – E2B sandbox template name.
+- **timeout** (<code>int</code>) – Sandbox inactivity timeout in seconds.
+- **environment_vars** (<code>dict\[str, str\] | None</code>) – Optional environment variables to inject into the sandbox.
+- **instance_id** (<code>str | None</code>) – 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:**
+
+- <code>RuntimeError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>dict\[str, Any\]</code>) – Dictionary created by :meth:`to_dict`.
+
+**Returns:**
+
+- <code>E2BSandbox</code> – 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: <code>Tool</code>
+
+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** (<code>E2BSandbox</code>) – 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: <code>Tool</code>
+
+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** (<code>E2BSandbox</code>) – 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: <code>Toolset</code>
+
+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** (<code>Secret</code>) – E2B API key. Defaults to `Secret.from_env_var("E2B_API_KEY")`.
+- **sandbox_template** (<code>str</code>) – E2B sandbox template name. Defaults to `"base"`.
+- **timeout** (<code>int</code>) – Sandbox inactivity timeout in seconds. Defaults to `120`.
+- **environment_vars** (<code>dict\[str, str\] | None</code>) – 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: <code>Tool</code>
+
+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** (<code>E2BSandbox</code>) – 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.

docs-website/reference/integrations-api/faiss.md

@@ -0,0 +1,456 @@
+---
+title: "FAISS"
+id: integrations-faiss
+description: "FAISS integration for Haystack"
+slug: "/integrations-faiss"
+---
+
+
+## haystack_integrations.components.retrievers.faiss.embedding_retriever
+
+### FAISSEmbeddingRetriever
+
+Retrieves documents from the `FAISSDocumentStore`, based on their dense embeddings.
+
+Example usage:
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack.document_stores.types import DuplicatePolicy
+
+from haystack_integrations.document_stores.faiss import FAISSDocumentStore
+from haystack_integrations.components.retrievers.faiss import FAISSEmbeddingRetriever
+
+document_store = FAISSDocumentStore(embedding_dim=768)
+
+documents = [
+    Document(content="There are over 7,000 languages spoken around the world today."),
+    Document(content="Elephants have been observed to behave in a way that indicates a high level of intelligence."),
+    Document(content="In certain places, you can witness the phenomenon of bioluminescent waves."),
+]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+
+document_store.write_documents(documents_with_embeddings, policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", FAISSEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+res = query_pipeline.run({"text_embedder": {"text": query}})
+
+assert res["retriever"]["documents"][0].content == "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: FAISSDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize FAISSEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>FAISSDocumentStore</code>) – An instance of `FAISSDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how init-time and runtime filters are combined.
+  See `FilterPolicy` for details. Defaults to `FilterPolicy.REPLACE`.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `FAISSDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FAISSEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>FAISSEmbeddingRetriever</code> – 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** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of Documents to return. Overrides the value set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of Documents to return. Overrides the value set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>str | None</code>) – Path to save/load the index and documents. If None, the store is in-memory only.
+- **index_string** (<code>str</code>) – The FAISS index factory string. Default is "Flat".
+- **embedding_dim** (<code>int</code>) – The dimension of the embeddings. Default is 768.
+
+**Raises:**
+
+- <code>DocumentStoreError</code> – If the FAISS index cannot be initialized.
+- <code>ValueError</code> – 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** (<code>dict\[str, Any\] | None</code>) – A dictionary of filters to apply.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of matching Documents.
+
+**Raises:**
+
+- <code>FilterError</code> – 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** (<code>list\[Document\]</code>) – The list of documents to write.
+- **policy** (<code>DuplicatePolicy</code>) – The policy to handle duplicate documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` is not an iterable of `Document` objects.
+- <code>DuplicateDocumentError</code> – If a duplicate document is found and `policy` is `DuplicatePolicy.FAIL`.
+- <code>DocumentStoreError</code> – 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:**
+
+- <code>DocumentStoreError</code> – 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** (<code>list\[float\]</code>) – The query embedding.
+- **top_k** (<code>int</code>) – The number of results to return.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters to apply.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of matching Documents.
+
+**Raises:**
+
+- <code>FilterError</code> – 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** (<code>dict\[str, Any\]</code>) – A dictionary of filters to apply to find documents to delete.
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>DocumentStoreError</code> – 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** (<code>dict\[str, Any\]</code>) – A dictionary of filters to apply.
+
+**Returns:**
+
+- <code>int</code> – The number of matching documents.
+
+**Raises:**
+
+- <code>FilterError</code> – 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** (<code>dict\[str, Any\]</code>) – A dictionary of filters to apply to find documents to update.
+- **meta** (<code>dict\[str, Any\]</code>) – A dictionary of metadata key-value pairs to update in the matching documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+**Raises:**
+
+- <code>FilterError</code> – 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:**
+
+- <code>dict\[str, dict\[str, Any\]\]</code> – 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** (<code>str</code>) – The name of the metadata field.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with keys "min" and "max" containing the respective min and max values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(field_name: str) -> list[Any]
+```
+
+Returns all unique values for a specific metadata field.
+
+**Parameters:**
+
+- **field_name** (<code>str</code>) – The name of the metadata field.
+
+**Returns:**
+
+- <code>list\[Any\]</code> – A list of unique values for the specified field.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns a count of unique values for multiple metadata fields, optionally scoped by a filter.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – A dictionary of filters to apply.
+- **metadata_fields** (<code>list\[str\]</code>) – A list of metadata field names to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>DocumentStoreError</code> – If the FAISS index is unexpectedly unavailable.
+
+#### load
+
+```python
+load(index_path: str | Path) -> None
+```
+
+Loads the index and documents from disk.
+
+**Raises:**
+
+- <code>ValueError</code> – If the `.faiss` file does not exist.

docs-website/reference/integrations-api/falkordb.md

@@ -0,0 +1,531 @@
+---
+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** (<code>FalkorDBDocumentStore</code>) – The FalkorDBDocumentStore instance.
+- **custom_cypher_query** (<code>str | None</code>) – A static OpenCypher query to execute. Can be
+  overridden at runtime by passing `query` to `run()`.
+
+**Raises:**
+
+- <code>ValueError</code> – If the provided `document_store` is not a `FalkorDBDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialise the retriever to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary representation of the retriever.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FalkorDBCypherRetriever
+```
+
+Deserialise a `FalkorDBCypherRetriever` produced by `to_dict`.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Serialised retriever dictionary.
+
+**Returns:**
+
+- <code>FalkorDBCypherRetriever</code> – 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** (<code>str | None</code>) – Optional OpenCypher query string.
+- **parameters** (<code>dict\[str, Any\] | None</code>) – Optional dictionary of query parameters (referenced as
+  `$param_name` in the Cypher string).
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – Dictionary containing a `"documents"` key with the retrieved documents.
+
+**Raises:**
+
+- <code>ValueError</code> – If no query string is provided (both here and at init).
+
+## haystack_integrations.components.retrievers.falkordb.embedding_retriever
+
+### FalkorDBEmbeddingRetriever
+
+A component for retrieving documents from a FalkorDBDocumentStore using vector similarity.
+
+The retriever uses FalkorDB's native vector search index to find documents whose embeddings
+are most similar to the provided query embedding.
+
+Usage example:
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.document_stores.falkordb import FalkorDBDocumentStore
+from haystack_integrations.components.retrievers.falkordb import FalkorDBEmbeddingRetriever
+
+store = FalkorDBDocumentStore(host="localhost", port=6379)
+store.write_documents([
+    Document(content="GraphRAG is powerful.", embedding=[0.1, 0.2, 0.3]),
+    Document(content="FalkorDB is fast.", embedding=[0.8, 0.9, 0.1]),
+])
+
+retriever = FalkorDBEmbeddingRetriever(document_store=store)
+res = retriever.run(query_embedding=[0.1, 0.2, 0.3])
+print(res["documents"][0].content)  # "GraphRAG is powerful."
+```
+
+#### __init__
+
+```python
+__init__(
+    document_store: FalkorDBDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Create a new FalkorDBEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>FalkorDBDocumentStore</code>) – The FalkorDBDocumentStore instance.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional Haystack filters to narrow down the search space.
+- **top_k** (<code>int</code>) – Maximum number of documents to retrieve.
+- **filter_policy** (<code>FilterPolicy</code>) – Policy to determine how runtime filters are combined with
+  initialization filters.
+
+**Raises:**
+
+- <code>ValueError</code> – If the provided `document_store` is not a `FalkorDBDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialise the retriever to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary representation of the retriever.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FalkorDBEmbeddingRetriever
+```
+
+Deserialise a `FalkorDBEmbeddingRetriever` produced by `to_dict`.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Serialised retriever dictionary.
+
+**Returns:**
+
+- <code>FalkorDBEmbeddingRetriever</code> – 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** (<code>list\[float\]</code>) – Query embedding vector.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional Haystack filters to be combined with the init filters based
+  on the configured filter policy.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return. If not provided, the default
+  top_k from initialization is used.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – Dictionary containing a `"documents"` key with the retrieved documents.
+
+## haystack_integrations.document_stores.falkordb.document_store
+
+### FalkorDBDocumentStore
+
+Bases: <code>DocumentStore</code>
+
+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** (<code>str</code>) – Hostname of the FalkorDB server.
+- **port** (<code>int</code>) – Port the FalkorDB server listens on.
+- **graph_name** (<code>str</code>) – Name of the FalkorDB graph to use. Each graph is an isolated
+  namespace.
+- **username** (<code>str | None</code>) – Optional username for FalkorDB authentication.
+- **password** (<code>Secret | None</code>) – Optional :class:`haystack.utils.Secret` holding the FalkorDB
+  password. The secret value is resolved lazily on first connection.
+- **node_label** (<code>str</code>) – Label used for document nodes in the graph.
+- **embedding_dim** (<code>int</code>) – Dimensionality of the vector embeddings. Used when
+  creating the vector index.
+- **embedding_field** (<code>str</code>) – Name of the node property that stores the embedding
+  vector.
+- **similarity** (<code>SimilarityFunction</code>) – Similarity function for the vector index. Accepted values
+  are `"cosine"` and `"euclidean"`.
+- **write_batch_size** (<code>int</code>) – Number of documents written per `UNWIND` batch.
+- **recreate_graph** (<code>bool</code>) – When `True` the existing graph (and all its data) is
+  dropped and recreated on initialisation. Useful for tests.
+- **verify_connectivity** (<code>bool</code>) – When `True` a connectivity probe is run
+  immediately in `__init__` — raises if the server is unreachable.
+
+**Raises:**
+
+- <code>ValueError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary representation of the store.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FalkorDBDocumentStore
+```
+
+Deserialise a `FalkorDBDocumentStore` produced by `to_dict`.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Serialised store dictionary.
+
+**Returns:**
+
+- <code>FalkorDBDocumentStore</code> – Reconstructed `FalkorDBDocumentStore` instance.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Return the number of documents currently stored in the graph.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>list\[Document\]</code> – List of matching :class:`haystack.dataclasses.Document` objects.
+
+**Raises:**
+
+- <code>ValueError</code> – 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** (<code>list\[Document\]</code>) – List of :class:`haystack.dataclasses.Document` objects.
+- **policy** (<code>DuplicatePolicy</code>) – How to handle documents whose `id` already exists.
+  Defaults to :attr:`DuplicatePolicy.NONE` (treated as FAIL).
+
+**Returns:**
+
+- <code>int</code> – Number of documents written or updated.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` contains non-Document elements.
+- <code>DuplicateDocumentError</code> – If `policy` is FAIL / NONE and a duplicate
+  ID is encountered.
+- <code>DocumentStoreError</code> – 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** (<code>list\[str\]</code>) – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict selecting which documents to update.
+- **meta** (<code>dict\[str, Any\]</code>) – Metadata fields to set. Keys may include or omit the `meta.` prefix.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict. Pass an empty dict to count across all documents.
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names. May include or omit the `meta.` prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – Dict mapping field names to a `{"type": <typename>}` dict.
+  Type names are `"str"`, `"int"`, `"float"`, or `"bool"`.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Return the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name. May include or omit the `meta.` prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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,
+    size: int | None = 10000,
+    after: dict[str, Any] | None = None,
+) -> tuple[list[Any], dict[str, Any] | None]
+```
+
+Return distinct values for the given metadata field with optional filtering and pagination.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name. May include or omit the `meta.` prefix.
+- **search_term** (<code>str | None</code>) – Optional substring filter applied to string field values.
+- **size** (<code>int | None</code>) – Maximum number of values to return per page. Defaults to 10 000.
+- **after** (<code>dict\[str, Any\] | None</code>) – Pagination cursor returned by a previous call. Pass `None` for the first page.
+
+**Returns:**
+
+- <code>tuple\[list\[Any\], dict\[str, Any\] | None\]</code> – Tuple of `(values, next_cursor)`. `next_cursor` is `None` on the last page.

docs-website/reference/integrations-api/fastembed.md

@@ -0,0 +1,701 @@
+---
+title: "FastEmbed"
+id: fastembed-embedders
+description: "FastEmbed integration for Haystack"
+slug: "/fastembed-embedders"
+---
+
+
+## haystack_integrations.components.embedders.fastembed.fastembed_document_embedder
+
+### FastembedDocumentEmbedder
+
+FastembedDocumentEmbedder computes Document embeddings using Fastembed embedding models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+# To use this component, install the "fastembed-haystack" package.
+# pip install fastembed-haystack
+
+from haystack_integrations.components.embedders.fastembed import FastembedDocumentEmbedder
+from haystack.dataclasses import Document
+
+doc_embedder = FastembedDocumentEmbedder(
+    model="BAAI/bge-small-en-v1.5",
+    batch_size=256,
+)
+
+# Text taken from PubMed QA Dataset (https://huggingface.co/datasets/pubmed_qa)
+document_list = [
+    Document(
+        content=("Oxidative stress generated within inflammatory joints can produce autoimmune phenomena and joint "
+                 "destruction. Radical species with oxidative activity, including reactive nitrogen species, "
+                 "represent mediators of inflammation and cartilage damage."),
+        meta={
+            "pubid": "25,445,628",
+            "long_answer": "yes",
+        },
+    ),
+    Document(
+        content=("Plasma levels of pancreatic polypeptide (PP) rise upon food intake. Although other pancreatic "
+                 "islet hormones, such as insulin and glucagon, have been extensively investigated, PP secretion "
+                 "and actions are still poorly understood."),
+        meta={
+            "pubid": "25,445,712",
+            "long_answer": "yes",
+        },
+    ),
+]
+
+result = doc_embedder.run(document_list)
+print(f"Document Text: {result['documents'][0].content}")
+print(f"Document Embedding: {result['documents'][0].embedding}")
+print(f"Embedding Dimension: {len(result['documents'][0].embedding)}")
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str = "BAAI/bge-small-en-v1.5",
+    cache_dir: str | None = None,
+    threads: int | None = None,
+    prefix: str = "",
+    suffix: str = "",
+    batch_size: int = 256,
+    progress_bar: bool = True,
+    parallel: int | None = None,
+    local_files_only: bool = False,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+) -> None
+```
+
+Create an FastembedDocumentEmbedder component.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – Local path or name of the model in Hugging Face's model hub,
+  such as `BAAI/bge-small-en-v1.5`.
+- **cache_dir** (<code>str | None</code>) – 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** (<code>int | None</code>) – The number of threads single onnxruntime session can use. Defaults to None.
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **batch_size** (<code>int</code>) – Number of strings to encode at once.
+- **progress_bar** (<code>bool</code>) – If `True`, displays progress bar during embedding.
+- **parallel** (<code>int | None</code>) – 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** (<code>bool</code>) – If `True`, only use the model files in the `cache_dir`.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document content.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document content.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>list\[Document\]</code>) – List of Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of Documents with each Document's `embedding` field set to the computed embeddings.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.fastembed.fastembed_sparse_document_embedder
+
+### FastembedSparseDocumentEmbedder
+
+FastembedSparseDocumentEmbedder computes Document embeddings using Fastembed sparse models.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.fastembed import FastembedSparseDocumentEmbedder
+from haystack.dataclasses import Document
+
+sparse_doc_embedder = FastembedSparseDocumentEmbedder(
+    model="prithivida/Splade_PP_en_v1",
+    batch_size=32,
+)
+
+# Text taken from PubMed QA Dataset (https://huggingface.co/datasets/pubmed_qa)
+document_list = [
+    Document(
+        content=("Oxidative stress generated within inflammatory joints can produce autoimmune phenomena and joint "
+                 "destruction. Radical species with oxidative activity, including reactive nitrogen species, "
+                 "represent mediators of inflammation and cartilage damage."),
+        meta={
+            "pubid": "25,445,628",
+            "long_answer": "yes",
+        },
+    ),
+    Document(
+        content=("Plasma levels of pancreatic polypeptide (PP) rise upon food intake. Although other pancreatic "
+                 "islet hormones, such as insulin and glucagon, have been extensively investigated, PP secretion "
+                 "and actions are still poorly understood."),
+        meta={
+            "pubid": "25,445,712",
+            "long_answer": "yes",
+        },
+    ),
+]
+
+result = sparse_doc_embedder.run(document_list)
+print(f"Document Text: {result['documents'][0].content}")
+print(f"Document Sparse Embedding: {result['documents'][0].sparse_embedding}")
+print(f"Sparse Embedding Dimension: {len(result['documents'][0].sparse_embedding)}")
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str = "prithivida/Splade_PP_en_v1",
+    cache_dir: str | None = None,
+    threads: int | None = None,
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    parallel: int | None = None,
+    local_files_only: bool = False,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    model_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Create an FastembedDocumentEmbedder component.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – Local path or name of the model in Hugging Face's model hub,
+  such as `prithivida/Splade_PP_en_v1`.
+- **cache_dir** (<code>str | None</code>) – 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** (<code>int | None</code>) – The number of threads single onnxruntime session can use.
+- **batch_size** (<code>int</code>) – Number of strings to encode at once.
+- **progress_bar** (<code>bool</code>) – If `True`, displays progress bar during embedding.
+- **parallel** (<code>int | None</code>) – 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** (<code>bool</code>) – If `True`, only use the model files in the `cache_dir`.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document content.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document content.
+- **model_kwargs** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>list\[Document\]</code>) – List of Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of Documents with each Document's `sparse_embedding`
+  field set to the computed embeddings.
+
+**Raises:**
+
+- <code>TypeError</code> – 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** (<code>str</code>) – Local path or name of the model in Fastembed's model hub, such as `prithivida/Splade_PP_en_v1`
+- **cache_dir** (<code>str | None</code>) – 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** (<code>int | None</code>) – The number of threads single onnxruntime session can use. Defaults to None.
+- **progress_bar** (<code>bool</code>) – If `True`, displays progress bar during embedding.
+- **parallel** (<code>int | None</code>) – 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** (<code>bool</code>) – If `True`, only use the model files in the `cache_dir`.
+- **model_kwargs** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – A string to embed.
+
+**Returns:**
+
+- <code>dict\[str, SparseEmbedding\]</code> – A dictionary with the following keys:
+- `embedding`: A list of floats representing the embedding of the input text.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.
+
+## haystack_integrations.components.embedders.fastembed.fastembed_text_embedder
+
+### FastembedTextEmbedder
+
+FastembedTextEmbedder computes string embedding using fastembed embedding models.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.fastembed import FastembedTextEmbedder
+
+text = ("It clearly says online this will work on a Mac OS system. "
+        "The disk comes and it does not, only Windows. Do Not order this if you have a Mac!!")
+
+text_embedder = FastembedTextEmbedder(
+    model="BAAI/bge-small-en-v1.5"
+)
+
+embedding = text_embedder.run(text)["embedding"]
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str = "BAAI/bge-small-en-v1.5",
+    cache_dir: str | None = None,
+    threads: int | None = None,
+    prefix: str = "",
+    suffix: str = "",
+    progress_bar: bool = True,
+    parallel: int | None = None,
+    local_files_only: bool = False,
+) -> None
+```
+
+Create a FastembedTextEmbedder component.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – Local path or name of the model in Fastembed's model hub, such as `BAAI/bge-small-en-v1.5`
+- **cache_dir** (<code>str | None</code>) – 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** (<code>int | None</code>) – The number of threads single onnxruntime session can use. Defaults to None.
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **progress_bar** (<code>bool</code>) – If `True`, displays progress bar during embedding.
+- **parallel** (<code>int | None</code>) – 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** (<code>bool</code>) – If `True`, only use the model files in the `cache_dir`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – A string to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\]\]</code> – A dictionary with the following keys:
+- `embedding`: A list of floats representing the embedding of the input text.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.
+
+## haystack_integrations.components.rankers.fastembed.late_interaction_ranker
+
+### FastembedLateInteractionRanker
+
+Ranks Documents based on their similarity to the query using ColBERT models via Fastembed.
+
+Uses late interaction (MaxSim) scoring to compute token-level similarity between
+query and document embeddings, then ranks documents accordingly.
+
+See https://qdrant.github.io/fastembed/examples/Supported_Models/ for supported models.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.fastembed import FastembedLateInteractionRanker
+
+ranker = FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0", top_k=2)
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "What is the capital of germany?"
+output = ranker.run(query=query, documents=docs)
+print(output["documents"][0].content)
+
+# Berlin
+```
+
+#### __init__
+
+```python
+__init__(
+    model_name: str = "colbert-ir/colbertv2.0",
+    top_k: int = 10,
+    cache_dir: str | None = None,
+    threads: int | None = None,
+    batch_size: int = 64,
+    parallel: int | None = None,
+    local_files_only: bool = False,
+    meta_fields_to_embed: list[str] | None = None,
+    meta_data_separator: str = "\n",
+    score_threshold: float | None = None,
+) -> None
+```
+
+Creates an instance of the 'FastembedLateInteractionRanker'.
+
+**Parameters:**
+
+- **model_name** (<code>str</code>) – Fastembed ColBERT model name. Check the list of supported models in the
+  [Fastembed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+- **top_k** (<code>int</code>) – The maximum number of documents to return.
+- **cache_dir** (<code>str | None</code>) – 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** (<code>int | None</code>) – The number of threads single onnxruntime session can use. Defaults to None.
+- **batch_size** (<code>int</code>) – Number of strings to encode at once.
+- **parallel** (<code>int | None</code>) – 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** (<code>bool</code>) – If `True`, only use the model files in the `cache_dir`.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be concatenated
+  with the document content for reranking.
+- **meta_data_separator** (<code>str</code>) – Separator used to concatenate the meta fields
+  to the Document content.
+- **score_threshold** (<code>float | None</code>) – If provided, only documents with a score above the threshold are returned.
+  Note that ColBERT scores are unnormalized sums and typically range from 3 to 25.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FastembedLateInteractionRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>FastembedLateInteractionRanker</code> – 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** (<code>str</code>) – The input query to compare the documents to.
+- **documents** (<code>list\[Document\]</code>) – A list of documents to be ranked.
+- **top_k** (<code>int | None</code>) – The maximum number of documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents closest to the query, sorted from most similar to least similar.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.
+
+## haystack_integrations.components.rankers.fastembed.ranker
+
+### FastembedRanker
+
+Ranks Documents based on their similarity to the query using Fastembed models.
+
+See https://qdrant.github.io/fastembed/examples/Supported_Models/ for supported models.
+
+Documents are indexed from most to least semantically relevant to the query.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.fastembed import FastembedRanker
+
+ranker = FastembedRanker(model_name="Xenova/ms-marco-MiniLM-L-6-v2", top_k=2)
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "What is the capital of germany?"
+output = ranker.run(query=query, documents=docs)
+print(output["documents"][0].content)
+
+# Berlin
+```
+
+#### __init__
+
+```python
+__init__(
+    model_name: str = "Xenova/ms-marco-MiniLM-L-6-v2",
+    top_k: int = 10,
+    cache_dir: str | None = None,
+    threads: int | None = None,
+    batch_size: int = 64,
+    parallel: int | None = None,
+    local_files_only: bool = False,
+    meta_fields_to_embed: list[str] | None = None,
+    meta_data_separator: str = "\n",
+    score_threshold: float | None = None,
+) -> None
+```
+
+Creates an instance of the 'FastembedRanker'.
+
+**Parameters:**
+
+- **model_name** (<code>str</code>) – Fastembed model name. Check the list of supported models in the [Fastembed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+- **top_k** (<code>int</code>) – The maximum number of documents to return.
+- **cache_dir** (<code>str | None</code>) – 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** (<code>int | None</code>) – The number of threads single onnxruntime session can use. Defaults to None.
+- **batch_size** (<code>int</code>) – Number of strings to encode at once.
+- **parallel** (<code>int | None</code>) – 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** (<code>bool</code>) – If `True`, only use the model files in the `cache_dir`.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be concatenated
+  with the document content for reranking.
+- **meta_data_separator** (<code>str</code>) – Separator used to concatenate the meta fields
+  to the Document content.
+- **score_threshold** (<code>float | None</code>) – If provided, only documents with a score above the threshold are returned.
+  Applied after `top_k`, so the output may contain fewer than `top_k` documents.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FastembedRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>FastembedRanker</code> – 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** (<code>str</code>) – The input query to compare the documents to.
+- **documents** (<code>list\[Document\]</code>) – A list of documents to be ranked.
+- **top_k** (<code>int | None</code>) – The maximum number of documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents closest to the query, sorted from most similar to least similar.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.

docs-website/reference/integrations-api/firecrawl.md

@@ -0,0 +1,206 @@
+---
+title: "Firecrawl"
+id: integrations-firecrawl
+description: "Firecrawl integration for Haystack"
+slug: "/integrations-firecrawl"
+---
+
+
+## haystack_integrations.components.fetchers.firecrawl.firecrawl_crawler
+
+### FirecrawlCrawler
+
+A component that uses Firecrawl to crawl one or more URLs and return the content as Haystack Documents.
+
+Crawling starts from each given URL and follows links to discover subpages, up to a configurable limit.
+This is useful for ingesting entire websites or documentation sites, not just single pages.
+
+Firecrawl is a service that crawls websites and returns content in a structured format (e.g. Markdown)
+suitable for LLMs. You need a Firecrawl API key from [firecrawl.dev](https://firecrawl.dev).
+
+### Usage example
+
+```python
+from haystack_integrations.components.fetchers.firecrawl import FirecrawlFetcher
+
+fetcher = FirecrawlFetcher(
+    api_key=Secret.from_env_var("FIRECRAWL_API_KEY"),
+    params={"limit": 5},
+)
+fetcher.warm_up()
+
+result = fetcher.run(urls=["https://docs.haystack.deepset.ai/docs/intro"])
+documents = result["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("FIRECRAWL_API_KEY"),
+    params: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the FirecrawlFetcher.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – API key for Firecrawl.
+  Defaults to the `FIRECRAWL_API_KEY` environment variable.
+- **params** (<code>dict\[str, Any\] | None</code>) – 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** (<code>list\[str\]</code>) – List of URLs to crawl.
+- **params** (<code>dict\[str, Any\] | None</code>) – Optional override of crawl parameters for this run.
+  If provided, fully replaces the init-time params.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>list\[str\]</code>) – List of URLs to crawl.
+- **params** (<code>dict\[str, Any\] | None</code>) – Optional override of crawl parameters for this run.
+  If provided, fully replaces the init-time params.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: List of documents, one for each URL crawled.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Firecrawl client by initializing the clients.
+This is useful to avoid cold start delays when crawling many URLs.
+
+## haystack_integrations.components.websearch.firecrawl.firecrawl_websearch
+
+### FirecrawlWebSearch
+
+A component that uses Firecrawl to search the web and return results as Haystack Documents.
+
+This component wraps the Firecrawl Search API, enabling web search queries that return
+structured documents with content and links. It follows the standard Haystack WebSearch
+component interface.
+
+Firecrawl is a service that crawls and scrapes websites, returning content in formats suitable
+for LLMs. You need a Firecrawl API key from [firecrawl.dev](https://firecrawl.dev).
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.firecrawl import FirecrawlWebSearch
+from haystack.utils import Secret
+
+websearch = FirecrawlWebSearch(
+    api_key=Secret.from_env_var("FIRECRAWL_API_KEY"),
+    top_k=5,
+)
+result = websearch.run(query="What is Haystack by deepset?")
+documents = result["documents"]
+links = result["links"]
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("FIRECRAWL_API_KEY"),
+    top_k: int | None = 10,
+    search_params: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the FirecrawlWebSearch component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – API key for Firecrawl.
+  Defaults to the `FIRECRAWL_API_KEY` environment variable.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return.
+  Defaults to 10. This can be overridden by the `"limit"` parameter in `search_params`.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – Additional parameters passed to the Firecrawl search API.
+  See the [Firecrawl API reference](https://docs.firecrawl.dev/api-reference/endpoint/search)
+  for available parameters. Supported keys include: `tbs`, `location`,
+  `scrape_options`, `sources`, `categories`, `timeout`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Firecrawl clients by initializing the sync and async clients.
+This is useful to avoid cold start delays when performing searches.
+
+#### run
+
+```python
+run(query: str, search_params: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Search the web using Firecrawl and return results as Documents.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Search query string.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – Optional override of search parameters for this run.
+  If provided, fully replaces the init-time search_params.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – Search query string.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – Optional override of search parameters for this run.
+  If provided, fully replaces the init-time search_params.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: List of documents with search result content.
+- `links`: List of URLs from the search results.

docs-website/reference/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** (<code>str</code>) – 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** (<code>str | None</code>) – 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** (<code>str | None</code>) – Punctuation restoration model. Set to `None` to disable punctuation.
+  Browse available punctuation models at https://www.modelscope.cn/models.
+- **spk_model** (<code>str | None</code>) – 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** (<code>ComponentDevice | None</code>) – 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** (<code>int</code>) – Batch size in seconds for VAD-segmented audio. Larger values
+  improve throughput at the cost of memory.
+- **store_full_path** (<code>bool</code>) – If `True`, store the full audio file path in Document metadata.
+  If `False` (default), store only the file name.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FunASRTranscriber
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>FunASRTranscriber</code> – 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** (<code>list\[str | Path | ByteStream\]</code>) – 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** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[Document\]\]</code> – Dictionary with key `"documents"` — one `Document` per source whose
+  `content` holds the full transcript text.

docs-website/reference/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: <code>str</code>, <code>Enum</code>
+
+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** (<code>Secret</code>) – GitHub personal access token for API authentication
+- **repo** (<code>str | None</code>) – Default repository in owner/repo format
+- **branch** (<code>str</code>) – Default branch to work with
+- **raise_on_failure** (<code>bool</code>) – If True, raises exceptions on API errors
+
+**Raises:**
+
+- <code>TypeError</code> – 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** (<code>Command | str</code>) – Operation to perform ("edit", "undo", "create", "delete")
+- **payload** (<code>dict\[str, Any\]</code>) – Dictionary containing command-specific parameters
+- **repo** (<code>str | None</code>) – Repository in owner/repo format (overrides default if provided)
+- **branch** (<code>str | None</code>) – Branch to perform operations on (overrides default if provided)
+
+**Returns:**
+
+- <code>dict\[str, str\]</code> – Dictionary containing operation result
+
+**Raises:**
+
+- <code>ValueError</code> – 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** (<code>Secret</code>) – GitHub personal access token for API authentication as a Secret
+- **raise_on_failure** (<code>bool</code>) – If True, raises exceptions on API errors
+- **retry_attempts** (<code>int</code>) – Number of retry attempts for failed requests
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GitHubIssueCommenter
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GitHubIssueCommenter</code> – Deserialized component.
+
+#### run
+
+```python
+run(url: str, comment: str) -> dict
+```
+
+Post a comment to a GitHub issue.
+
+**Parameters:**
+
+- **url** (<code>str</code>) – GitHub issue URL
+- **comment** (<code>str</code>) – Comment text to post
+
+**Returns:**
+
+- <code>dict</code> – 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** (<code>Secret | None</code>) – GitHub personal access token for API authentication as a Secret
+- **raise_on_failure** (<code>bool</code>) – If True, raises exceptions on API errors
+- **retry_attempts** (<code>int</code>) – Number of retry attempts for failed requests
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GitHubIssueViewer
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GitHubIssueViewer</code> – Deserialized component.
+
+#### run
+
+```python
+run(url: str) -> dict
+```
+
+Process a GitHub issue URL and return documents.
+
+**Parameters:**
+
+- **url** (<code>str</code>) – GitHub issue URL
+
+**Returns:**
+
+- <code>dict</code> – 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** (<code>Secret</code>) – GitHub personal access token for authentication (from the fork owner)
+- **raise_on_failure** (<code>bool</code>) – 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** (<code>str</code>) – URL of the GitHub issue to link the PR to
+- **title** (<code>str</code>) – Title of the pull request
+- **branch** (<code>str</code>) – Name of the branch in your fork where changes are implemented
+- **base** (<code>str</code>) – Name of the branch in the original repo you want to merge into
+- **body** (<code>str</code>) – Additional content for the pull request description
+- **draft** (<code>bool</code>) – Whether to create a draft pull request
+
+**Returns:**
+
+- <code>dict\[str, str\]</code> – 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** (<code>Secret</code>) – GitHub personal access token for API authentication
+- **raise_on_failure** (<code>bool</code>) – If True, raises exceptions on API errors
+- **wait_for_completion** (<code>bool</code>) – If True, waits until fork is fully created
+- **max_wait_seconds** (<code>int</code>) – Maximum time to wait for fork completion in seconds
+- **poll_interval** (<code>int</code>) – Time between status checks in seconds
+- **auto_sync** (<code>bool</code>) – If True, syncs fork with original repository if it already exists
+- **create_branch** (<code>bool</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GitHubRepoForker
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GitHubRepoForker</code> – Deserialized component.
+
+#### run
+
+```python
+run(url: str) -> dict
+```
+
+Process a GitHub issue URL and create or sync a fork of the repository.
+
+**Parameters:**
+
+- **url** (<code>str</code>) – GitHub issue URL
+
+**Returns:**
+
+- <code>dict</code> – 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** (<code>Secret | None</code>) – GitHub personal access token for API authentication
+- **raise_on_failure** (<code>bool</code>) – If True, raises exceptions on API errors
+- **max_file_size** (<code>int</code>) – Maximum file size in bytes to fetch (default: 1MB)
+- **repo** (<code>str | None</code>) – Repository in format "owner/repo"
+- **branch** (<code>str</code>) – Git reference (branch, tag, commit) to use
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GitHubRepoViewer
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GitHubRepoViewer</code> – 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** (<code>str | None</code>) – Repository in format "owner/repo"
+- **path** (<code>str</code>) – Path within repository (default: root)
+- **branch** (<code>str | None</code>) – Git reference (branch, tag, commit) to use
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – Dictionary containing list of documents

docs-website/reference/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"
+---
+
+<a id="haystack_integrations.components.generators.google_ai.gemini"></a>
+
+## Module haystack\_integrations.components.generators.google\_ai.gemini
+
+<a id="haystack_integrations.components.generators.google_ai.gemini.GoogleAIGeminiGenerator"></a>
+
+### 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("<MY_API_KEY>"))
+res = gemini.run(parts = ["What is the most interesting thing you know?"])
+for answer in res["replies"]:
+    print(answer)
+```
+
+#### Multimodal example
+
+```python
+import requests
+from haystack.utils import Secret
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_ai import GoogleAIGeminiGenerator
+
+BASE_URL = (
+    "https://raw.githubusercontent.com/deepset-ai/haystack-core-integrations"
+    "/main/integrations/google_ai/example_assets"
+)
+
+URLS = [
+    f"{BASE_URL}/robot1.jpg",
+    f"{BASE_URL}/robot2.jpg",
+    f"{BASE_URL}/robot3.jpg",
+    f"{BASE_URL}/robot4.jpg"
+]
+images = [
+    ByteStream(data=requests.get(url).content, mime_type="image/jpeg")
+    for url in URLS
+]
+
+gemini = GoogleAIGeminiGenerator(model="gemini-2.0-flash", api_key=Secret.from_token("<MY_API_KEY>"))
+result = gemini.run(parts = ["What can you tell me about this robots?", *images])
+for answer in result["replies"]:
+    print(answer)
+```
+
+<a id="haystack_integrations.components.generators.google_ai.gemini.GoogleAIGeminiGenerator.__init__"></a>
+
+#### GoogleAIGeminiGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+             api_key: Secret = Secret.from_env_var("GOOGLE_API_KEY"),
+             model: str = "gemini-2.0-flash",
+             generation_config: Optional[Union[GenerationConfig,
+                                               dict[str, Any]]] = None,
+             safety_settings: Optional[dict[HarmCategory,
+                                            HarmBlockThreshold]] = None,
+             streaming_callback: Optional[Callable[[StreamingChunk],
+                                                   None]] = None)
+```
+
+Initializes a `GoogleAIGeminiGenerator` instance.
+
+To get an API key, visit: https://makersuite.google.com
+
+**Arguments**:
+
+- `api_key`: Google AI Studio API key.
+- `model`: Name of the model to use. For available models, see https://ai.google.dev/gemini-api/docs/models/gemini
+- `generation_config`: The generation configuration to use.
+This can either be a `GenerationConfig` object or a dictionary of parameters.
+For available parameters, see
+[the `GenerationConfig` API reference](https://ai.google.dev/api/python/google/generativeai/GenerationConfig).
+- `safety_settings`: The safety settings to use.
+A dictionary with `HarmCategory` as keys and `HarmBlockThreshold` as values.
+For more information, see [the API reference](https://ai.google.dev/api)
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+The callback function accepts StreamingChunk as an argument.
+
+<a id="haystack_integrations.components.generators.google_ai.gemini.GoogleAIGeminiGenerator.to_dict"></a>
+
+#### GoogleAIGeminiGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.generators.google_ai.gemini.GoogleAIGeminiGenerator.from_dict"></a>
+
+#### GoogleAIGeminiGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GoogleAIGeminiGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.generators.google_ai.gemini.GoogleAIGeminiGenerator.run"></a>
+
+#### GoogleAIGeminiGenerator.run
+
+```python
+@component.output_types(replies=list[str])
+def run(parts: Variadic[Union[str, ByteStream, Part]],
+        streaming_callback: Optional[Callable[[StreamingChunk], None]] = None)
+```
+
+Generates text based on the given input parts.
+
+**Arguments**:
+
+- `parts`: A heterogeneous list of strings, `ByteStream` or `Part` objects.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+
+**Returns**:
+
+A dictionary containing the following key:
+- `replies`: A list of strings containing the generated responses.
+
+<a id="haystack_integrations.components.generators.google_ai.chat.gemini"></a>
+
+## Module haystack\_integrations.components.generators.google\_ai.chat.gemini
+
+<a id="haystack_integrations.components.generators.google_ai.chat.gemini.GoogleAIGeminiChatGenerator"></a>
+
+### GoogleAIGeminiChatGenerator
+
+Completes chats using Gemini models through Google AI Studio.
+
+It uses the [`ChatMessage`](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage)
+  dataclass to interact with the model.
+
+### Usage example
+
+```python
+from haystack.utils import Secret
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack_integrations.components.generators.google_ai import GoogleAIGeminiChatGenerator
+
+
+gemini_chat = GoogleAIGeminiChatGenerator(model="gemini-2.0-flash", api_key=Secret.from_token("<MY_API_KEY>"))
+
+messages = [ChatMessage.from_user("What is the most interesting thing you know?")]
+res = gemini_chat.run(messages=messages)
+for reply in res["replies"]:
+    print(reply.text)
+
+messages += res["replies"] + [ChatMessage.from_user("Tell me more about it")]
+res = gemini_chat.run(messages=messages)
+for reply in res["replies"]:
+    print(reply.text)
+```
+
+
+#### With function 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_ai import GoogleAIGeminiChatGenerator
+
+# 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 = GoogleAIGeminiChatGenerator(
+    model="gemini-2.0-flash-exp",
+    api_key=Secret.from_token("<MY_API_KEY>"),
+    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)
+```
+
+<a id="haystack_integrations.components.generators.google_ai.chat.gemini.GoogleAIGeminiChatGenerator.__init__"></a>
+
+#### GoogleAIGeminiChatGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+             api_key: Secret = Secret.from_env_var("GOOGLE_API_KEY"),
+             model: str = "gemini-2.0-flash",
+             generation_config: Optional[Union[GenerationConfig,
+                                               dict[str, Any]]] = None,
+             safety_settings: Optional[dict[HarmCategory,
+                                            HarmBlockThreshold]] = None,
+             tools: Optional[list[Tool]] = None,
+             tool_config: Optional[content_types.ToolConfigDict] = None,
+             streaming_callback: Optional[StreamingCallbackT] = None)
+```
+
+Initializes a `GoogleAIGeminiChatGenerator` instance.
+
+To get an API key, visit: https://aistudio.google.com/
+
+**Arguments**:
+
+- `api_key`: Google AI Studio API key. To get a key,
+see [Google AI Studio](https://aistudio.google.com/).
+- `model`: Name of the model to use. For available models, see https://ai.google.dev/gemini-api/docs/models/gemini.
+- `generation_config`: The generation configuration to use.
+This can either be a `GenerationConfig` object or a dictionary of parameters.
+For available parameters, see
+[the API reference](https://ai.google.dev/api/generate-content).
+- `safety_settings`: The safety settings to use.
+A dictionary with `HarmCategory` as keys and `HarmBlockThreshold` as values.
+For more information, see [the API reference](https://ai.google.dev/api/generate-content)
+- `tools`: A list of tools for which the model can prepare calls.
+- `tool_config`: The tool config to use. See the documentation for
+[ToolConfig](https://ai.google.dev/api/caching#ToolConfig).
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+The callback function accepts StreamingChunk as an argument.
+
+<a id="haystack_integrations.components.generators.google_ai.chat.gemini.GoogleAIGeminiChatGenerator.to_dict"></a>
+
+#### GoogleAIGeminiChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.generators.google_ai.chat.gemini.GoogleAIGeminiChatGenerator.from_dict"></a>
+
+#### GoogleAIGeminiChatGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GoogleAIGeminiChatGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.generators.google_ai.chat.gemini.GoogleAIGeminiChatGenerator.run"></a>
+
+#### GoogleAIGeminiChatGenerator.run
+
+```python
+@component.output_types(replies=list[ChatMessage])
+def run(messages: list[ChatMessage],
+        streaming_callback: Optional[StreamingCallbackT] = None,
+        *,
+        tools: Optional[list[Tool]] = None)
+```
+
+Generates text based on the provided messages.
+
+**Arguments**:
+
+- `messages`: A list of `ChatMessage` instances, representing the input messages.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+- `tools`: A list of tools for which the model can prepare calls. If set, it will override the `tools` parameter set
+during component initialization.
+
+**Returns**:
+
+A dictionary containing the following key:
+- `replies`:  A list containing the generated responses as `ChatMessage` instances.
+
+<a id="haystack_integrations.components.generators.google_ai.chat.gemini.GoogleAIGeminiChatGenerator.run_async"></a>
+
+#### GoogleAIGeminiChatGenerator.run\_async
+
+```python
+@component.output_types(replies=list[ChatMessage])
+async def run_async(messages: list[ChatMessage],
+                    streaming_callback: Optional[StreamingCallbackT] = None,
+                    *,
+                    tools: Optional[list[Tool]] = None)
+```
+
+Async version of the run method. Generates text based on the provided messages.
+
+**Arguments**:
+
+- `messages`: A list of `ChatMessage` instances, representing the input messages.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+- `tools`: A list of tools for which the model can prepare calls. If set, it will override the `tools` parameter set
+during component initialization.
+
+**Returns**:
+
+A dictionary containing the following key:
+- `replies`:  A list containing the generated responses as `ChatMessage` instances.
+

docs-website/reference/integrations-api/google_drive.md

@@ -0,0 +1,350 @@
+---
+title: "Google Drive"
+id: integrations-google-drive
+description: "Google Drive integration for Haystack"
+slug: "/integrations-google-drive"
+---
+
+
+## haystack_integrations.components.fetchers.google_drive.fetcher
+
+### GoogleDriveFetcher
+
+Fetches the full content of Google Drive files via the Drive API v3.
+
+The fetcher complements `GoogleDriveRetriever`, which returns only metadata (and optionally exported text).
+Wire the retriever's `documents` (or a list of file ids / Drive URLs) into this fetcher to download the full
+content. It dispatches on each file's mime type and always returns `ByteStream`s, ready for a downstream
+converter (for example a `FileTypeRouter` in front of `PyPDFToDocument`, `DOCXToDocument`, `XLSXToDocument`,
+or `PPTXToDocument`):
+
+- **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`.
+
+The fetcher takes a per-user `access_token` as a run input, typically wired from an upstream `OAuthTokenResolver`.
+The token must carry a delegated Google OAuth scope that allows reading file content (for example
+`https://www.googleapis.com/auth/drive.readonly`).
+
+### Usage example
+
+```python
+from haystack_integrations.components.fetchers.google_drive import GoogleDriveFetcher
+
+fetcher = GoogleDriveFetcher()
+
+# `access_token` is a per-user delegated Google OAuth bearer token.
+result = fetcher.run(
+    access_token="my-delegated-google-token",
+    targets=["https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/view"],
+)
+streams = result["streams"]
+```
+
+In a pipeline, connect `GoogleDriveRetriever.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__(
+    *,
+    api_base_url: str = DEFAULT_API_BASE_URL,
+    timeout: float = 30.0,
+    max_retries: int = 3,
+    max_concurrent_requests: int = 5,
+    raise_on_failure: bool = True,
+    export_mime_types: dict[str, str] | None = None
+) -> None
+```
+
+Initialize the fetcher.
+
+**Parameters:**
+
+- **api_base_url** (<code>str</code>) – The Drive API base URL. Defaults to `https://www.googleapis.com/drive/v3`.
+- **timeout** (<code>float</code>) – The HTTP timeout in seconds for each request to the Drive API.
+- **max_retries** (<code>int</code>) – The maximum number of retries for throttled (HTTP 429) or transient server errors.
+- **max_concurrent_requests** (<code>int</code>) – 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** (<code>bool</code>) – 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** (<code>dict\[str, str\] | None</code>) – 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:**
+
+- <code>GoogleDriveConfigError</code> – 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** (<code>str | Secret</code>) – 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** (<code>list\[Document | str\]</code>) – 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:**
+
+- <code>dict\[str, list\[ByteStream\]\]</code> – 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:**
+
+- <code>GoogleDriveConfigError</code> – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+  `Secret` that does not resolve to a string.
+- <code>GoogleDriveRequestError</code> – 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** (<code>str | Secret</code>) – 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** (<code>list\[Document | str\]</code>) – 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:**
+
+- <code>dict\[str, list\[ByteStream\]\]</code> – 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:**
+
+- <code>GoogleDriveConfigError</code> – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+  `Secret` that does not resolve to a string.
+- <code>GoogleDriveRequestError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleDriveFetcher
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>GoogleDriveFetcher</code> – 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** (<code>bool</code>) – 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** (<code>int</code>) – The maximum number of documents to return. Maps to the Drive `pageSize` and is
+  paginated when it exceeds a single page.
+- **query_filter** (<code>str | None</code>) – Optional Drive query clause AND-ed with the full-text search term, for example
+  `"mimeType != 'application/vnd.google-apps.folder'"` or `"'<folderId>' in parents"`.
+- **include_shared_drives** (<code>bool</code>) – When `True`, the search spans shared drives as well as the user's My
+  Drive (sets `includeItemsFromAllDrives`, `supportsAllDrives`, and `corpora=allDrives`).
+- **order_by** (<code>str | None</code>) – Optional Drive `orderBy` expression, for example `"modifiedTime desc"`.
+- **fields** (<code>list\[str\] | None</code>) – Optional list of file properties to request via the Drive `fields` selection.
+  Defaults to a standard set covering the returned metadata.
+- **api_base_url** (<code>str</code>) – The Drive API base URL. Defaults to `https://www.googleapis.com/drive/v3`.
+- **timeout** (<code>float</code>) – The HTTP timeout in seconds for each request to the Drive API.
+- **max_retries** (<code>int</code>) – The maximum number of retries on HTTP 429 (rate limit), 500, 502, 503,
+  or 504 responses. Set to 0 to disable retries.
+
+**Raises:**
+
+- <code>GoogleDriveConfigError</code> – 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** (<code>str</code>) – The search query string, matched against the full text of files via
+  `fullText contains`.
+- **access_token** (<code>str | Secret</code>) – 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** (<code>int | None</code>) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- <code>GoogleDriveConfigError</code> – If `access_token` is a `Secret` that does not resolve to a string.
+- <code>GoogleDriveRequestError</code> – If the Drive API returns an error response.
+- <code>httpx.HTTPError</code> – 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** (<code>str</code>) – The search query string, matched against the full text of files via
+  `fullText contains`.
+- **access_token** (<code>str | Secret</code>) – 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** (<code>int | None</code>) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- <code>GoogleDriveConfigError</code> – If `access_token` is a `Secret` that does not resolve to a string.
+- <code>GoogleDriveRequestError</code> – If the Drive API returns an error response.
+- <code>httpx.HTTPError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleDriveRetriever
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>GoogleDriveRetriever</code> – The deserialized component instance.

docs-website/reference/integrations-api/google_genai.md

@@ -0,0 +1,873 @@
+---
+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** (<code>Secret</code>) – 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** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+  Application Default Credentials.
+- **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+  Required when using Vertex AI with Application Default Credentials.
+- **model** (<code>str</code>) – The name of the model to use for calculating embeddings.
+  The default model is `gemini-embedding-001`.
+- **prefix** (<code>str</code>) – 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** (<code>str</code>) – A string to add at the end of each text.
+- **batch_size** (<code>int</code>) – Number of documents to embed at once.
+- **progress_bar** (<code>bool</code>) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the metadata fields to the document text.
+- **config** (<code>dict\[str, Any\] | None</code>) – 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** (<code>float | None</code>) – The timeout in seconds for the underlying Google GenAI client network requests.
+- **max_retries** (<code>int | None</code>) – The maximum number of retries for the underlying Google GenAI client network requests.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAIDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GoogleGenAIDocumentEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]] | dict[str, Any]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – 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** (<code>list\[Document\]</code>) – A list of documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – 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** (<code>Secret</code>) – 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** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+  Application Default Credentials.
+- **vertex_ai_location** (<code>str | None</code>) – 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** (<code>str</code>) – The metadata field in the Document that contains the file path to the file to embed.
+- **root_path** (<code>str | None</code>) – 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** (<code>tuple\[int, int\] | None</code>) – 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** (<code>str</code>) – The name of the model to use for calculating embeddings.
+- **batch_size** (<code>int</code>) – 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** (<code>bool</code>) – If `True`, shows a progress bar when running.
+- **config** (<code>dict\[str, Any\] | None</code>) – 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** (<code>float | None</code>) – The timeout in seconds for the underlying Google GenAI client network requests.
+- **max_retries** (<code>int | None</code>) – The maximum number of retries for the underlying Google GenAI client network requests.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAIMultimodalDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GoogleGenAIMultimodalDocumentEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]] | dict[str, Any]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – 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** (<code>list\[Document\]</code>) – A list of documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.embedders.google_genai.text_embedder
+
+### GoogleGenAITextEmbedder
+
+Embeds strings using Google AI models.
+
+You can use it to embed user query and send it to an embedding Retriever.
+
+### Authentication examples
+
+**1. Gemini Developer API (API Key Authentication)**
+
+````python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+text_embedder = GoogleGenAITextEmbedder(model="gemini-embedding-001")
+
+**2. Vertex AI (Application Default Credentials)**
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+# Using Application Default Credentials (requires gcloud auth setup)
+text_embedder = GoogleGenAITextEmbedder(
+    api="vertex",
+    vertex_ai_project="my-project",
+    vertex_ai_location="us-central1",
+    model="gemini-embedding-001"
+)
+````
+
+**3. Vertex AI (API Key Authentication)**
+
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+text_embedder = GoogleGenAITextEmbedder(
+    api="vertex",
+    model="gemini-embedding-001"
+)
+```
+
+### Usage example
+
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = GoogleGenAITextEmbedder()
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+# 'meta': {'model': 'gemini-embedding-001-v2',
+#          'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var(
+        ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
+    ),
+    api: Literal["gemini", "vertex"] = "gemini",
+    vertex_ai_project: str | None = None,
+    vertex_ai_location: str | None = None,
+    model: str = "gemini-embedding-001",
+    prefix: str = "",
+    suffix: str = "",
+    config: dict[str, Any] | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None
+) -> None
+```
+
+Creates an GoogleGenAITextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – 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** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+  Application Default Credentials.
+- **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+  Required when using Vertex AI with Application Default Credentials.
+- **model** (<code>str</code>) – The name of the model to use for calculating embeddings.
+  The default model is `gemini-embedding-001`.
+- **prefix** (<code>str</code>) – 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** (<code>str</code>) – A string to add at the end of each text to embed.
+- **config** (<code>dict\[str, Any\] | None</code>) – 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** (<code>float | None</code>) – The timeout in seconds for the underlying Google GenAI client network requests.
+- **max_retries** (<code>int | None</code>) – The maximum number of retries for the underlying Google GenAI client network requests.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAITextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GoogleGenAITextEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float]] | dict[str, Any]
+```
+
+Embeds a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\]\] | dict\[str, Any\]</code> – 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** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.generators.google_genai.chat.chat_generator
+
+### GoogleGenAIChatGenerator
+
+A component for generating chat completions using Google's Gemini models via the Google Gen AI SDK.
+
+Supports models like gemini-2.5-flash and other Gemini variants. For Gemini 2.5 series models,
+enables thinking features via `generation_kwargs={"thinking_budget": value}`.
+
+### Thinking Support (Gemini 2.5 Series)
+
+- **Reasoning transparency**: Models can show their reasoning process
+- **Thought signatures**: Maintains thought context across multi-turn conversations with tools
+- **Configurable thinking budgets**: Control token allocation for reasoning
+
+Configure thinking behavior:
+
+- `thinking_budget: -1`: Dynamic allocation (default)
+- `thinking_budget: 0`: Disable thinking (Flash/Flash-Lite only)
+- `thinking_budget: N`: Set explicit token budget
+
+### Multi-Turn Thinking with Thought Signatures
+
+Gemini uses **thought signatures** when tools are present - encrypted "save states" that maintain
+context across turns. Include previous assistant responses in chat history for context preservation.
+
+### Authentication
+
+**Gemini Developer API**: Set `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable
+**Vertex AI**: Use `api="vertex"` with Application Default Credentials or API key
+
+### Authentication Examples
+
+**1. Gemini Developer API (API Key Authentication)**
+
+```python
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+chat_generator = GoogleGenAIChatGenerator(model="gemini-2.5-flash")
+```
+
+**2. Vertex AI (Application Default Credentials)**
+
+```python
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# Using Application Default Credentials (requires gcloud auth setup)
+chat_generator = GoogleGenAIChatGenerator(
+    api="vertex",
+    vertex_ai_project="my-project",
+    vertex_ai_location="us-central1",
+    model="gemini-2.5-flash",
+)
+```
+
+**3. Vertex AI (API Key Authentication)**
+
+```python
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+chat_generator = GoogleGenAIChatGenerator(
+    api="vertex",
+    model="gemini-2.5-flash",
+)
+```
+
+### Usage example
+
+```python
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# Initialize the chat generator with thinking support
+chat_generator = GoogleGenAIChatGenerator(
+    model="gemini-2.5-flash",
+    generation_kwargs={"thinking_budget": 1024}  # Enable thinking with 1024 token budget
+)
+
+# Generate a response
+messages = [ChatMessage.from_user("Tell me about the future of AI")]
+response = chat_generator.run(messages=messages)
+print(response["replies"][0].text)
+
+# Access reasoning content if available
+message = response["replies"][0]
+if message.reasonings:
+    for reasoning in message.reasonings:
+        print("Reasoning:", reasoning.reasoning_text)
+
+# Tool usage example with thinking
+def weather_function(city: str):
+    return f"The weather in {city} is sunny and 25°C"
+
+weather_tool = Tool(
+    name="weather",
+    description="Get weather information for a city",
+    parameters={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
+    function=weather_function
+)
+
+# Can use either List[Tool] or Toolset
+chat_generator_with_tools = GoogleGenAIChatGenerator(
+    model="gemini-2.5-flash",
+    tools=[weather_tool],  # or tools=Toolset([weather_tool])
+    generation_kwargs={"thinking_budget": -1}  # Dynamic thinking allocation
+)
+
+messages = [ChatMessage.from_user("What's the weather in Paris?")]
+response = chat_generator_with_tools.run(messages=messages)
+```
+
+### Usage example with structured output
+
+```python
+from pydantic import BaseModel
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+class City(BaseModel):
+    name: str
+    country: str
+    population: int
+
+chat_generator = GoogleGenAIChatGenerator(
+    model="gemini-2.5-flash",
+    generation_kwargs={"response_format": City}
+)
+
+messages = [ChatMessage.from_user("Tell me about Paris")]
+response = chat_generator.run(messages=messages)
+print(response["replies"][0].text)  # JSON output matching the City schema
+```
+
+### Usage example with FileContent embedded in a ChatMessage
+
+```python
+from haystack.dataclasses import ChatMessage, FileContent
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+file_content = FileContent.from_url("https://arxiv.org/pdf/2309.08632")
+chat_message = ChatMessage.from_user(content_parts=[file_content, "Summarize this paper in 100 words."])
+chat_generator = GoogleGenAIChatGenerator()
+response = chat_generator.run(messages=[chat_message])
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "gemini-3.1-pro-preview",
+    "gemini-3-flash-preview",
+    "gemini-3.1-flash-lite-preview",
+    "gemini-2.5-pro",
+    "gemini-2.5-flash",
+    "gemini-2.5-flash-lite",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+
+See https://ai.google.dev/gemini-api/docs/models for the full list of models and up-to-date model IDs.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var(
+        ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
+    ),
+    api: Literal["gemini", "vertex"] = "gemini",
+    vertex_ai_project: str | None = None,
+    vertex_ai_location: str | None = None,
+    model: str = "gemini-2.5-flash",
+    generation_kwargs: dict[str, Any] | None = None,
+    safety_settings: list[dict[str, Any]] | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    tools: ToolsType | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None
+) -> None
+```
+
+Initialize a GoogleGenAIChatGenerator instance.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – 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** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+  Application Default Credentials.
+- **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+  Required when using Vertex AI with Application Default Credentials.
+- **model** (<code>str</code>) – Name of the model to use (e.g., "gemini-2.5-flash")
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>list\[dict\[str, Any\]\] | None</code>) – Safety settings for content filtering
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **tools** (<code>ToolsType | None</code>) – 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** (<code>float | None</code>) – Timeout for Google GenAI client calls. If not set, it defaults to the default set by the Google GenAI
+  client.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by
+  the Google GenAI client.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAIChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GoogleGenAIChatGenerator</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Configuration for generation. If provided, it will override
+  the default config. Supports `thinking_budget` for Gemini 2.5 series thinking configuration.
+- **safety_settings** (<code>list\[dict\[str, Any\]\] | None</code>) – Safety settings for content filtering. If provided, it will override the
+  default settings.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is
+  received from the stream.
+- **tools** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `replies`: A list containing the generated ChatMessage responses.
+
+**Raises:**
+
+- <code>RuntimeError</code> – If there is an error in the Google Gen AI chat generation.
+- <code>ValueError</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Configuration for generation. If provided, it will override
+  the default config. Supports `thinking_budget` for Gemini 2.5 series thinking configuration.
+  See https://ai.google.dev/gemini-api/docs/thinking for possible values.
+- **safety_settings** (<code>list\[dict\[str, Any\]\] | None</code>) – Safety settings for content filtering. If provided, it will override the
+  default settings.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is
+  received from the stream.
+- **tools** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `replies`: A list containing the generated ChatMessage responses.
+
+**Raises:**
+
+- <code>RuntimeError</code> – If there is an error in the async Google Gen AI chat generation.
+- <code>ValueError</code> – 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.

docs-website/reference/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** (<code>Literal['word', 'sentence', 'passage', 'page', 'line', 'period', 'function']</code>) – 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** (<code>int</code>) – The maximum number of units in each split.
+- **split_overlap** (<code>int</code>) – The number of overlapping units for each split.
+- **split_threshold** (<code>int</code>) – 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** (<code>bool</code>) – 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** (<code>Callable | None</code>) – 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** (<code>Literal['coarse', 'fine']</code>) – The granularity of Chinese word segmentation, either 'coarse' or 'fine'.
+
+**Raises:**
+
+- <code>ValueError</code> – 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** (<code>list\[Document\]</code>) – The documents to split.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary containing the split documents.
+
+**Raises:**
+
+- <code>RuntimeError</code> – 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** (<code>str</code>) – The text to split.
+
+**Returns:**
+
+- <code>list\[dict\[str, Any\]\]</code> – 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.

docs-website/reference/integrations-api/huggingface_api.md

@@ -0,0 +1,796 @@
+---
+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("<your-api-key>"))
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### With paid inference endpoints
+
+```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="inference_endpoints",
+                                              api_params={"url": "<your-inference-endpoint-url>"},
+                                              token=Secret.from_token("<your-api-key>"))
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### With self-hosted text embeddings inference
+
+```python
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder
+from haystack.dataclasses import Document
+
+doc = Document(content="I love pizza!")
+
+doc_embedder = HuggingFaceAPIDocumentEmbedder(api_type="text_embeddings_inference",
+                                              api_params={"url": "http://localhost:8080"})
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+    api_type: HFEmbeddingAPIType | str,
+    api_params: dict[str, str],
+    token: Secret | None = Secret.from_env_var(
+        ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+    ),
+    prefix: str = "",
+    suffix: str = "",
+    truncate: bool | None = True,
+    normalize: bool | None = False,
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    concurrency_limit: int = 4,
+) -> None
+```
+
+Creates a HuggingFaceAPIDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_type** (<code>HFEmbeddingAPIType | str</code>) – The type of Hugging Face API to use.
+- **api_params** (<code>dict\[str, str\]</code>) – 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** (<code>Secret | None</code>) – The Hugging Face token to use as HTTP bearer authorization.
+  Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **truncate** (<code>bool | None</code>) – 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** (<code>bool | None</code>) – 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** (<code>int</code>) – Number of documents to process at once.
+- **progress_bar** (<code>bool</code>) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the metadata fields to the document text.
+- **concurrency_limit** (<code>int</code>) – The maximum number of requests that should be allowed to run concurrently.
+  This parameter is only used in the `run_async` method.
+
+**Raises:**
+
+- <code>ValueError</code> – If the required `model` or `url` is missing from `api_params`, the `url` is invalid,
+  or the `api_type` is unknown.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPIDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>HuggingFaceAPIDocumentEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+
+**Raises:**
+
+- <code>TypeError</code> – If `documents` is not a list of Documents.
+- <code>ValueError</code> – 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** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+
+**Raises:**
+
+- <code>TypeError</code> – If `documents` is not a list of Documents.
+- <code>ValueError</code> – If the embeddings returned by the API have an unexpected shape.
+
+## 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("<your-api-key>"))
+
+print(text_embedder.run("I love pizza!"))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+```
+
+#### With paid inference endpoints
+
+```python
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder
+from haystack.utils import Secret
+text_embedder = HuggingFaceAPITextEmbedder(api_type="inference_endpoints",
+                                           api_params={"model": "BAAI/bge-small-en-v1.5"},
+                                           token=Secret.from_token("<your-api-key>"))
+
+print(text_embedder.run("I love pizza!"))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+```
+
+#### With self-hosted text embeddings inference
+
+```python
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder
+from haystack.utils import Secret
+
+text_embedder = HuggingFaceAPITextEmbedder(api_type="text_embeddings_inference",
+                                           api_params={"url": "http://localhost:8080"})
+
+print(text_embedder.run("I love pizza!"))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+```
+
+#### __init__
+
+```python
+__init__(
+    api_type: HFEmbeddingAPIType | str,
+    api_params: dict[str, str],
+    token: Secret | None = Secret.from_env_var(
+        ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+    ),
+    prefix: str = "",
+    suffix: str = "",
+    truncate: bool | None = True,
+    normalize: bool | None = False,
+) -> None
+```
+
+Creates a HuggingFaceAPITextEmbedder component.
+
+**Parameters:**
+
+- **api_type** (<code>HFEmbeddingAPIType | str</code>) – The type of Hugging Face API to use.
+- **api_params** (<code>dict\[str, str\]</code>) – 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** (<code>Secret | None</code>) – The Hugging Face token to use as HTTP bearer authorization.
+  Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **truncate** (<code>bool | None</code>) – 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** (<code>bool | None</code>) – 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:**
+
+- <code>ValueError</code> – If the required `model` or `url` is missing from `api_params`, the `url` is invalid,
+  or the `api_type` is unknown.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPITextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>HuggingFaceAPITextEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embeds a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+
+**Raises:**
+
+- <code>TypeError</code> – If `text` is not a string.
+- <code>ValueError</code> – 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** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+
+**Raises:**
+
+- <code>TypeError</code> – If `text` is not a string.
+- <code>ValueError</code> – 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/Qwen2.5-7B-Instruct",
+                                                    "provider": "together"},
+                                        token=Secret.from_token("<your-api-key>"))
+
+result = generator.run(messages)
+print(result)
+```
+
+#### With the serverless inference API (Inference Providers) and text+image input
+
+```python
+from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack.utils import Secret
+from haystack_integrations.common.huggingface_api.utils import HFGenerationAPIType
+
+# Create an image from file path, URL, or base64
+image = ImageContent.from_file_path("path/to/your/image.jpg")
+
+# Create a multimodal message with both text and image
+messages = [ChatMessage.from_user(content_parts=["Describe this image in detail", image])]
+
+generator = HuggingFaceAPIChatGenerator(
+    api_type=HFGenerationAPIType.SERVERLESS_INFERENCE_API,
+    api_params={
+        "model": "Qwen/Qwen2.5-VL-7B-Instruct",  # Vision Language Model
+        "provider": "hyperbolic"
+    },
+    token=Secret.from_token("<your-api-key>")
+)
+
+result = generator.run(messages)
+print(result)
+```
+
+#### With paid inference endpoints
+
+```python
+from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
+            ChatMessage.from_user("What's Natural Language Processing?")]
+
+generator = HuggingFaceAPIChatGenerator(api_type="inference_endpoints",
+                                        api_params={"url": "<your-inference-endpoint-url>"},
+                                        token=Secret.from_token("<your-api-key>"))
+
+result = generator.run(messages)
+print(result)
+```
+
+#### With self-hosted text generation inference
+
+```python
+from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
+            ChatMessage.from_user("What's Natural Language Processing?")]
+
+generator = HuggingFaceAPIChatGenerator(api_type="text_generation_inference",
+                                        api_params={"url": "http://localhost:8080"})
+
+result = generator.run(messages)
+print(result)
+```
+
+#### __init__
+
+```python
+__init__(
+    api_type: HFGenerationAPIType | str,
+    api_params: dict[str, str],
+    token: Secret | None = Secret.from_env_var(
+        ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+    ),
+    generation_kwargs: dict[str, Any] | None = None,
+    stop_words: list[str] | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    tools: ToolsType | None = None,
+) -> None
+```
+
+Initialize the HuggingFaceAPIChatGenerator instance.
+
+**Parameters:**
+
+- **api_type** (<code>HFGenerationAPIType | str</code>) – 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** (<code>dict\[str, str\]</code>) – 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** (<code>Secret | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>list\[str\] | None</code>) – An optional list of strings representing the stop words.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – An optional callable for handling streaming responses.
+- **tools** (<code>ToolsType | None</code>) – 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:**
+
+- <code>ValueError</code> – 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 will warm up the tools registered in the chat generator.
+This method is idempotent and will only warm up the tools once.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation.
+- **tools** (<code>ToolsType | None</code>) – 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** (<code>StreamingCallbackT | None</code>) – An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
+  parameter set during component initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `replies`: A list containing the generated responses as ChatMessage objects.
+
+**Raises:**
+
+- <code>ValueError</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation.
+- **tools** (<code>ToolsType | None</code>) – 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** (<code>StreamingCallbackT | None</code>) – An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
+  parameter set during component initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `replies`: A list containing the generated responses as ChatMessage objects.
+
+**Raises:**
+
+- <code>ValueError</code> – 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: <code>str</code>, <code>Enum</code>
+
+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** (<code>str</code>) – Base URL of the TEI reranking service (for example, "https://api.example.com").
+- **top_k** (<code>int</code>) – Maximum number of top documents to return.
+- **raw_scores** (<code>bool</code>) – If True, include raw relevance scores in the API payload.
+- **timeout** (<code>int | None</code>) – Request timeout in seconds.
+- **max_retries** (<code>int</code>) – Maximum number of retry attempts for failed requests.
+- **retry_status_codes** (<code>list\[int\] | None</code>) – List of HTTP status codes that will trigger a retry.
+  When None, HTTP 408, 418, 429 and 503 will be retried (default: None).
+- **token** (<code>Secret | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceTEIRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>HuggingFaceTEIRanker</code> – 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** (<code>str</code>) – The user query string to guide reranking.
+- **documents** (<code>list\[Document\]</code>) – List of `Document` objects to rerank.
+- **top_k** (<code>int | None</code>) – Optional override for the maximum number of documents to return.
+- **truncation_direction** (<code>TruncationDirection | None</code>) – If set, enables text truncation in the specified direction.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of reranked documents.
+
+**Raises:**
+
+- <code>RuntimeError</code> – - If the API request fails.
+- <code>RuntimeError</code> – - If the API returns an error response.
+- <code>TypeError</code> – - 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** (<code>str</code>) – The user query string to guide reranking.
+- **documents** (<code>list\[Document\]</code>) – List of `Document` objects to rerank.
+- **top_k** (<code>int | None</code>) – Optional override for the maximum number of documents to return.
+- **truncation_direction** (<code>TruncationDirection | None</code>) – If set, enables text truncation in the specified direction.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of reranked documents.
+
+**Raises:**
+
+- <code>httpx.RequestError</code> – - If the API request fails.
+- <code>RuntimeError</code> – - If the API returns an error response.
+- <code>TypeError</code> – - If the API response is not in the expected list format.

docs-website/reference/integrations-api/ibm_db.md

@@ -0,0 +1,374 @@
+---
+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** (<code>IBMDb2DocumentStore</code>) – An instance of `IBMDb2DocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>TypeError</code> – 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** (<code>list\[float\]</code>) – Dense float vector from an embedder component.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Runtime filters, merged with constructor filters according to filter_policy.
+- **top_k** (<code>int | None</code>) – Override the constructor top_k for this call.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with key `documents` containing a list of matching :class:`Document` objects.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> IBMDb2EmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>IBMDb2EmbeddingRetriever</code> – 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** (<code>str</code>) – Database name
+- **hostname** (<code>str</code>) – Database server hostname
+- **username** (<code>Secret</code>) – Database username as a `Secret`, e.g. `Secret.from_env_var("DB2_USERNAME")`.
+- **password** (<code>Secret</code>) – Database password as a `Secret`, e.g. `Secret.from_env_var("DB2_PASSWORD")`.
+- **port** (<code>int</code>) – Database server port (default: 50000)
+- **protocol** (<code>str</code>) – Connection protocol (default: "TCPIP")
+- **schema** (<code>str | None</code>) – Database schema (optional)
+- **use_ssl** (<code>bool</code>) – Enable SSL/TLS connection (default: False)
+- **ssl_certificate** (<code>str | None</code>) – Path to SSL certificate file (optional, required if use_ssl is True)
+- **connection_options** (<code>dict\[str, Any\] | None</code>) – Additional connection options as dict (optional)
+- **table_name** (<code>str</code>) – Name of the table to store documents (default: "haystack_documents")
+- **embedding_dim** (<code>int</code>) – Dimension of embedding vectors (default: 768)
+- **distance_metric** (<code>Literal['EUCLIDEAN', 'COSINE', 'MANHATTAN']</code>) – Distance metric for similarity search (default: "COSINE")
+- **recreate_table** (<code>bool</code>) – If True, drop and recreate the table (default: False)
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Count all documents in the store.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\] | None</code>) – Filters to apply. See Haystack documentation for filter syntax.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>list\[Document\]</code>) – List of documents to write
+- **policy** (<code>DuplicatePolicy</code>) – Policy for handling duplicate documents
+
+**Returns:**
+
+- <code>int</code> – Number of documents written
+
+**Raises:**
+
+- <code>ValueError</code> – If documents is not a list of Document objects or has invalid embeddings
+- <code>TypeError</code> – If embeddings have invalid types
+- <code>DuplicateDocumentError</code> – 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** (<code>dict\[str, Any\] | None</code>) – Optional filter dictionary to constrain the returned documents.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – List of matching documents.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents by their IDs.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Filters to apply. See Haystack documentation for filter syntax.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>bool</code>) – If True, recreate the table after deletion
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\] | None</code>) – Filters to apply. See Haystack documentation for filter syntax.
+- **meta** (<code>dict\[str, Any\] | None</code>) – Dictionary of metadata fields to update
+
+**Returns:**
+
+- <code>int</code> – Number of documents updated
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(field: str) -> list[Any]
+```
+
+Get all unique values for a given metadata field.
+
+**Parameters:**
+
+- **field** (<code>str</code>) – The metadata field name (can include 'meta.' prefix)
+
+**Returns:**
+
+- <code>list\[Any\]</code> – List of unique values for the field
+
+#### 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** (<code>str</code>) – The metadata field name (can include 'meta.' prefix)
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, Any\]\]</code> – 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** (<code>dict\[str, Any\] | None</code>) – Optional filters to apply before counting
+- **metadata_fields** (<code>list\[str\] | None</code>) – List of metadata field names to count unique values for
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary representation
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> IBMDb2DocumentStore
+```
+
+Deserialize the document store from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary representation
+
+**Returns:**
+
+- <code>IBMDb2DocumentStore</code> – IBMDb2DocumentStore instance

docs-website/reference/integrations-api/jina.md

@@ -0,0 +1,685 @@
+---
+title: "Jina"
+id: integrations-jina
+description: "Jina integration for Haystack"
+slug: "/integrations-jina"
+---
+
+
+## haystack_integrations.components.connectors.jina.reader
+
+### JinaReaderConnector
+
+A component that interacts with Jina AI's reader service to process queries and return documents.
+
+This component supports different modes of operation: `read`, `search`, and `ground`.
+
+Usage example:
+
+```python
+from haystack_integrations.components.connectors.jina import JinaReaderConnector
+
+reader = JinaReaderConnector(mode="read")
+query = "https://example.com"
+result = reader.run(query=query)
+document = result["documents"][0]
+print(document.content)
+
+>>> "This domain is for use in illustrative examples..."
+```
+
+#### __init__
+
+```python
+__init__(
+    mode: JinaReaderMode | str,
+    api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+    json_response: bool = True,
+) -> None
+```
+
+Initialize a JinaReader instance.
+
+**Parameters:**
+
+- **mode** (<code>JinaReaderMode | str</code>) – 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** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
+  environment variable JINA_API_KEY (recommended).
+- **json_response** (<code>bool</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaReaderConnector
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>JinaReaderConnector</code> – 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** (<code>str</code>) – The query string or URL to process.
+- **headers** (<code>dict\[str, str\] | None</code>) – Optional headers to include in the request for customization. Refer to the
+  [Jina Reader documentation](https://jina.ai/reader/) for more information.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>str</code>) – The query string or URL to process.
+- **headers** (<code>dict\[str, str\] | None</code>) – Optional headers to include in the request for customization. Refer to the
+  [Jina Reader documentation](https://jina.ai/reader/) for more information.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>Secret</code>) – The Jina API key.
+- **model** (<code>str</code>) – The name of the Jina model to use.
+  Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **batch_size** (<code>int</code>) – Number of Documents to encode at once.
+- **progress_bar** (<code>bool</code>) – 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** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
+- **task** (<code>str | None</code>) – 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** (<code>int | None</code>) – Number of desired dimension.
+  Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
+- **late_chunking** (<code>bool | None</code>) – 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** (<code>str</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>JinaDocumentEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, Any]
+```
+
+Compute the embeddings for a list of Documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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:**
+
+- <code>TypeError</code> – 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** (<code>list\[Document\]</code>) – A list of Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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:**
+
+- <code>TypeError</code> – 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** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
+  environment variable `JINA_API_KEY` (recommended).
+- **model** (<code>str</code>) – 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** (<code>str</code>) – The base URL of the Jina API.
+- **file_path_meta_field** (<code>str</code>) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (<code>str | None</code>) – 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** (<code>int | None</code>) – 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** (<code>tuple\[int, int\] | None</code>) – 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** (<code>int</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaDocumentImageEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>JinaDocumentImageEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of image documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
+  environment variable `JINA_API_KEY` (recommended).
+- **model** (<code>str</code>) – The name of the Jina model to use.
+  Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **task** (<code>str | None</code>) – 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** (<code>int | None</code>) – Number of desired dimension.
+  Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
+- **late_chunking** (<code>bool | None</code>) – 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** (<code>str</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>JinaTextEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embed a string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – The string to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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:**
+
+- <code>TypeError</code> – 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** (<code>str</code>) – The string to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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:**
+
+- <code>TypeError</code> – 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** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
+  environment variable JINA_API_KEY (recommended).
+- **model** (<code>str</code>) – The name of the Jina model to use. Check the list of available models on `https://jina.ai/reranker/`
+- **top_k** (<code>int | None</code>) – The maximum number of Documents to return per query. If `None`, all documents are returned
+- **score_threshold** (<code>float | None</code>) – If provided only returns documents with a score above this threshold.
+- **base_url** (<code>str</code>) – The base URL of the Jina API.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>JinaRanker</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query: str,
+    documents: list[Document],
+    top_k: int | None = None,
+    score_threshold: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Returns a list of Documents ranked by their similarity to the given query.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Query string.
+- **documents** (<code>list\[Document\]</code>) – List of Documents.
+- **top_k** (<code>int | None</code>) – The maximum number of Documents you want the Ranker to return.
+- **score_threshold** (<code>float | None</code>) – If provided only returns documents with a score above this threshold.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.
+
+#### run_async
+
+```python
+run_async(
+    query: str,
+    documents: list[Document],
+    top_k: int | None = None,
+    score_threshold: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously returns a list of Documents ranked by their similarity to the given query.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Query string.
+- **documents** (<code>list\[Document\]</code>) – List of Documents.
+- **top_k** (<code>int | None</code>) – The maximum number of Documents you want the Ranker to return.
+- **score_threshold** (<code>float | None</code>) – If provided only returns documents with a score above this threshold.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.

docs-website/reference/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** (<code>ExtractionConfig | None</code>) – 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** (<code>str | Path | None</code>) – Path to a kreuzberg configuration file (`.toml`, `.yaml`, or
+  `.json`). Cannot be used together with `config`.
+- **store_full_path** (<code>bool</code>) – If `True`, the full file path is stored in the Document metadata.
+  If `False`, only the file name is stored.
+- **batch** (<code>bool</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> KreuzbergConverter
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>KreuzbergConverter</code> – 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** (<code>list\[str | Path | ByteStream\]</code>) – 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** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following key:
+
+- `documents`: A list of created Documents.

docs-website/reference/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** (<code>list\[str\] | None</code>) – 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** (<code>list\[Document\]</code>) – A list of documents for language classification.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following key:
+- `documents`: A list of documents with an added `language` metadata field.
+
+**Raises:**
+
+- <code>TypeError</code> – 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** (<code>list\[str\] | None</code>) – 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** (<code>str</code>) – A text string to route.
+
+**Returns:**
+
+- <code>dict\[str, str\]</code> – A dictionary in which the key is the language (or `"unmatched"`),
+  and the value is the text.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.

docs-website/reference/integrations-api/langfuse.md

@@ -0,0 +1,495 @@
+---
+title: "langfuse"
+id: integrations-langfuse
+description: "Langfuse integration for Haystack"
+slug: "/integrations-langfuse"
+---
+
+
+## haystack_integrations.components.connectors.langfuse.langfuse_connector
+
+### LangfuseConnector
+
+LangfuseConnector connects Haystack LLM framework with [Langfuse](https://langfuse.com) in order to enable the
+
+tracing of operations and data flow within various components of a pipeline.
+
+To use LangfuseConnector, add it to your pipeline without connecting it to any other components.
+It will automatically trace all pipeline operations when tracing is enabled.
+
+**Environment Configuration:**
+
+- `LANGFUSE_SECRET_KEY` and `LANGFUSE_PUBLIC_KEY`: Required Langfuse API credentials.
+- `HAYSTACK_CONTENT_TRACING_ENABLED`: Must be set to `"true"` to enable tracing.
+- `HAYSTACK_LANGFUSE_ENFORCE_FLUSH`: (Optional) If set to `"false"`, disables flushing after each component.
+  Be cautious: this may cause data loss on crashes unless you manually flush before shutdown.
+  By default, the data is flushed after each component and blocks the thread until the data is sent to Langfuse.
+
+If you disable flushing after each component make sure you will call langfuse.flush() explicitly before the
+program exits. For example:
+
+```python
+from haystack.tracing import tracer
+
+try:
+    # your code here
+finally:
+    tracer.actual_tracer.flush()
+```
+
+or in FastAPI by defining a shutdown event handler:
+
+```python
+from haystack.tracing import tracer
+
+# ...
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    tracer.actual_tracer.flush()
+```
+
+Here is an example of how to use LangfuseConnector in a pipeline:
+
+```python
+import os
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.connectors.langfuse import (
+    LangfuseConnector,
+)
+
+pipe = Pipeline()
+pipe.add_component("tracer", LangfuseConnector("Chat example"))
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+messages = [
+    ChatMessage.from_system(
+        "Always respond in German even if some input data is in other languages."
+    ),
+    ChatMessage.from_user("Tell me about {{location}}"),
+]
+
+response = pipe.run(
+    data={
+        "prompt_builder": {
+            "template_variables": {"location": "Berlin"},
+            "template": messages,
+        }
+    }
+)
+print(response["llm"]["replies"][0])
+print(response["tracer"]["trace_url"])
+print(response["tracer"]["trace_id"])
+```
+
+For advanced use cases, you can also customize how spans are created and processed by providing a custom
+SpanHandler. This allows you to add custom metrics, set warning levels, or attach additional metadata to your
+Langfuse traces:
+
+```python
+from haystack_integrations.tracing.langfuse import DefaultSpanHandler, LangfuseSpan
+from typing import Optional
+
+class CustomSpanHandler(DefaultSpanHandler):
+
+    def handle(self, span: LangfuseSpan, component_type: Optional[str]) -> None:
+        # Custom span handling logic, customize Langfuse spans however it fits you
+        # see DefaultSpanHandler for how we create and process spans by default
+        pass
+
+connector = LangfuseConnector(span_handler=CustomSpanHandler())
+```
+
+#### __init__
+
+```python
+__init__(
+    name: str,
+    public: bool = False,
+    public_key: Secret | None = Secret.from_env_var("LANGFUSE_PUBLIC_KEY"),
+    secret_key: Secret | None = Secret.from_env_var("LANGFUSE_SECRET_KEY"),
+    httpx_client: httpx.Client | None = None,
+    span_handler: SpanHandler | None = None,
+    *,
+    host: str | None = None,
+    langfuse_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Initialize the LangfuseConnector component.
+
+**Parameters:**
+
+- **name** (<code>str</code>) – The name for the trace. This name will be used to identify the tracing run in the Langfuse
+  dashboard.
+- **public** (<code>bool</code>) – 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** (<code>Secret | None</code>) – The Langfuse public key. Defaults to reading from LANGFUSE_PUBLIC_KEY environment variable.
+- **secret_key** (<code>Secret | None</code>) – The Langfuse secret key. Defaults to reading from LANGFUSE_SECRET_KEY environment variable.
+- **httpx_client** (<code>Client | None</code>) – 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** (<code>SpanHandler | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Optional custom configuration for the Langfuse client. This is a dictionary
+  containing any additional configuration options for the Langfuse client. See the Langfuse documentation
+  for more details on available configuration options.
+
+#### run
+
+```python
+run(invocation_context: dict[str, Any] | None = None) -> dict[str, str]
+```
+
+Runs the LangfuseConnector component.
+
+**Parameters:**
+
+- **invocation_context** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, str\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LangfuseConnector
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>LangfuseConnector</code> – The deserialized component instance.
+
+## haystack_integrations.tracing.langfuse.tracer
+
+### LangfuseSpan
+
+Bases: <code>Span</code>
+
+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** (<code>AbstractContextManager</code>) – 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** (<code>str</code>) – The tag key.
+- **value** (<code>Any</code>) – 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** (<code>str</code>) – The content tag key.
+- **value** (<code>Any</code>) – The content tag value.
+
+#### raw_span
+
+```python
+raw_span() -> LangfuseClientSpan
+```
+
+Return the underlying span instance.
+
+**Returns:**
+
+- <code>LangfuseSpan</code> – The Langfuse span instance.
+
+#### get_data
+
+```python
+get_data() -> dict[str, Any]
+```
+
+Return the data associated with the span.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – The name of the span to create. For components, this is typically the component name.
+- **operation_name** (<code>str</code>) – The operation being traced (e.g. "haystack.pipeline.run"). Used to determine
+  if a new trace should be created without warning.
+- **component_type** (<code>str | None</code>) – The type of component creating the span (e.g. "OpenAIChatGenerator").
+  Can be used to determine the type of span to create.
+- **tags** (<code>dict\[str, Any\]</code>) – Additional metadata to attach to the span. Contains component input/output data
+  and other trace information.
+- **parent_span** (<code>Span | None</code>) – The parent span if this is a child span. If None, a new trace will be created.
+- **trace_name** (<code>str</code>) – The name to use for the trace when creating a parent span. Defaults to "Haystack".
+- **public** (<code>bool</code>) – Whether traces should be publicly accessible. Defaults to False.
+
+### SpanHandler
+
+Bases: <code>ABC</code>
+
+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** (<code>Langfuse</code>) – 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** (<code>SpanContext</code>) – The context containing all information needed to create the span
+
+**Returns:**
+
+- <code>LangfuseSpan</code> – 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** (<code>LangfuseSpan</code>) – The span that was yielded by the component
+- **component_type** (<code>str | None</code>) – 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: <code>SpanHandler</code>
+
+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: <code>Tracer</code>
+
+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** (<code>Langfuse</code>) – The Langfuse tracer instance.
+- **name** (<code>str</code>) – The name of the pipeline or component. This name will be used to identify the tracing run on the
+  Langfuse dashboard.
+- **public** (<code>bool</code>) – 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** (<code>SpanHandler | None</code>) – 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:**
+
+- <code>Span | None</code> – The current span if available, else None.
+
+#### get_trace_url
+
+```python
+get_trace_url() -> str
+```
+
+Return the URL to the tracing data.
+
+**Returns:**
+
+- <code>str</code> – The URL to the tracing data.
+
+#### get_trace_id
+
+```python
+get_trace_id() -> str
+```
+
+Return the trace ID.
+
+**Returns:**
+
+- <code>str</code> – The trace ID.

docs-website/reference/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** (<code>Secret</code>) – Lara API access key ID. Defaults to the `LARA_ACCESS_KEY_ID` environment variable.
+- **access_key_secret** (<code>Secret</code>) – Lara API access key secret. Defaults to the `LARA_ACCESS_KEY_SECRET` environment variable.
+- **source_lang** (<code>str | None</code>) – 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** (<code>str | None</code>) – Language code of the target text.
+  Use locale codes from the
+  [supported languages list](https://developers.laratranslate.com/docs/supported-languages).
+- **context** (<code>str | None</code>) – 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** (<code>str | None</code>) – 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** (<code>Literal['faithful', 'fluid', 'creative']</code>) – 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** (<code>list\[str\] | None</code>) – 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** (<code>list\[str\] | None</code>) – 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** (<code>bool</code>) – 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** (<code>list\[Document\]</code>) – List of Haystack Documents whose `content` is to be translated.
+- **source_lang** (<code>str | list\[str | None\] | None</code>) – 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** (<code>str | list\[str\] | None</code>) – 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** (<code>str | list\[str\] | None</code>) – 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** (<code>str | list\[str\] | None</code>) – 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** (<code>str | list\[str\] | None</code>) – 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** (<code>list\[str\] | list\[list\[str\]\] | None</code>) – 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** (<code>list\[str\] | list\[list\[str\]\] | None</code>) – 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** (<code>bool | list\[bool\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of translated documents.
+
+**Raises:**
+
+- <code>ValueError</code> – If any list-valued parameter has length != `len(documents)`.

docs-website/reference/integrations-api/libreoffice.md

@@ -0,0 +1,194 @@
+---
+title: "LibreOffice"
+id: integrations-libreoffice
+description: "LibreOffice integration for Haystack"
+slug: "/integrations-libreoffice"
+---
+
+
+## haystack_integrations.components.converters.libreoffice.converter
+
+### LibreOfficeFileConverter
+
+Component that uses libreoffice's command line utility (soffice) to convert files into various formats.
+
+### Usage examples
+
+**Simple conversion:**
+
+```python
+from pathlib import Path
+
+from haystack_integrations.components.converters.libreoffice import LibreOfficeFileConverter
+
+# Convert documents
+converter = LibreOfficeFileConverter()
+results = converter.run(sources=[Path("sample.doc")], output_file_type="docx")
+print(results["output"])  # [ByteStream(data=b'...', meta={}, mime_type=None)]
+```
+
+**Conversion pipeline:**
+
+```python
+from pathlib import Path
+
+from haystack import Pipeline
+from haystack.components.converters import DOCXToDocument
+
+from haystack_integrations.components.converters.libreoffice import LibreOfficeFileConverter
+
+# Create pipeline with components
+pipeline = Pipeline()
+pipeline.add_component("libreoffice_converter", LibreOfficeFileConverter())
+pipeline.add_component("docx_converter", DOCXToDocument())
+
+pipeline.connect("libreoffice_converter.output", "docx_converter.sources")
+
+# Run pipeline and convert legacy documents into Haystack documents
+results = pipeline.run(
+    {
+        "libreoffice_converter": {
+            "sources": [Path("sample_doc.doc")],
+            "output_file_type": "docx",
+        }
+    }
+)
+print(results["docx_converter"]["documents"])
+```
+
+#### SUPPORTED_TYPES
+
+```python
+SUPPORTED_TYPES: dict[str, frozenset[str]] = {
+    "doc": frozenset(["pdf", "docx", "odt", "rtf", "txt", "html", "epub"]),
+    "docx": frozenset(["pdf", "doc", "odt", "rtf", "txt", "html", "epub"]),
+    "odt": frozenset(["pdf", "docx", "doc", "rtf", "txt", "html", "epub"]),
+    "rtf": frozenset(["pdf", "docx", "doc", "odt", "txt", "html"]),
+    "txt": frozenset(["pdf", "docx", "doc", "odt", "rtf", "html"]),
+    "html": frozenset(["pdf", "docx", "doc", "odt", "rtf", "txt"]),
+    "xlsx": frozenset(["pdf", "xls", "ods", "csv", "html"]),
+    "xls": frozenset(["pdf", "xlsx", "ods", "csv", "html"]),
+    "ods": frozenset(["pdf", "xlsx", "xls", "csv", "html"]),
+    "csv": frozenset(["pdf", "xlsx", "xls", "ods"]),
+    "pptx": frozenset(["pdf", "ppt", "odp", "html", "png", "jpg"]),
+    "ppt": frozenset(["pdf", "pptx", "odp", "html", "png", "jpg"]),
+    "odp": frozenset(["pdf", "pptx", "ppt", "html", "png", "jpg"]),
+}
+
+```
+
+A non-exhaustive mapping of supported conversion types by this component.
+See https://help.libreoffice.org/latest/en-GB/text/shared/guide/convertfilters.html for more information.
+
+#### __init__
+
+```python
+__init__(output_file_type: OUTPUT_FILE_TYPE | None = None) -> None
+```
+
+Check whether soffice is installed.
+
+**Parameters:**
+
+- **output_file_type** (<code>OUTPUT_FILE_TYPE | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Self
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>Self</code> – 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** (<code>Iterable\[str | Path | ByteStream\]</code>) – 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** (<code>OUTPUT_FILE_TYPE | None</code>) – 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:**
+
+- <code>LibreOfficeFileConverterOutput</code> – A dictionary with the following key:
+- `output`: List of `ByteStream` objects containing the converted file
+  data, in the same order as `sources`.
+
+**Raises:**
+
+- <code>FileNotFoundError</code> – If a source file path does not exist.
+- <code>OSError</code> – If the internal temporary output directory is not writable.
+- <code>ValueError</code> – If a source's file type is not in :attr:`SUPPORTED_TYPES`,
+  or if `output_file_type` is not a valid conversion target for it,
+  or if `output_file_type` has not been provided anywhere.
+
+#### run_async
+
+```python
+run_async(
+    sources: Iterable[str | Path | ByteStream],
+    output_file_type: OUTPUT_FILE_TYPE | None = None,
+) -> LibreOfficeFileConverterOutput
+```
+
+Asynchronously convert office files to the specified output format using LibreOffice.
+
+This is the asynchronous version of the `run` method with the same parameters and return values.
+
+**Parameters:**
+
+- **sources** (<code>Iterable\[str | Path | ByteStream\]</code>) – 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** (<code>OUTPUT_FILE_TYPE | None</code>) – 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:**
+
+- <code>LibreOfficeFileConverterOutput</code> – A dictionary with the following key:
+- `output`: List of `ByteStream` objects containing the converted file
+  data, in the same order as `sources`.
+
+**Raises:**
+
+- <code>FileNotFoundError</code> – If a source file path does not exist.
+- <code>OSError</code> – If the internal temporary output directory is not writable.
+- <code>ValueError</code> – 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.

docs-website/reference/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** (<code>Secret | None</code>) – 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** (<code>str</code>) – The model name in LiteLLM format (provider/model-name).
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function invoked with each new StreamingChunk.
+- **api_base_url** (<code>str | None</code>) – Custom API base URL (e.g. for a self-hosted LiteLLM proxy).
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional parameters passed to litellm.completion().
+  See https://docs.litellm.ai/docs/completion/input for details.
+- **tools** (<code>ToolsType | None</code>) – 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** (<code>list\[ChatMessage\] | str</code>) – Input messages as ChatMessage instances.
+  If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – Override the streaming callback for this call.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Override generation parameters for this call.
+- **tools** (<code>ToolsType | None</code>) – Override tools for this call.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>list\[ChatMessage\] | str</code>) – Input messages as ChatMessage instances.
+  If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – Override the streaming callback for this call.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Override generation parameters for this call.
+- **tools** (<code>ToolsType | None</code>) – Override tools for this call.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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.

docs-website/reference/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=<ChatRole.ASSISTANT: "assistant">, name=None, meta={...})}
+```
+
+Usage example with multimodal (image + text):
+
+```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])]
+
+# Initialize with multimodal support
+generator = LlamaCppChatGenerator(
+    model="llava-v1.5-7b-q4_0.gguf",
+    chat_handler_name="Llava15ChatHandler",  # Use llava-1-5 handler
+    model_clip_path="mmproj-model-f16.gguf",  # CLIP model
+    n_ctx=4096  # Larger context for image processing
+)
+
+result = generator.run(messages)
+print(result)
+```
+
+#### __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,
+    *,
+    tools: ToolsType | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    chat_handler_name: str | None = None,
+    model_clip_path: str | None = None
+) -> None
+```
+
+Initialize LlamaCppChatGenerator.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – 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** (<code>int | None</code>) – The number of tokens in the context. When set to 0, the context will be taken from the model.
+- **n_batch** (<code>int | None</code>) – Prompt processing maximum batch size.
+- **model_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **chat_handler_name** (<code>str | None</code>) – 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** (<code>str | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LlamaCppChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>LlamaCppChatGenerator</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>StreamingCallbackT | None</code>) – 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:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>StreamingCallbackT | None</code>) – 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:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>str</code>) – 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** (<code>int | None</code>) – The number of tokens in the context. When set to 0, the context will be taken from the model.
+- **n_batch** (<code>int | None</code>) – Prompt processing maximum batch size.
+- **model_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>str</code>) – the prompt to be sent to the generative model.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[str\] | list\[dict\[str, Any\]\]\]</code> – A dictionary with the following keys:
+- `replies`: the list of replies generated by the model.
+- `meta`: metadata about the request.

docs-website/reference/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"
+---
+
+<a id="haystack_integrations.components.generators.llama_stack.chat.chat_generator"></a>
+
+## Module haystack\_integrations.components.generators.llama\_stack.chat.chat\_generator
+
+<a id="haystack_integrations.components.generators.llama_stack.chat.chat_generator.LlamaStackChatGenerator"></a>
+
+### 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=<ChatRole.ASSISTANT: 'assistant'>, _name=None,
+>>_meta={'model': 'ollama/llama3.2:3b', 'index': 0, 'finish_reason': 'stop',
+>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]}
+
+<a id="haystack_integrations.components.generators.llama_stack.chat.chat_generator.LlamaStackChatGenerator.__init__"></a>
+
+#### LlamaStackChatGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+             model: str,
+             api_base_url: str = "http://localhost:8321/v1",
+             organization: str | None = None,
+             streaming_callback: StreamingCallbackT | None = None,
+             generation_kwargs: dict[str, Any] | None = None,
+             timeout: int | None = None,
+             tools: ToolsType | None = None,
+             tools_strict: bool = False,
+             max_retries: int | None = None,
+             http_client_kwargs: dict[str, Any] | None = None)
+```
+
+Creates an instance of LlamaStackChatGenerator. To use this chat generator,
+
+you need to setup Llama Stack Server with an inference provider and have a model available.
+
+**Arguments**:
+
+- `model`: The name of the model to use for chat completion.
+This depends on the inference provider used for the Llama Stack Server.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+The callback function accepts StreamingChunk as an argument.
+- `api_base_url`: The Llama Stack API base url. If not specified, the localhost is used with the default port 8321.
+- `organization`: Your organization ID, defaults to `None`.
+- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to
+the Llama Stack endpoint. See [Llama Stack API docs](https://llama-stack.readthedocs.io/) 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.
+- `timeout`: Timeout for client calls using OpenAI API. If not set, it defaults to either the
+`OPENAI_TIMEOUT` environment variable, or 30 seconds.
+- `tools`: 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.
+- `tools_strict`: 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.
+- `max_retries`: 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`: 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`).
+
+<a id="haystack_integrations.components.generators.llama_stack.chat.chat_generator.LlamaStackChatGenerator.to_dict"></a>
+
+#### LlamaStackChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns**:
+
+The serialized component as a dictionary.
+
+<a id="haystack_integrations.components.generators.llama_stack.chat.chat_generator.LlamaStackChatGenerator.from_dict"></a>
+
+#### LlamaStackChatGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "LlamaStackChatGenerator"
+```
+
+Deserialize this component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary representation of this component.
+
+**Returns**:
+
+The deserialized component instance.
+

docs-website/reference/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** (<code>bool</code>) – 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** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths or ByteStream objects to convert.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with key `documents` containing the converted Documents.

docs-website/reference/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** (<code>Coroutine\[Any, Any, Any\]</code>) – Coroutine to execute
+- **timeout** (<code>float | None</code>) – Optional timeout in seconds
+
+**Returns:**
+
+- <code>Any</code> – Result of the coroutine
+
+**Raises:**
+
+- <code>TimeoutError</code> – If execution exceeds timeout
+
+#### get_loop
+
+```python
+get_loop() -> asyncio.AbstractEventLoop
+```
+
+Get the event loop.
+
+**Returns:**
+
+- <code>AbstractEventLoop</code> – 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** (<code>Callable\\[[Event\], Coroutine\[Any, Any, Any\]\]</code>) – A callable receiving the stop_event and returning the coroutine to execute.
+- **timeout** (<code>float | None</code>) – Optional timeout while waiting for the stop_event to be created.
+
+**Returns:**
+
+- <code>tuple\[Future\[Any\], Event\]</code> – Tuple `(future, stop_event)`.
+
+#### shutdown
+
+```python
+shutdown(timeout: float = 2) -> None
+```
+
+Shut down the background event loop and thread.
+
+**Parameters:**
+
+- **timeout** (<code>float</code>) – Timeout in seconds for shutting down the event loop
+
+### MCPError
+
+Bases: <code>Exception</code>
+
+Base class for MCP-related errors.
+
+#### __init__
+
+```python
+__init__(message: str) -> None
+```
+
+Initialize the MCPError.
+
+**Parameters:**
+
+- **message** (<code>str</code>) – Descriptive error message
+
+### MCPConnectionError
+
+Bases: <code>MCPError</code>
+
+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** (<code>str</code>) – Descriptive error message
+- **server_info** (<code>MCPServerInfo | None</code>) – Server connection information that was used
+- **operation** (<code>str | None</code>) – Name of the operation that was being attempted
+
+### MCPToolNotFoundError
+
+Bases: <code>MCPError</code>
+
+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** (<code>str</code>) – Descriptive error message
+- **tool_name** (<code>str</code>) – Name of the tool that was requested but not found
+- **available_tools** (<code>list\[str\] | None</code>) – List of available tool names, if known
+
+### MCPInvocationError
+
+Bases: <code>ToolInvocationError</code>
+
+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** (<code>str</code>) – Descriptive error message
+- **tool_name** (<code>str</code>) – Name of the tool that was being invoked
+- **tool_args** (<code>dict\[str, Any\] | None</code>) – Arguments that were passed to the tool
+
+### MCPClient
+
+Bases: <code>ABC</code>
+
+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:**
+
+- <code>list\[Tool\]</code> – List of available tools on the server
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – 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** (<code>str</code>) – Name of the tool to call
+- **tool_args** (<code>dict\[str, Any\]</code>) – Arguments to pass to the tool
+
+**Returns:**
+
+- <code>str</code> – JSON string representation of the tool invocation result
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – If not connected to an MCP server
+- <code>MCPInvocationError</code> – 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: <code>MCPClient</code>
+
+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** (<code>str</code>) – Command to run (e.g., "python", "node")
+- **args** (<code>list\[str\] | None</code>) – Arguments to pass to the command
+- **env** (<code>dict\[str, str | Secret\] | None</code>) – Environment variables for the command
+- **max_retries** (<code>int</code>) – Maximum number of reconnection attempts
+- **base_delay** (<code>float</code>) – Base delay for exponential backoff in seconds
+
+#### connect
+
+```python
+connect() -> list[types.Tool]
+```
+
+Connect to an MCP server using stdio transport.
+
+**Returns:**
+
+- <code>list\[Tool\]</code> – List of available tools on the server
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – If connection to the server fails
+
+### SSEClient
+
+Bases: <code>MCPClient</code>
+
+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** (<code>SSEServerInfo</code>) – Configuration object containing URL, token, timeout, etc.
+- **max_retries** (<code>int</code>) – Maximum number of reconnection attempts
+- **base_delay** (<code>float</code>) – 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:**
+
+- <code>list\[Tool\]</code> – List of available tools on the server
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – If connection to the server fails
+
+### StreamableHttpClient
+
+Bases: <code>MCPClient</code>
+
+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** (<code>StreamableHttpServerInfo</code>) – Configuration object containing URL, token, timeout, etc.
+- **max_retries** (<code>int</code>) – Maximum number of reconnection attempts
+- **base_delay** (<code>float</code>) – 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:**
+
+- <code>list\[Tool\]</code> – List of available tools on the server
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – If connection to the server fails
+
+### MCPServerInfo
+
+Bases: <code>ABC</code>
+
+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:**
+
+- <code>MCPClient</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary representation of this server info
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MCPServerInfo
+```
+
+Deserialize server info from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary containing serialized server info
+
+**Returns:**
+
+- <code>MCPServerInfo</code> – Instance of the appropriate server info class
+
+### SSEServerInfo
+
+Bases: <code>MCPServerInfo</code>
+
+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** (<code>str | None</code>) – Full URL of the MCP server (including /sse endpoint)
+- **base_url** (<code>str | None</code>) – Base URL of the MCP server (deprecated, use url instead)
+- **token** (<code>str | Secret | None</code>) – Authentication token for the server (optional, generates "Authorization: Bearer `<token>`" header)
+- **headers** (<code>dict\[str, str | Secret\] | None</code>) – Custom HTTP headers (optional, takes precedence over token parameter if provided)
+- **timeout** (<code>int</code>) – Connection timeout in seconds
+
+#### create_client
+
+```python
+create_client() -> MCPClient
+```
+
+Create an SSE MCP client.
+
+**Returns:**
+
+- <code>MCPClient</code> – Configured MCPClient instance
+
+### StreamableHttpServerInfo
+
+Bases: <code>MCPServerInfo</code>
+
+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** (<code>str</code>) – Full URL of the MCP server (streamable HTTP endpoint)
+- **token** (<code>str | Secret | None</code>) – Authentication token for the server (optional, generates "Authorization: Bearer `<token>`" header)
+- **headers** (<code>dict\[str, str | Secret\] | None</code>) – Custom HTTP headers (optional, takes precedence over token parameter if provided)
+- **timeout** (<code>int</code>) – Connection timeout in seconds
+
+#### create_client
+
+```python
+create_client() -> MCPClient
+```
+
+Create a streamable HTTP MCP client.
+
+**Returns:**
+
+- <code>MCPClient</code> – Configured StreamableHttpClient instance
+
+### StdioServerInfo
+
+Bases: <code>MCPServerInfo</code>
+
+Data class that encapsulates stdio MCP server connection parameters.
+
+**Parameters:**
+
+- **command** (<code>str</code>) – Command to run (e.g., "python", "node")
+- **args** (<code>list\[str\] | None</code>) – Arguments to pass to the command
+- **env** (<code>dict\[str, str | Secret\] | None</code>) – 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:**
+
+- <code>MCPClient</code> – Configured StdioMCPClient instance
+
+### MCPTool
+
+Bases: <code>Tool</code>
+
+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** (<code>str</code>) – Name of the tool to use
+- **server_info** (<code>MCPServerInfo</code>) – Server connection information
+- **description** (<code>str | None</code>) – Custom description (if None, server description will be used)
+- **connection_timeout** (<code>int</code>) – Timeout in seconds for server connection
+- **invocation_timeout** (<code>int</code>) – Default timeout in seconds for tool invocations
+- **eager_connect** (<code>bool</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>dict\[str, str\] | None</code>) – Optional dictionary mapping state keys to tool parameter names.
+  Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- **outputs_to_state** (<code>dict\[str, dict\[str, Any\]\] | None</code>) – 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:**
+
+- <code>MCPConnectionError</code> – If connection to the server fails
+- <code>MCPToolNotFoundError</code> – If no tools are available or the requested tool is not found
+- <code>TimeoutError</code> – If connection times out
+
+#### ainvoke
+
+```python
+ainvoke(**kwargs: Any) -> str | dict[str, Any]
+```
+
+Asynchronous tool invocation.
+
+**Parameters:**
+
+- **kwargs** (<code>Any</code>) – Arguments to pass to the tool
+
+**Returns:**
+
+- <code>str | dict\[str, Any\]</code> – JSON string or dictionary representation of the tool invocation result.
+  Returns a dictionary when outputs_to_state is configured to enable state updates.
+
+**Raises:**
+
+- <code>MCPInvocationError</code> – If the tool invocation fails
+- <code>TimeoutError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>dict\[str, Any\]</code>) – Dictionary containing serialized tool data
+
+**Returns:**
+
+- <code>Tool</code> – A fully initialized MCPTool instance
+
+**Raises:**
+
+- <code>Exception</code> – if connection fails
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the tool synchronously.
+
+## haystack_integrations.tools.mcp.mcp_toolset
+
+### MCPToolset
+
+Bases: <code>Toolset</code>
+
+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** (<code>MCPServerInfo</code>) – Connection information for the MCP server
+- **tool_names** (<code>list\[str\] | None</code>) – Optional list of tool names to include. If provided, only tools with
+  matching names will be added to the toolset.
+- **connection_timeout** (<code>float</code>) – Timeout in seconds for server connection
+- **invocation_timeout** (<code>float</code>) – Default timeout in seconds for tool invocations
+- **eager_connect** (<code>bool</code>) – If True, connect to server and load tools during initialization.
+  If False (default), defer connection to warm_up.
+- **inputs_from_state** (<code>dict\[str, dict\[str, str\]\] | None</code>) – 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** (<code>dict\[str, dict\[str, dict\[str, Any\]\]\] | None</code>) – 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** (<code>dict\[str, dict\[str, Any\]\] | None</code>) – 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:**
+
+- <code>MCPToolNotFoundError</code> – If any of the specified tool names are not found on the server
+- <code>ValueError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – A dictionary representation of the MCPToolset
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MCPToolset
+```
+
+Deserialize an MCPToolset from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary representation of the MCPToolset
+
+**Returns:**
+
+- <code>MCPToolset</code> – A new MCPToolset instance
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the underlying MCP client safely.

docs-website/reference/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** (<code>Mem0MemoryStore</code>) – The Mem0MemoryStore instance to retrieve memories from.
+- **top_k** (<code>int</code>) – 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** (<code>str | None</code>) – Text query used to search for relevant memories. Pass `None` to retrieve all memories matching
+  the scope.
+- **user_id** (<code>str | None</code>) – User ID to scope the search.
+- **run_id** (<code>str | None</code>) – Run ID to scope the search.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope the search.
+- **app_id** (<code>str | None</code>) – App ID to scope the search.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of memories to return. Overrides the init-time default.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>Mem0MemoryStore</code>) – The Mem0MemoryStore instance to write memories to.
+- **infer** (<code>bool</code>) – 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** (<code>list\[ChatMessage\]</code>) – List of ChatMessage objects to store.
+- **user_id** (<code>str | None</code>) – User ID to scope the stored memories.
+- **run_id** (<code>str | None</code>) – Run ID to scope the stored memories.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope the stored memories.
+- **app_id** (<code>str | None</code>) – App ID to scope the stored memories.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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: <code>RuntimeError</code>
+
+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** (<code>Secret</code>) – 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** (<code>list\[ChatMessage\]</code>) – List of ChatMessage objects to store as memories.
+- **user_id** (<code>str | None</code>) – User ID to scope these memories.
+- **run_id** (<code>str | None</code>) – Run ID to scope these memories.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope these memories. Required for Mem0 to store assistant messages.
+- **app_id** (<code>str | None</code>) – App ID to scope these memories.
+- **infer** (<code>bool</code>) – If True, Mem0 extracts memories from messages. If False, Mem0 stores message text as-is.
+- **kwargs** (<code>Any</code>) – 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:**
+
+- <code>list\[dict\[str, Any\]\]</code> – List of objects with `memory_id` and `memory` text for each stored memory.
+
+**Raises:**
+
+- <code>Mem0MemoryStoreError</code> – 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** (<code>str | None</code>) – Text query to search. If omitted, returns all memories matching the scope.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – Maximum number of results to return.
+- **user_id** (<code>str | None</code>) – User ID to scope the search.
+- **run_id** (<code>str | None</code>) – Run ID to scope the search.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope the search.
+- **app_id** (<code>str | None</code>) – App ID to scope the search.
+- **kwargs** (<code>Any</code>) – Additional keyword arguments forwarded to the Mem0 client.
+
+**Returns:**
+
+- <code>list\[ChatMessage\]</code> – 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:**
+
+- <code>Mem0MemoryStoreError</code> – If the Mem0 API call fails.
+
+## haystack_integrations.tools.mem0.retriever_tool
+
+### Mem0MemoryRetrieverTool
+
+Bases: <code>Tool</code>
+
+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** (<code>Mem0MemoryStore</code>) – The Mem0MemoryStore instance to query.
+- **top_k** (<code>int</code>) – Default maximum number of memories to return. The LLM may override this.
+- **name** (<code>str</code>) – Tool name exposed to the LLM.
+- **description** (<code>str</code>) – Tool description exposed to the LLM.
+- **parameters** (<code>dict\[str, Any\]</code>) – JSON schema for the parameters exposed to the LLM. Defaults to optional `query` and `top_k`.
+- **inputs_from_state** (<code>dict\[str, str\]</code>) – 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** (<code>str | None</code>) – Text query used to search for relevant memories. If omitted or `None`, all memories matching
+  the scope are returned.
+- **top_k** (<code>int | None</code>) – Maximum number of memories to return for query searches. Overrides the tool default.
+- **user_id** (<code>str | None</code>) – User ID to scope the search. Injected from Agent State by default.
+- **run_id** (<code>str | None</code>) – Run ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+- **app_id** (<code>str | None</code>) – App ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+
+**Returns:**
+
+- <code>str</code> – 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: <code>Tool</code>
+
+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** (<code>Mem0MemoryStore</code>) – The Mem0MemoryStore instance to write to.
+- **name** (<code>str</code>) – Tool name exposed to the LLM.
+- **description** (<code>str</code>) – Tool description exposed to the LLM.
+- **parameters** (<code>dict\[str, Any\]</code>) – JSON schema for the parameters exposed to the LLM. Defaults to `text` and `infer`.
+- **inputs_from_state** (<code>dict\[str, str\]</code>) – 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** (<code>str</code>) – The information to store as a memory.
+- **infer** (<code>bool</code>) – If True, Mem0 extracts memories from the text. If False, Mem0 stores the text as-is.
+- **user_id** (<code>str | None</code>) – User ID to scope the stored memory. Injected from Agent State by default.
+- **run_id** (<code>str | None</code>) – Run ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+- **app_id** (<code>str | None</code>) – App ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+
+**Returns:**
+
+- <code>str</code> – 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.

docs-website/reference/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: <code>OpenAIChatGenerator</code>
+
+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** (<code>Secret</code>) – The Llama API key.
+- **model** (<code>str</code>) – The name of the Llama chat completion model to use.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>str | None</code>) – The Llama API Base url.
+  For more details, see LlamaAPI [docs](https://llama.developer.meta.com/docs/features/compatibility/).
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>float | None</code>) – Timeout for Llama API client calls.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to attempt for failed requests.
+- **tools** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.

docs-website/reference/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** (<code>str</code>) – The Microsoft Graph base URL. Defaults to `https://graph.microsoft.com/v1.0`.
+  Override for sovereign clouds.
+- **timeout** (<code>float</code>) – The HTTP timeout in seconds for each request to Microsoft Graph.
+- **max_retries** (<code>int</code>) – The maximum number of retries for throttled (HTTP 429) or transient server errors.
+- **max_concurrent_requests** (<code>int</code>) – 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** (<code>bool</code>) – 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:**
+
+- <code>SharePointConfigError</code> – 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** (<code>str | Secret</code>) – 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** (<code>list\[Document | str\]</code>) – 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:**
+
+- <code>dict\[str, list\[ByteStream\]\]</code> – 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:**
+
+- <code>SharePointConfigError</code> – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+  `Secret` that does not resolve to a string.
+- <code>SharePointRequestError</code> – 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** (<code>str | Secret</code>) – 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** (<code>list\[Document | str\]</code>) – 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:**
+
+- <code>dict\[str, list\[ByteStream\]\]</code> – 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:**
+
+- <code>SharePointConfigError</code> – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+  `Secret` that does not resolve to a string.
+- <code>SharePointRequestError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MSSharePointFetcher
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>MSSharePointFetcher</code> – 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** (<code>list\[str\] | None</code>) – 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** (<code>int</code>) – The maximum number of documents to return. Maps to the Search API `size` and is paginated
+  when it exceeds a single page.
+- **fields** (<code>list\[str\] | None</code>) – 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** (<code>str | None</code>) – 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** (<code>str</code>) – The Microsoft Graph base URL. Defaults to `https://graph.microsoft.com/v1.0`.
+  Override for sovereign clouds.
+- **timeout** (<code>float</code>) – The HTTP timeout in seconds for each request to Microsoft Graph.
+- **max_retries** (<code>int</code>) – The maximum number of retries for throttled (HTTP 429) or transient server errors.
+
+**Raises:**
+
+- <code>SharePointConfigError</code> – 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** (<code>str</code>) – 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** (<code>str | Secret</code>) – 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** (<code>int | None</code>) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- <code>SharePointConfigError</code> – If `access_token` is a `Secret` that does not resolve to a string.
+- <code>SharePointRequestError</code> – 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** (<code>str</code>) – 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** (<code>str | Secret</code>) – 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** (<code>int | None</code>) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- <code>SharePointConfigError</code> – If `access_token` is a `Secret` that does not resolve to a string.
+- <code>SharePointRequestError</code> – If Microsoft Graph returns an error response.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MSSharePointRetriever
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>MSSharePointRetriever</code> – The deserialized component instance.

docs-website/reference/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: <code>Tool</code>
+
+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** (<code>MirageWorkspace</code>) – The :class:`MirageWorkspace` describing the mount tree.
+- **name** (<code>str</code>) – Tool name exposed to the LLM.
+- **description** (<code>str | None</code>) – Custom description. If None, one is generated from the mount tree.
+- **invocation_timeout** (<code>float</code>) – Maximum seconds to wait for a command to finish.
+- **max_output_chars** (<code>int</code>) – Truncate command output to this many characters before returning it.
+- **allowed_commands** (<code>list\[str\] | None</code>) – 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** (<code>list\[str\] | None</code>) – 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** (<code>str</code>) – Mount point in the virtual filesystem, e.g. `"/s3"`.
+- **resource** (<code>str</code>) – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>bool</code>) – 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** (<code>list\[MirageMount\]</code>) – The backends to mount, as a list of :class:`MirageMount`.
+- **cache_limit** (<code>str | int</code>) – Mirage file-cache size limit (e.g. `"512MB"` or an int byte count).
+
+**Raises:**
+
+- <code>MirageConfigError</code> – 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** (<code>str</code>) – A bash command line, e.g. `"grep -r alert /s3/logs | wc -l"`.
+- **timeout** (<code>float</code>) – Maximum seconds to wait for the command.
+- **max_chars** (<code>int | None</code>) – If set, truncate the returned text to this many characters.
+
+**Returns:**
+
+- <code>str</code> – 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).

docs-website/reference/integrations-api/mistral.md

@@ -0,0 +1,648 @@
+---
+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** (<code>Secret</code>) – The Mistral API key. Defaults to the MISTRAL_API_KEY environment variable.
+- **model** (<code>str</code>) – The OCR model to use. Default is "mistral-ocr-2505".
+  See more: https://docs.mistral.ai/getting-started/models/models_overview/
+- **include_image_base64** (<code>bool</code>) – If True, includes base64 encoded images in the response.
+  This may significantly increase response size and processing time.
+- **pages** (<code>list\[int\] | None</code>) – Specific page numbers to process (0-indexed). If None, processes all pages.
+- **image_limit** (<code>int | None</code>) – Maximum number of images to extract from the document.
+- **image_min_size** (<code>int | None</code>) – Minimum height and width (in pixels) for images to be extracted.
+- **cleanup_uploaded_files** (<code>bool</code>) – If True, automatically deletes files uploaded to Mistral after processing.
+  Only affects files uploaded from local sources (str, Path, ByteStream).
+  Files provided as FileChunk are not deleted. Default is True.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MistralOCRDocumentConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>MistralOCRDocumentConverter</code> – 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** (<code>list\[str | Path | ByteStream | DocumentURLChunk | FileChunk | ImageURLChunk\]</code>) – 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** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – 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** (<code>type\[BaseModel\] | None</code>) – 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** (<code>type\[BaseModel\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – 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: <code>OpenAIDocumentEmbedder</code>
+
+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** (<code>Secret</code>) – The Mistral API key.
+- **model** (<code>str</code>) – The name of the model to use.
+- **api_base_url** (<code>str | None</code>) – The Mistral API Base url. For more details, see Mistral [docs](https://docs.mistral.ai/api/).
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **batch_size** (<code>int</code>) – Number of Documents to encode at once.
+- **progress_bar** (<code>bool</code>) – 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** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
+- **timeout** (<code>float | None</code>) – Timeout for Mistral client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.components.embedders.mistral.text_embedder
+
+### MistralTextEmbedder
+
+Bases: <code>OpenAITextEmbedder</code>
+
+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** (<code>Secret</code>) – The Mistral API key.
+- **model** (<code>str</code>) – The name of the Mistral embedding model to be used.
+- **api_base_url** (<code>str | None</code>) – The Mistral API Base url.
+  For more details, see Mistral [docs](https://docs.mistral.ai/api/).
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **timeout** (<code>float | None</code>) – Timeout for Mistral client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.components.generators.mistral.chat.chat_generator
+
+### MistralChatGenerator
+
+Bases: <code>OpenAIChatGenerator</code>
+
+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=<ChatRole.ASSISTANT: 'assistant'>, _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.")], _name=None,
+>> _meta={'model': 'mistral-small-latest', 'index': 0, 'finish_reason': 'stop',
+>> 'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]}
+```
+
+Reasoning usage example:
+
+```python
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("Solve: if x + 3 = 7, what is x?")]
+
+client = MistralChatGenerator(
+    model="mistral-small-latest",
+    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
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "mistral-medium-2505",
+    "mistral-medium-2508",
+    "mistral-medium-latest",
+    "mistral-medium",
+    "mistral-vibe-cli-with-tools",
+    "open-mistral-nemo",
+    "open-mistral-nemo-2407",
+    "mistral-tiny-2407",
+    "mistral-tiny-latest",
+    "codestral-2508",
+    "codestral-latest",
+    "devstral-2512",
+    "mistral-vibe-cli-latest",
+    "devstral-medium-latest",
+    "devstral-latest",
+    "mistral-small-2506",
+    "mistral-small-latest",
+    "labs-mistral-small-creative",
+    "magistral-medium-2509",
+    "magistral-medium-latest",
+    "magistral-small-2509",
+    "magistral-small-latest",
+    "voxtral-small-2507",
+    "voxtral-small-latest",
+    "mistral-large-2512",
+    "mistral-large-latest",
+    "ministral-3b-2512",
+    "ministral-3b-latest",
+    "ministral-8b-2512",
+    "ministral-8b-latest",
+    "ministral-14b-2512",
+    "ministral-14b-latest",
+    "mistral-large-2411",
+    "pixtral-large-2411",
+    "pixtral-large-latest",
+    "mistral-large-pixtral-2411",
+    "devstral-small-2507",
+    "devstral-medium-2507",
+    "labs-devstral-small-2512",
+    "devstral-small-latest",
+    "voxtral-mini-2507",
+    "voxtral-mini-latest",
+    "voxtral-mini-2602",
+]
+
+```
+
+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-small-latest",
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: str | None = "https://api.mistral.ai/v1",
+    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 MistralChatGenerator.
+
+Unless specified otherwise in the `model`, this is for Mistral's `mistral-small-latest` model.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Mistral API key.
+- **model** (<code>str</code>) – The name of the Mistral chat completion model to use.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>str | None</code>) – The Mistral API Base url.
+  For more details, see Mistral [docs](https://docs.mistral.ai/api/).
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>float | None</code>) – The timeout for the Mistral API call. If not set, it defaults to either the `OPENAI_TIMEOUT`
+  environment variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will
+  override the parameters passed during component initialization.
+  For details on Mistral API parameters, see
+  [Mistral docs](https://docs.mistral.ai/api/).
+- **tools** (<code>ToolsType | None</code>) – 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** (<code>bool | None</code>) – Whether to enable strict schema adherence for tool calls.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  Must be a coroutine.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset.
+- **tools_strict** (<code>bool | None</code>) – Whether to enable strict schema adherence for tool calls.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.

docs-website/reference/integrations-api/mongodb_atlas.md

@@ -0,0 +1,853 @@
+---
+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** (<code>MongoDBAtlasDocumentStore</code>) – An instance of MongoDBAtlasDocumentStore.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `MongoDBAtlasDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MongoDBAtlasEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>MongoDBAtlasEmbeddingRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the MongoDBAtlasDocumentStore, based on the provided embedding similarity.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>MongoDBAtlasDocumentStore</code>) – An instance of MongoDBAtlasDocumentStore.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of MongoDBAtlasDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MongoDBAtlasFullTextRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>MongoDBAtlasFullTextRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query: str | list[str],
+    fuzzy: dict[str, int] | None = None,
+    match_criteria: Literal["any", "all"] | None = None,
+    score: dict[str, dict] | None = None,
+    synonyms: str | None = None,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the MongoDBAtlasDocumentStore by full-text search.
+
+**Parameters:**
+
+- **query** (<code>str | list\[str\]</code>) – 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** (<code>dict\[str, int\] | None</code>) – 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** (<code>Literal['any', 'all'] | None</code>) – 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** (<code>dict\[str, dict\] | None</code>) – 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** (<code>str | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>str | list\[str\]</code>) – 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** (<code>dict\[str, int\] | None</code>) – 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** (<code>Literal['any', 'all'] | None</code>) – 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** (<code>dict\[str, dict\] | None</code>) – 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** (<code>str | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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"
+) -> None
+```
+
+Creates a new MongoDBAtlasDocumentStore instance.
+
+**Parameters:**
+
+- **mongo_connection_string** (<code>Secret</code>) – 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** (<code>str</code>) – Name of the database to use.
+- **collection_name** (<code>str</code>) – 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** (<code>str</code>) – 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** (<code>str</code>) – 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** (<code>str</code>) – The name of the field containing document embeddings. Default is "embedding".
+- **content_field** (<code>str</code>) – The name of the field containing the document content. Default is "content".
+  This field allows defining which field to load into the Haystack Document object as content.
+  It can be particularly useful when integrating with an existing collection for retrieval. We discourage
+  using this parameter when working with collections created by Haystack.
+
+**Raises:**
+
+- <code>ValueError</code> – If the collection name contains invalid characters.
+
+#### 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MongoDBAtlasDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>MongoDBAtlasDocumentStore</code> – Deserialized component.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+- **metadata_fields** (<code>list\[str\]</code>) – The metadata fields to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+- **metadata_fields** (<code>list\[str\]</code>) – The metadata fields to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>dict\[str, dict\]</code> – 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:**
+
+- <code>dict\[str, dict\]</code> – 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** (<code>str</code>) – The metadata field to get the min and max values for.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – The metadata field to get the min and max values for.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with 'min' and 'max' keys.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a field matching a search_term or all possible values if no search term is given.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to retrieve unique values for.
+- **search_term** (<code>str | None</code>) – The search term to filter values. Matches as a case-insensitive substring.
+- **from\_** (<code>int</code>) – The starting index for pagination.
+- **size** (<code>int</code>) – The number of values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing a list of unique values and the total count of unique values matching the
+  search term.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously retrieves unique values for a metadata field, optionally filtered by a search term.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to retrieve unique values for.
+- **search_term** (<code>str | None</code>) – The search term to filter values. Matches as a case-insensitive substring.
+- **from\_** (<code>int</code>) – The starting index for pagination.
+- **size** (<code>int</code>) – The number of values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing a list of unique values and the total count of unique values matching the
+  search term.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the Haystack [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – The filters to apply. It returns only the documents that match the filters.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>dict\[str, Any\] | None</code>) – The filters to apply. It returns only the documents that match the filters.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>DuplicateDocumentError</code> – If a document with the same ID already exists in the document store
+  and the policy is set to DuplicatePolicy.FAIL (or not specified).
+- <code>ValueError</code> – 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** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>DuplicateDocumentError</code> – If a document with the same ID already exists in the document store
+  and the policy is set to DuplicatePolicy.FAIL (or not specified).
+- <code>ValueError</code> – 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** (<code>list\[str\]</code>) – 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** (<code>list\[str\]</code>) – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>bool</code>) – 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** (<code>bool</code>) – 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

docs-website/reference/integrations-api/nvidia.md

@@ -0,0 +1,730 @@
+---
+title: "Nvidia"
+id: integrations-nvidia
+description: "Nvidia integration for Haystack"
+slug: "/integrations-nvidia"
+---
+
+
+## haystack_integrations.components.embedders.nvidia.document_embedder
+
+### NvidiaDocumentEmbedder
+
+A component for embedding documents using embedding models provided by [NVIDIA NIMs](https://ai.nvidia.com).
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.nvidia import NvidiaDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+text_embedder = NvidiaDocumentEmbedder(model="nvidia/nv-embedqa-e5-v5", api_url="https://integrate.api.nvidia.com/v1")
+# Components warm up automatically on first run.
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str | None = None,
+    api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+    api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+    prefix: str = "",
+    suffix: str = "",
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    truncate: EmbeddingTruncateMode | str | None = None,
+    timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaTextEmbedder component.
+
+**Parameters:**
+
+- **model** (<code>str | None</code>) – 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** (<code>Secret | None</code>) – API key for the NVIDIA NIM.
+- **api_url** (<code>str</code>) – Custom API URL for the NVIDIA NIM.
+  Format for API URL is `http://host:port`
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **batch_size** (<code>int</code>) – Number of Documents to encode at once.
+  Cannot be greater than 50.
+- **progress_bar** (<code>bool</code>) – Whether to show a progress bar or not.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
+- **truncate** (<code>EmbeddingTruncateMode | str | None</code>) – 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** (<code>float | None</code>) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+  or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### default_model
+
+```python
+default_model() -> None
+```
+
+Set default model in local NIM mode.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>NvidiaDocumentEmbedder</code> – 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** (<code>list\[Document\]</code>) – A list of Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with the following keys and values:
+- `documents` - List of processed Documents with embeddings.
+- `meta` - Metadata on usage statistics, etc.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.nvidia.text_embedder
+
+### NvidiaTextEmbedder
+
+A component for embedding strings using embedding models provided by [NVIDIA NIMs](https://ai.nvidia.com).
+
+For models that differentiate between query and document inputs,
+this component embeds the input string as a query.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.nvidia import NvidiaTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = NvidiaTextEmbedder(model="nvidia/nv-embedqa-e5-v5", api_url="https://integrate.api.nvidia.com/v1")
+# Components warm up automatically on first run.
+
+print(text_embedder.run(text_to_embed))
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str | None = None,
+    api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+    api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+    prefix: str = "",
+    suffix: str = "",
+    truncate: EmbeddingTruncateMode | str | None = None,
+    timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaTextEmbedder component.
+
+**Parameters:**
+
+- **model** (<code>str | None</code>) – 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** (<code>Secret | None</code>) – API key for the NVIDIA NIM.
+- **api_url** (<code>str</code>) – Custom API URL for the NVIDIA NIM.
+  Format for API URL is `http://host:port`
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **truncate** (<code>EmbeddingTruncateMode | str | None</code>) – 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** (<code>float | None</code>) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+  or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### default_model
+
+```python
+default_model() -> None
+```
+
+Set default model in local NIM mode.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>NvidiaTextEmbedder</code> – The deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Embed a string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – The text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – A dictionary with the following keys and values:
+- `embedding` - Embedding of the text.
+- `meta` - Metadata on usage statistics, etc.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.
+- <code>ValueError</code> – If the input string is empty.
+
+## haystack_integrations.components.embedders.nvidia.truncate
+
+### EmbeddingTruncateMode
+
+Bases: <code>Enum</code>
+
+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** (<code>str</code>) – String to convert.
+
+**Returns:**
+
+- <code>EmbeddingTruncateMode</code> – Truncate mode.
+
+## haystack_integrations.components.generators.nvidia.chat.chat_generator
+
+### NvidiaChatGenerator
+
+Bases: <code>OpenAIChatGenerator</code>
+
+Enables text generation using NVIDIA generative models.
+
+For supported models, see [NVIDIA Docs](https://build.nvidia.com/models).
+
+Users can pass any text generation parameters valid for the NVIDIA Chat Completion API
+directly to this component via the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage)
+
+For more details on the parameters supported by the NVIDIA API, refer to the
+[NVIDIA Docs](https://build.nvidia.com/models).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = NvidiaChatGenerator()
+response = client.run(messages)
+print(response)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("NVIDIA_API_KEY"),
+    model: str = "meta/llama-3.1-8b-instruct",
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: str | None = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+    generation_kwargs: dict[str, Any] | None = None,
+    tools: ToolsType | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of NvidiaChatGenerator.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The NVIDIA API key.
+- **model** (<code>str</code>) – The name of the NVIDIA chat completion model to use.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>str | None</code>) – The NVIDIA API Base url.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>float | None</code>) – The timeout for the NVIDIA API call.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+## haystack_integrations.components.generators.nvidia.generator
+
+### NvidiaGenerator
+
+Generates text using generative models hosted with [NVIDIA NIM](https://ai.nvidia.com).
+
+Available via the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover).
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.nvidia import NvidiaGenerator
+
+generator = NvidiaGenerator(
+    model="meta/llama3-8b-instruct",
+    model_arguments={
+        "temperature": 0.2,
+        "top_p": 0.7,
+        "max_tokens": 1024,
+    },
+)
+# Components warm up automatically on first run.
+
+result = generator.run(prompt="What is the answer?")
+print(result["replies"])
+print(result["meta"])
+print(result["usage"])
+```
+
+You need an NVIDIA API key for this component to work.
+
+#### __init__
+
+```python
+__init__(
+    model: str | None = None,
+    api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+    api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+    model_arguments: dict[str, Any] | None = None,
+    timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaGenerator component.
+
+**Parameters:**
+
+- **model** (<code>str | None</code>) – Name of the model to use for text generation.
+  See the [NVIDIA NIMs](https://ai.nvidia.com)
+  for more information on the supported models.
+  `Note`: If no specific model along with locally hosted API URL is provided,
+  the system defaults to the available model found using /models API.
+  Check supported models at [NVIDIA NIM](https://ai.nvidia.com).
+- **api_key** (<code>Secret | None</code>) – API key for the NVIDIA NIM. Set it as the `NVIDIA_API_KEY` environment
+  variable or pass it here.
+- **api_url** (<code>str</code>) – Custom API URL for the NVIDIA NIM.
+- **model_arguments** (<code>dict\[str, Any\] | None</code>) – Additional arguments to pass to the model provider. These arguments are
+  specific to a model.
+  Search your model in the [NVIDIA NIM](https://ai.nvidia.com)
+  to find the arguments it accepts.
+- **timeout** (<code>float | None</code>) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+  or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### default_model
+
+```python
+default_model() -> None
+```
+
+Set default model in local NIM mode.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### available_models
+
+```python
+available_models: list[Model]
+```
+
+Get a list of available models that work with ChatNVIDIA.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NvidiaGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>NvidiaGenerator</code> – Deserialized component.
+
+#### run
+
+```python
+run(prompt: str) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Queries the model with the provided prompt.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – Text to be sent to the generative model.
+
+**Returns:**
+
+- <code>dict\[str, list\[str\] | list\[dict\[str, Any\]\]\]</code> – A dictionary with the following keys:
+- `replies` - Replies generated by the model.
+- `meta` - Metadata for each reply.
+
+## haystack_integrations.components.rankers.nvidia.ranker
+
+### NvidiaRanker
+
+A component for ranking documents using ranking models provided by [NVIDIA NIMs](https://ai.nvidia.com).
+
+Usage example:
+
+```python
+from haystack_integrations.components.rankers.nvidia import NvidiaRanker
+from haystack import Document
+from haystack.utils import Secret
+
+ranker = NvidiaRanker(
+    model="nvidia/nv-rerankqa-mistral-4b-v3",
+    api_key=Secret.from_env_var("NVIDIA_API_KEY"),
+)
+# Components warm up automatically on first run.
+
+query = "What is the capital of Germany?"
+documents = [
+    Document(content="Berlin is the capital of Germany."),
+    Document(content="The capital of Germany is Berlin."),
+    Document(content="Germany's capital is Berlin."),
+]
+
+result = ranker.run(query, documents, top_k=2)
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str | None = None,
+    truncate: RankerTruncateMode | str | None = None,
+    api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+    api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+    top_k: int = 5,
+    query_prefix: str = "",
+    document_prefix: str = "",
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaRanker component.
+
+**Parameters:**
+
+- **model** (<code>str | None</code>) – Ranking model to use.
+- **truncate** (<code>RankerTruncateMode | str | None</code>) – Truncation strategy to use. Can be "NONE", "END", or RankerTruncateMode. Defaults to NIM's default.
+- **api_key** (<code>Secret | None</code>) – API key for the NVIDIA NIM.
+- **api_url** (<code>str</code>) – Custom API URL for the NVIDIA NIM.
+- **top_k** (<code>int</code>) – Number of documents to return.
+- **query_prefix** (<code>str</code>) – 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** (<code>str</code>) – 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** (<code>list\[str\] | None</code>) – List of metadata fields to embed with the document.
+- **embedding_separator** (<code>str</code>) – Separator to concatenate metadata fields to the document.
+- **timeout** (<code>float | None</code>) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+  or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the ranker to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>dict\[str, Any\]</code>) – A dictionary containing the ranker's attributes.
+
+**Returns:**
+
+- <code>NvidiaRanker</code> – The deserialized ranker.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the ranker.
+
+**Raises:**
+
+- <code>ValueError</code> – If the API key is required for hosted NVIDIA NIMs.
+
+#### run
+
+```python
+run(
+    query: str, documents: list[Document], top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Rank a list of documents based on a given query.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The query to rank the documents against.
+- **documents** (<code>list\[Document\]</code>) – The list of documents to rank.
+- **top_k** (<code>int | None</code>) – The number of documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary containing the ranked documents.
+
+**Raises:**
+
+- <code>TypeError</code> – If the arguments are of the wrong type.
+
+## haystack_integrations.components.rankers.nvidia.truncate
+
+### RankerTruncateMode
+
+Bases: <code>str</code>, <code>Enum</code>
+
+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** (<code>str</code>) – String to convert.
+
+**Returns:**
+
+- <code>RankerTruncateMode</code> – Truncate mode.

docs-website/reference/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** (<code>TokenSource | SubjectTokenSource</code>) – 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:**
+
+- <code>OAuthConfigError</code> – 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** (<code>Any</code>) – 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:**
+
+- <code>dict\[str, str\]</code> – A dictionary with a single `access_token` key containing a bearer token string.
+
+**Raises:**
+
+- <code>OAuthConfigError</code> – 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** (<code>Any</code>) – Carries `subject_token` when the configured source requires it.
+
+**Returns:**
+
+- <code>dict\[str, str\]</code> – A dictionary with a single `access_token` key containing a bearer token string.
+
+**Raises:**
+
+- <code>OAuthConfigError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OAuthTokenResolver
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>OAuthTokenResolver</code> – The deserialized component instance.
+
+**Raises:**
+
+- <code>ImportError</code> – If the serialized `token_source` type cannot be imported.
+
+## haystack_integrations.utils.oauth.errors
+
+### OAuthError
+
+Bases: <code>Exception</code>
+
+Base class for errors raised by the OAuth integration.
+
+### OAuthConfigError
+
+Bases: <code>OAuthError</code>
+
+Raised when an OAuth component or token source is misconfigured.
+
+### TokenRefreshError
+
+Bases: <code>OAuthError</code>
+
+Raised when a token cannot be resolved or refreshed at the identity provider.
+
+## haystack_integrations.utils.oauth.protocols
+
+### TokenSource
+
+Bases: <code>Protocol</code>
+
+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: <code>Protocol</code>
+
+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** (<code>str</code>) – The OAuth 2.0 token endpoint.
+- **client_id** (<code>str</code>) – The OAuth client identifier.
+- **refresh_token** (<code>Secret</code>) – The refresh token to exchange. Defaults to the value of the `OAUTH_REFRESH_TOKEN`
+  environment variable.
+- **client_secret** (<code>Secret | None</code>) – The client secret for confidential clients. Omit it for public clients.
+- **scopes** (<code>list\[str\] | None</code>) – The OAuth scopes to request, joined with `scope_delimiter`. Scope *values* are
+  provider-specific (consult your identity provider's documentation).
+- **scope_delimiter** (<code>str</code>) – The delimiter used to join scopes. Defaults to a space (some providers use a comma).
+- **expiry_buffer_seconds** (<code>int</code>) – Refresh the cached access token this many seconds before its declared expiry.
+- **timeout** (<code>float</code>) – The timeout, in seconds, for the request to the token endpoint.
+- **on_rotate** (<code>Callable\\[[str\], None\] | None</code>) – 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:**
+
+- <code>OAuthConfigError</code> – 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:**
+
+- <code>str</code> – 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** (<code>str</code>) – The OAuth 2.0 token endpoint.
+- **client_id** (<code>str</code>) – The OAuth client identifier.
+- **client_secret** (<code>Secret | None</code>) – The client secret for confidential clients. Omit it for public clients.
+- **grant_type** (<code>str</code>) – 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** (<code>str</code>) – 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** (<code>str | None</code>) – 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** (<code>str | None</code>) – The RFC 8693 identifier for the token to return, sent as the
+  `requested_token_type` form parameter (omitted when not set). Optional.
+- **scopes** (<code>list\[str\] | None</code>) – 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** (<code>str</code>) – The delimiter used to join scopes. Defaults to a space.
+- **extra_token_params** (<code>dict\[str, str\] | None</code>) – 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** (<code>int</code>) – Refresh a cached access token this many seconds before its declared expiry.
+- **cache_max_size** (<code>int</code>) – 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** (<code>float</code>) – The timeout, in seconds, for the request to the token endpoint.
+
+**Raises:**
+
+- <code>OAuthConfigError</code> – 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** (<code>str</code>) – The controller-injected per-request subject token (for example an incoming user
+  assertion) to exchange for a downstream access token.
+
+**Returns:**
+
+- <code>str</code> – 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** (<code>Secret</code>) – The long-lived access token to return.
+
+#### resolve
+
+```python
+resolve() -> str
+```
+
+Return the configured token.
+
+**Returns:**
+
+- <code>str</code> – 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.

docs-website/reference/integrations-api/ollama.md

@@ -0,0 +1,495 @@
+---
+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** (<code>str</code>) – The name of the model to use. The model should be available in the running Ollama instance.
+- **url** (<code>str</code>) – The URL of a running Ollama instance.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – The number of seconds before throwing a timeout error from the Ollama API.
+- **keep_alive** (<code>float | str | None</code>) – 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** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **progress_bar** (<code>bool</code>) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the metadata fields to the document text.
+- **batch_size** (<code>int</code>) – Number of documents to process at once.
+- **dimensions** (<code>int | None</code>) – 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.
+
+#### 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** (<code>list\[Document\]</code>) – Documents to be converted to an embedding.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – 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** (<code>list\[Document\]</code>) – Documents to be converted to an embedding.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – 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** (<code>str</code>) – The name of the model to use. The model should be available in the running Ollama instance.
+- **url** (<code>str</code>) – The URL of a running Ollama instance.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – The number of seconds before throwing a timeout error from the Ollama API.
+- **keep_alive** (<code>float | str | None</code>) – 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** (<code>int | None</code>) – 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.
+
+#### 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** (<code>str</code>) – Text to be converted to an embedding.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – 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** (<code>str</code>) – Text to be converted to an embedding.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – 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** (<code>str</code>) – The name of the model to use. The model must already be present (pulled) in the running Ollama instance.
+- **url** (<code>str</code>) – The base URL of the Ollama server (default "http://localhost:11434").
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – The number of seconds before throwing a timeout error from the Ollama API.
+- **max_retries** (<code>int</code>) – 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** (<code>bool | Literal['low', 'medium', 'high']</code>) – 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** (<code>float | str | None</code>) – 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** (<code>Callable\\[[StreamingChunk\], None\] | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts StreamingChunk as an argument.
+- **tools** (<code>ToolsType | None</code>) – 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** (<code>None | Literal['json'] | JsonSchemaValue | None</code>) – The format for structured model outputs. The value can be:
+- None: No specific structure or format is applied to the response. The response is returned as-is.
+- "json": The response is formatted as a JSON object.
+- JSON Schema: The response is formatted as a JSON object
+  that adheres to the specified JSON Schema. (needs Ollama ≥ 0.1.34)
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OllamaChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OllamaChatGenerator</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callable to receive `StreamingChunk` objects as they
+  arrive. Supplying a callback (here or in the constructor) switches
+  the component into streaming mode.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Per-call overrides for Ollama inference options.
+  These are merged on top of the instance-level `generation_kwargs`.
+- **tools** (<code>ToolsType | None</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callable to receive `StreamingChunk` objects as they arrive.
+  Supplying a callback switches the component into streaming mode.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `replies`: A list of ChatMessages containing the model's response
+
+## haystack_integrations.components.generators.ollama.generator
+
+### OllamaGenerator
+
+Provides an interface to generate text using an LLM running on Ollama.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.ollama import OllamaGenerator
+
+generator = OllamaGenerator(model="zephyr",
+                            url = "http://localhost:11434",
+                            generation_kwargs={
+                            "num_predict": 100,
+                            "temperature": 0.9,
+                            })
+
+print(generator.run("Who is the best American actor?"))
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str = "orca-mini",
+    url: str = "http://localhost:11434",
+    generation_kwargs: dict[str, Any] | None = None,
+    system_prompt: str | None = None,
+    template: str | None = None,
+    raw: bool = False,
+    timeout: int = 120,
+    keep_alive: float | str | None = None,
+    streaming_callback: Callable[[StreamingChunk], None] | None = None,
+) -> None
+```
+
+Create a new OllamaGenerator instance.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the model to use. The model should be available in the running Ollama instance.
+- **url** (<code>str</code>) – The URL of a running Ollama instance.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+  top_p, and others. See the available arguments in
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **system_prompt** (<code>str | None</code>) – Optional system message (overrides what is defined in the Ollama Modelfile).
+- **template** (<code>str | None</code>) – The full prompt template (overrides what is defined in the Ollama Modelfile).
+- **raw** (<code>bool</code>) – If True, no formatting will be applied to the prompt. You may choose to use the raw parameter
+  if you are specifying a full templated prompt in your API request.
+- **timeout** (<code>int</code>) – The number of seconds before throwing a timeout error from the Ollama API.
+- **streaming_callback** (<code>Callable\\[[StreamingChunk\], None\] | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts StreamingChunk as an argument.
+- **keep_alive** (<code>float | str | None</code>) – The option that controls how long the model will stay loaded into memory following the request.
+  If not set, it will use the default value from the Ollama (5 minutes).
+  The value can be set to:
+- a duration string (such as "10m" or "24h")
+- a number in seconds (such as 3600)
+- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m")
+- '0' which will unload the model immediately after generating a response.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OllamaGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OllamaGenerator</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    prompt: str,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    streaming_callback: Callable[[StreamingChunk], None] | None = None
+) -> dict[str, list[Any]]
+```
+
+Runs an Ollama Model on the given prompt.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – The prompt to generate a response for.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+  top_p, and others. See the available arguments in
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **streaming_callback** (<code>Callable\\[[StreamingChunk\], None\] | None</code>) – A callback function that is called when a new token is received from the stream.
+
+**Returns:**
+
+- <code>dict\[str, list\[Any\]\]</code> – A dictionary with the following keys:
+- `replies`: The responses from the model
+- `meta`: The metadata collected during the run

docs-website/reference/integrations-api/openapi.md

@@ -0,0 +1,332 @@
+---
+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** (<code>str</code>) – URL, file path, or raw string of the OpenAPI specification
+- **credentials** (<code>Secret | None</code>) – Optional API key or credentials for the service wrapped in a Secret
+- **service_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments passed to OpenAPIClient.from_spec()
+  For example, you can pass a custom config_factory or other configuration options.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAPIConnector
+```
+
+Deserialize this component from a dictionary.
+
+#### run
+
+```python
+run(
+    operation_id: str, arguments: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Invokes a REST endpoint specified in the OpenAPI specification.
+
+**Parameters:**
+
+- **operation_id** (<code>str</code>) – The operationId from the OpenAPI spec to invoke
+- **arguments** (<code>dict\[str, Any\] | None</code>) – Optional parameters for the endpoint (query, path, or body parameters)
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – The URL to append this operation's path to when making
+  the call.
+- **data** (<code>Any | None</code>) – The request body to send.
+- **parameters** (<code>dict\[str, Any\] | None</code>) – The parameters used to create the path.
+- **raw_response** (<code>bool</code>) – If true, return the raw response instead of validating
+  and extrapolating it.
+- **security** (<code>dict\[str, str\] | None</code>) – The security scheme to use, and the values it needs to
+  process successfully.
+- **session** (<code>Any | None</code>) – A persistent request session.
+- **verify** (<code>bool | str</code>) – If we should do an SSL verification on the request or not.
+  In case str was provided, will use that as the CA.
+
+**Returns:**
+
+- <code>Any | None</code> – 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=<ChatRole.USER: 'user'>, _content=[TextContent(text=
+# '{"searchParameters": {"q": "Why was Sam Altman ousted from OpenAI?",
+# "type": "search", "engine": "google"}, "answerBox": {"snippet": "Concerns over AI safety and OpenAI's role
+# in protecting were at the center of Altman's brief ouster from the company."...
+```
+
+#### __init__
+
+```python
+__init__(ssl_verify: bool | str | None = None) -> None
+```
+
+Initializes the OpenAPIServiceConnector instance
+
+**Parameters:**
+
+- **ssl_verify** (<code>[bool | str | None</code>) – 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** (<code>list\[ChatMessage\]</code>) – A list of `ChatMessage` objects containing the messages to be processed. The last message
+  should contain the tool calls.
+- **service_openapi_spec** (<code>dict\[str, Any\]</code>) – The OpenAPI JSON specification object of the service to be invoked. All the refs
+  should already be resolved.
+- **service_credentials** (<code>dict | str | None</code>) – The credentials to be used for authentication with the service.
+  Currently, only the http and apiKey OpenAPI security schemes are supported.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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:**
+
+- <code>ValueError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OpenAPIServiceConnector</code> – 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** (<code>list\[str | Path | ByteStream\]</code>) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format).
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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:**
+
+- <code>RuntimeError</code> – If the OpenAPI definitions cannot be downloaded or processed.
+- <code>ValueError</code> – If the source type is not recognized or no functions are found in the OpenAPI definitions.

docs-website/reference/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: <code>OpenAIChatGenerator</code>
+
+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** (<code>Secret</code>) – The OpenRouter API key.
+- **model** (<code>str</code>) – The name of the OpenRouter chat completion model to use.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>str | None</code>) – The OpenRouter API Base url.
+  For more details, see OpenRouter [docs](https://openrouter.ai/docs/quickstart).
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>float | None</code>) – The timeout for the OpenRouter API call.
+- **extra_headers** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>bool | None</code>) – Whether to enable strict schema adherence for tool calls.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  Must be a coroutine.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset.
+- **tools_strict** (<code>bool | None</code>) – Whether to enable strict schema adherence for tool calls.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.

docs-website/reference/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** (<code>str</code>) – 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:**
+
+- <code>dict\[str, str\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenTelemetryConnector
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>OpenTelemetryConnector</code> – The deserialized component instance.
+
+## haystack_integrations.tracing.opentelemetry.tracer
+
+### OpenTelemetrySpan
+
+Bases: <code>Span</code>
+
+#### __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** (<code>str</code>) – the name of the tag.
+- **value** (<code>Any</code>) – the value of the tag.
+
+#### raw_span
+
+```python
+raw_span() -> Any
+```
+
+Provides access to the underlying span object of the tracer.
+
+**Returns:**
+
+- <code>Any</code> – 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: <code>Tracer</code>
+
+#### __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

docs-website/reference/integrations-api/optimum.md

@@ -0,0 +1,629 @@
+---
+title: "Optimum"
+id: integrations-optimum
+description: "Optimum integration for Haystack"
+slug: "/integrations-optimum"
+---
+
+<a id="haystack_integrations.components.embedders.optimum.optimization"></a>
+
+## Module haystack\_integrations.components.embedders.optimum.optimization
+
+<a id="haystack_integrations.components.embedders.optimum.optimization.OptimumEmbedderOptimizationMode"></a>
+
+### OptimumEmbedderOptimizationMode
+
+[ONXX Optimization modes](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/optimization)
+support by the Optimum Embedders.
+
+<a id="haystack_integrations.components.embedders.optimum.optimization.OptimumEmbedderOptimizationMode.O1"></a>
+
+#### O1
+
+Basic general optimizations.
+
+<a id="haystack_integrations.components.embedders.optimum.optimization.OptimumEmbedderOptimizationMode.O2"></a>
+
+#### O2
+
+Basic and extended general optimizations, transformers-specific fusions.
+
+<a id="haystack_integrations.components.embedders.optimum.optimization.OptimumEmbedderOptimizationMode.O3"></a>
+
+#### O3
+
+Same as O2 with Gelu approximation.
+
+<a id="haystack_integrations.components.embedders.optimum.optimization.OptimumEmbedderOptimizationMode.O4"></a>
+
+#### O4
+
+Same as O3 with mixed precision.
+
+<a id="haystack_integrations.components.embedders.optimum.optimization.OptimumEmbedderOptimizationMode.from_str"></a>
+
+#### OptimumEmbedderOptimizationMode.from\_str
+
+```python
+@classmethod
+def from_str(cls, string: str) -> "OptimumEmbedderOptimizationMode"
+```
+
+Create an optimization mode from a string.
+
+**Arguments**:
+
+- `string`: String to convert.
+
+**Returns**:
+
+Optimization mode.
+
+<a id="haystack_integrations.components.embedders.optimum.optimization.OptimumEmbedderOptimizationConfig"></a>
+
+### OptimumEmbedderOptimizationConfig
+
+Configuration for Optimum Embedder Optimization.
+
+**Arguments**:
+
+- `mode`: Optimization mode.
+- `for_gpu`: Whether to optimize for GPUs.
+
+<a id="haystack_integrations.components.embedders.optimum.optimization.OptimumEmbedderOptimizationConfig.to_optimum_config"></a>
+
+#### OptimumEmbedderOptimizationConfig.to\_optimum\_config
+
+```python
+def to_optimum_config() -> OptimizationConfig
+```
+
+Convert the configuration to a Optimum configuration.
+
+**Returns**:
+
+Optimum configuration.
+
+<a id="haystack_integrations.components.embedders.optimum.optimization.OptimumEmbedderOptimizationConfig.to_dict"></a>
+
+#### OptimumEmbedderOptimizationConfig.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Convert the configuration to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.embedders.optimum.optimization.OptimumEmbedderOptimizationConfig.from_dict"></a>
+
+#### OptimumEmbedderOptimizationConfig.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str,
+                              Any]) -> "OptimumEmbedderOptimizationConfig"
+```
+
+Create an optimization configuration from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Optimization configuration.
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_document_embedder"></a>
+
+## Module haystack\_integrations.components.embedders.optimum.optimum\_document\_embedder
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_document_embedder.OptimumDocumentEmbedder"></a>
+
+### OptimumDocumentEmbedder
+
+A component for computing `Document` embeddings using models loaded with the
+[HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library,
+leveraging the ONNX runtime for high-speed inference.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.embedders.optimum import OptimumDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = OptimumDocumentEmbedder(model="sentence-transformers/all-mpnet-base-v2")
+document_embedder.warm_up()
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_document_embedder.OptimumDocumentEmbedder.__init__"></a>
+
+#### OptimumDocumentEmbedder.\_\_init\_\_
+
+```python
+def __init__(model: str = "sentence-transformers/all-mpnet-base-v2",
+             token: Secret | None = Secret.from_env_var("HF_API_TOKEN",
+                                                        strict=False),
+             prefix: str = "",
+             suffix: str = "",
+             normalize_embeddings: bool = True,
+             onnx_execution_provider: str = "CPUExecutionProvider",
+             pooling_mode: str | OptimumEmbedderPooling | None = None,
+             model_kwargs: dict[str, Any] | None = None,
+             working_dir: str | None = None,
+             optimizer_settings: OptimumEmbedderOptimizationConfig
+             | None = None,
+             quantizer_settings: OptimumEmbedderQuantizationConfig
+             | None = None,
+             batch_size: int = 32,
+             progress_bar: bool = True,
+             meta_fields_to_embed: list[str] | None = None,
+             embedding_separator: str = "\n") -> None
+```
+
+Create a OptimumDocumentEmbedder component.
+
+**Arguments**:
+
+- `model`: A string representing the model id on HF Hub.
+- `token`: The HuggingFace token to use as HTTP bearer authorization.
+- `prefix`: A string to add to the beginning of each text.
+- `suffix`: A string to add to the end of each text.
+- `normalize_embeddings`: Whether to normalize the embeddings to unit length.
+- `onnx_execution_provider`: The [execution provider](https://onnxruntime.ai/docs/execution-providers/)
+to use for ONNX models.
+
+Note: Using the TensorRT execution provider
+TensorRT requires to build its inference engine ahead of inference,
+which takes some time due to the model optimization and nodes fusion.
+To avoid rebuilding the engine every time the model is loaded, ONNX
+Runtime provides a pair of options to save the engine: `trt_engine_cache_enable`
+and `trt_engine_cache_path`. We recommend setting these two provider
+options using the `model_kwargs` parameter, when using the TensorRT execution provider.
+The usage is as follows:
+```python
+embedder = OptimumDocumentEmbedder(
+    model="sentence-transformers/all-mpnet-base-v2",
+    onnx_execution_provider="TensorrtExecutionProvider",
+    model_kwargs={
+        "provider_options": {
+            "trt_engine_cache_enable": True,
+            "trt_engine_cache_path": "tmp/trt_cache",
+        }
+    },
+)
+```
+- `pooling_mode`: The pooling mode to use. When `None`, pooling mode will be inferred from the model config.
+- `model_kwargs`: Dictionary containing additional keyword arguments to pass to the model.
+In case of duplication, these kwargs override `model`, `onnx_execution_provider`
+and `token` initialization parameters.
+- `working_dir`: The directory to use for storing intermediate files
+generated during model optimization/quantization. Required
+for optimization and quantization.
+- `optimizer_settings`: Configuration for Optimum Embedder Optimization.
+If `None`, no additional optimization is be applied.
+- `quantizer_settings`: Configuration for Optimum Embedder Quantization.
+If `None`, no quantization is be applied.
+- `batch_size`: Number of Documents to encode at once.
+- `progress_bar`: Whether to show a progress bar or not.
+- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document text.
+- `embedding_separator`: Separator used to concatenate the meta fields to the Document text.
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_document_embedder.OptimumDocumentEmbedder.warm_up"></a>
+
+#### OptimumDocumentEmbedder.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Initializes the component.
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_document_embedder.OptimumDocumentEmbedder.to_dict"></a>
+
+#### OptimumDocumentEmbedder.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_document_embedder.OptimumDocumentEmbedder.from_dict"></a>
+
+#### OptimumDocumentEmbedder.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "OptimumDocumentEmbedder"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_document_embedder.OptimumDocumentEmbedder.run"></a>
+
+#### OptimumDocumentEmbedder.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of Documents.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+**Arguments**:
+
+- `documents`: A list of Documents to embed.
+
+**Raises**:
+
+- `TypeError`: If the input is not a list of Documents.
+
+**Returns**:
+
+The updated Documents with their embeddings.
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_text_embedder"></a>
+
+## Module haystack\_integrations.components.embedders.optimum.optimum\_text\_embedder
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_text_embedder.OptimumTextEmbedder"></a>
+
+### OptimumTextEmbedder
+
+A component to embed text using models loaded with the
+[HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library,
+leveraging the ONNX runtime for high-speed inference.
+
+Usage example:
+```python
+from haystack_integrations.components.embedders.optimum import OptimumTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = OptimumTextEmbedder(model="sentence-transformers/all-mpnet-base-v2")
+text_embedder.warm_up()
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]}
+```
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_text_embedder.OptimumTextEmbedder.__init__"></a>
+
+#### OptimumTextEmbedder.\_\_init\_\_
+
+```python
+def __init__(
+        model: str = "sentence-transformers/all-mpnet-base-v2",
+        token: Secret | None = Secret.from_env_var("HF_API_TOKEN",
+                                                   strict=False),
+        prefix: str = "",
+        suffix: str = "",
+        normalize_embeddings: bool = True,
+        onnx_execution_provider: str = "CPUExecutionProvider",
+        pooling_mode: str | OptimumEmbedderPooling | None = None,
+        model_kwargs: dict[str, Any] | None = None,
+        working_dir: str | None = None,
+        optimizer_settings: OptimumEmbedderOptimizationConfig | None = None,
+        quantizer_settings: OptimumEmbedderQuantizationConfig | None = None)
+```
+
+Create a OptimumTextEmbedder component.
+
+**Arguments**:
+
+- `model`: A string representing the model id on HF Hub.
+- `token`: The HuggingFace token to use as HTTP bearer authorization.
+- `prefix`: A string to add to the beginning of each text.
+- `suffix`: A string to add to the end of each text.
+- `normalize_embeddings`: Whether to normalize the embeddings to unit length.
+- `onnx_execution_provider`: The [execution provider](https://onnxruntime.ai/docs/execution-providers/)
+to use for ONNX models.
+
+Note: Using the TensorRT execution provider
+TensorRT requires to build its inference engine ahead of inference,
+which takes some time due to the model optimization and nodes fusion.
+To avoid rebuilding the engine every time the model is loaded, ONNX
+Runtime provides a pair of options to save the engine: `trt_engine_cache_enable`
+and `trt_engine_cache_path`. We recommend setting these two provider
+options using the `model_kwargs` parameter, when using the TensorRT execution provider.
+The usage is as follows:
+```python
+embedder = OptimumDocumentEmbedder(
+    model="sentence-transformers/all-mpnet-base-v2",
+    onnx_execution_provider="TensorrtExecutionProvider",
+    model_kwargs={
+        "provider_options": {
+            "trt_engine_cache_enable": True,
+            "trt_engine_cache_path": "tmp/trt_cache",
+        }
+    },
+)
+```
+- `pooling_mode`: The pooling mode to use. When `None`, pooling mode will be inferred from the model config.
+- `model_kwargs`: Dictionary containing additional keyword arguments to pass to the model.
+In case of duplication, these kwargs override `model`, `onnx_execution_provider`
+and `token` initialization parameters.
+- `working_dir`: The directory to use for storing intermediate files
+generated during model optimization/quantization. Required
+for optimization and quantization.
+- `optimizer_settings`: Configuration for Optimum Embedder Optimization.
+If `None`, no additional optimization is be applied.
+- `quantizer_settings`: Configuration for Optimum Embedder Quantization.
+If `None`, no quantization is be applied.
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_text_embedder.OptimumTextEmbedder.warm_up"></a>
+
+#### OptimumTextEmbedder.warm\_up
+
+```python
+def warm_up()
+```
+
+Initializes the component.
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_text_embedder.OptimumTextEmbedder.to_dict"></a>
+
+#### OptimumTextEmbedder.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_text_embedder.OptimumTextEmbedder.from_dict"></a>
+
+#### OptimumTextEmbedder.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "OptimumTextEmbedder"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="haystack_integrations.components.embedders.optimum.optimum_text_embedder.OptimumTextEmbedder.run"></a>
+
+#### OptimumTextEmbedder.run
+
+```python
+@component.output_types(embedding=list[float])
+def run(text: str) -> dict[str, list[float]]
+```
+
+Embed a string.
+
+**Arguments**:
+
+- `text`: The text to embed.
+
+**Raises**:
+
+- `TypeError`: If the input is not a string.
+
+**Returns**:
+
+The embeddings of the text.
+
+<a id="haystack_integrations.components.embedders.optimum.pooling"></a>
+
+## Module haystack\_integrations.components.embedders.optimum.pooling
+
+<a id="haystack_integrations.components.embedders.optimum.pooling.OptimumEmbedderPooling"></a>
+
+### OptimumEmbedderPooling
+
+Pooling modes support by the Optimum Embedders.
+
+<a id="haystack_integrations.components.embedders.optimum.pooling.OptimumEmbedderPooling.CLS"></a>
+
+#### CLS
+
+Perform CLS Pooling on the output of the embedding model
+using the first token (CLS token).
+
+<a id="haystack_integrations.components.embedders.optimum.pooling.OptimumEmbedderPooling.MEAN"></a>
+
+#### MEAN
+
+Perform Mean Pooling on the output of the embedding model.
+
+<a id="haystack_integrations.components.embedders.optimum.pooling.OptimumEmbedderPooling.MAX"></a>
+
+#### MAX
+
+Perform Max Pooling on the output of the embedding model
+using the maximum value in each dimension over all the tokens.
+
+<a id="haystack_integrations.components.embedders.optimum.pooling.OptimumEmbedderPooling.MEAN_SQRT_LEN"></a>
+
+#### MEAN\_SQRT\_LEN
+
+Perform mean-pooling on the output of the embedding model but
+divide by the square root of the sequence length.
+
+<a id="haystack_integrations.components.embedders.optimum.pooling.OptimumEmbedderPooling.WEIGHTED_MEAN"></a>
+
+#### WEIGHTED\_MEAN
+
+Perform weighted (position) mean pooling on the output of the
+embedding model.
+
+<a id="haystack_integrations.components.embedders.optimum.pooling.OptimumEmbedderPooling.LAST_TOKEN"></a>
+
+#### LAST\_TOKEN
+
+Perform Last Token Pooling on the output of the embedding model.
+
+<a id="haystack_integrations.components.embedders.optimum.pooling.OptimumEmbedderPooling.from_str"></a>
+
+#### OptimumEmbedderPooling.from\_str
+
+```python
+@classmethod
+def from_str(cls, string: str) -> "OptimumEmbedderPooling"
+```
+
+Create a pooling mode from a string.
+
+**Arguments**:
+
+- `string`: String to convert.
+
+**Returns**:
+
+Pooling mode.
+
+<a id="haystack_integrations.components.embedders.optimum.quantization"></a>
+
+## Module haystack\_integrations.components.embedders.optimum.quantization
+
+<a id="haystack_integrations.components.embedders.optimum.quantization.OptimumEmbedderQuantizationMode"></a>
+
+### OptimumEmbedderQuantizationMode
+
+[Dynamic Quantization modes](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/quantization)
+support by the Optimum Embedders.
+
+<a id="haystack_integrations.components.embedders.optimum.quantization.OptimumEmbedderQuantizationMode.ARM64"></a>
+
+#### ARM64
+
+Quantization for the ARM64 architecture.
+
+<a id="haystack_integrations.components.embedders.optimum.quantization.OptimumEmbedderQuantizationMode.AVX2"></a>
+
+#### AVX2
+
+Quantization with AVX-2 instructions.
+
+<a id="haystack_integrations.components.embedders.optimum.quantization.OptimumEmbedderQuantizationMode.AVX512"></a>
+
+#### AVX512
+
+Quantization with AVX-512 instructions.
+
+<a id="haystack_integrations.components.embedders.optimum.quantization.OptimumEmbedderQuantizationMode.AVX512_VNNI"></a>
+
+#### AVX512\_VNNI
+
+Quantization with AVX-512 and VNNI instructions.
+
+<a id="haystack_integrations.components.embedders.optimum.quantization.OptimumEmbedderQuantizationMode.from_str"></a>
+
+#### OptimumEmbedderQuantizationMode.from\_str
+
+```python
+@classmethod
+def from_str(cls, string: str) -> "OptimumEmbedderQuantizationMode"
+```
+
+Create an quantization mode from a string.
+
+**Arguments**:
+
+- `string`: String to convert.
+
+**Returns**:
+
+Quantization mode.
+
+<a id="haystack_integrations.components.embedders.optimum.quantization.OptimumEmbedderQuantizationConfig"></a>
+
+### OptimumEmbedderQuantizationConfig
+
+Configuration for Optimum Embedder Quantization.
+
+**Arguments**:
+
+- `mode`: Quantization mode.
+- `per_channel`: Whether to apply per-channel quantization.
+
+<a id="haystack_integrations.components.embedders.optimum.quantization.OptimumEmbedderQuantizationConfig.to_optimum_config"></a>
+
+#### OptimumEmbedderQuantizationConfig.to\_optimum\_config
+
+```python
+def to_optimum_config() -> QuantizationConfig
+```
+
+Convert the configuration to a Optimum configuration.
+
+**Returns**:
+
+Optimum configuration.
+
+<a id="haystack_integrations.components.embedders.optimum.quantization.OptimumEmbedderQuantizationConfig.to_dict"></a>
+
+#### OptimumEmbedderQuantizationConfig.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Convert the configuration to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.embedders.optimum.quantization.OptimumEmbedderQuantizationConfig.from_dict"></a>
+
+#### OptimumEmbedderQuantizationConfig.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str,
+                              Any]) -> "OptimumEmbedderQuantizationConfig"
+```
+
+Create a configuration from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Quantization configuration.
+

docs-website/reference/integrations-api/oracle.md

@@ -0,0 +1,760 @@
+---
+title: "Oracle AI Vector Search"
+id: integrations-oracle
+description: "Oracle AI Vector Search integration for Haystack"
+slug: "/integrations-oracle"
+---
+
+
+## haystack_integrations.components.retrievers.oracle.embedding_retriever
+
+### OracleEmbeddingRetriever
+
+Retrieves documents from an OracleDocumentStore using vector similarity.
+
+Use inside a Haystack pipeline after a text embedder::
+
+```
+pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
+pipeline.add_component("retriever", OracleEmbeddingRetriever(
+    document_store=store, top_k=5
+))
+pipeline.connect("embedder.embedding", "retriever.query_embedding")
+```
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by vector similarity.
+
+Args:
+query_embedding: Dense float vector from an embedder component.
+filters: Runtime filters, merged with constructor filters according to filter_policy.
+top_k: Override the constructor top_k for this call.
+
+Returns:
+`{"documents": [Document, ...]}`
+
+#### run_async
+
+```python
+run_async(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Async variant of :meth:`run`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OracleEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OracleEmbeddingRetriever</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OracleConnectionConfig
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OracleConnectionConfig</code> – 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** (<code>OracleConnectionConfig</code>) – Oracle connection settings (user, password, DSN, optional wallet).
+- **table_name** (<code>str</code>) – 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** (<code>int</code>) – Dimensionality of the embedding vectors. Must match the model producing them.
+- **distance_metric** (<code>Literal['COSINE', 'EUCLIDEAN', 'DOT']</code>) – Vector distance function used for similarity search.
+  One of `"COSINE"`, `"EUCLIDEAN"`, or `"DOT"`.
+- **create_table_if_not_exists** (<code>bool</code>) – 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** (<code>bool</code>) – When `True`, creates an HNSW vector index on initialisation. Equivalent to
+  calling :meth:`create_hnsw_index` manually. Defaults to `False`.
+- **hnsw_neighbors** (<code>int</code>) – 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** (<code>int</code>) – 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** (<code>int</code>) – Target recall accuracy percentage for the HNSW index (0-100).
+  Defaults to `95`.
+- **hnsw_parallel** (<code>int</code>) – Degree of parallelism used when building the HNSW index. Defaults to `4`.
+
+**Raises:**
+
+- <code>ValueError</code> – If `table_name` is not a valid Oracle identifier or `embedding_dim` is not
+  a positive integer.
+
+#### create_keyword_index
+
+```python
+create_keyword_index() -> None
+```
+
+Create the DBMS_SEARCH keyword index on this table.
+
+Safe to call multiple times — silently skips if the index already exists.
+Required for keyword retrieval. Called automatically when
+`create_table_if_not_exists=True`, but must be called explicitly
+when connecting to a pre-existing table.
+
+#### create_hnsw_index
+
+```python
+create_hnsw_index() -> None
+```
+
+Create an HNSW vector index on the embedding column.
+
+Safe to call multiple times — uses IF NOT EXISTS.
+
+#### create_hnsw_index_async
+
+```python
+create_hnsw_index_async() -> None
+```
+
+Asynchronously creates an HNSW vector index on the embedding column.
+
+Safe to call multiple times — uses `IF NOT EXISTS`.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>DuplicateDocumentError</code> – 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** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>DuplicateDocumentError</code> – 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** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>list\[str\]</code>) – 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** (<code>list\[str\]</code>) – the document ids to delete
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – 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:**
+
+- <code>int</code> – 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:**
+
+- <code>DocumentStoreError</code> – 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:**
+
+- <code>DocumentStoreError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict. An empty dict matches all documents.
+  See the `metadata filtering docs <https://docs.haystack.deepset.ai/docs/metadata-filtering>`\_.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict. An empty dict matches all documents.
+  See the `metadata filtering docs <https://docs.haystack.deepset.ai/docs/metadata-filtering>`\_.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict. An empty dict is treated as a no-op and returns `0`
+  without touching the table.
+  See the `metadata filtering docs <https://docs.haystack.deepset.ai/docs/metadata-filtering>`\_.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict. An empty dict is treated as a no-op and returns `0`
+  without touching the table.
+  See the `metadata filtering docs <https://docs.haystack.deepset.ai/docs/metadata-filtering>`\_.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict that selects which documents to update.
+  See the `metadata filtering docs <https://docs.haystack.deepset.ai/docs/metadata-filtering>`\_.
+- **meta** (<code>dict\[str, Any\]</code>) – Metadata patch to apply. Must be a non-empty dictionary.
+
+**Returns:**
+
+- <code>int</code> – Number of updated documents.
+
+**Raises:**
+
+- <code>ValueError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict that selects which documents to update.
+  See the `metadata filtering docs <https://docs.haystack.deepset.ai/docs/metadata-filtering>`\_.
+- **meta** (<code>dict\[str, Any\]</code>) – Metadata patch to apply. Must be a non-empty dictionary.
+
+**Returns:**
+
+- <code>int</code> – Number of updated documents.
+
+**Raises:**
+
+- <code>ValueError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict that scopes the document set.
+  See the `metadata filtering docs <https://docs.haystack.deepset.ai/docs/metadata-filtering>`\_.
+- **metadata_fields** (<code>list\[str\]</code>) – 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:**
+
+- <code>dict\[str, int\]</code> – Dict mapping each field name to its distinct-value count.
+
+**Raises:**
+
+- <code>ValueError</code> – If `metadata_fields` is empty.
+- <code>ValueError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dict that scopes the document set.
+  See the `metadata filtering docs <https://docs.haystack.deepset.ai/docs/metadata-filtering>`\_.
+- **metadata_fields** (<code>list\[str\]</code>) – 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:**
+
+- <code>dict\[str, int\]</code> – Dict mapping each field name to its distinct-value count.
+
+**Raises:**
+
+- <code>ValueError</code> – If `metadata_fields` is empty.
+- <code>ValueError</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – Dict of the form `{"field_name": {"type": "<type>"}, ...}` where `<type>`
+  is one of `"text"`, `"number"`, or `"boolean"`.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Return the minimum and maximum values of a metadata field across all documents.
+
+First attempts numeric comparison via `TO_NUMBER` so that `MAX(1, 5, 10)` returns `10`
+rather than `"5"` (which would win under lexicographic ordering). Falls back to plain string
+comparison when the field contains non-numeric values. Numeric strings are automatically
+converted to `int` or `float` in the result.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name. May be prefixed with `"meta."`
+  (e.g. `"meta.year"` or `"year"`).
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – `{"min": <value>, "max": <value>}`. Both values are `None` when the table is
+  empty or the field does not exist.
+
+**Raises:**
+
+- <code>ValueError</code> – If `metadata_field` contains characters outside `[A-Za-z0-9_.]`.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int | None = None,
+) -> tuple[list[str], int]
+```
+
+Return a paginated list of distinct values for a metadata field, plus the total distinct count.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name. May be prefixed with `"meta."`
+  (e.g. `"meta.lang"` or `"lang"`).
+- **search_term** (<code>str | None</code>) – Optional substring filter applied to both the document text and the field value.
+- **from\_** (<code>int</code>) – Zero-based offset for pagination. Defaults to `0`.
+- **size** (<code>int | None</code>) – Maximum number of values to return. When `None` all values from `from_` onward
+  are returned.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple `(values, total)` where `values` is the paginated list of distinct field
+  values as strings and `total` is the overall distinct count (before pagination).
+
+**Raises:**
+
+- <code>ValueError</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – Dict of the form `{"field_name": {"type": "<type>"}, ...}` where `<type>`
+  is one of `"text"`, `"number"`, or `"boolean"`.
+
+#### 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 of a metadata field across all documents.
+
+First attempts numeric comparison via `TO_NUMBER`, falling back to string comparison for
+non-numeric fields. Numeric strings are automatically converted to `int` or `float`.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name. May be prefixed with `"meta."`
+  (e.g. `"meta.year"` or `"year"`).
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – `{"min": <value>, "max": <value>}`. Both values are `None` when the table is
+  empty or the field does not exist.
+
+**Raises:**
+
+- <code>ValueError</code> – If `metadata_field` contains characters outside `[A-Za-z0-9_.]`.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int | None = None,
+) -> tuple[list[str], int]
+```
+
+Asynchronously returns a paginated list of distinct values for a metadata field, plus the total count.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name. May be prefixed with `"meta."`
+  (e.g. `"meta.lang"` or `"lang"`).
+- **search_term** (<code>str | None</code>) – Optional substring filter applied to both the document text and the field value.
+- **from\_** (<code>int</code>) – Zero-based offset for pagination. Defaults to `0`.
+- **size** (<code>int | None</code>) – Maximum number of values to return. When `None` all values from `from_` onward
+  are returned.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple `(values, total)` where `values` is the paginated list of distinct field
+  values as strings and `total` is the overall distinct count (before pagination).
+
+**Raises:**
+
+- <code>ValueError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OracleDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OracleDocumentStore</code> – Deserialized component.

docs-website/reference/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: <code>OpenAIChatGenerator</code>
+
+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** (<code>Secret</code>) – The OrcaRouter API key.
+- **model** (<code>str</code>) – 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** (<code>StreamingCallbackT | None</code>) – 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** (<code>str | None</code>) – The OrcaRouter API base URL. For more details, see the OrcaRouter
+  [documentation](https://docs.orcarouter.ai).
+- **organization** (<code>str | None</code>) – Your OrcaRouter organization ID, if any.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>bool</code>) – 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** (<code>float | None</code>) – The timeout for the OrcaRouter API call.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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).

docs-website/reference/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** (<code>str | None</code>) – Base URL for the PaddleOCR API. Falls back to `PADDLEOCR_BASE_URL`
+  env var, then the SDK default.
+- **access_token** (<code>Secret</code>) – PaddleOCR access token. Falls back to `PADDLEOCR_ACCESS_TOKEN` env var.
+- **model** (<code>Model | str</code>) – Document parsing model. Defaults to `Model.PADDLE_OCR_VL_16`.
+- **file_type** (<code>FileTypeInput</code>) – "pdf", "image", or None for auto-detection.
+- **use_doc_orientation_classify** (<code>bool | None</code>) – Enable document orientation classification.
+- **use_doc_unwarping** (<code>bool | None</code>) – Enable text image unwarping.
+- **use_layout_detection** (<code>bool | None</code>) – Enable layout detection.
+- **use_chart_recognition** (<code>bool | None</code>) – Enable chart recognition.
+- **use_seal_recognition** (<code>bool | None</code>) – Enable seal recognition.
+- **use_ocr_for_image_block** (<code>bool | None</code>) – Recognize text in image blocks.
+- **layout_threshold** (<code>float | dict | None</code>) – Layout detection threshold.
+- **layout_nms** (<code>bool | None</code>) – Perform NMS on layout detection results.
+- **layout_unclip_ratio** (<code>float | list | dict | None</code>) – Layout unclip ratio.
+- **layout_merge_bboxes_mode** (<code>str | dict | None</code>) – Layout merge bounding boxes mode.
+- **layout_shape_mode** (<code>str | None</code>) – Layout shape mode.
+- **prompt_label** (<code>str | None</code>) – Prompt type for the VLM ("ocr", "formula", "table", "chart", "seal", "spotting").
+- **format_block_content** (<code>bool | None</code>) – Format block content.
+- **repetition_penalty** (<code>float | None</code>) – Repetition penalty for VLM sampling.
+- **temperature** (<code>float | None</code>) – Temperature for VLM sampling.
+- **top_p** (<code>float | None</code>) – Top-p for VLM sampling.
+- **min_pixels** (<code>int | None</code>) – Minimum pixels for VLM preprocessing.
+- **max_pixels** (<code>int | None</code>) – Maximum pixels for VLM preprocessing.
+- **max_new_tokens** (<code>int | None</code>) – Maximum tokens generated by the VLM.
+- **merge_layout_blocks** (<code>bool | None</code>) – Merge layout detection boxes for cross-column content.
+- **markdown_ignore_labels** (<code>list\[str\] | None</code>) – Layout labels to ignore in Markdown output.
+- **vlm_extra_args** (<code>dict | None</code>) – Extra configuration for the VLM.
+- **prettify_markdown** (<code>bool | None</code>) – Prettify output Markdown.
+- **show_formula_number** (<code>bool | None</code>) – Include formula numbers in Markdown output.
+- **restructure_pages** (<code>bool | None</code>) – Restructure results across multiple pages.
+- **merge_tables** (<code>bool | None</code>) – Merge tables across pages.
+- **relevel_titles** (<code>bool | None</code>) – Relevel titles.
+- **visualize** (<code>bool | None</code>) – Return visualization results.
+- **additional_params** (<code>dict\[str, Any\] | None</code>) – Extra options passed to `PaddleOCRVLOptions.extra_options`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PaddleOCRVLDocumentConverter
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PaddleOCRVLDocumentConverter</code> – 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** (<code>list\[str | Path | ByteStream\]</code>) – List of image or PDF file paths or ByteStream objects.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the Documents. A single dict is applied
+  to all documents; a list must match the number of sources.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with:
+- `documents`: List of created Documents.
+- `raw_paddleocr_responses`: List of raw PaddleOCR API responses.

docs-website/reference/integrations-api/perplexity.md

@@ -0,0 +1,421 @@
+---
+title: "Perplexity"
+id: integrations-perplexity
+description: "Perplexity integration for Haystack"
+slug: "/integrations-perplexity"
+---
+
+
+## haystack_integrations.components.embedders.perplexity.document_embedder
+
+### PerplexityDocumentEmbedder
+
+Bases: <code>OpenAIDocumentEmbedder</code>
+
+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** (<code>Secret</code>) – The Perplexity API key.
+- **model** (<code>str</code>) – The name of the model to use.
+- **api_base_url** (<code>str | None</code>) – The Perplexity API base URL.
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **batch_size** (<code>int</code>) – Number of Documents to encode at once.
+- **progress_bar** (<code>bool</code>) – 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** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
+- **encoding_format** (<code>str</code>) – The Perplexity embedding encoding format. Supported values are `base64_int8` and `base64_binary`.
+- **timeout** (<code>float | None</code>) – Timeout for Perplexity client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PerplexityDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PerplexityDocumentEmbedder</code> – Deserialized component.
+
+## haystack_integrations.components.embedders.perplexity.text_embedder
+
+### PerplexityTextEmbedder
+
+Bases: <code>OpenAITextEmbedder</code>
+
+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** (<code>Secret</code>) – The Perplexity API key.
+- **model** (<code>str</code>) – The name of the Perplexity embedding model to be used.
+- **api_base_url** (<code>str | None</code>) – The Perplexity API base URL.
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **encoding_format** (<code>str</code>) – The Perplexity embedding encoding format. Supported values are `base64_int8` and `base64_binary`.
+- **timeout** (<code>float | None</code>) – Timeout for Perplexity client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PerplexityTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PerplexityTextEmbedder</code> – Deserialized component.
+
+## haystack_integrations.components.generators.perplexity.chat.chat_generator
+
+### PerplexityChatGenerator
+
+Bases: <code>OpenAIResponsesChatGenerator</code>
+
+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** (<code>Secret</code>) – The Perplexity API key.
+- **model** (<code>str</code>) – The Perplexity Agent API model to use.
+- **api_base_url** (<code>str | None</code>) – The Perplexity API base URL.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function called when a new token is received from the stream.
+- **organization** (<code>str | None</code>) – Organization ID forwarded to the OpenAI-compatible client.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional parameters sent directly to the Perplexity Agent API.
+- **tools** (<code>ToolsType | list\[dict\[str, Any\]\] | None</code>) – A list of Haystack tools, a Toolset, or OpenAI-compatible tool definitions.
+- **tools_strict** (<code>bool</code>) – Whether to enable strict schema adherence for Haystack tool calls.
+- **timeout** (<code>float | None</code>) – Timeout for Perplexity API calls.
+- **extra_headers** (<code>dict\[str, Any\] | None</code>) – Additional HTTP headers to include in requests to the Perplexity API.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to contact Perplexity after an internal error.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PerplexityChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>PerplexityChatGenerator</code> – 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** (<code>Secret</code>) – API key for Perplexity. Defaults to the `PERPLEXITY_API_KEY` environment variable.
+- **top_k** (<code>int | None</code>) – Maximum number of results to return. Maps to the `max_results` API parameter (1-20).
+- **search_params** (<code>dict\[str, Any\] | None</code>) – 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** (<code>float</code>) – Request timeout in seconds.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the sync and async HTTP clients.
+
+Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+
+#### run
+
+```python
+run(
+    query: str, search_params: dict[str, Any] | None = None
+) -> dict[str, list[Document] | list[str]]
+```
+
+Search the web using Perplexity and return results as Documents.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Search query string.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – Optional per-run override of search parameters.
+  If provided, fully replaces the init-time `search_params`.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | list\[str\]\]</code> – 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** (<code>str</code>) – Search query string.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – Optional per-run override of search parameters.
+  If provided, fully replaces the init-time `search_params`.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | list\[str\]\]</code> – A dictionary with:
+- `documents`: List of Documents containing search result content.
+- `links`: List of URLs from the search results.

docs-website/reference/integrations-api/pgvector.md

@@ -0,0 +1,891 @@
+---
+title: "Pgvector"
+id: integrations-pgvector
+description: "Pgvector integration for Haystack"
+slug: "/integrations-pgvector"
+---
+
+
+## haystack_integrations.components.retrievers.pgvector.embedding_retriever
+
+### PgvectorEmbeddingRetriever
+
+Retrieves documents from the `PgvectorDocumentStore`, based on their dense embeddings.
+
+Example usage:
+
+```python
+from haystack.document_stores import DuplicatePolicy
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack_integrations.components.retrievers.pgvector import PgvectorEmbeddingRetriever
+
+# Set an environment variable `PG_CONN_STR` with the connection string to your PostgreSQL database.
+# e.g., "postgresql://USER:PASSWORD@HOST:PORT/DB_NAME"
+
+document_store = PgvectorDocumentStore(
+    embedding_dimension=768,
+    vector_function="cosine_similarity",
+    recreate_table=True,
+)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+             Document(content="Elephants have been observed to behave in a way that indicates..."),
+             Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", PgvectorEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+res = query_pipeline.run({"text_embedder": {"text": query}})
+
+assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: PgvectorDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    vector_function: (
+        Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+    ) = None,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the PgvectorEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>PgvectorDocumentStore</code>) – An instance of `PgvectorDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – 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** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PgvectorEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PgvectorEmbeddingRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+    vector_function: (
+        Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+    ) = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `PgvectorDocumentStore`, based on their embeddings.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of Documents to return.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – The similarity function to use when searching for similar embeddings.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of Documents to return.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – The similarity function to use when searching for similar embeddings.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>PgvectorDocumentStore</code>) – An instance of `PgvectorDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `PgvectorDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PgvectorKeywordRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PgvectorKeywordRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `PgvectorDocumentStore`, based on keywords.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – String to search in `Document`s' content.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of Documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>str</code>) – String to search in `Document`s' content.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of Documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>Secret</code>) – 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** (<code>bool</code>) – 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** (<code>str</code>) – The name of the schema the table is created in. The schema must already exist.
+- **table_name** (<code>str</code>) – The name of the table to use to store Haystack documents.
+- **language** (<code>str</code>) – 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** (<code>int</code>) – The dimension of the embedding.
+- **vector_type** (<code>Literal['vector', 'halfvec']</code>) – 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** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance']</code>) – 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** (<code>bool</code>) – Whether to recreate the table if it already exists.
+- **search_strategy** (<code>Literal['exact_nearest_neighbor', 'hnsw']</code>) – 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** (<code>bool</code>) – Whether to recreate the HNSW index if it already exists.
+  Only used if search_strategy is set to `"hnsw"`.
+- **hnsw_index_creation_kwargs** (<code>dict\[str, int\] | None</code>) – 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** (<code>str</code>) – Index name for the HNSW index.
+- **hnsw_ef_search** (<code>int | None</code>) – 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** (<code>str</code>) – Index name for the Keyword index.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PgvectorDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PgvectorDocumentStore</code> – Deserialized component.
+
+#### 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:**
+
+- <code>int</code> – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+**Raises:**
+
+- <code>TypeError</code> – If `filters` is not a dictionary.
+- <code>ValueError</code> – 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** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+**Raises:**
+
+- <code>TypeError</code> – If `filters` is not a dictionary.
+- <code>ValueError</code> – 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** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` contains objects that are not of type `Document`.
+- <code>DuplicateDocumentError</code> – If a document with the same id already exists in the document store
+  and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+- <code>DocumentStoreError</code> – 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** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` contains objects that are not of type `Document`.
+- <code>DuplicateDocumentError</code> – If a document with the same id already exists in the document store
+  and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+- <code>DocumentStoreError</code> – 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** (<code>list\[str\]</code>) – 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** (<code>list\[str\]</code>) – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names to count unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names to count unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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** (<code>str</code>) – The name of the metadata field. Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – The name of the metadata field. Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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, from_: int, size: int
+) -> tuple[list[str], int]
+```
+
+Returns unique values for a given metadata field, optionally filtered by a search term.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The name of the metadata field. Can include or omit the "meta." prefix.
+- **search_term** (<code>str | None</code>) – Optional search term to filter documents by content before extracting unique values.
+  If None, all documents are considered.
+- **from\_** (<code>int</code>) – The offset for pagination (0-based).
+- **size** (<code>int</code>) – The number of unique values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing:
+- A list of unique values (as strings)
+- The total count of unique values
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str, search_term: str | None, from_: int, size: int
+) -> tuple[list[str], int]
+```
+
+Asynchronously returns unique values for a given metadata field, optionally filtered by a search term.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The name of the metadata field. Can include or omit the "meta." prefix.
+- **search_term** (<code>str | None</code>) – Optional search term to filter documents by content before extracting unique values.
+  If None, all documents are considered.
+- **from\_** (<code>int</code>) – The offset for pagination (0-based).
+- **size** (<code>int</code>) – The number of unique values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing:
+- A list of unique values (as strings)
+- The total count of unique values

docs-website/reference/integrations-api/pinecone.md

@@ -0,0 +1,702 @@
+---
+title: "Pinecone"
+id: integrations-pinecone
+description: "Pinecone integration for Haystack"
+slug: "/integrations-pinecone"
+---
+
+
+## haystack_integrations.components.retrievers.pinecone.embedding_retriever
+
+### PineconeEmbeddingRetriever
+
+Retrieves documents from the `PineconeDocumentStore`, based on their dense embeddings.
+
+Usage example:
+
+```python
+import os
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack_integrations.components.retrievers.pinecone import PineconeEmbeddingRetriever
+from haystack_integrations.document_stores.pinecone import PineconeDocumentStore
+
+os.environ["PINECONE_API_KEY"] = "YOUR_PINECONE_API_KEY"
+document_store = PineconeDocumentStore(index="my_index", namespace="my_namespace", dimension=768)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+             Document(content="Elephants have been observed to behave in a way that indicates..."),
+             Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", PineconeEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+res = query_pipeline.run({"text_embedder": {"text": query}})
+assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: PineconeDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the PineconeEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>PineconeDocumentStore</code>) – The Pinecone Document Store.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `PineconeDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PineconeEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PineconeEmbeddingRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `PineconeDocumentStore`, based on their dense embeddings.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of `Document`s to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of `Document`s to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>Secret</code>) – The Pinecone API key.
+- **index** (<code>str</code>) – The Pinecone index to connect to. If the index does not exist, it will be created.
+- **namespace** (<code>str</code>) – The Pinecone namespace to connect to. If the namespace does not exist, it will be created
+  at the first write.
+- **batch_size** (<code>int</code>) – 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** (<code>int</code>) – The dimension of the embeddings. This parameter is only used when creating a new index.
+- **spec** (<code>dict\[str, Any\] | None</code>) – 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** (<code>Literal['cosine', 'euclidean', 'dotproduct']</code>) – The metric to use for similarity search. This parameter is only used when creating a new index.
+- **show_progress** (<code>bool</code>) – Whether to show a progress bar when upserting documents. Set to False to disable
+  (e.g. in tests or scripts where quiet output is preferred).
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the associated synchronous resources.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the associated asynchronous resources. To be invoked manually when the Document Store is no longer needed.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PineconeDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PineconeDocumentStore</code> – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+  PineconeDocumentStore only supports `DuplicatePolicy.OVERWRITE`.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+  PineconeDocumentStore only supports `DuplicatePolicy.OVERWRITE`.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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** (<code>list\[str\]</code>) – 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** (<code>list\[str\]</code>) – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – 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** (<code>dict\[str, Any\]</code>) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents.
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents.
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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** (<code>str</code>) – The metadata field name to analyze.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – The metadata field name to analyze.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with 'min' and 'max' keys. Both values are None if the field has no
+  values (empty store, field absent, or unsupported field type).
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a metadata field with optional search and pagination.
+
+Note: This method fetches documents and extracts unique values in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field name to get unique values for.
+- **search_term** (<code>str | None</code>) – Optional search term to filter values (case-insensitive substring match).
+- **from\_** (<code>int</code>) – Starting offset for pagination (default: 0).
+- **size** (<code>int</code>) – Number of values to return (default: 10).
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – Tuple of (list of unique values, total count of matching values).
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously retrieves unique values for a metadata field with optional search and pagination.
+
+Note: This method fetches documents and extracts unique values in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field name to get unique values for.
+- **search_term** (<code>str | None</code>) – Optional search term to filter values (case-insensitive substring match).
+- **from\_** (<code>int</code>) – Starting offset for pagination (default: 0).
+- **size** (<code>int</code>) – Number of values to return (default: 10).
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – Tuple of (list of unique values, total count of matching values).

docs-website/reference/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** (<code>str</code>) – 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** (<code>list\[str\] | None</code>) – 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** (<code>float</code>) – 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** (<code>list\[dict\[str, str\]\] | None</code>) – 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** (<code>list\[Document\]</code>) – List of Documents to analyze for PII entities.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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. `<PERSON>`, `<EMAIL_ADDRESS>`). Original Documents are not mutated.
+
+Documents without text content are passed through unchanged.
+
+The analyzer and anonymizer engines are 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.preprocessors.presidio import PresidioDocumentCleaner
+
+cleaner = PresidioDocumentCleaner()
+result = cleaner.run(documents=[Document(content="My name is John and my email is john@example.com")])
+print(result["documents"][0].content)
+# My name is <PERSON> and my email is <EMAIL_ADDRESS>
+```
+
+#### 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 PresidioDocumentCleaner.
+
+**Parameters:**
+
+- **language** (<code>str</code>) – 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** (<code>list\[str\] | None</code>) – 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** (<code>float</code>) – 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** (<code>list\[dict\[str, str\]\] | None</code>) – 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** (<code>list\[Document\]</code>) – List of Documents whose text content will be anonymized.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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. `<PERSON>`).
+Useful for sanitizing user queries before they are sent to an LLM.
+
+The analyzer and anonymizer engines are loaded on the first call to `run()`,
+or by calling `warm_up()` explicitly beforehand.
+
+### Usage example
+
+```python
+from haystack_integrations.components.preprocessors.presidio import PresidioTextCleaner
+
+cleaner = PresidioTextCleaner()
+result = cleaner.run(texts=["Hi, I am John Smith, call me at 212-555-1234"])
+print(result["texts"][0])
+# Hi, I am <PERSON>, call me at <PHONE_NUMBER>
+```
+
+#### 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 PresidioTextCleaner.
+
+**Parameters:**
+
+- **language** (<code>str</code>) – 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** (<code>list\[str\] | None</code>) – 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** (<code>float</code>) – 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** (<code>list\[dict\[str, str\]\] | None</code>) – 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** (<code>list\[str\]</code>) – List of strings to anonymize.
+
+**Returns:**
+
+- <code>dict\[str, list\[str\]\]</code> – A dictionary with key `texts` containing the cleaned strings.

docs-website/reference/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 <https://github.com/Pringled/pyversity>`\_.
+
+Wraps pyversity's diversification algorithms as a Haystack `@component`,
+making it easy to drop result diversification into any Haystack pipeline.
+
+### PyversityRanker
+
+Reranks documents using [pyversity](https://github.com/Pringled/pyversity)'s diversification algorithms.
+
+Balances relevance and diversity in a ranked list of documents. Documents
+must have both `score` and `embedding` populated (e.g. as returned by
+a dense retriever with `return_embedding=True`).
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.pyversity import PyversityRanker
+from pyversity import Strategy
+
+ranker = PyversityRanker(top_k=5, strategy=Strategy.MMR, diversity=0.5)
+
+docs = [
+    Document(content="Paris", score=0.9, embedding=[0.1, 0.2]),
+    Document(content="Berlin", score=0.8, embedding=[0.3, 0.4]),
+]
+output = ranker.run(documents=docs)
+docs = output["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+    top_k: int | None = None,
+    *,
+    strategy: Strategy = Strategy.DPP,
+    diversity: float = 0.5
+) -> None
+```
+
+Creates an instance of PyversityRanker.
+
+**Parameters:**
+
+- **top_k** (<code>int | None</code>) – Number of documents to return after diversification.
+  If `None`, all documents are returned in diversified order.
+- **strategy** (<code>Strategy</code>) – Pyversity diversification strategy (e.g. `Strategy.MMR`). Defaults to `Strategy.DPP`.
+- **diversity** (<code>float</code>) – 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:**
+
+- <code>ValueError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PyversityRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PyversityRanker</code> – 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** (<code>list\[Document\]</code>) – List of Documents to rerank. Each document must have `score` and `embedding` set.
+- **top_k** (<code>int | None</code>) – Overrides the initialized `top_k` for this call. `None` falls back to the initialized value.
+- **strategy** (<code>Strategy | None</code>) – Overrides the initialized `strategy` for this call. `None` falls back to the initialized value.
+- **diversity** (<code>float | None</code>) – Overrides the initialized `diversity` for this call.
+  `None` falls back to the initialized value.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of up to `top_k` reranked Documents, ordered by the diversification algorithm.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not a positive integer or `diversity` is not in [0, 1].

docs-website/reference/integrations-api/ragas.md

@@ -0,0 +1,161 @@
+---
+title: "Ragas"
+id: integrations-ragas
+description: "Ragas integration for Haystack"
+slug: "/integrations-ragas"
+---
+
+
+## haystack_integrations.components.evaluators.ragas.evaluator
+
+### RagasEvaluator
+
+A component that uses the Ragas framework to evaluate inputs against specified Ragas metrics.
+
+See the [Ragas framework](https://docs.ragas.io/) for more details.
+
+This component supports the modern Ragas metrics API (`ragas.metrics.collections`).
+Each metric must be a `SimpleBaseMetric` instance with its LLM configured at construction time.
+
+Usage example:
+
+```python
+from openai import AsyncOpenAI
+from ragas.llms import llm_factory
+from ragas.metrics.collections import Faithfulness
+from haystack_integrations.components.evaluators.ragas import RagasEvaluator
+
+client = AsyncOpenAI()
+llm = llm_factory("gpt-4o-mini", client=client)
+
+evaluator = RagasEvaluator(
+    ragas_metrics=[Faithfulness(llm=llm)],
+)
+output = evaluator.run(
+    query="Which is the most popular global sport?",
+    documents=[
+        "Football is undoubtedly the world's most popular sport with"
+        " major events like the FIFA World Cup and sports personalities"
+        " like Ronaldo and Messi, drawing a followership of more than 4"
+        " billion people."
+    ],
+    reference="Football is the most popular sport with around 4 billion"
+              " followers worldwide",
+)
+
+output['result']
+```
+
+#### __init__
+
+```python
+__init__(
+    ragas_metrics: list[SimpleBaseMetric], concurrency_limit: int = 4
+) -> None
+```
+
+Constructs a new Ragas evaluator.
+
+**Parameters:**
+
+- **ragas_metrics** (<code>list\[SimpleBaseMetric\]</code>) – 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** (<code>int</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> RagasEvaluator
+```
+
+Deserialize this component from a dictionary.
+
+Metrics are reconstructed from their stored class path and LLM/embedding
+configuration. Only the `openai` provider is supported for automatic
+deserialization; the API key is read from the `OPENAI_API_KEY` environment
+variable at load time.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>RagasEvaluator</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query: str | None = None,
+    response: list[ChatMessage] | str | None = None,
+    documents: list[Document | str] | None = None,
+    reference_contexts: list[str] | None = None,
+    multi_responses: list[str] | None = None,
+    reference: str | None = None,
+    rubrics: dict[str, str] | None = None,
+) -> dict[str, dict[str, MetricResult]]
+```
+
+Evaluates the provided inputs against each metric and returns the results.
+
+**Parameters:**
+
+- **query** (<code>str | None</code>) – The input query from the user.
+- **response** (<code>list\[ChatMessage\] | str | None</code>) – A list of ChatMessage responses (typically from a language model or agent).
+- **documents** (<code>list\[Document | str\] | None</code>) – A list of Haystack Document or strings that were retrieved for the query.
+- **reference_contexts** (<code>list\[str\] | None</code>) – A list of reference contexts that should have been retrieved for the query.
+- **multi_responses** (<code>list\[str\] | None</code>) – List of multiple responses generated for the query.
+- **reference** (<code>str | None</code>) – A string reference answer for the query.
+- **rubrics** (<code>dict\[str, str\] | None</code>) – A dictionary of evaluation rubric, where keys represent the score
+  and the values represent the corresponding evaluation criteria.
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, MetricResult\]\]</code> – 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** (<code>str | None</code>) – The input query from the user.
+- **response** (<code>list\[ChatMessage\] | str | None</code>) – A list of ChatMessage responses (typically from a language model or agent).
+- **documents** (<code>list\[Document | str\] | None</code>) – A list of Haystack Document or strings that were retrieved for the query.
+- **reference_contexts** (<code>list\[str\] | None</code>) – A list of reference contexts that should have been retrieved for the query.
+- **multi_responses** (<code>list\[str\] | None</code>) – List of multiple responses generated for the query.
+- **reference** (<code>str | None</code>) – A string reference answer for the query.
+- **rubrics** (<code>dict\[str, str\] | None</code>) – A dictionary of evaluation rubric, where keys represent the score
+  and the values represent the corresponding evaluation criteria.
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, MetricResult\]\]</code> – A dictionary with key `result` mapping metric names to their `MetricResult`.

docs-website/reference/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** (<code>Secret</code>) – API key for the SearchApi API
+- **top_k** (<code>int | None</code>) – Number of documents to return.
+- **allowed_domains** (<code>list\[str\] | None</code>) – List of domains to limit the search to.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SearchApiWebSearch
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SearchApiWebSearch</code> – 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** (<code>str</code>) – Search query.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | list\[str\]\]</code> – 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:**
+
+- <code>TimeoutError</code> – If the request to the SearchApi API times out.
+- <code>SearchApiError</code> – 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** (<code>str</code>) – Search query.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | list\[str\]\]</code> – 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:**
+
+- <code>TimeoutError</code> – If the request to the SearchApi API times out.
+- <code>SearchApiError</code> – If an error occurs while querying the SearchApi API.

docs-website/reference/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** (<code>Secret</code>) – API key for the Serper API.
+- **top_k** (<code>int | None</code>) – Number of documents to return.
+- **allowed_domains** (<code>list\[str\] | None</code>) – List of domains to limit the search to.
+- **exclude_subdomains** (<code>bool</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SerperDevWebSearch
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SerperDevWebSearch</code> – 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** (<code>str</code>) – Search query.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | list\[str\]\]</code> – 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:**
+
+- <code>SerperDevError</code> – If an error occurs while querying the SerperDev API.
+- <code>TimeoutError</code> – 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** (<code>str</code>) – Search query.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | list\[str\]\]</code> – 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:**
+
+- <code>SerperDevError</code> – If an error occurs while querying the SerperDev API.
+- <code>TimeoutError</code> – If the request to the SerperDev API times out.

docs-website/reference/integrations-api/snowflake.md

@@ -0,0 +1,209 @@
+---
+title: "Snowflake"
+id: integrations-snowflake
+description: "Snowflake integration for Haystack"
+slug: "/integrations-snowflake"
+---
+
+<a id="haystack_integrations.components.retrievers.snowflake.snowflake_table_retriever"></a>
+
+## Module haystack\_integrations.components.retrievers.snowflake.snowflake\_table\_retriever
+
+<a id="haystack_integrations.components.retrievers.snowflake.snowflake_table_retriever.SnowflakeTableRetriever"></a>
+
+### 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="<ACCOUNT-USER>",
+    account="<ACCOUNT-IDENTIFIER>",
+    authenticator="SNOWFLAKE",
+    api_key=Secret.from_env_var("SNOWFLAKE_API_KEY"),
+    database="<DATABASE-NAME>",
+    db_schema="<SCHEMA-NAME>",
+    warehouse="<WAREHOUSE-NAME>",
+)
+executor.warm_up()
+```
+
+#### Key-pair Authentication (MFA):
+```python
+executor = SnowflakeTableRetriever(
+    user="<ACCOUNT-USER>",
+    account="<ACCOUNT-IDENTIFIER>",
+    authenticator="SNOWFLAKE_JWT",
+    private_key_file=Secret.from_env_var("SNOWFLAKE_PRIVATE_KEY_FILE"),
+    private_key_file_pwd=Secret.from_env_var("SNOWFLAKE_PRIVATE_KEY_PWD"),
+    database="<DATABASE-NAME>",
+    db_schema="<SCHEMA-NAME>",
+    warehouse="<WAREHOUSE-NAME>",
+)
+executor.warm_up()
+```
+
+#### OAuth Authentication (MFA):
+```python
+executor = SnowflakeTableRetriever(
+    user="<ACCOUNT-USER>",
+    account="<ACCOUNT-IDENTIFIER>",
+    authenticator="OAUTH",
+    oauth_client_id=Secret.from_env_var("SNOWFLAKE_OAUTH_CLIENT_ID"),
+    oauth_client_secret=Secret.from_env_var("SNOWFLAKE_OAUTH_CLIENT_SECRET"),
+    oauth_token_request_url="<TOKEN-REQUEST-URL>",
+    database="<DATABASE-NAME>",
+    db_schema="<SCHEMA-NAME>",
+    warehouse="<WAREHOUSE-NAME>",
+)
+executor.warm_up()
+```
+
+#### Running queries:
+```python
+query = "SELECT * FROM table_name"
+results = executor.run(query=query)
+
+>> print(results["dataframe"].head(2))
+
+    column1  column2        column3
+0     123   'data1'  2024-03-20
+1     456   'data2'  2024-03-21
+
+>> print(results["table"])
+
+shape: (3, 3)
+| column1 | column2 | column3    |
+|---------|---------|------------|
+| int     | str     | date       |
+|---------|---------|------------|
+| 123     | data1   | 2024-03-20 |
+| 456     | data2   | 2024-03-21 |
+| 789     | data3   | 2024-03-22 |
+```
+
+<a id="haystack_integrations.components.retrievers.snowflake.snowflake_table_retriever.SnowflakeTableRetriever.__init__"></a>
+
+#### SnowflakeTableRetriever.\_\_init\_\_
+
+```python
+def __init__(user: str,
+             account: str,
+             authenticator: Literal["SNOWFLAKE", "SNOWFLAKE_JWT",
+                                    "OAUTH"] = "SNOWFLAKE",
+             api_key: Secret | None = Secret.from_env_var("SNOWFLAKE_API_KEY",
+                                                          strict=False),
+             database: str | None = None,
+             db_schema: str | None = None,
+             warehouse: str | None = None,
+             login_timeout: int | None = 60,
+             return_markdown: bool = True,
+             private_key_file: Secret | None = Secret.from_env_var(
+                 "SNOWFLAKE_PRIVATE_KEY_FILE", strict=False),
+             private_key_file_pwd: Secret | None = Secret.from_env_var(
+                 "SNOWFLAKE_PRIVATE_KEY_PWD", strict=False),
+             oauth_client_id: Secret | None = Secret.from_env_var(
+                 "SNOWFLAKE_OAUTH_CLIENT_ID", strict=False),
+             oauth_client_secret: Secret | None = Secret.from_env_var(
+                 "SNOWFLAKE_OAUTH_CLIENT_SECRET", strict=False),
+             oauth_token_request_url: str | None = None,
+             oauth_authorization_url: str | None = None) -> None
+```
+
+**Arguments**:
+
+- `user`: User's login.
+- `account`: Snowflake account identifier.
+- `authenticator`: Authentication method. Required. Options: "SNOWFLAKE" (password),
+"SNOWFLAKE_JWT" (key-pair), or "OAUTH".
+- `api_key`: Snowflake account password. Required for SNOWFLAKE authentication.
+- `database`: Name of the database to use.
+- `db_schema`: Name of the schema to use.
+- `warehouse`: Name of the warehouse to use.
+- `login_timeout`: Timeout in seconds for login.
+- `return_markdown`: Whether to return a Markdown-formatted string of the DataFrame.
+- `private_key_file`: Secret containing the path to private key file.
+Required for SNOWFLAKE_JWT authentication.
+- `private_key_file_pwd`: Secret containing the passphrase for private key file.
+Required only when the private key file is encrypted.
+- `oauth_client_id`: Secret containing the OAuth client ID.
+Required for OAUTH authentication.
+- `oauth_client_secret`: Secret containing the OAuth client secret.
+Required for OAUTH authentication.
+- `oauth_token_request_url`: OAuth token request URL for Client Credentials flow.
+- `oauth_authorization_url`: OAuth authorization URL for Authorization Code flow.
+
+<a id="haystack_integrations.components.retrievers.snowflake.snowflake_table_retriever.SnowflakeTableRetriever.warm_up"></a>
+
+#### SnowflakeTableRetriever.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Warm up the component by initializing the authenticator handler and testing the database connection.
+
+<a id="haystack_integrations.components.retrievers.snowflake.snowflake_table_retriever.SnowflakeTableRetriever.to_dict"></a>
+
+#### SnowflakeTableRetriever.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.retrievers.snowflake.snowflake_table_retriever.SnowflakeTableRetriever.from_dict"></a>
+
+#### SnowflakeTableRetriever.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "SnowflakeTableRetriever"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.retrievers.snowflake.snowflake_table_retriever.SnowflakeTableRetriever.run"></a>
+
+#### SnowflakeTableRetriever.run
+
+```python
+@component.output_types(dataframe=DataFrame, table=str)
+def run(query: str,
+        return_markdown: bool | None = None) -> dict[str, DataFrame | str]
+```
+
+Executes a SQL query against a Snowflake database using ADBC and Polars.
+
+**Arguments**:
+
+- `query`: The SQL query to execute.
+- `return_markdown`: Whether to return a Markdown-formatted string of the DataFrame.
+If not provided, uses the value set during initialization.
+
+**Returns**:
+
+A dictionary containing:
+- `"dataframe"`: A Pandas DataFrame with the query results.
+- `"table"`: A Markdown-formatted string representation of the DataFrame.
+

docs-website/reference/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** (<code>str</code>) – Entity label.
+- **start** (<code>int</code>) – Start index of the entity in the document.
+- **end** (<code>int</code>) – End index of the entity in the document.
+- **score** (<code>float | None</code>) – 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** (<code>str</code>) – Name of the spaCy model or a path to the model on
+  the local disk.
+- **pipeline_kwargs** (<code>dict\[str, Any\] | None</code>) – Keyword arguments passed to the pipeline. The
+  pipeline can override these arguments.
+- **device** (<code>ComponentDevice | None</code>) – The device on which the model is loaded. If `None`,
+  the default device is automatically selected.
+
+**Raises:**
+
+- <code>ValueError</code> – If the device represents multiple devices, which the
+  spaCy backend does not support.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the component.
+
+**Raises:**
+
+- <code>ComponentError</code> – 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** (<code>list\[Document\]</code>) – Documents to process.
+- **batch_size** (<code>int</code>) – Batch size used for processing the documents.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Processed documents.
+
+**Raises:**
+
+- <code>ComponentError</code> – If the model fails to process a document.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SpacyNamedEntityExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SpacyNamedEntityExtractor</code> – 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** (<code>Document</code>) – Document whose annotations are to be fetched.
+
+**Returns:**
+
+- <code>list\[NamedEntityAnnotation\] | None</code> – The stored annotations.

docs-website/reference/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** (<code>str</code>) – The SQLAlchemy driver name (e.g., `"sqlite"`,
+  `"postgresql+psycopg2"`).
+- **username** (<code>str | None</code>) – Database username.
+- **password** (<code>Secret | None</code>) – Database password as a Haystack `Secret`.
+- **host** (<code>str | None</code>) – Database host.
+- **port** (<code>int | None</code>) – Database port.
+- **database** (<code>str | None</code>) – Database name or path (e.g., `":memory:"` for SQLite in-memory).
+- **init_script** (<code>list\[str\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SQLAlchemyTableRetriever
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SQLAlchemyTableRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(query: str) -> dict[str, Any]
+```
+
+Execute a SQL query and return the results.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The SQL query to execute.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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.

docs-website/reference/integrations-api/stackit.md

@@ -0,0 +1,295 @@
+---
+title: "STACKIT"
+id: integrations-stackit
+description: "STACKIT integration for Haystack"
+slug: "/integrations-stackit"
+---
+
+
+## haystack_integrations.components.embedders.stackit.document_embedder
+
+### STACKITDocumentEmbedder
+
+Bases: <code>OpenAIDocumentEmbedder</code>
+
+A component for computing Document embeddings using STACKIT as model provider.
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.stackit import STACKITDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = STACKITDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "intfloat/e5-mistral-7b-instruct",
+    "Qwen/Qwen3-VL-Embedding-8B",
+]
+
+```
+
+A non-exhaustive list of embedding models supported by this component.
+See https://docs.stackit.cloud/products/data-and-ai/ai-model-serving/basics/available-shared-models
+for the full list.
+
+#### __init__
+
+```python
+__init__(
+    model: str,
+    api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"),
+    api_base_url: (
+        str | None
+    ) = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1",
+    prefix: str = "",
+    suffix: str = "",
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates a STACKITDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The STACKIT API key.
+- **model** (<code>str</code>) – The name of the model to use.
+- **api_base_url** (<code>str | None</code>) – 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** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **batch_size** (<code>int</code>) – Number of Documents to encode at once.
+- **progress_bar** (<code>bool</code>) – 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** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
+- **timeout** (<code>float | None</code>) – Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.components.embedders.stackit.text_embedder
+
+### STACKITTextEmbedder
+
+Bases: <code>OpenAITextEmbedder</code>
+
+A component for embedding strings using STACKIT as model provider.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.stackit import STACKITTextEmbedder
+
+text_to_embed = "I love pizza!"
+text_embedder = STACKITTextEmbedder()
+print(text_embedder.run(text_to_embed))
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "intfloat/e5-mistral-7b-instruct",
+    "Qwen/Qwen3-VL-Embedding-8B",
+]
+
+```
+
+A non-exhaustive list of embedding models supported by this component.
+See https://docs.stackit.cloud/products/data-and-ai/ai-model-serving/basics/available-shared-models
+for the full list.
+
+#### __init__
+
+```python
+__init__(
+    model: str,
+    api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"),
+    api_base_url: (
+        str | None
+    ) = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1",
+    prefix: str = "",
+    suffix: str = "",
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates a STACKITTextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The STACKIT API key.
+- **model** (<code>str</code>) – The name of the STACKIT embedding model to be used.
+- **api_base_url** (<code>str | None</code>) – 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** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **timeout** (<code>float | None</code>) – Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.components.generators.stackit.chat.chat_generator
+
+### STACKITChatGenerator
+
+Bases: <code>OpenAIChatGenerator</code>
+
+Enables text generation using STACKIT generative models through their model serving service.
+
+Users can pass any text generation parameters valid for the STACKIT Chat Completion API
+directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage)
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.stackit import STACKITChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = STACKITChatGenerator(model="neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8")
+
+result = generator.run([ChatMessage.from_user("Tell me a joke.")])
+print(result)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "Qwen/Qwen3-VL-235B-A22B-Instruct-FP8",
+    "cortecs/Llama-3.3-70B-Instruct-FP8-Dynamic",
+    "openai/gpt-oss-120b",
+    "google/gemma-3-27b-it",
+    "openai/gpt-oss-20b",
+    "neuralmagic/Mistral-Nemo-Instruct-2407-FP8",
+    "neuralmagic/Meta-Llama-3.1-8B-Instruct-FP8",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+See https://docs.stackit.cloud/products/data-and-ai/ai-model-serving/basics/available-shared-models
+for the full list.
+
+#### __init__
+
+```python
+__init__(
+    model: str,
+    api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"),
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: (
+        str | None
+    ) = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1",
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates an instance of STACKITChatGenerator class.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the chat completion model to use.
+- **api_key** (<code>Secret</code>) – The STACKIT API key.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>str | None</code>) – The STACKIT API Base url.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>float | None</code>) – Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.

docs-website/reference/integrations-api/supabase.md

@@ -0,0 +1,444 @@
+---
+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://<project-ref>.supabase.co",
+    supabase_key=Secret.from_env_var("SUPABASE_SERVICE_KEY"),
+    bucket_name="my-documents",
+)
+result = downloader.run(sources=["reports/report.pdf", "data/notes.txt"])
+streams = result["streams"]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    supabase_url: str,
+    supabase_key: Secret = Secret.from_env_var("SUPABASE_SERVICE_KEY"),
+    bucket_name: str,
+    file_extensions: list[str] | None = None
+) -> None
+```
+
+Creates a new SupabaseBucketDownloader instance.
+
+**Parameters:**
+
+- **supabase_url** (<code>str</code>) – The URL of your Supabase project, e.g. `https://<project-ref>.supabase.co`.
+- **supabase_key** (<code>Secret</code>) – 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** (<code>str</code>) – The name of the Supabase Storage bucket to download files from.
+- **file_extensions** (<code>list\[str\] | None</code>) – 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** (<code>list\[str\]</code>) – List of file paths within the bucket to download,
+  e.g. `["folder/file.pdf", "notes.txt"]`.
+
+**Returns:**
+
+- <code>dict\[str, list\[ByteStream\]\]</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabaseBucketDownloader
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SupabaseBucketDownloader</code> – Deserialized component.
+
+## haystack_integrations.components.retrievers.supabase.embedding_retriever
+
+### SupabasePgvectorEmbeddingRetriever
+
+Bases: <code>PgvectorEmbeddingRetriever</code>
+
+Retrieves documents from the `SupabasePgvectorDocumentStore`, based on their dense embeddings.
+
+This is a thin wrapper around `PgvectorEmbeddingRetriever`, adapted for use with
+`SupabasePgvectorDocumentStore`.
+
+Example usage:
+
+# Set an environment variable `SUPABASE_DB_URL` with the connection string to your Supabase database.
+
+```bash
+export SUPABASE_DB_URL=postgresql://postgres:postgres@localhost:5432/postgres
+```
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.types.policy import DuplicatePolicy
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+
+from haystack_integrations.document_stores.supabase import SupabasePgvectorDocumentStore
+from haystack_integrations.components.retrievers.supabase import SupabasePgvectorEmbeddingRetriever
+
+document_store = SupabasePgvectorDocumentStore(
+    embedding_dimension=768,
+    vector_function="cosine_similarity",
+    recreate_table=True,
+)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+             Document(content="Elephants have been observed to behave in a way that indicates..."),
+             Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", SupabasePgvectorEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+res = query_pipeline.run({"text_embedder": {"text": query}})
+print(res['retriever']['documents'][0].content)
+# >> "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: SupabasePgvectorDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    vector_function: (
+        Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+    ) = None,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the SupabasePgvectorEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>SupabasePgvectorDocumentStore</code>) – An instance of `SupabasePgvectorDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – 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** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabasePgvectorEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SupabasePgvectorEmbeddingRetriever</code> – Deserialized component.
+
+## haystack_integrations.components.retrievers.supabase.keyword_retriever
+
+### SupabasePgvectorKeywordRetriever
+
+Bases: <code>PgvectorKeywordRetriever</code>
+
+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** (<code>SupabasePgvectorDocumentStore</code>) – An instance of `SupabasePgvectorDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `SupabasePgvectorDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabasePgvectorKeywordRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SupabasePgvectorKeywordRetriever</code> – Deserialized component.
+
+## haystack_integrations.document_stores.supabase.document_store
+
+### SupabasePgvectorDocumentStore
+
+Bases: <code>PgvectorDocumentStore</code>
+
+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** (<code>Secret</code>) – 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** (<code>bool</code>) – Whether to create the pgvector extension if it doesn't exist.
+  Defaults to `False` since Supabase has pgvector pre-installed.
+- **schema_name** (<code>str</code>) – The name of the schema the table is created in.
+- **table_name** (<code>str</code>) – The name of the table to use to store Haystack documents.
+- **language** (<code>str</code>) – The language to be used to parse query and document content in keyword retrieval.
+- **embedding_dimension** (<code>int</code>) – The dimension of the embedding.
+- **vector_type** (<code>Literal['vector', 'halfvec']</code>) – The type of vector used for embedding storage. `"vector"` or `"halfvec"`.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance']</code>) – The similarity function to use when searching for similar embeddings.
+- **recreate_table** (<code>bool</code>) – Whether to recreate the table if it already exists.
+- **search_strategy** (<code>Literal['exact_nearest_neighbor', 'hnsw']</code>) – The search strategy to use: `"exact_nearest_neighbor"` or `"hnsw"`.
+- **hnsw_recreate_index_if_exists** (<code>bool</code>) – Whether to recreate the HNSW index if it already exists.
+- **hnsw_index_creation_kwargs** (<code>dict\[str, int\] | None</code>) – Additional keyword arguments for HNSW index creation.
+- **hnsw_index_name** (<code>str</code>) – Index name for the HNSW index.
+- **hnsw_ef_search** (<code>int | None</code>) – The `ef_search` parameter to use at query time for HNSW.
+- **keyword_index_name** (<code>str</code>) – Index name for the Keyword index.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabasePgvectorDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SupabasePgvectorDocumentStore</code> – Deserialized component.

docs-website/reference/integrations-api/tavily.md

@@ -0,0 +1,107 @@
+---
+title: "Tavily"
+id: integrations-tavily
+description: "Tavily integration for Haystack"
+slug: "/integrations-tavily"
+---
+
+
+## haystack_integrations.components.websearch.tavily.tavily_websearch
+
+### TavilyWebSearch
+
+A component that uses Tavily to search the web and return results as Haystack Documents.
+
+This component wraps the Tavily Search API, enabling web search queries that return
+structured documents with content and links.
+
+Tavily is an AI-powered search API optimized for LLM applications. You need a Tavily
+API key from [tavily.com](https://tavily.com).
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.tavily import TavilyWebSearch
+from haystack.utils import Secret
+
+websearch = TavilyWebSearch(
+    api_key=Secret.from_env_var("TAVILY_API_KEY"),
+    top_k=5,
+)
+result = websearch.run(query="What is Haystack by deepset?")
+documents = result["documents"]
+links = result["links"]
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("TAVILY_API_KEY"),
+    top_k: int | None = 10,
+    search_params: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the TavilyWebSearch component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – API key for Tavily. Defaults to the `TAVILY_API_KEY` environment variable.
+- **top_k** (<code>int | None</code>) – Maximum number of results to return.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – Additional parameters passed to the Tavily search API.
+  See the [Tavily API reference](https://docs.tavily.com/docs/tavily-api/rest_api)
+  for available options. Supported keys include: `search_depth`, `include_answer`,
+  `include_raw_content`, `include_domains`, `exclude_domains`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Tavily sync and async clients.
+
+Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+
+#### run
+
+```python
+run(query: str, search_params: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Search the web using Tavily and return results as Documents.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Search query string.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – Optional per-run override of search parameters.
+  If provided, fully replaces the init-time `search_params`.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>str</code>) – Search query string.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – Optional per-run override of search parameters.
+  If provided, fully replaces the init-time `search_params`.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with:
+- `documents`: List of Documents containing search result content.
+- `links`: List of URLs from the search results.

docs-website/reference/integrations-api/tika.md

@@ -0,0 +1,128 @@
+---
+title: "Tika"
+id: integrations-tika
+description: "Tika integration for Haystack"
+slug: "/integrations-tika"
+---
+
+
+## haystack_integrations.components.converters.tika.converter
+
+### XHTMLParser
+
+Bases: <code>HTMLParser</code>
+
+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** (<code>str</code>) – The HTML tag name.
+- **attrs** (<code>list\[tuple\[str, str | None\]\]</code>) – The HTML tag attributes.
+
+#### handle_endtag
+
+```python
+handle_endtag(tag: str) -> None
+```
+
+Identify the end of a page div.
+
+**Parameters:**
+
+- **tag** (<code>str</code>) – The HTML tag name.
+
+#### handle_data
+
+```python
+handle_data(data: str) -> None
+```
+
+Populate the page content.
+
+**Parameters:**
+
+- **data** (<code>str</code>) – 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.
+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** (<code>str</code>) – Tika server URL.
+- **store_full_path** (<code>bool</code>) – 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** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths or ByteStream objects.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – 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:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: Created Documents

docs-website/reference/integrations-api/togetherai.md

@@ -0,0 +1,282 @@
+---
+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: <code>OpenAIChatGenerator</code>
+
+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=<ChatRole.ASSISTANT: 'assistant'>, _name=None,
+>>_meta={'model': 'meta-llama/Llama-3.3-70B-Instruct-Turbo', 'index': 0, 'finish_reason': 'stop',
+>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]}
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("TOGETHER_API_KEY"),
+    model: str = "meta-llama/Llama-3.3-70B-Instruct-Turbo",
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: str | None = "https://api.together.xyz/v1",
+    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 TogetherAIChatGenerator.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Together API key.
+- **model** (<code>str</code>) – The name of the Together AI chat completion model to use.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>str | None</code>) – The Together AI API Base url.
+  For more details, see Together AI [docs](https://docs.together.ai/docs/openai-api-compatibility).
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>ToolsType | None</code>) – 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** (<code>float | None</code>) – The timeout for the Together AI API call.
+- **max_retries** (<code>int | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+## haystack_integrations.components.generators.togetherai.generator
+
+### TogetherAIGenerator
+
+Bases: <code>TogetherAIChatGenerator</code>
+
+Provides an interface to generate text using an LLM running on Together AI.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.togetherai import TogetherAIGenerator
+
+generator = TogetherAIGenerator(model="deepseek-ai/DeepSeek-R1",
+                            generation_kwargs={
+                            "temperature": 0.9,
+                            })
+
+print(generator.run("Who is the best Italian actor?"))
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("TOGETHER_API_KEY"),
+    model: str = "meta-llama/Llama-3.3-70B-Instruct-Turbo",
+    api_base_url: str | None = "https://api.together.xyz/v1",
+    streaming_callback: StreamingCallbackT | None = None,
+    system_prompt: str | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+) -> None
+```
+
+Initialize the TogetherAIGenerator.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Together API key.
+- **model** (<code>str</code>) – The name of the model to use.
+- **api_base_url** (<code>str | None</code>) – The base URL of the Together AI API.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts StreamingChunk as an argument.
+- **system_prompt** (<code>str | None</code>) – The system prompt to use for text generation. If not provided, the system prompt is
+  omitted, and the default system prompt of the model is used.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Other parameters to use for the model. These parameters are all sent directly to
+  the Together AI endpoint. See Together AI
+  [documentation](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.
+- `n`: How many completions to generate for each prompt. For example, if the LLM gets 3 prompts and n is 2,
+  it will generate two completions for each of the three prompts, ending up with 6 completions in total.
+- `stop`: One or more sequences after which the LLM should stop generating tokens.
+- `presence_penalty`: What penalty to apply if a token is already present at all. Bigger values mean
+  the model will be less likely to repeat the same token in the text.
+- `frequency_penalty`: What penalty to apply if a token has already been generated in the text.
+  Bigger values mean the model will be less likely to repeat the same token in the text.
+- `logit_bias`: Add a logit bias to specific tokens. The keys of the dictionary are tokens, and the
+  values are the bias to add to that token.
+- **timeout** (<code>float | None</code>) – Timeout for together.ai Client calls, if not set it is inferred from the `OPENAI_TIMEOUT` environment
+  variable or set to 30.
+- **max_retries** (<code>int | None</code>) – Maximum retries to establish contact with Together AI if it returns an internal error, if not set it is
+  inferred from the `OPENAI_MAX_RETRIES` environment variable or set to 5.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TogetherAIGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>TogetherAIGenerator</code> – The deserialized component instance.
+
+#### run
+
+```python
+run(
+    *,
+    prompt: str,
+    system_prompt: str | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Generate text completions synchronously.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – The input prompt string for text generation.
+- **system_prompt** (<code>str | None</code>) – An optional system prompt to provide context or instructions for the generation.
+  If not provided, the system prompt set in the `__init__` method will be used.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  If provided, this will override the `streaming_callback` set in the `__init__` method.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+  passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `replies`: A list of generated text completions as strings.
+- `meta`: A list of metadata dictionaries containing information about each generation,
+  including model name, finish reason, and token usage statistics.
+
+#### run_async
+
+```python
+run_async(
+    *,
+    prompt: str,
+    system_prompt: str | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Generate text completions asynchronously.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – The input prompt string for text generation.
+- **system_prompt** (<code>str | None</code>) – An optional system prompt to provide context or instructions for the generation.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  If provided, this will override the `streaming_callback` set in the `__init__` method.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+  passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `replies`: A list of generated text completions as strings.
+- `meta`: A list of metadata dictionaries containing information about each generation,
+  including model name, finish reason, and token usage statistics.

docs-website/reference/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** (<code>Secret</code>) – The TwelveLabs API key. Read from the `TWELVELABS_API_KEY`
+  environment variable by default.
+- **model** (<code>str</code>) – The Pegasus model name (`pegasus1.5` or `pegasus1.2`).
+- **prompt** (<code>str</code>) – The analysis prompt sent to Pegasus for each video.
+- **temperature** (<code>float</code>) – Sampling temperature (0-1).
+- **max_tokens** (<code>int</code>) – Maximum output tokens per analysis.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TwelveLabsVideoConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>TwelveLabsVideoConverter</code> – 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** (<code>list\[str\]</code>) – Video sources — publicly accessible direct video URLs or
+  local file paths.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the produced Documents. Either
+  a single dict applied to all, or a list aligned with `sources`.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>Secret</code>) – The TwelveLabs API key. Read from the `TWELVELABS_API_KEY`
+  environment variable by default.
+- **model** (<code>str</code>) – The Marengo model name.
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text before embedding.
+- **suffix** (<code>str</code>) – A string to add to the end of each text before embedding.
+- **batch_size** (<code>int</code>) – Number of Documents per batch; within a batch `run_async` embeds concurrently.
+- **progress_bar** (<code>bool</code>) – 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** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TwelveLabsDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>TwelveLabsDocumentEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, Any]
+```
+
+Embed a list of Documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – The Documents to embed (their `content` is embedded).
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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:**
+
+- <code>TypeError</code> – 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** (<code>list\[Document\]</code>) – The Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with keys `documents` (copies with `embedding` populated) and `meta`.
+
+**Raises:**
+
+- <code>TypeError</code> – 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** (<code>Secret</code>) – The TwelveLabs API key. Read from the `TWELVELABS_API_KEY`
+  environment variable by default.
+- **model** (<code>str</code>) – The Marengo model name.
+- **prefix** (<code>str</code>) – A string to add to the beginning of the text before embedding.
+- **suffix** (<code>str</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TwelveLabsTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>TwelveLabsTextEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embed a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – The string to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with keys:
+- `embedding`: The embedding vector for the input string.
+- `meta`: Metadata about the request (the model used).
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, Any]
+```
+
+Asynchronously embed a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – The string to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with keys `embedding` and `meta`.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.

docs-website/reference/integrations-api/unstructured.md

@@ -0,0 +1,136 @@
+---
+title: "Unstructured"
+id: integrations-unstructured
+description: "Unstructured integration for Haystack"
+slug: "/integrations-unstructured"
+---
+
+<a id="haystack_integrations.components.converters.unstructured.converter"></a>
+
+## Module haystack\_integrations.components.converters.unstructured.converter
+
+<a id="haystack_integrations.components.converters.unstructured.converter.UnstructuredFileConverter"></a>
+
+### 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"]
+```
+
+<a id="haystack_integrations.components.converters.unstructured.converter.UnstructuredFileConverter.__init__"></a>
+
+#### 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.
+
+<a id="haystack_integrations.components.converters.unstructured.converter.UnstructuredFileConverter.to_dict"></a>
+
+#### UnstructuredFileConverter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.converters.unstructured.converter.UnstructuredFileConverter.from_dict"></a>
+
+#### 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.
+
+<a id="haystack_integrations.components.converters.unstructured.converter.UnstructuredFileConverter.run"></a>
+
+#### 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.
+

docs-website/reference/integrations-api/valkey.md

@@ -0,0 +1,995 @@
+---
+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
+from haystack.components.embedders import SentenceTransformersTextEmbedder, 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()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", 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** (<code>ValkeyDocumentStore</code>) – The Valkey Document Store.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `ValkeyDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ValkeyEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ValkeyEmbeddingRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `ValkeyDocumentStore`, based on their dense embeddings.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of `Document`s to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int | None</code>) – Maximum number of `Document`s to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – List of Document similar to `query_embedding`.
+
+## haystack_integrations.document_stores.valkey.document_store
+
+### ValkeyDocumentStore
+
+Bases: <code>DocumentStore</code>
+
+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** (<code>list\[tuple\[str, int\]\] | None</code>) – List of (host, port) tuples for Valkey nodes. Defaults to [("localhost", 6379)].
+- **cluster_mode** (<code>bool</code>) – Whether to connect in cluster mode. Defaults to False.
+- **use_tls** (<code>bool</code>) – Whether to use TLS for connections. Defaults to False.
+- **username** (<code>Secret | None</code>) – Username for authentication. If not provided, reads from VALKEY_USERNAME environment variable.
+  Defaults to None.
+- **password** (<code>Secret | None</code>) – Password for authentication. If not provided, reads from VALKEY_PASSWORD environment variable.
+  Defaults to None.
+- **request_timeout** (<code>int</code>) – Request timeout in milliseconds. Defaults to 500.
+- **retry_attempts** (<code>int</code>) – Number of retry attempts for failed operations. Defaults to 3.
+- **retry_base_delay_ms** (<code>int</code>) – Base delay in milliseconds for exponential backoff. Defaults to 1000.
+- **retry_exponent_base** (<code>int</code>) – Exponent base for exponential backoff calculation. Defaults to 2.
+- **batch_size** (<code>int</code>) – Number of documents to process in a single batch for async operations. Defaults to 100.
+- **index_name** (<code>str</code>) – Name of the search index. Defaults to "haystack_document".
+- **distance_metric** (<code>Literal['l2', 'cosine', 'ip']</code>) – Distance metric for vector similarity. Options: "l2", "cosine", "ip" (inner product).
+  Defaults to "cosine".
+- **embedding_dim** (<code>int</code>) – Dimension of document embeddings. Defaults to 768.
+- **metadata_fields** (<code>dict\[str, type\[str\] | type\[int\]\] | None</code>) – 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
+```
+
+Close the synchronous Valkey client connection.
+
+#### close_async
+
+```python
+close_async() -> None
+```
+
+Close the asynchronous Valkey client connection.
+
+#### 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:**
+
+- <code>int</code> – The number of documents in the document store.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – 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:**
+
+- <code>int</code> – The number of documents in the document store.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>list\[Document\]</code> – List of documents matching the filters, with score set to None.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>list\[Document\]</code> – List of documents matching the filters, with score set to None.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>list\[Document\]</code>) – 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** (<code>DuplicatePolicy</code>) – How to handle duplicate documents. Only NONE and OVERWRITE are supported.
+  Defaults to DuplicatePolicy.NONE.
+
+**Returns:**
+
+- <code>int</code> – Number of documents successfully written.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error writing documents.
+- <code>ValueError</code> – 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** (<code>list\[Document\]</code>) – 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** (<code>DuplicatePolicy</code>) – How to handle duplicate documents. Only NONE and OVERWRITE are supported.
+  Defaults to DuplicatePolicy.NONE.
+
+**Returns:**
+
+- <code>int</code> – Number of documents successfully written.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error writing documents.
+- <code>ValueError</code> – 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** (<code>list\[str\]</code>) – List of document IDs to delete. These should be the same IDs
+  used when the documents were originally stored.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>list\[str\]</code>) – List of document IDs to delete. These should be the same IDs
+  used when the documents were originally stored.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents to delete.
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents to delete.
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents to update.
+- **meta** (<code>dict\[str, Any\]</code>) – Metadata key-value pairs to set on matching documents (merged with existing meta).
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents to update.
+- **meta** (<code>dict\[str, Any\]</code>) – Metadata key-value pairs to set on matching documents (merged with existing meta).
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to apply.
+
+**Returns:**
+
+- <code>int</code> – The number of matching documents.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to apply.
+
+**Returns:**
+
+- <code>int</code> – The number of matching documents.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents.
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names (e.g. "category" or "meta.category").
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – Dictionary mapping each field name to the count of its unique values.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValueError</code> – If a field in metadata_fields is not configured for filtering.
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents.
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names (e.g. "category" or "meta.category").
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – Dictionary mapping each field name to the count of its unique values.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValueError</code> – If a field in metadata_fields is not configured for filtering.
+- <code>ValkeyDocumentStoreError</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – 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** (<code>str</code>) – Metadata field name (e.g. "priority" or "meta.priority"). Must be a configured
+  numeric field.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with "min" and "max" keys (values are int/float or None if no values).
+
+**Raises:**
+
+- <code>ValueError</code> – If the field is not configured or is not numeric.
+- <code>ValkeyDocumentStoreError</code> – 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** (<code>str</code>) – Metadata field name (e.g. "priority" or "meta.priority"). Must be a configured
+  numeric field.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with "min" and "max" keys (values are int/float or None if no values).
+
+**Raises:**
+
+- <code>ValueError</code> – If the field is not configured or is not numeric.
+- <code>ValkeyDocumentStoreError</code> – If the operation fails.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Return unique values for a metadata field with optional search and pagination.
+
+Values are stringified. For tag fields the distinct values are returned; for numeric fields
+the string representation of each distinct value is returned.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name (e.g. "category" or "meta.category").
+- **search_term** (<code>str | None</code>) – Optional case-insensitive substring filter on the value.
+- **from\_** (<code>int</code>) – Start index for pagination (default 0).
+- **size** (<code>int</code>) – Number of values to return (default 10).
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – Tuple of (list of unique values for the requested page, total count of unique values).
+
+**Raises:**
+
+- <code>ValueError</code> – If the field is not configured for filtering.
+- <code>ValkeyDocumentStoreError</code> – If the operation fails.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously return unique values for a metadata field with optional search and pagination.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name (e.g. "category" or "meta.category").
+- **search_term** (<code>str | None</code>) – Optional case-insensitive substring filter on the value.
+- **from\_** (<code>int</code>) – Start index for pagination (default 0).
+- **size** (<code>int</code>) – Number of values to return (default 10).
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – Tuple of (list of unique values for the requested page, total count of unique values).
+
+**Raises:**
+
+- <code>ValueError</code> – If the field is not configured for filtering.
+- <code>ValkeyDocumentStoreError</code> – 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:**
+
+- <code>ValkeyDocumentStoreError</code> – 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:**
+
+- <code>ValkeyDocumentStoreError</code> – 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}
+    ]
+}
+```

docs-website/reference/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** (<code>VespaDocumentStore</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – Default maximum number of documents to return per query (for example `10`).
+- **ranking** (<code>str | None</code>) – 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** (<code>str</code>) – 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** (<code>int | None</code>) – 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:**
+
+- <code>ValueError</code> – 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** (<code>list\[float\]</code>) – Dense query embedding.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied when fetching documents from the Document Store.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>VespaDocumentStore</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>int</code>) – Default maximum number of documents to return per query (for example `10`).
+- **ranking** (<code>str | None</code>) – 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:**
+
+- <code>ValueError</code> – 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** (<code>str</code>) – Query text.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied when fetching documents from the Document Store.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – 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** (<code>str | None</code>) – Vespa endpoint base URL. If omitted, the `VESPA_URL` environment variable is used.
+- **port** (<code>int</code>) – Vespa HTTP port.
+- **cert** (<code>Secret | None</code>) – Secret resolving to the data plane certificate file path for mTLS authentication.
+- **key** (<code>Secret | None</code>) – Secret resolving to the data plane key file path for mTLS authentication.
+- **vespa_cloud_secret_token** (<code>Secret | None</code>) – 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** (<code>dict\[str, str\] | None</code>) – Additional headers to send to the Vespa application.
+- **content_cluster_name** (<code>str</code>) – Vespa content cluster name.
+- **schema** (<code>str</code>) – Vespa schema name to read from and write to.
+- **namespace** (<code>str | None</code>) – Vespa namespace. Defaults to the schema name when omitted.
+- **groupname** (<code>str | None</code>) – Optional Vespa group name.
+- **content_field** (<code>str</code>) – Vespa field containing the document text.
+- **embedding_field** (<code>str</code>) – Vespa field containing the dense embedding.
+- **id_field** (<code>str</code>) – 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** (<code>list\[str\] | None</code>) – Optional allowlist of metadata fields to feed and return.
+- **query_limit** (<code>int</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Serialized document store data.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Return the total number of documents in Vespa.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack metadata filters.
+
+**Returns:**
+
+- <code>int</code> – Count of matching documents.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to Vespa.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to store.
+- **policy** (<code>DuplicatePolicy</code>) – Duplicate handling policy.
+
+**Returns:**
+
+- <code>int</code> – Number of documents written.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents by id.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – 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** (<code>dict\[str, Any\]</code>) – Haystack metadata filters.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>dict\[str, Any\]</code>) – Haystack metadata filters.
+- **meta** (<code>dict\[str, Any\]</code>) – Metadata values to merge into the matched documents.
+
+**Returns:**
+
+- <code>int</code> – 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** (<code>list\[str\]</code>) – Document ids to fetch.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – Matching documents.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Retrieve documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Haystack metadata filters.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – 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:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – Field metadata information.
+
+## haystack_integrations.document_stores.vespa.filters

docs-website/reference/integrations-api/vllm.md

@@ -0,0 +1,699 @@
+---
+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** (<code>str</code>) – 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** (<code>Secret | None</code>) – 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** (<code>str</code>) – The base URL of the vLLM server.
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **dimensions** (<code>int | None</code>) – 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** (<code>int</code>) – Number of documents to encode at once.
+- **progress_bar** (<code>bool</code>) – Whether to show a progress bar.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields to embed along with the document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the document text.
+- **timeout** (<code>float | None</code>) – Timeout in seconds for vLLM client calls. If not set, the OpenAI client default applies.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries for failed requests. If not set, the OpenAI client
+  default applies.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>bool</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Additional parameters forwarded as `extra_body` to the vLLM embeddings
+  endpoint. Use this to pass parameters not part of the standard OpenAI Embeddings API, such as
+  `truncate_prompt_tokens`, `truncation_side`, etc. See the
+  [vLLM Embeddings API docs](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#openai-compatible-embeddings-api).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the OpenAI clients.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Embed a list of Documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – 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** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – 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** (<code>str</code>) – The name of the model served by vLLM (e.g., "intfloat/e5-mistral-7b-instruct").
+- **api_key** (<code>Secret | None</code>) – 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** (<code>str</code>) – The base URL of the vLLM server.
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text to embed.
+- **suffix** (<code>str</code>) – A string to add at the end of each text to embed.
+- **dimensions** (<code>int | None</code>) – 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** (<code>float | None</code>) – Timeout in seconds for vLLM client calls. If not set, the OpenAI client default applies.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries for failed requests. If not set, the OpenAI client
+  default applies.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Additional parameters forwarded as `extra_body` to the vLLM embeddings
+  endpoint. Use this to pass parameters not part of the standard OpenAI Embeddings API, such as
+  `truncate_prompt_tokens`, `truncation_side`, `additional_data`, `use_activation`, etc. See the
+  [vLLM Embeddings API docs](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#openai-compatible-embeddings-api).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the OpenAI clients.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Embed a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – 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** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – 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** (<code>str</code>) – The name of the model served by vLLM (e.g., "Qwen/Qwen3-0.6B").
+- **api_key** (<code>Secret | None</code>) – 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** (<code>StreamingCallbackT | None</code>) – 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** (<code>str</code>) – The base URL of the vLLM server.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>float | None</code>) – Timeout for vLLM client calls. If not set, it defaults to the default set by the OpenAI client.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default
+  set by the OpenAI client.
+- **tools** (<code>ToolsType | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client` or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the OpenAI clients and warm up tools.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> VLLMChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>VLLMChatGenerator</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will
+  override the parameters passed during component initialization.
+  For details on vLLM API parameters, see
+  [vLLM documentation](https://docs.vllm.ai/en/stable/serving/openai_compatible_server/).
+- **tools** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  Must be a coroutine.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will
+  override the parameters passed during component initialization.
+  For details on vLLM API parameters, see
+  [vLLM documentation](https://docs.vllm.ai/en/stable/serving/openai_compatible_server/).
+- **tools** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>str</code>) – 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** (<code>Secret | None</code>) – 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** (<code>str</code>) – The base URL of the vLLM server.
+- **top_k** (<code>int | None</code>) – The maximum number of Documents to return. If `None`, all documents are returned.
+- **score_threshold** (<code>float | None</code>) – 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** (<code>list\[str\] | None</code>) – List of meta fields that should be concatenated with the document
+  content before reranking.
+- **meta_data_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the document content.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the httpx clients.
+
+#### run
+
+```python
+run(
+    query: str,
+    documents: list[Document],
+    top_k: int | None = None,
+    score_threshold: float | None = None,
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Returns a list of Documents ranked by their similarity to the given query.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Query string.
+- **documents** (<code>list\[Document\]</code>) – List of Documents to rank.
+- **top_k** (<code>int | None</code>) – The maximum number of Documents to return. Overrides the value set at initialization.
+- **score_threshold** (<code>float | None</code>) – Minimum relevance score required for a document to be returned. Overrides
+  the value set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with:
+- `documents`: Documents sorted from most to least relevant.
+- `meta`: Information about the model and usage.
+
+**Raises:**
+
+- <code>ValueError</code> – 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** (<code>str</code>) – Query string.
+- **documents** (<code>list\[Document\]</code>) – List of Documents to rank.
+- **top_k** (<code>int | None</code>) – The maximum number of Documents to return. Overrides the value set at initialization.
+- **score_threshold** (<code>float | None</code>) – Minimum relevance score required for a document to be returned. Overrides
+  the value set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with:
+- `documents`: Documents sorted from most to least relevant.
+- `meta`: Information about the model and usage.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.

docs-website/reference/integrations-api/watsonx.md

@@ -0,0 +1,701 @@
+---
+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** (<code>str</code>) – The name of the model to use for calculating embeddings.
+  Default is "ibm/slate-30m-english-rtrvr-v2".
+- **api_key** (<code>Secret</code>) – The WATSONX API key. Can be set via environment variable WATSONX_API_KEY.
+- **api_base_url** (<code>str</code>) – The WATSONX URL for the watsonx.ai service.
+  Default is "https://us-south.ml.cloud.ibm.com".
+- **project_id** (<code>Secret</code>) – The ID of the Watson Studio project.
+  Can be set via environment variable WATSONX_PROJECT_ID.
+- **truncate_input_tokens** (<code>int | None</code>) – 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** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **batch_size** (<code>int</code>) – Number of documents to embed in one API call. Default is 1000.
+- **concurrency_limit** (<code>int</code>) – Number of parallel requests to make. Default is 5.
+- **timeout** (<code>float | None</code>) – Timeout for API requests in seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries for API requests.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> 'WatsonxDocumentEmbedder'
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>'WatsonxDocumentEmbedder'</code> – The deserialized component instance.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – 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** (<code>str</code>) – The name of the IBM watsonx model to use for calculating embeddings.
+  Default is "ibm/slate-30m-english-rtrvr-v2".
+- **api_key** (<code>Secret</code>) – The WATSONX API key. Can be set via environment variable WATSONX_API_KEY.
+- **api_base_url** (<code>str</code>) – The WATSONX URL for the watsonx.ai service.
+  Default is "https://us-south.ml.cloud.ibm.com".
+- **project_id** (<code>Secret</code>) – The ID of the Watson Studio project.
+  Can be set via environment variable WATSONX_PROJECT_ID.
+- **truncate_input_tokens** (<code>int | None</code>) – 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** (<code>str</code>) – A string to add at the beginning of each text to embed.
+- **suffix** (<code>str</code>) – A string to add at the end of each text to embed.
+- **timeout** (<code>float | None</code>) – Timeout for API requests in seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries for API requests.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WatsonxTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>WatsonxTextEmbedder</code> – The deserialized component instance.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Embeds a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – 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** (<code>Secret</code>) – IBM Cloud API key for watsonx.ai access.
+  Can be set via `WATSONX_API_KEY` environment variable or passed directly.
+- **model** (<code>str</code>) – 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** (<code>Secret</code>) – IBM Cloud project ID
+- **api_base_url** (<code>str</code>) – Custom base URL for the API endpoint.
+  Defaults to "https://us-south.ml.cloud.ibm.com".
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>float | None</code>) – Timeout in seconds for API requests.
+  Defaults to environment variable `WATSONX_TIMEOUT` or 30 seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retry attempts for failed requests.
+  Defaults to environment variable `WATSONX_MAX_RETRIES` or 5.
+- **verify** (<code>bool | str | None</code>) – SSL verification setting. Can be:
+- True: Verify SSL certificates (default)
+- False: Skip verification (insecure)
+- Path to CA bundle for custom certificates
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function for streaming responses.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WatsonxChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>WatsonxChatGenerator</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+  passed in the `__init__` method.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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** (<code>list\[ChatMessage\] | str</code>) – 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** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+  passed in the `__init__` method.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>ToolsType | None</code>) – 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:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+## haystack_integrations.components.generators.watsonx.generator
+
+### WatsonxGenerator
+
+Bases: <code>WatsonxChatGenerator</code>
+
+Enables text completions using IBM's watsonx.ai foundation models.
+
+This component extends WatsonxChatGenerator to provide the standard Generator interface that works with prompt
+strings instead of ChatMessage objects.
+
+The generator works with IBM's foundation models that are listed
+[here](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx&audience=wdp).
+
+You can customize the generation behavior by passing parameters to the watsonx.ai API through the
+`generation_kwargs` argument. These parameters are passed directly to the watsonx.ai inference endpoint.
+
+For details on watsonx.ai API parameters, see
+[IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-parameters.html).
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.watsonx.generator import WatsonxGenerator
+from haystack.utils import Secret
+
+generator = WatsonxGenerator(
+    api_key=Secret.from_env_var("WATSONX_API_KEY"),
+    model="ibm/granite-4-h-small",
+    project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+
+response = generator.run(
+    prompt="Explain quantum computing in simple terms",
+    system_prompt="You are a helpful physics teacher.",
+)
+print(response)
+```
+
+Output:
+
+```
+{
+    "replies": ["Quantum computing uses quantum-mechanical phenomena like...."],
+    "meta": [
+        {
+            "model": "ibm/granite-4-h-small",
+            "project_id": "your-project-id",
+            "usage": {
+                "prompt_tokens": 12,
+                "completion_tokens": 45,
+                "total_tokens": 57,
+            },
+        }
+    ],
+}
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "ibm/granite-3-1-8b-base",
+    "ibm/granite-3-8b-instruct",
+    "ibm/granite-4-h-small",
+    "ibm/granite-8b-code-instruct",
+    "ibm/granite-guardian-3-8b",
+    "meta-llama/llama-3-1-70b-gptq",
+    "meta-llama/llama-3-1-8b",
+    "meta-llama/llama-3-2-11b-vision-instruct",
+    "meta-llama/llama-3-2-90b-vision-instruct",
+    "meta-llama/llama-3-3-70b-instruct",
+    "meta-llama/llama-3-405b-instruct",
+    "meta-llama/llama-4-maverick-17b-128e-instruct-fp8",
+    "meta-llama/llama-guard-3-11b-vision",
+    "mistral-large-2512",
+    "mistralai/mistral-medium-2505",
+    "mistralai/mistral-small-3-1-24b-instruct-2503",
+    "openai/gpt-oss-120b",
+]
+
+```
+
+A non-exhaustive list of models supported by this component.
+
+See https://www.ibm.com/docs/en/watsonx/saas?topic=solutions-supported-foundation-models for the
+full list of models and up-to-date model IDs.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"),
+    model: str = "ibm/granite-4-h-small",
+    project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"),
+    api_base_url: str = "https://us-south.ml.cloud.ibm.com",
+    system_prompt: str | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    verify: bool | str | None = None,
+    streaming_callback: StreamingCallbackT | None = None
+) -> None
+```
+
+Creates an instance of WatsonxGenerator.
+
+Before initializing the component, you can set environment variables:
+
+- `WATSONX_TIMEOUT` to override the default timeout
+- `WATSONX_MAX_RETRIES` to override the default retry count
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – IBM Cloud API key for watsonx.ai access.
+  Can be set via `WATSONX_API_KEY` environment variable or passed directly.
+- **model** (<code>str</code>) – 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** (<code>Secret</code>) – IBM Cloud project ID
+- **api_base_url** (<code>str</code>) – Custom base URL for the API endpoint.
+  Defaults to "https://us-south.ml.cloud.ibm.com".
+- **system_prompt** (<code>str | None</code>) – The system prompt to use for text generation.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – 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** (<code>float | None</code>) – Timeout in seconds for API requests.
+  Defaults to environment variable `WATSONX_TIMEOUT` or 30 seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retry attempts for failed requests.
+  Defaults to environment variable `WATSONX_MAX_RETRIES` or 5.
+- **verify** (<code>bool | str | None</code>) – SSL verification setting. Can be:
+- True: Verify SSL certificates (default)
+- False: Skip verification (insecure)
+- Path to CA bundle for custom certificates
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function for streaming responses.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WatsonxGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>WatsonxGenerator</code> – The deserialized component instance.
+
+#### run
+
+```python
+run(
+    *,
+    prompt: str,
+    system_prompt: str | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Generate text completions synchronously.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – The input prompt string for text generation.
+- **system_prompt** (<code>str | None</code>) – An optional system prompt to provide context or instructions for the generation.
+  If not provided, the system prompt set in the `__init__` method will be used.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  If provided, this will override the `streaming_callback` set in the `__init__` method.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+  passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `replies`: A list of generated text completions as strings.
+- `meta`: A list of metadata dictionaries containing information about each generation,
+  including model name, finish reason, and token usage statistics.
+
+#### run_async
+
+```python
+run_async(
+    *,
+    prompt: str,
+    system_prompt: str | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Generate text completions asynchronously.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – The input prompt string for text generation.
+- **system_prompt** (<code>str | None</code>) – An optional system prompt to provide context or instructions for the generation.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  If provided, this will override the `streaming_callback` set in the `__init__` method.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+  passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `replies`: A list of generated text completions as strings.
+- `meta`: A list of metadata dictionaries containing information about each generation,
+  including model name, finish reason, and token usage statistics.

docs-website/reference/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/<user_name>/projects` and see the complete trace for your pipeline under
+the pipeline name you specified, when creating the `WeaveConnector`
+
+#### __init__
+
+```python
+__init__(
+    pipeline_name: str, weave_init_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Initialize WeaveConnector.
+
+**Parameters:**
+
+- **pipeline_name** (<code>str</code>) – The name of the pipeline you want to trace.
+- **weave_init_kwargs** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>WeaveConnector</code> – Deserialized component.
+
+## haystack_integrations.tracing.weave.tracer
+
+### WeaveSpan
+
+Bases: <code>Span</code>
+
+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** (<code>str</code>) – The tag key.
+- **value** (<code>Any</code>) – 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: <code>Tracer</code>
+
+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** (<code>str</code>) – The name of the project to trace, this is will be the name appearing in Weave project.
+- **weave_init_kwargs** (<code>Any</code>) – 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.

docs-website/reference/integrations-api/whisper.md

@@ -0,0 +1,241 @@
+---
+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** (<code>WhisperLocalModel</code>) – 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** (<code>ComponentDevice | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LocalWhisperTranscriber
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>LocalWhisperTranscriber</code> – 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** (<code>list\[str | Path | ByteStream\]</code>) – A list of paths or binary streams to transcribe.
+- **whisper_params** (<code>dict\[str, Any\] | None</code>) – 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:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>Secret</code>) – OpenAI API key.
+  You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter
+  during initialization.
+- **model** (<code>str</code>) – Name of the model to use. Currently accepts only `whisper-1`.
+- **organization** (<code>str | None</code>) – 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** (<code>str | None</code>) – 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** (<code>dict\[str, Any\] | None</code>) – 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** (<code>Any</code>) – 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.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> RemoteWhisperTranscriber
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>RemoteWhisperTranscriber</code> – 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** (<code>list\[str | Path | ByteStream\]</code>) – A list of file paths or `ByteStream` objects containing the audio files to transcribe.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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** (<code>list\[str | Path | ByteStream\]</code>) – A list of file paths or `ByteStream` objects containing the audio files to transcribe.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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.