diff --git a/docs-website/reference/haystack-api/builders_api.md b/docs-website/reference/haystack-api/builders_api.md
index 1c14e3d50c..8298eb0604 100644
--- a/docs-website/reference/haystack-api/builders_api.md
+++ b/docs-website/reference/haystack-api/builders_api.md
@@ -147,208 +147,6 @@ Example: `\[(\d+)\]` finds "1" in a string "this is an answer[1]".
A dictionary with the following keys:
- `answers`: The answers received from the output of the Generator.
-
-
-## Module prompt\_builder
-
-
-
-### PromptBuilder
-
-Renders a prompt filling in any variables so that it can send it to a Generator.
-
-The prompt uses Jinja2 template syntax.
-The variables in the default template are used as PromptBuilder's input and are all optional.
-If they're not provided, they're replaced with an empty string in the rendered prompt.
-To try out different prompts, you can replace the prompt template at runtime by
-providing a template for each pipeline run invocation.
-
-### Usage examples
-
-#### On its own
-
-This example uses PromptBuilder to render a prompt template and fill it with `target_language`
-and `snippet`. PromptBuilder returns a prompt with the string "Translate the following context to Spanish.
-Context: I can't speak Spanish.; Translation:".
-```python
-from haystack.components.builders import PromptBuilder
-
-template = "Translate the following context to {{ target_language }}. Context: {{ snippet }}; Translation:"
-builder = PromptBuilder(template=template)
-builder.run(target_language="spanish", snippet="I can't speak spanish.")
-```
-
-#### In a Pipeline
-
-This is an example of a RAG pipeline where PromptBuilder renders a custom prompt template and fills it
-with the contents of the retrieved documents and a query. The rendered prompt is then sent to a Generator.
-```python
-from haystack import Pipeline, Document
-from haystack.utils import Secret
-from haystack.components.generators import OpenAIGenerator
-from haystack.components.builders.prompt_builder import PromptBuilder
-
-# in a real world use case documents could come from a retriever, web, or any other source
-documents = [Document(content="Joe lives in Berlin"), Document(content="Joe is a software engineer")]
-prompt_template = """
- Given these documents, answer the question.
- Documents:
- {% for doc in documents %}
- {{ doc.content }}
- {% endfor %}
-
- Question: {{query}}
- Answer:
- """
-p = Pipeline()
-p.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
-p.add_component(instance=OpenAIGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")), name="llm")
-p.connect("prompt_builder", "llm")
-
-question = "Where does Joe live?"
-result = p.run({"prompt_builder": {"documents": documents, "query": question}})
-print(result)
-```
-
-#### Changing the template at runtime (prompt engineering)
-
-You can change the prompt template of an existing pipeline, like in this example:
-```python
-documents = [
- Document(content="Joe lives in Berlin", meta={"name": "doc1"}),
- Document(content="Joe is a software engineer", meta={"name": "doc1"}),
-]
-new_template = """
- You are a helpful assistant.
- Given these documents, answer the question.
- Documents:
- {% for doc in documents %}
- Document {{ loop.index }}:
- Document name: {{ doc.meta['name'] }}
- {{ doc.content }}
- {% endfor %}
-
- Question: {{ query }}
- Answer:
- """
-p.run({
- "prompt_builder": {
- "documents": documents,
- "query": question,
- "template": new_template,
- },
-})
-```
-To replace the variables in the default template when testing your prompt,
-pass the new variables in the `variables` parameter.
-
-#### Overwriting variables at runtime
-
-To overwrite the values of variables, use `template_variables` during runtime:
-```python
-language_template = """
-You are a helpful assistant.
-Given these documents, answer the question.
-Documents:
-{% for doc in documents %}
- Document {{ loop.index }}:
- Document name: {{ doc.meta['name'] }}
- {{ doc.content }}
-{% endfor %}
-
-Question: {{ query }}
-Please provide your answer in {{ answer_language | default('English') }}
-Answer:
-"""
-p.run({
- "prompt_builder": {
- "documents": documents,
- "query": question,
- "template": language_template,
- "template_variables": {"answer_language": "German"},
- },
-})
-```
-Note that `language_template` introduces variable `answer_language` which is not bound to any pipeline variable.
-If not set otherwise, it will use its default value 'English'.
-This example overwrites its value to 'German'.
-Use `template_variables` to overwrite pipeline variables (such as documents) as well.
-
-
-
-#### PromptBuilder.\_\_init\_\_
-
-```python
-def __init__(template: str,
- required_variables: Optional[Union[list[str],
- Literal["*"]]] = None,
- variables: Optional[list[str]] = None)
-```
-
-Constructs a PromptBuilder component.
-
-**Arguments**:
-
-- `template`: A prompt template that uses Jinja2 syntax to add variables. For example:
-`"Summarize this document: {{ documents[0].content }}\nSummary:"`
-It's used to render the prompt.
-The variables in the default template are input for PromptBuilder and are all optional,
-unless explicitly specified.
-If an optional variable is not provided, it's replaced with an empty string in the rendered prompt.
-- `required_variables`: List variables that must be provided as input to PromptBuilder.
-If a variable listed as required is not provided, an exception is raised.
-If set to "*", all variables found in the prompt are required. Optional.
-- `variables`: List input variables to use in prompt templates instead of the ones inferred from the
-`template` parameter. For example, to use more variables during prompt engineering than the ones present
-in the default template, you can provide them here.
-
-
-
-#### PromptBuilder.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Returns a dictionary representation of the component.
-
-**Returns**:
-
-Serialized dictionary representation of the component.
-
-
-
-#### PromptBuilder.run
-
-```python
-@component.output_types(prompt=str)
-def run(template: Optional[str] = None,
- template_variables: Optional[dict[str, Any]] = None,
- **kwargs)
-```
-
-Renders the prompt template with the provided variables.
-
-It applies the template variables to render the final prompt. You can provide variables via pipeline kwargs.
-In order to overwrite the default template, you can set the `template` parameter.
-In order to overwrite pipeline kwargs, you can set the `template_variables` parameter.
-
-**Arguments**:
-
-- `template`: An optional string template to overwrite PromptBuilder's default template. If None, the default template
-provided at initialization is used.
-- `template_variables`: An optional dictionary of template variables to overwrite the pipeline variables.
-- `kwargs`: Pipeline variables used for rendering the prompt.
-
-**Raises**:
-
-- `ValueError`: If any of the required template variables is not provided.
-
-**Returns**:
-
-A dictionary with the following keys:
-- `prompt`: The updated prompt text after rendering the prompt template.
-
## Module chat\_prompt\_builder
@@ -553,3 +351,205 @@ Deserialize this component from a dictionary.
The deserialized component.
+
+
+## Module prompt\_builder
+
+
+
+### PromptBuilder
+
+Renders a prompt filling in any variables so that it can send it to a Generator.
+
+The prompt uses Jinja2 template syntax.
+The variables in the default template are used as PromptBuilder's input and are all optional.
+If they're not provided, they're replaced with an empty string in the rendered prompt.
+To try out different prompts, you can replace the prompt template at runtime by
+providing a template for each pipeline run invocation.
+
+### Usage examples
+
+#### On its own
+
+This example uses PromptBuilder to render a prompt template and fill it with `target_language`
+and `snippet`. PromptBuilder returns a prompt with the string "Translate the following context to Spanish.
+Context: I can't speak Spanish.; Translation:".
+```python
+from haystack.components.builders import PromptBuilder
+
+template = "Translate the following context to {{ target_language }}. Context: {{ snippet }}; Translation:"
+builder = PromptBuilder(template=template)
+builder.run(target_language="spanish", snippet="I can't speak spanish.")
+```
+
+#### In a Pipeline
+
+This is an example of a RAG pipeline where PromptBuilder renders a custom prompt template and fills it
+with the contents of the retrieved documents and a query. The rendered prompt is then sent to a Generator.
+```python
+from haystack import Pipeline, Document
+from haystack.utils import Secret
+from haystack.components.generators import OpenAIGenerator
+from haystack.components.builders.prompt_builder import PromptBuilder
+
+# in a real world use case documents could come from a retriever, web, or any other source
+documents = [Document(content="Joe lives in Berlin"), Document(content="Joe is a software engineer")]
+prompt_template = """
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ Question: {{query}}
+ Answer:
+ """
+p = Pipeline()
+p.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+p.add_component(instance=OpenAIGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")), name="llm")
+p.connect("prompt_builder", "llm")
+
+question = "Where does Joe live?"
+result = p.run({"prompt_builder": {"documents": documents, "query": question}})
+print(result)
+```
+
+#### Changing the template at runtime (prompt engineering)
+
+You can change the prompt template of an existing pipeline, like in this example:
+```python
+documents = [
+ Document(content="Joe lives in Berlin", meta={"name": "doc1"}),
+ Document(content="Joe is a software engineer", meta={"name": "doc1"}),
+]
+new_template = """
+ You are a helpful assistant.
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ Document {{ loop.index }}:
+ Document name: {{ doc.meta['name'] }}
+ {{ doc.content }}
+ {% endfor %}
+
+ Question: {{ query }}
+ Answer:
+ """
+p.run({
+ "prompt_builder": {
+ "documents": documents,
+ "query": question,
+ "template": new_template,
+ },
+})
+```
+To replace the variables in the default template when testing your prompt,
+pass the new variables in the `variables` parameter.
+
+#### Overwriting variables at runtime
+
+To overwrite the values of variables, use `template_variables` during runtime:
+```python
+language_template = """
+You are a helpful assistant.
+Given these documents, answer the question.
+Documents:
+{% for doc in documents %}
+ Document {{ loop.index }}:
+ Document name: {{ doc.meta['name'] }}
+ {{ doc.content }}
+{% endfor %}
+
+Question: {{ query }}
+Please provide your answer in {{ answer_language | default('English') }}
+Answer:
+"""
+p.run({
+ "prompt_builder": {
+ "documents": documents,
+ "query": question,
+ "template": language_template,
+ "template_variables": {"answer_language": "German"},
+ },
+})
+```
+Note that `language_template` introduces variable `answer_language` which is not bound to any pipeline variable.
+If not set otherwise, it will use its default value 'English'.
+This example overwrites its value to 'German'.
+Use `template_variables` to overwrite pipeline variables (such as documents) as well.
+
+
+
+#### PromptBuilder.\_\_init\_\_
+
+```python
+def __init__(template: str,
+ required_variables: Optional[Union[list[str],
+ Literal["*"]]] = None,
+ variables: Optional[list[str]] = None)
+```
+
+Constructs a PromptBuilder component.
+
+**Arguments**:
+
+- `template`: A prompt template that uses Jinja2 syntax to add variables. For example:
+`"Summarize this document: {{ documents[0].content }}\nSummary:"`
+It's used to render the prompt.
+The variables in the default template are input for PromptBuilder and are all optional,
+unless explicitly specified.
+If an optional variable is not provided, it's replaced with an empty string in the rendered prompt.
+- `required_variables`: List variables that must be provided as input to PromptBuilder.
+If a variable listed as required is not provided, an exception is raised.
+If set to "*", all variables found in the prompt are required. Optional.
+- `variables`: List input variables to use in prompt templates instead of the ones inferred from the
+`template` parameter. For example, to use more variables during prompt engineering than the ones present
+in the default template, you can provide them here.
+
+
+
+#### PromptBuilder.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the component.
+
+**Returns**:
+
+Serialized dictionary representation of the component.
+
+
+
+#### PromptBuilder.run
+
+```python
+@component.output_types(prompt=str)
+def run(template: Optional[str] = None,
+ template_variables: Optional[dict[str, Any]] = None,
+ **kwargs)
+```
+
+Renders the prompt template with the provided variables.
+
+It applies the template variables to render the final prompt. You can provide variables via pipeline kwargs.
+In order to overwrite the default template, you can set the `template` parameter.
+In order to overwrite pipeline kwargs, you can set the `template_variables` parameter.
+
+**Arguments**:
+
+- `template`: An optional string template to overwrite PromptBuilder's default template. If None, the default template
+provided at initialization is used.
+- `template_variables`: An optional dictionary of template variables to overwrite the pipeline variables.
+- `kwargs`: Pipeline variables used for rendering the prompt.
+
+**Raises**:
+
+- `ValueError`: If any of the required template variables is not provided.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `prompt`: The updated prompt text after rendering the prompt template.
+
diff --git a/docs-website/reference/haystack-api/classifiers_api.md b/docs-website/reference/haystack-api/classifiers_api.md
index 3c4904bbdc..1ad122544d 100644
--- a/docs-website/reference/haystack-api/classifiers_api.md
+++ b/docs-website/reference/haystack-api/classifiers_api.md
@@ -36,7 +36,15 @@ document_store = InMemoryDocumentStore()
p = Pipeline()
p.add_component(instance=DocumentLanguageClassifier(languages=["en"]), name="language_classifier")
-p.add_component(instance=MetadataRouter(rules={"en": {"language": {"$eq": "en"}}}), name="router")
+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")
diff --git a/docs-website/reference/haystack-api/connectors_api.md b/docs-website/reference/haystack-api/connectors_api.md
index 1ec9902011..2baa88fb79 100644
--- a/docs-website/reference/haystack-api/connectors_api.md
+++ b/docs-website/reference/haystack-api/connectors_api.md
@@ -5,6 +5,105 @@ description: "Various connectors to integrate with external services."
slug: "/connectors-api"
---
+
+
+## Module openapi
+
+
+
+### OpenAPIConnector
+
+OpenAPIConnector enables direct invocation of REST endpoints defined in an OpenAPI specification.
+
+The OpenAPIConnector serves as a bridge between Haystack pipelines and any REST API that follows
+the OpenAPI(formerly Swagger) specification. It dynamically interprets the API specification and
+provides an interface for executing API operations. It is usually invoked by passing input
+arguments to it from a Haystack pipeline run method or by other components in a pipeline that
+pass input arguments to this component.
+
+**Example**:
+
+```python
+from haystack.utils import Secret
+from haystack.components.connectors.openapi import OpenAPIConnector
+
+connector = OpenAPIConnector(
+ openapi_spec="https://bit.ly/serperdev_openapi",
+ credentials=Secret.from_env_var("SERPERDEV_API_KEY"),
+ service_kwargs={"config_factory": my_custom_config_factory}
+)
+response = connector.run(
+ operation_id="search",
+ arguments={"q": "Who was Nikola Tesla?"}
+)
+```
+
+**Notes**:
+
+ - The `parameters` argument is required for this component.
+ - The `service_kwargs` argument is optional, it can be used to pass additional options to the OpenAPIClient.
+
+
+
+#### OpenAPIConnector.\_\_init\_\_
+
+```python
+def __init__(openapi_spec: str,
+ credentials: Optional[Secret] = None,
+ service_kwargs: Optional[dict[str, Any]] = None)
+```
+
+Initialize the OpenAPIConnector with a specification and optional credentials.
+
+**Arguments**:
+
+- `openapi_spec`: URL, file path, or raw string of the OpenAPI specification
+- `credentials`: Optional API key or credentials for the service wrapped in a Secret
+- `service_kwargs`: Additional keyword arguments passed to OpenAPIClient.from_spec()
+For example, you can pass a custom config_factory or other configuration options.
+
+
+
+#### OpenAPIConnector.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+
+
+#### OpenAPIConnector.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "OpenAPIConnector"
+```
+
+Deserialize this component from a dictionary.
+
+
+
+#### OpenAPIConnector.run
+
+```python
+@component.output_types(response=dict[str, Any])
+def run(operation_id: str,
+ arguments: Optional[dict[str, Any]] = None) -> dict[str, Any]
+```
+
+Invokes a REST endpoint specified in the OpenAPI specification.
+
+**Arguments**:
+
+- `operation_id`: The operationId from the OpenAPI spec to invoke
+- `arguments`: Optional parameters for the endpoint (query, path, or body parameters)
+
+**Returns**:
+
+Dictionary containing the service response
+
## Module openapi\_service
@@ -146,102 +245,3 @@ Deserializes the component from a dictionary.
The deserialized component.
-
-
-## Module openapi
-
-
-
-### OpenAPIConnector
-
-OpenAPIConnector enables direct invocation of REST endpoints defined in an OpenAPI specification.
-
-The OpenAPIConnector serves as a bridge between Haystack pipelines and any REST API that follows
-the OpenAPI(formerly Swagger) specification. It dynamically interprets the API specification and
-provides an interface for executing API operations. It is usually invoked by passing input
-arguments to it from a Haystack pipeline run method or by other components in a pipeline that
-pass input arguments to this component.
-
-**Example**:
-
-```python
-from haystack.utils import Secret
-from haystack.components.connectors.openapi import OpenAPIConnector
-
-connector = OpenAPIConnector(
- openapi_spec="https://bit.ly/serperdev_openapi",
- credentials=Secret.from_env_var("SERPERDEV_API_KEY"),
- service_kwargs={"config_factory": my_custom_config_factory}
-)
-response = connector.run(
- operation_id="search",
- arguments={"q": "Who was Nikola Tesla?"}
-)
-```
-
-**Notes**:
-
- - The `parameters` argument is required for this component.
- - The `service_kwargs` argument is optional, it can be used to pass additional options to the OpenAPIClient.
-
-
-
-#### OpenAPIConnector.\_\_init\_\_
-
-```python
-def __init__(openapi_spec: str,
- credentials: Optional[Secret] = None,
- service_kwargs: Optional[dict[str, Any]] = None)
-```
-
-Initialize the OpenAPIConnector with a specification and optional credentials.
-
-**Arguments**:
-
-- `openapi_spec`: URL, file path, or raw string of the OpenAPI specification
-- `credentials`: Optional API key or credentials for the service wrapped in a Secret
-- `service_kwargs`: Additional keyword arguments passed to OpenAPIClient.from_spec()
-For example, you can pass a custom config_factory or other configuration options.
-
-
-
-#### OpenAPIConnector.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Serialize this component to a dictionary.
-
-
-
-#### OpenAPIConnector.from\_dict
-
-```python
-@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "OpenAPIConnector"
-```
-
-Deserialize this component from a dictionary.
-
-
-
-#### OpenAPIConnector.run
-
-```python
-@component.output_types(response=dict[str, Any])
-def run(operation_id: str,
- arguments: Optional[dict[str, Any]] = None) -> dict[str, Any]
-```
-
-Invokes a REST endpoint specified in the OpenAPI specification.
-
-**Arguments**:
-
-- `operation_id`: The operationId from the OpenAPI spec to invoke
-- `arguments`: Optional parameters for the endpoint (query, path, or body parameters)
-
-**Returns**:
-
-Dictionary containing the service response
-
diff --git a/docs-website/reference/haystack-api/embedders_api.md b/docs-website/reference/haystack-api/embedders_api.md
index d31aa8a618..c62729859d 100644
--- a/docs-website/reference/haystack-api/embedders_api.md
+++ b/docs-website/reference/haystack-api/embedders_api.md
@@ -696,6 +696,176 @@ Embeds a single string asynchronously.
A dictionary with the following keys:
- `embedding`: The embedding of the input text.
+
+
+## Module image/sentence\_transformers\_doc\_image\_embedder
+
+
+
+### SentenceTransformersDocumentImageEmbedder
+
+A component for computing Document embeddings based on images using Sentence Transformers models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+### Usage example
+```python
+from haystack import Document
+from haystack.components.embedders.image import SentenceTransformersDocumentImageEmbedder
+
+embedder = SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32")
+embedder.warm_up()
+
+documents = [
+ Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
+ Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}),
+]
+
+result = embedder.run(documents=documents)
+documents_with_embeddings = result["documents"]
+print(documents_with_embeddings)
+
+# [Document(id=...,
+# content='A photo of a cat',
+# meta={'file_path': 'cat.jpg',
+# 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}},
+# embedding=vector of size 512),
+# ...]
+```
+
+
+
+#### SentenceTransformersDocumentImageEmbedder.\_\_init\_\_
+
+```python
+def __init__(*,
+ file_path_meta_field: str = "file_path",
+ root_path: Optional[str] = None,
+ model: str = "sentence-transformers/clip-ViT-B-32",
+ device: Optional[ComponentDevice] = None,
+ token: Optional[Secret] = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False),
+ batch_size: int = 32,
+ progress_bar: bool = True,
+ normalize_embeddings: bool = False,
+ trust_remote_code: bool = False,
+ local_files_only: bool = False,
+ model_kwargs: Optional[dict[str, Any]] = None,
+ tokenizer_kwargs: Optional[dict[str, Any]] = None,
+ config_kwargs: Optional[dict[str, Any]] = None,
+ precision: Literal["float32", "int8", "uint8", "binary",
+ "ubinary"] = "float32",
+ encode_kwargs: Optional[dict[str, Any]] = None,
+ backend: Literal["torch", "onnx", "openvino"] = "torch") -> None
+```
+
+Creates a SentenceTransformersDocumentEmbedder component.
+
+**Arguments**:
+
+- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF.
+- `root_path`: The root directory path where document files are located. If provided, file paths in
+document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- `model`: The Sentence Transformers model to use for calculating embeddings. Pass a local path or ID of the model on
+Hugging Face. To be used with this component, the model must be able to embed images and text into the same
+vector space. Compatible models include:
+- "sentence-transformers/clip-ViT-B-32"
+- "sentence-transformers/clip-ViT-L-14"
+- "sentence-transformers/clip-ViT-B-16"
+- "sentence-transformers/clip-ViT-B-32-multilingual-v1"
+- "jinaai/jina-embeddings-v4"
+- "jinaai/jina-clip-v1"
+- "jinaai/jina-clip-v2".
+- `device`: The device to use for loading the model.
+Overrides the default device.
+- `token`: The API token to download private models from Hugging Face.
+- `batch_size`: Number of documents to embed at once.
+- `progress_bar`: If `True`, shows a progress bar when embedding documents.
+- `normalize_embeddings`: If `True`, the embeddings are normalized using L2 normalization, so that each embedding has a norm of 1.
+- `trust_remote_code`: If `False`, allows only Hugging Face verified model architectures.
+If `True`, allows custom models and scripts.
+- `local_files_only`: If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files.
+- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
+when loading the model. Refer to specific model documentation for available kwargs.
+- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
+Refer to specific model documentation for available kwargs.
+- `config_kwargs`: Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration.
+- `precision`: The precision to use for the embeddings.
+All non-float32 precisions are quantized embeddings.
+Quantized embeddings are smaller and faster to compute, but may have a lower accuracy.
+They are useful for reducing the size of the embeddings of a corpus for semantic search, among other tasks.
+- `encode_kwargs`: Additional keyword arguments for `SentenceTransformer.encode` when embedding documents.
+This parameter is provided for fine customization. Be careful not to clash with already set parameters and
+avoid passing parameters that change the output type.
+- `backend`: The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino".
+Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html)
+for more information on acceleration and quantization options.
+
+
+
+#### SentenceTransformersDocumentImageEmbedder.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### SentenceTransformersDocumentImageEmbedder.from\_dict
+
+```python
+@classmethod
+def from_dict(
+ cls, data: dict[str,
+ Any]) -> "SentenceTransformersDocumentImageEmbedder"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+
+
+#### SentenceTransformersDocumentImageEmbedder.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Initializes the component.
+
+
+
+#### SentenceTransformersDocumentImageEmbedder.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of documents.
+
+**Arguments**:
+
+- `documents`: Documents to embed.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `documents`: Documents with embeddings.
+
## Module openai\_document\_embedder
@@ -1170,162 +1340,6 @@ Embed a list of documents.
A dictionary with the following keys:
- `documents`: Documents with embeddings.
-
-
-## Module sentence\_transformers\_text\_embedder
-
-
-
-### SentenceTransformersTextEmbedder
-
-Embeds strings using Sentence Transformers models.
-
-You can use it to embed user query and send it to an embedding retriever.
-
-Usage example:
-```python
-from haystack.components.embedders import SentenceTransformersTextEmbedder
-
-text_to_embed = "I love pizza!"
-
-text_embedder = SentenceTransformersTextEmbedder()
-text_embedder.warm_up()
-
-print(text_embedder.run(text_to_embed))
-
-# {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]}
-```
-
-
-
-#### SentenceTransformersTextEmbedder.\_\_init\_\_
-
-```python
-def __init__(model: str = "sentence-transformers/all-mpnet-base-v2",
- device: Optional[ComponentDevice] = None,
- token: Optional[Secret] = Secret.from_env_var(
- ["HF_API_TOKEN", "HF_TOKEN"], strict=False),
- prefix: str = "",
- suffix: str = "",
- batch_size: int = 32,
- progress_bar: bool = True,
- normalize_embeddings: bool = False,
- trust_remote_code: bool = False,
- local_files_only: bool = False,
- truncate_dim: Optional[int] = None,
- model_kwargs: Optional[dict[str, Any]] = None,
- tokenizer_kwargs: Optional[dict[str, Any]] = None,
- config_kwargs: Optional[dict[str, Any]] = None,
- precision: Literal["float32", "int8", "uint8", "binary",
- "ubinary"] = "float32",
- encode_kwargs: Optional[dict[str, Any]] = None,
- backend: Literal["torch", "onnx", "openvino"] = "torch",
- revision: Optional[str] = None)
-```
-
-Create a SentenceTransformersTextEmbedder component.
-
-**Arguments**:
-
-- `model`: The model to use for calculating embeddings.
-Specify the path to a local model or the ID of the model on Hugging Face.
-- `device`: Overrides the default device used to load the model.
-- `token`: An API token to use private models from Hugging Face.
-- `prefix`: A string to add at the beginning of each text to be embedded.
-You can use it to prepend the text with an instruction, as required by some embedding models,
-such as E5 and bge.
-- `suffix`: A string to add at the end of each text to embed.
-- `batch_size`: Number of texts to embed at once.
-- `progress_bar`: If `True`, shows a progress bar for calculating embeddings.
-If `False`, disables the progress bar.
-- `normalize_embeddings`: If `True`, the embeddings are normalized using L2 normalization, so that the embeddings have a norm of 1.
-- `trust_remote_code`: If `False`, permits only Hugging Face verified model architectures.
-If `True`, permits custom models and scripts.
-- `local_files_only`: If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files.
-- `truncate_dim`: The dimension to truncate sentence embeddings to. `None` does no truncation.
-If the model has not been trained with Matryoshka Representation Learning,
-truncation of embeddings can significantly affect performance.
-- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
-when loading the model. Refer to specific model documentation for available kwargs.
-- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
-Refer to specific model documentation for available kwargs.
-- `config_kwargs`: Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration.
-- `precision`: The precision to use for the embeddings.
-All non-float32 precisions are quantized embeddings.
-Quantized embeddings are smaller in size and faster to compute, but may have a lower accuracy.
-They are useful for reducing the size of the embeddings of a corpus for semantic search, among other tasks.
-- `encode_kwargs`: Additional keyword arguments for `SentenceTransformer.encode` when embedding texts.
-This parameter is provided for fine customization. Be careful not to clash with already set parameters and
-avoid passing parameters that change the output type.
-- `backend`: The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino".
-Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html)
-for more information on acceleration and quantization options.
-- `revision`: The specific model version to use. It can be a branch name, a tag name, or a commit id,
-for a stored model on Hugging Face.
-
-
-
-#### SentenceTransformersTextEmbedder.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Serializes the component to a dictionary.
-
-**Returns**:
-
-Dictionary with serialized data.
-
-
-
-#### SentenceTransformersTextEmbedder.from\_dict
-
-```python
-@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "SentenceTransformersTextEmbedder"
-```
-
-Deserializes the component from a dictionary.
-
-**Arguments**:
-
-- `data`: Dictionary to deserialize from.
-
-**Returns**:
-
-Deserialized component.
-
-
-
-#### SentenceTransformersTextEmbedder.warm\_up
-
-```python
-def warm_up()
-```
-
-Initializes the component.
-
-
-
-#### SentenceTransformersTextEmbedder.run
-
-```python
-@component.output_types(embedding=list[float])
-def run(text: str)
-```
-
-Embed a single string.
-
-**Arguments**:
-
-- `text`: Text to embed.
-
-**Returns**:
-
-A dictionary with the following keys:
-- `embedding`: The embedding of the input text.
-
## Module sentence\_transformers\_sparse\_document\_embedder
@@ -1612,95 +1626,81 @@ Embed a single string.
A dictionary with the following keys:
- `sparse_embedding`: The sparse embedding of the input text.
-
+
-## Module image/sentence\_transformers\_doc\_image\_embedder
+## Module sentence\_transformers\_text\_embedder
-
+
-### SentenceTransformersDocumentImageEmbedder
+### SentenceTransformersTextEmbedder
-A component for computing Document embeddings based on images using Sentence Transformers models.
+Embeds strings using Sentence Transformers models.
-The embedding of each Document is stored in the `embedding` field of the Document.
+You can use it to embed user query and send it to an embedding retriever.
-### Usage example
+Usage example:
```python
-from haystack import Document
-from haystack.components.embedders.image import SentenceTransformersDocumentImageEmbedder
+from haystack.components.embedders import SentenceTransformersTextEmbedder
-embedder = SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32")
-embedder.warm_up()
+text_to_embed = "I love pizza!"
-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"}),
-]
+text_embedder = SentenceTransformersTextEmbedder()
+text_embedder.warm_up()
-result = embedder.run(documents=documents)
-documents_with_embeddings = result["documents"]
-print(documents_with_embeddings)
+print(text_embedder.run(text_to_embed))
-# [Document(id=...,
-# content='A photo of a cat',
-# meta={'file_path': 'cat.jpg',
-# 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}},
-# embedding=vector of size 512),
-# ...]
+# {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]}
```
-
+
-#### SentenceTransformersDocumentImageEmbedder.\_\_init\_\_
+#### SentenceTransformersTextEmbedder.\_\_init\_\_
```python
-def __init__(*,
- file_path_meta_field: str = "file_path",
- root_path: Optional[str] = None,
- model: str = "sentence-transformers/clip-ViT-B-32",
+def __init__(model: str = "sentence-transformers/all-mpnet-base-v2",
device: Optional[ComponentDevice] = None,
token: Optional[Secret] = Secret.from_env_var(
["HF_API_TOKEN", "HF_TOKEN"], strict=False),
+ prefix: str = "",
+ suffix: str = "",
batch_size: int = 32,
progress_bar: bool = True,
normalize_embeddings: bool = False,
trust_remote_code: bool = False,
local_files_only: bool = False,
+ truncate_dim: Optional[int] = None,
model_kwargs: Optional[dict[str, Any]] = None,
tokenizer_kwargs: Optional[dict[str, Any]] = None,
config_kwargs: Optional[dict[str, Any]] = None,
precision: Literal["float32", "int8", "uint8", "binary",
"ubinary"] = "float32",
encode_kwargs: Optional[dict[str, Any]] = None,
- backend: Literal["torch", "onnx", "openvino"] = "torch") -> None
+ backend: Literal["torch", "onnx", "openvino"] = "torch",
+ revision: Optional[str] = None)
```
-Creates a SentenceTransformersDocumentEmbedder component.
+Create a SentenceTransformersTextEmbedder component.
**Arguments**:
-- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF.
-- `root_path`: The root directory path where document files are located. If provided, file paths in
-document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
-- `model`: The Sentence Transformers model to use for calculating embeddings. Pass a local path or ID of the model on
-Hugging Face. To be used with this component, the model must be able to embed images and text into the same
-vector space. Compatible models include:
-- "sentence-transformers/clip-ViT-B-32"
-- "sentence-transformers/clip-ViT-L-14"
-- "sentence-transformers/clip-ViT-B-16"
-- "sentence-transformers/clip-ViT-B-32-multilingual-v1"
-- "jinaai/jina-embeddings-v4"
-- "jinaai/jina-clip-v1"
-- "jinaai/jina-clip-v2".
-- `device`: The device to use for loading the model.
-Overrides the default device.
-- `token`: The API token to download private models from Hugging Face.
-- `batch_size`: Number of documents to embed at once.
-- `progress_bar`: If `True`, shows a progress bar when embedding documents.
-- `normalize_embeddings`: If `True`, the embeddings are normalized using L2 normalization, so that each embedding has a norm of 1.
-- `trust_remote_code`: If `False`, allows only Hugging Face verified model architectures.
-If `True`, allows custom models and scripts.
+- `model`: The model to use for calculating embeddings.
+Specify the path to a local model or the ID of the model on Hugging Face.
+- `device`: Overrides the default device used to load the model.
+- `token`: An API token to use private models from Hugging Face.
+- `prefix`: A string to add at the beginning of each text to be embedded.
+You can use it to prepend the text with an instruction, as required by some embedding models,
+such as E5 and bge.
+- `suffix`: A string to add at the end of each text to embed.
+- `batch_size`: Number of texts to embed at once.
+- `progress_bar`: If `True`, shows a progress bar for calculating embeddings.
+If `False`, disables the progress bar.
+- `normalize_embeddings`: If `True`, the embeddings are normalized using L2 normalization, so that the embeddings have a norm of 1.
+- `trust_remote_code`: If `False`, permits only Hugging Face verified model architectures.
+If `True`, permits custom models and scripts.
- `local_files_only`: If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files.
+- `truncate_dim`: The dimension to truncate sentence embeddings to. `None` does no truncation.
+If the model has not been trained with Matryoshka Representation Learning,
+truncation of embeddings can significantly affect performance.
- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained`
when loading the model. Refer to specific model documentation for available kwargs.
- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer.
@@ -1708,18 +1708,20 @@ Refer to specific model documentation for available kwargs.
- `config_kwargs`: Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration.
- `precision`: The precision to use for the embeddings.
All non-float32 precisions are quantized embeddings.
-Quantized embeddings are smaller and faster to compute, but may have a lower accuracy.
+Quantized embeddings are smaller in size and faster to compute, but may have a lower accuracy.
They are useful for reducing the size of the embeddings of a corpus for semantic search, among other tasks.
-- `encode_kwargs`: Additional keyword arguments for `SentenceTransformer.encode` when embedding documents.
+- `encode_kwargs`: Additional keyword arguments for `SentenceTransformer.encode` when embedding texts.
This parameter is provided for fine customization. Be careful not to clash with already set parameters and
avoid passing parameters that change the output type.
- `backend`: The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino".
Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html)
for more information on acceleration and quantization options.
+- `revision`: The specific model version to use. It can be a branch name, a tag name, or a commit id,
+for a stored model on Hugging Face.
-
+
-#### SentenceTransformersDocumentImageEmbedder.to\_dict
+#### SentenceTransformersTextEmbedder.to\_dict
```python
def to_dict() -> dict[str, Any]
@@ -1731,15 +1733,13 @@ Serializes the component to a dictionary.
Dictionary with serialized data.
-
+
-#### SentenceTransformersDocumentImageEmbedder.from\_dict
+#### SentenceTransformersTextEmbedder.from\_dict
```python
@classmethod
-def from_dict(
- cls, data: dict[str,
- Any]) -> "SentenceTransformersDocumentImageEmbedder"
+def from_dict(cls, data: dict[str, Any]) -> "SentenceTransformersTextEmbedder"
```
Deserializes the component from a dictionary.
@@ -1752,33 +1752,33 @@ Deserializes the component from a dictionary.
Deserialized component.
-
+
-#### SentenceTransformersDocumentImageEmbedder.warm\_up
+#### SentenceTransformersTextEmbedder.warm\_up
```python
-def warm_up() -> None
+def warm_up()
```
Initializes the component.
-
+
-#### SentenceTransformersDocumentImageEmbedder.run
+#### SentenceTransformersTextEmbedder.run
```python
-@component.output_types(documents=list[Document])
-def run(documents: list[Document]) -> dict[str, list[Document]]
+@component.output_types(embedding=list[float])
+def run(text: str)
```
-Embed a list of documents.
+Embed a single string.
**Arguments**:
-- `documents`: Documents to embed.
+- `text`: Text to embed.
**Returns**:
A dictionary with the following keys:
-- `documents`: Documents with embeddings.
+- `embedding`: The embedding of the input text.
diff --git a/docs-website/reference/haystack-api/extractors_api.md b/docs-website/reference/haystack-api/extractors_api.md
index bc6c990607..50acd8fa09 100644
--- a/docs-website/reference/haystack-api/extractors_api.md
+++ b/docs-website/reference/haystack-api/extractors_api.md
@@ -5,154 +5,95 @@ description: "Components to extract specific elements from textual data."
slug: "/extractors-api"
---
-
+
-## Module named\_entity\_extractor
+## Module image/llm\_document\_content\_extractor
-
+
-### NamedEntityExtractorBackend
+### LLMDocumentContentExtractor
-NLP backend to use for Named Entity Recognition.
+Extracts textual content from image-based documents using a vision-enabled LLM (Large Language Model).
-
+This component converts each input document into an image using the DocumentToImageContent component,
+uses a prompt to instruct the LLM on how to extract content, and uses a ChatGenerator to extract structured
+textual content based on the provided prompt.
-#### HUGGING\_FACE
+The prompt must not contain variables; it should only include instructions for the LLM. Image data and the prompt
+are passed together to the LLM as a chat message.
-Uses an Hugging Face model and pipeline.
+Documents for which the LLM fails to extract content are returned in a separate `failed_documents` list. These
+failed documents will have a `content_extraction_error` entry in their metadata. This metadata can be used for
+debugging or for reprocessing the documents later.
-
-
-#### SPACY
-
-Uses a spaCy model and pipeline.
-
-
-
-#### NamedEntityExtractorBackend.from\_str
-
-```python
-@staticmethod
-def from_str(string: str) -> "NamedEntityExtractorBackend"
-```
-
-Convert a string to a NamedEntityExtractorBackend enum.
-
-
-
-### NamedEntityAnnotation
-
-Describes a single NER annotation.
-
-**Arguments**:
-
-- `entity`: Entity label.
-- `start`: Start index of the entity in the document.
-- `end`: End index of the entity in the document.
-- `score`: Score calculated by the model.
-
-
-
-### NamedEntityExtractor
-
-Annotates named entities in a collection of documents.
-
-The component supports two backends: Hugging Face and spaCy. The
-former can be used with any sequence classification model from the
-[Hugging Face model hub](https://huggingface.co/models), while the
-latter can be used with any [spaCy model](https://spacy.io/models)
-that contains an NER component. Annotations are stored as metadata
-in the documents.
-
-Usage example:
+### Usage example
```python
from haystack import Document
-from haystack.components.extractors.named_entity_extractor import NamedEntityExtractor
-
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+chat_generator = OpenAIChatGenerator()
+extractor = LLMDocumentContentExtractor(chat_generator=chat_generator)
documents = [
- Document(content="I'm Merlin, the happy pig!"),
- Document(content="My name is Clara and I live in Berkeley, California."),
+ Document(content="", meta={"file_path": "image.jpg"}),
+ Document(content="", meta={"file_path": "document.pdf", "page_number": 1}),
]
-extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
-extractor.warm_up()
-results = extractor.run(documents=documents)["documents"]
-annotations = [NamedEntityExtractor.get_stored_annotations(doc) for doc in results]
-print(annotations)
+updated_documents = extractor.run(documents=documents)["documents"]
+print(updated_documents)
+# [Document(content='Extracted text from image.jpg',
+# meta={'file_path': 'image.jpg'}),
+# ...]
```
-
+
-#### NamedEntityExtractor.\_\_init\_\_
+#### LLMDocumentContentExtractor.\_\_init\_\_
```python
-def __init__(
- *,
- backend: Union[str, NamedEntityExtractorBackend],
- model: str,
- pipeline_kwargs: Optional[dict[str, Any]] = None,
- device: Optional[ComponentDevice] = None,
- token: Optional[Secret] = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"],
- strict=False)
-) -> None
+def __init__(*,
+ chat_generator: ChatGenerator,
+ prompt: str = DEFAULT_PROMPT_TEMPLATE,
+ file_path_meta_field: str = "file_path",
+ root_path: Optional[str] = None,
+ detail: Optional[Literal["auto", "high", "low"]] = None,
+ size: Optional[tuple[int, int]] = None,
+ raise_on_failure: bool = False,
+ max_workers: int = 3)
```
-Create a Named Entity extractor component.
+Initialize the LLMDocumentContentExtractor component.
**Arguments**:
-- `backend`: Backend to use for NER.
-- `model`: Name of the model or a path to the model on
-the local disk. Dependent on the backend.
-- `pipeline_kwargs`: Keyword arguments passed to the pipeline. The
-pipeline can override these arguments. Dependent on the backend.
-- `device`: The device on which the model is loaded. If `None`,
-the default device is automatically selected. If a
-device/device map is specified in `pipeline_kwargs`,
-it overrides this parameter (only applicable to the
-HuggingFace backend).
-- `token`: The API token to download private models from Hugging Face.
+- `chat_generator`: A ChatGenerator instance representing the LLM used to extract text. This generator must
+support vision-based input and return a plain text response.
+- `prompt`: Instructional text provided to the LLM. It must not contain Jinja variables.
+The prompt should only contain instructions on how to extract the content of the image-based document.
+- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF.
+- `root_path`: The root directory path where document files are located. If provided, file paths in
+document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- `detail`: Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low".
+This will be passed to chat_generator when processing the images.
+- `size`: 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.
+- `raise_on_failure`: If True, exceptions from the LLM are raised. If False, failed documents are logged
+and returned.
+- `max_workers`: Maximum number of threads used to parallelize LLM calls across documents using a
+ThreadPoolExecutor.
-
+
-#### NamedEntityExtractor.warm\_up
+#### LLMDocumentContentExtractor.warm\_up
```python
def warm_up()
```
-Initialize the component.
+Warm up the ChatGenerator if it has a warm_up method.
-**Raises**:
+
-- `ComponentError`: If the backend fails to initialize successfully.
-
-
-
-#### NamedEntityExtractor.run
-
-```python
-@component.output_types(documents=list[Document])
-def 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.
-
-**Arguments**:
-
-- `documents`: Documents to process.
-- `batch_size`: Batch size used for processing the documents.
-
-**Raises**:
-
-- `ComponentError`: If the backend fails to process a document.
-
-**Returns**:
-
-Processed documents.
-
-
-
-#### NamedEntityExtractor.to\_dict
+#### LLMDocumentContentExtractor.to\_dict
```python
def to_dict() -> dict[str, Any]
@@ -164,55 +105,50 @@ Serializes the component to a dictionary.
Dictionary with serialized data.
-
+
-#### NamedEntityExtractor.from\_dict
+#### LLMDocumentContentExtractor.from\_dict
```python
@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "NamedEntityExtractor"
+def from_dict(cls, data: dict[str, Any]) -> "LLMDocumentContentExtractor"
```
Deserializes the component from a dictionary.
**Arguments**:
-- `data`: Dictionary to deserialize from.
+- `data`: Dictionary with serialized data.
**Returns**:
-Deserialized component.
+An instance of the component.
-
+
-#### NamedEntityExtractor.initialized
+#### LLMDocumentContentExtractor.run
```python
-@property
-def initialized() -> bool
+@component.output_types(documents=list[Document],
+ failed_documents=list[Document])
+def run(documents: list[Document]) -> dict[str, list[Document]]
```
-Returns if the extractor is ready to annotate text.
+Run content extraction on a list of image-based documents using a vision-capable LLM.
-
-
-#### NamedEntityExtractor.get\_stored\_annotations
-
-```python
-@classmethod
-def get_stored_annotations(
- cls, document: Document) -> Optional[list[NamedEntityAnnotation]]
-```
-
-Returns the document's named entity annotations stored in its metadata, if any.
+Each document is passed to the LLM along with a predefined prompt. The response is used to update the document's
+content. If the extraction fails, the document is returned in the `failed_documents` list with metadata
+describing the failure.
**Arguments**:
-- `document`: Document whose annotations are to be fetched.
+- `documents`: A list of image-based documents to process. Each must have a valid file path in its metadata.
**Returns**:
-The stored annotations.
+A dictionary with:
+- "documents": Successfully processed documents, updated with extracted content.
+- "failed_documents": Documents that failed processing, annotated with failure metadata.
@@ -431,95 +367,154 @@ A dictionary with the keys:
"metadata_extraction_error" and "metadata_extraction_response" in their metadata. These documents can be
re-run with the extractor to extract metadata.
-
+
-## Module image/llm\_document\_content\_extractor
+## Module named\_entity\_extractor
-
+
-### LLMDocumentContentExtractor
+### NamedEntityExtractorBackend
-Extracts textual content from image-based documents using a vision-enabled LLM (Large Language Model).
+NLP backend to use for Named Entity Recognition.
-This component converts each input document into an image using the DocumentToImageContent component,
-uses a prompt to instruct the LLM on how to extract content, and uses a ChatGenerator to extract structured
-textual content based on the provided prompt.
+
-The prompt must not contain variables; it should only include instructions for the LLM. Image data and the prompt
-are passed together to the LLM as a chat message.
+#### HUGGING\_FACE
-Documents for which the LLM fails to extract content are returned in a separate `failed_documents` list. These
-failed documents will have a `content_extraction_error` entry in their metadata. This metadata can be used for
-debugging or for reprocessing the documents later.
+Uses an Hugging Face model and pipeline.
-### Usage example
-```python
-from haystack import Document
-from haystack.components.generators.chat import OpenAIChatGenerator
-from haystack.components.extractors.image import LLMDocumentContentExtractor
-chat_generator = OpenAIChatGenerator()
-extractor = LLMDocumentContentExtractor(chat_generator=chat_generator)
-documents = [
- Document(content="", meta={"file_path": "image.jpg"}),
- Document(content="", meta={"file_path": "document.pdf", "page_number": 1}),
-]
-updated_documents = extractor.run(documents=documents)["documents"]
-print(updated_documents)
-# [Document(content='Extracted text from image.jpg',
-# meta={'file_path': 'image.jpg'}),
-# ...]
-```
+
-
+#### SPACY
-#### LLMDocumentContentExtractor.\_\_init\_\_
+Uses a spaCy model and pipeline.
+
+
+
+#### NamedEntityExtractorBackend.from\_str
```python
-def __init__(*,
- chat_generator: ChatGenerator,
- prompt: str = DEFAULT_PROMPT_TEMPLATE,
- file_path_meta_field: str = "file_path",
- root_path: Optional[str] = None,
- detail: Optional[Literal["auto", "high", "low"]] = None,
- size: Optional[tuple[int, int]] = None,
- raise_on_failure: bool = False,
- max_workers: int = 3)
+@staticmethod
+def from_str(string: str) -> "NamedEntityExtractorBackend"
```
-Initialize the LLMDocumentContentExtractor component.
+Convert a string to a NamedEntityExtractorBackend enum.
+
+
+
+### NamedEntityAnnotation
+
+Describes a single NER annotation.
**Arguments**:
-- `chat_generator`: A ChatGenerator instance representing the LLM used to extract text. This generator must
-support vision-based input and return a plain text response.
-- `prompt`: Instructional text provided to the LLM. It must not contain Jinja variables.
-The prompt should only contain instructions on how to extract the content of the image-based document.
-- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF.
-- `root_path`: The root directory path where document files are located. If provided, file paths in
-document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
-- `detail`: Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low".
-This will be passed to chat_generator when processing the images.
-- `size`: 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.
-- `raise_on_failure`: If True, exceptions from the LLM are raised. If False, failed documents are logged
-and returned.
-- `max_workers`: Maximum number of threads used to parallelize LLM calls across documents using a
-ThreadPoolExecutor.
+- `entity`: Entity label.
+- `start`: Start index of the entity in the document.
+- `end`: End index of the entity in the document.
+- `score`: Score calculated by the model.
-
+
-#### LLMDocumentContentExtractor.warm\_up
+### NamedEntityExtractor
+
+Annotates named entities in a collection of documents.
+
+The component supports two backends: Hugging Face and spaCy. The
+former can be used with any sequence classification model from the
+[Hugging Face model hub](https://huggingface.co/models), while the
+latter can be used with any [spaCy model](https://spacy.io/models)
+that contains an NER component. Annotations are stored as metadata
+in the documents.
+
+Usage example:
+```python
+from haystack import Document
+from haystack.components.extractors.named_entity_extractor import NamedEntityExtractor
+
+documents = [
+ Document(content="I'm Merlin, the happy pig!"),
+ Document(content="My name is Clara and I live in Berkeley, California."),
+]
+extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
+extractor.warm_up()
+results = extractor.run(documents=documents)["documents"]
+annotations = [NamedEntityExtractor.get_stored_annotations(doc) for doc in results]
+print(annotations)
+```
+
+
+
+#### NamedEntityExtractor.\_\_init\_\_
+
+```python
+def __init__(
+ *,
+ backend: Union[str, NamedEntityExtractorBackend],
+ model: str,
+ pipeline_kwargs: Optional[dict[str, Any]] = None,
+ device: Optional[ComponentDevice] = None,
+ token: Optional[Secret] = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"],
+ strict=False)
+) -> None
+```
+
+Create a Named Entity extractor component.
+
+**Arguments**:
+
+- `backend`: Backend to use for NER.
+- `model`: Name of the model or a path to the model on
+the local disk. Dependent on the backend.
+- `pipeline_kwargs`: Keyword arguments passed to the pipeline. The
+pipeline can override these arguments. Dependent on the backend.
+- `device`: The device on which the model is loaded. If `None`,
+the default device is automatically selected. If a
+device/device map is specified in `pipeline_kwargs`,
+it overrides this parameter (only applicable to the
+HuggingFace backend).
+- `token`: The API token to download private models from Hugging Face.
+
+
+
+#### NamedEntityExtractor.warm\_up
```python
def warm_up()
```
-Warm up the ChatGenerator if it has a warm_up method.
+Initialize the component.
-
+**Raises**:
-#### LLMDocumentContentExtractor.to\_dict
+- `ComponentError`: If the backend fails to initialize successfully.
+
+
+
+#### NamedEntityExtractor.run
+
+```python
+@component.output_types(documents=list[Document])
+def 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.
+
+**Arguments**:
+
+- `documents`: Documents to process.
+- `batch_size`: Batch size used for processing the documents.
+
+**Raises**:
+
+- `ComponentError`: If the backend fails to process a document.
+
+**Returns**:
+
+Processed documents.
+
+
+
+#### NamedEntityExtractor.to\_dict
```python
def to_dict() -> dict[str, Any]
@@ -531,50 +526,55 @@ Serializes the component to a dictionary.
Dictionary with serialized data.
-
+
-#### LLMDocumentContentExtractor.from\_dict
+#### NamedEntityExtractor.from\_dict
```python
@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "LLMDocumentContentExtractor"
+def from_dict(cls, data: dict[str, Any]) -> "NamedEntityExtractor"
```
Deserializes the component from a dictionary.
**Arguments**:
-- `data`: Dictionary with serialized data.
+- `data`: Dictionary to deserialize from.
**Returns**:
-An instance of the component.
+Deserialized component.
-
+
-#### LLMDocumentContentExtractor.run
+#### NamedEntityExtractor.initialized
```python
-@component.output_types(documents=list[Document],
- failed_documents=list[Document])
-def run(documents: list[Document]) -> dict[str, list[Document]]
+@property
+def initialized() -> bool
```
-Run content extraction on a list of image-based documents using a vision-capable LLM.
+Returns if the extractor is ready to annotate text.
-Each document is passed to the LLM along with a predefined prompt. The response is used to update the document's
-content. If the extraction fails, the document is returned in the `failed_documents` list with metadata
-describing the failure.
+
+
+#### NamedEntityExtractor.get\_stored\_annotations
+
+```python
+@classmethod
+def get_stored_annotations(
+ cls, document: Document) -> Optional[list[NamedEntityAnnotation]]
+```
+
+Returns the document's named entity annotations stored in its metadata, if any.
**Arguments**:
-- `documents`: A list of image-based documents to process. Each must have a valid file path in its metadata.
+- `document`: Document whose annotations are to be fetched.
**Returns**:
-A dictionary with:
-- "documents": Successfully processed documents, updated with extracted content.
-- "failed_documents": Documents that failed processing, annotated with failure metadata.
+The stored annotations.
diff --git a/docs-website/reference/haystack-api/generators_api.md b/docs-website/reference/haystack-api/generators_api.md
index a1dd40e899..aa9d12ecd5 100644
--- a/docs-website/reference/haystack-api/generators_api.md
+++ b/docs-website/reference/haystack-api/generators_api.md
@@ -183,594 +183,6 @@ the OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat/c
A list of strings containing the generated responses and a list of dictionaries containing the metadata
for each response.
-
-
-## Module hugging\_face\_local
-
-
-
-### HuggingFaceLocalGenerator
-
-Generates text using models from Hugging Face that run locally.
-
-LLMs running locally may need powerful hardware.
-
-### Usage example
-
-```python
-from haystack.components.generators import HuggingFaceLocalGenerator
-
-generator = HuggingFaceLocalGenerator(
- model="google/flan-t5-large",
- task="text2text-generation",
- generation_kwargs={"max_new_tokens": 100, "temperature": 0.9})
-
-generator.warm_up()
-
-print(generator.run("Who is the best American actor?"))
-# {'replies': ['John Cusack']}
-```
-
-
-
-#### HuggingFaceLocalGenerator.\_\_init\_\_
-
-```python
-def __init__(model: str = "google/flan-t5-base",
- task: Optional[Literal["text-generation",
- "text2text-generation"]] = None,
- device: Optional[ComponentDevice] = None,
- token: Optional[Secret] = Secret.from_env_var(
- ["HF_API_TOKEN", "HF_TOKEN"], strict=False),
- generation_kwargs: Optional[dict[str, Any]] = None,
- huggingface_pipeline_kwargs: Optional[dict[str, Any]] = None,
- stop_words: Optional[list[str]] = None,
- streaming_callback: Optional[StreamingCallbackT] = None)
-```
-
-Creates an instance of a HuggingFaceLocalGenerator.
-
-**Arguments**:
-
-- `model`: The Hugging Face text generation model name or path.
-- `task`: The task for the Hugging Face pipeline. Possible options:
-- `text-generation`: Supported by decoder models, like GPT.
-- `text2text-generation`: Supported by encoder-decoder models, like T5.
-If the task is specified in `huggingface_pipeline_kwargs`, this parameter is ignored.
-If not specified, the component calls the Hugging Face API to infer the task from the model name.
-- `device`: The device for loading the model. If `None`, automatically selects the default device.
-If a device or device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter.
-- `token`: The token to use as HTTP bearer authorization for remote files.
-If the token is specified in `huggingface_pipeline_kwargs`, this parameter is ignored.
-- `generation_kwargs`: A dictionary with keyword arguments to customize text generation.
-Some examples: `max_length`, `max_new_tokens`, `temperature`, `top_k`, `top_p`.
-See Hugging Face's documentation for more information:
-- [customize-text-generation](https://huggingface.co/docs/transformers/main/en/generation_strategies#customize-text-generation)
-- [transformers.GenerationConfig](https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationConfig)
-- `huggingface_pipeline_kwargs`: Dictionary with keyword arguments to initialize the
-Hugging Face pipeline for text generation.
-These keyword arguments provide fine-grained control over the Hugging Face pipeline.
-In case of duplication, these kwargs override `model`, `task`, `device`, and `token` init parameters.
-For available kwargs, see [Hugging Face documentation](https://huggingface.co/docs/transformers/en/main_classes/pipelines#transformers.pipeline.task).
-In this dictionary, you can also include `model_kwargs` to specify the kwargs for model initialization:
-[transformers.PreTrainedModel.from_pretrained](https://huggingface.co/docs/transformers/en/main_classes/model#transformers.PreTrainedModel.from_pretrained)
-- `stop_words`: If the model generates a stop word, the generation stops.
-If you provide this parameter, don't specify the `stopping_criteria` in `generation_kwargs`.
-For some chat models, the output includes both the new text and the original prompt.
-In these cases, make sure your prompt has no stop words.
-- `streaming_callback`: An optional callable for handling streaming responses.
-
-
-
-#### HuggingFaceLocalGenerator.warm\_up
-
-```python
-def warm_up()
-```
-
-Initializes the component.
-
-
-
-#### HuggingFaceLocalGenerator.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Serializes the component to a dictionary.
-
-**Returns**:
-
-Dictionary with serialized data.
-
-
-
-#### HuggingFaceLocalGenerator.from\_dict
-
-```python
-@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceLocalGenerator"
-```
-
-Deserializes the component from a dictionary.
-
-**Arguments**:
-
-- `data`: The dictionary to deserialize from.
-
-**Returns**:
-
-The deserialized component.
-
-
-
-#### HuggingFaceLocalGenerator.run
-
-```python
-@component.output_types(replies=list[str])
-def run(prompt: str,
- streaming_callback: Optional[StreamingCallbackT] = None,
- generation_kwargs: Optional[dict[str, Any]] = None)
-```
-
-Run the text generation model on the given prompt.
-
-**Arguments**:
-
-- `prompt`: A string representing the prompt.
-- `streaming_callback`: A callback function that is called when a new token is received from the stream.
-- `generation_kwargs`: Additional keyword arguments for text generation.
-
-**Returns**:
-
-A dictionary containing the generated replies.
-- replies: A list of strings representing the generated replies.
-
-
-
-## Module hugging\_face\_api
-
-
-
-### HuggingFaceAPIGenerator
-
-Generates text using Hugging Face APIs.
-
-Use it with the following Hugging Face APIs:
-- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
-- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
-
-**Note:** As of July 2025, the Hugging Face Inference API no longer offers generative models through the
-`text_generation` endpoint. Generative models are now only available through providers supporting the
-`chat_completion` endpoint. As a result, this component might no longer work with the Hugging Face Inference API.
-Use the `HuggingFaceAPIChatGenerator` component, which supports the `chat_completion` endpoint.
-
-### Usage examples
-
-#### With Hugging Face Inference Endpoints
-
-
-#### With self-hosted text generation inference
-
-#### With the free serverless inference API
-
-Be aware that this example might not work as the Hugging Face Inference API no longer offer models that support the
-`text_generation` endpoint. Use the `HuggingFaceAPIChatGenerator` for generative models through the
-`chat_completion` endpoint.
-
-```python
-from haystack.components.generators import HuggingFaceAPIGenerator
-from haystack.utils import Secret
-
-generator = HuggingFaceAPIGenerator(api_type="inference_endpoints",
- api_params={"url": ""},
- token=Secret.from_token(""))
-
-result = generator.run(prompt="What's Natural Language Processing?")
-print(result)
-```
-```python
-from haystack.components.generators import HuggingFaceAPIGenerator
-
-generator = HuggingFaceAPIGenerator(api_type="text_generation_inference",
- api_params={"url": "http://localhost:8080"})
-
-result = generator.run(prompt="What's Natural Language Processing?")
-print(result)
-```
-```python
-from haystack.components.generators import HuggingFaceAPIGenerator
-from haystack.utils import Secret
-
-generator = HuggingFaceAPIGenerator(api_type="serverless_inference_api",
- api_params={"model": "HuggingFaceH4/zephyr-7b-beta"},
- token=Secret.from_token(""))
-
-result = generator.run(prompt="What's Natural Language Processing?")
-print(result)
-```
-
-
-
-#### HuggingFaceAPIGenerator.\_\_init\_\_
-
-```python
-def __init__(api_type: Union[HFGenerationAPIType, str],
- api_params: dict[str, str],
- token: Optional[Secret] = Secret.from_env_var(
- ["HF_API_TOKEN", "HF_TOKEN"], strict=False),
- generation_kwargs: Optional[dict[str, Any]] = None,
- stop_words: Optional[list[str]] = None,
- streaming_callback: Optional[StreamingCallbackT] = None)
-```
-
-Initialize the HuggingFaceAPIGenerator instance.
-
-**Arguments**:
-
-- `api_type`: The type of Hugging Face API to use. Available types:
-- `text_generation_inference`: See [TGI](https://github.com/huggingface/text-generation-inference).
-- `inference_endpoints`: See [Inference Endpoints](https://huggingface.co/inference-endpoints).
-- `serverless_inference_api`: See [Serverless Inference API](https://huggingface.co/inference-api).
- This might no longer work due to changes in the models offered in the Hugging Face Inference API.
- Please use the `HuggingFaceAPIChatGenerator` component instead.
-- `api_params`: A dictionary with the following keys:
-- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.
-- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or
-`TEXT_GENERATION_INFERENCE`.
-- Other parameters specific to the chosen API type, such as `timeout`, `headers`, `provider` etc.
-- `token`: 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`: A dictionary with keyword arguments to customize text generation. Some examples: `max_new_tokens`,
-`temperature`, `top_k`, `top_p`.
-For details, see [Hugging Face documentation](https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client#huggingface_hub.InferenceClient.text_generation)
-for more information.
-- `stop_words`: An optional list of strings representing the stop words.
-- `streaming_callback`: An optional callable for handling streaming responses.
-
-
-
-#### HuggingFaceAPIGenerator.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Serialize this component to a dictionary.
-
-**Returns**:
-
-A dictionary containing the serialized component.
-
-
-
-#### HuggingFaceAPIGenerator.from\_dict
-
-```python
-@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceAPIGenerator"
-```
-
-Deserialize this component from a dictionary.
-
-
-
-#### HuggingFaceAPIGenerator.run
-
-```python
-@component.output_types(replies=list[str], meta=list[dict[str, Any]])
-def run(prompt: str,
- streaming_callback: Optional[StreamingCallbackT] = None,
- generation_kwargs: Optional[dict[str, Any]] = None)
-```
-
-Invoke the text generation inference for the given prompt and generation parameters.
-
-**Arguments**:
-
-- `prompt`: A string representing the prompt.
-- `streaming_callback`: A callback function that is called when a new token is received from the stream.
-- `generation_kwargs`: Additional keyword arguments for text generation.
-
-**Returns**:
-
-A dictionary with the generated replies and metadata. Both are lists of length n.
-- replies: A list of strings representing the generated replies.
-
-
-
-## Module openai
-
-
-
-### OpenAIGenerator
-
-Generates text using OpenAI's large language models (LLMs).
-
-It works with the gpt-4 and gpt-5 series models and supports streaming responses
-from OpenAI API. It uses strings as input and output.
-
-You can customize how the text is generated by passing parameters to the
-OpenAI API. Use the `**generation_kwargs` argument when you initialize
-the component or when you run it. Any parameter that works with
-`openai.ChatCompletion.create` will work here too.
-
-
-For details on OpenAI API parameters, see
-[OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
-
-### Usage example
-
-```python
-from haystack.components.generators import OpenAIGenerator
-client = OpenAIGenerator()
-response = client.run("What's Natural Language Processing? Be brief.")
-print(response)
-
->> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on
->> the interaction between computers and human language. It involves enabling computers to understand, interpret,
->> and respond to natural human language in a way that is both meaningful and useful.'], 'meta': [{'model':
->> 'gpt-5-mini', 'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 16,
->> 'completion_tokens': 49, 'total_tokens': 65}}]}
-```
-
-
-
-#### OpenAIGenerator.\_\_init\_\_
-
-```python
-def __init__(api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
- model: str = "gpt-5-mini",
- streaming_callback: Optional[StreamingCallbackT] = None,
- api_base_url: Optional[str] = None,
- organization: Optional[str] = None,
- system_prompt: Optional[str] = None,
- generation_kwargs: Optional[dict[str, Any]] = None,
- timeout: Optional[float] = None,
- max_retries: Optional[int] = None,
- http_client_kwargs: Optional[dict[str, Any]] = None)
-```
-
-Creates an instance of OpenAIGenerator. Unless specified otherwise in `model`, uses OpenAI's gpt-5-mini
-
-By setting the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES' you can change the timeout and max_retries parameters
-in the OpenAI client.
-
-**Arguments**:
-
-- `api_key`: The OpenAI API key to connect to OpenAI.
-- `model`: The name of the 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`: An optional base URL.
-- `organization`: The Organization ID, defaults to `None`.
-- `system_prompt`: 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`: Other parameters to use for the model. These parameters are all sent directly to
-the OpenAI endpoint. See OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat) for
-more details.
-Some of the supported parameters:
-- `max_completion_tokens`: An upper bound for the number of tokens that can be generated for a completion,
- including visible output tokens and reasoning tokens.
-- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
- Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
-- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
- considers the results of the tokens with top_p probability mass. So, 0.1 means only the tokens
- comprising the top 10% probability mass are considered.
-- `n`: How many completions to generate for each prompt. For example, if the LLM gets 3 prompts and n is 2,
- it will generate two completions for each of the three prompts, ending up with 6 completions in total.
-- `stop`: One or more sequences after which the LLM should stop generating tokens.
-- `presence_penalty`: What penalty to apply if a token is already present at all. Bigger values mean
- the model will be less likely to repeat the same token in the text.
-- `frequency_penalty`: What penalty to apply if a token has already been generated in the text.
- Bigger values mean the model will be less likely to repeat the same token in the text.
-- `logit_bias`: Add a logit bias to specific tokens. The keys of the dictionary are tokens, and the
- values are the bias to add to that token.
-- `timeout`: Timeout for OpenAI Client calls, if not set it is inferred from the `OPENAI_TIMEOUT` environment variable
-or set to 30.
-- `max_retries`: Maximum retries to establish contact with OpenAI if it returns an internal error, if not set it is inferred
-from the `OPENAI_MAX_RETRIES` environment variable or set to 5.
-- `http_client_kwargs`: 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`).
-
-
-
-#### OpenAIGenerator.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Serialize this component to a dictionary.
-
-**Returns**:
-
-The serialized component as a dictionary.
-
-
-
-#### OpenAIGenerator.from\_dict
-
-```python
-@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "OpenAIGenerator"
-```
-
-Deserialize this component from a dictionary.
-
-**Arguments**:
-
-- `data`: The dictionary representation of this component.
-
-**Returns**:
-
-The deserialized component instance.
-
-
-
-#### OpenAIGenerator.run
-
-```python
-@component.output_types(replies=list[str], meta=list[dict[str, Any]])
-def run(
- prompt: str,
- system_prompt: Optional[str] = None,
- streaming_callback: Optional[StreamingCallbackT] = None,
- generation_kwargs: Optional[dict[str, Any]] = None
-) -> dict[str, Union[list[str], list[dict[str, Any]]]]
-```
-
-Invoke the text generation inference based on the provided messages and generation parameters.
-
-**Arguments**:
-
-- `prompt`: The string prompt to use for text generation.
-- `system_prompt`: The system prompt to use for text generation. If this run time system prompt is omitted, the system
-prompt, if defined at initialisation time, is used.
-- `streaming_callback`: A callback function that is called when a new token is received from the stream.
-- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters
-passed in the `__init__` method. For more details on the parameters supported by the OpenAI API, refer to
-the OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat/create).
-
-**Returns**:
-
-A list of strings containing the generated responses and a list of dictionaries containing the metadata
-for each response.
-
-
-
-## Module openai\_dalle
-
-
-
-### DALLEImageGenerator
-
-Generates images using OpenAI's DALL-E model.
-
-For details on OpenAI API parameters, see
-[OpenAI documentation](https://platform.openai.com/docs/api-reference/images/create).
-
-### Usage example
-
-```python
-from haystack.components.generators import DALLEImageGenerator
-image_generator = DALLEImageGenerator()
-response = image_generator.run("Show me a picture of a black cat.")
-print(response)
-```
-
-
-
-#### DALLEImageGenerator.\_\_init\_\_
-
-```python
-def __init__(model: str = "dall-e-3",
- quality: Literal["standard", "hd"] = "standard",
- size: Literal["256x256", "512x512", "1024x1024", "1792x1024",
- "1024x1792"] = "1024x1024",
- response_format: Literal["url", "b64_json"] = "url",
- api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
- api_base_url: Optional[str] = None,
- organization: Optional[str] = None,
- timeout: Optional[float] = None,
- max_retries: Optional[int] = None,
- http_client_kwargs: Optional[dict[str, Any]] = None)
-```
-
-Creates an instance of DALLEImageGenerator. Unless specified otherwise in `model`, uses OpenAI's dall-e-3.
-
-**Arguments**:
-
-- `model`: The model to use for image generation. Can be "dall-e-2" or "dall-e-3".
-- `quality`: The quality of the generated image. Can be "standard" or "hd".
-- `size`: The size of the generated images.
-Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2.
-Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models.
-- `response_format`: The format of the response. Can be "url" or "b64_json".
-- `api_key`: The OpenAI API key to connect to OpenAI.
-- `api_base_url`: An optional base URL.
-- `organization`: The Organization ID, defaults to `None`.
-- `timeout`: Timeout for OpenAI Client calls. If not set, it is inferred from the `OPENAI_TIMEOUT` environment variable
-or set to 30.
-- `max_retries`: Maximum retries to establish contact with OpenAI if it returns an internal error. If not set, it is inferred
-from the `OPENAI_MAX_RETRIES` environment variable or set to 5.
-- `http_client_kwargs`: 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`).
-
-
-
-#### DALLEImageGenerator.warm\_up
-
-```python
-def warm_up() -> None
-```
-
-Warm up the OpenAI client.
-
-
-
-#### DALLEImageGenerator.run
-
-```python
-@component.output_types(images=list[str], revised_prompt=str)
-def run(prompt: str,
- size: Optional[Literal["256x256", "512x512", "1024x1024", "1792x1024",
- "1024x1792"]] = None,
- quality: Optional[Literal["standard", "hd"]] = None,
- response_format: Optional[Optional[Literal["url",
- "b64_json"]]] = None)
-```
-
-Invokes the image generation inference based on the provided prompt and generation parameters.
-
-**Arguments**:
-
-- `prompt`: The prompt to generate the image.
-- `size`: If provided, overrides the size provided during initialization.
-- `quality`: If provided, overrides the quality provided during initialization.
-- `response_format`: If provided, overrides the response format provided during initialization.
-
-**Returns**:
-
-A dictionary containing the generated list of images and the revised prompt.
-Depending on the `response_format` parameter, the list of images can be URLs or base64 encoded JSON strings.
-The revised prompt is the prompt that was used to generate the image, if there was any revision
-to the prompt made by OpenAI.
-
-
-
-#### DALLEImageGenerator.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Serialize this component to a dictionary.
-
-**Returns**:
-
-The serialized component as a dictionary.
-
-
-
-#### DALLEImageGenerator.from\_dict
-
-```python
-@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "DALLEImageGenerator"
-```
-
-Deserialize this component from a dictionary.
-
-**Arguments**:
-
-- `data`: The dictionary representation of this component.
-
-**Returns**:
-
-The deserialized component instance.
-
## Module chat/azure
@@ -1266,6 +678,403 @@ If set, it will override the `tools_strict` parameter set during component initi
A dictionary with the following key:
- `replies`: A list containing the generated responses as ChatMessage instances.
+
+
+## Module chat/fallback
+
+
+
+### FallbackChatGenerator
+
+A chat generator wrapper that tries multiple chat generators sequentially.
+
+It forwards all parameters transparently to the underlying chat generators and returns the first successful result.
+Calls chat generators sequentially until one succeeds. Falls back on any exception raised by a generator.
+If all chat generators fail, it raises a RuntimeError with details.
+
+Timeout enforcement is fully delegated to the underlying chat generators. The fallback mechanism will only
+work correctly if the underlying chat generators implement proper timeout handling and raise exceptions
+when timeouts occur. For predictable latency guarantees, ensure your chat generators:
+- Support a `timeout` parameter in their initialization
+- Implement timeout as total wall-clock time (shared deadline for both streaming and non-streaming)
+- Raise timeout exceptions (e.g., TimeoutError, asyncio.TimeoutError, httpx.TimeoutException) when exceeded
+
+Note: Most well-implemented chat generators (OpenAI, Anthropic, Cohere, etc.) support timeout parameters
+with consistent semantics. For HTTP-based LLM providers, a single timeout value (e.g., `timeout=30`)
+typically applies to all connection phases: connection setup, read, write, and pool. For streaming
+responses, read timeout is the maximum gap between chunks. For non-streaming, it's the time limit for
+receiving the complete response.
+
+Failover is automatically triggered when a generator raises any exception, including:
+- Timeout errors (if the generator implements and raises them)
+- Rate limit errors (429)
+- Authentication errors (401)
+- Context length errors (400)
+- Server errors (500+)
+- Any other exception
+
+
+
+#### FallbackChatGenerator.\_\_init\_\_
+
+```python
+def __init__(chat_generators: list[ChatGenerator]) -> None
+```
+
+Creates an instance of FallbackChatGenerator.
+
+**Arguments**:
+
+- `chat_generators`: A non-empty list of chat generator components to try in order.
+
+
+
+#### FallbackChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component, including nested chat generators when they support serialization.
+
+
+
+#### FallbackChatGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> FallbackChatGenerator
+```
+
+Rebuild the component from a serialized representation, restoring nested chat generators.
+
+
+
+#### FallbackChatGenerator.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Warm up all underlying chat generators.
+
+This method calls warm_up() on each underlying generator that supports it.
+
+
+
+#### FallbackChatGenerator.run
+
+```python
+@component.output_types(replies=list[ChatMessage], meta=dict[str, Any])
+def run(
+ messages: list[ChatMessage],
+ generation_kwargs: Union[dict[str, Any], None] = None,
+ tools: Optional[ToolsType] = None,
+ streaming_callback: Union[StreamingCallbackT, None] = None
+) -> dict[str, Union[list[ChatMessage], dict[str, Any]]]
+```
+
+Execute chat generators sequentially until one succeeds.
+
+**Arguments**:
+
+- `messages`: The conversation history as a list of ChatMessage instances.
+- `generation_kwargs`: Optional parameters for the chat generator (e.g., temperature, max_tokens).
+- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for function calling capabilities.
+- `streaming_callback`: Optional callable for handling streaming responses.
+
+**Raises**:
+
+- `RuntimeError`: If all chat generators fail.
+
+**Returns**:
+
+A dictionary with:
+- "replies": Generated ChatMessage instances from the first successful generator.
+- "meta": Execution metadata including successful_chat_generator_index, successful_chat_generator_class,
+ total_attempts, failed_chat_generators, plus any metadata from the successful generator.
+
+
+
+#### FallbackChatGenerator.run\_async
+
+```python
+@component.output_types(replies=list[ChatMessage], meta=dict[str, Any])
+async def run_async(
+ messages: list[ChatMessage],
+ generation_kwargs: Union[dict[str, Any], None] = None,
+ tools: Optional[ToolsType] = None,
+ streaming_callback: Union[StreamingCallbackT, None] = None
+) -> dict[str, Union[list[ChatMessage], dict[str, Any]]]
+```
+
+Asynchronously execute chat generators sequentially until one succeeds.
+
+**Arguments**:
+
+- `messages`: The conversation history as a list of ChatMessage instances.
+- `generation_kwargs`: Optional parameters for the chat generator (e.g., temperature, max_tokens).
+- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for function calling capabilities.
+- `streaming_callback`: Optional callable for handling streaming responses.
+
+**Raises**:
+
+- `RuntimeError`: If all chat generators fail.
+
+**Returns**:
+
+A dictionary with:
+- "replies": Generated ChatMessage instances from the first successful generator.
+- "meta": Execution metadata including successful_chat_generator_index, successful_chat_generator_class,
+ total_attempts, failed_chat_generators, plus any metadata from the successful generator.
+
+
+
+## Module chat/hugging\_face\_api
+
+
+
+### HuggingFaceAPIChatGenerator
+
+Completes chats using Hugging Face APIs.
+
+HuggingFaceAPIChatGenerator uses the [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage)
+format for input and output. Use it to generate text with Hugging Face APIs:
+- [Serverless Inference API (Inference Providers)](https://huggingface.co/docs/inference-providers)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
+
+### Usage examples
+
+#### With the serverless inference API (Inference Providers) - free tier available
+
+```python
+from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack.utils.hf import HFGenerationAPIType
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
+ ChatMessage.from_user("What's Natural Language Processing?")]
+
+# the api_type can be expressed using the HFGenerationAPIType enum or as a string
+api_type = HFGenerationAPIType.SERVERLESS_INFERENCE_API
+api_type = "serverless_inference_api" # this is equivalent to the above
+
+generator = HuggingFaceAPIChatGenerator(api_type=api_type,
+ api_params={"model": "Qwen/Qwen2.5-7B-Instruct",
+ "provider": "together"},
+ token=Secret.from_token(""))
+
+result = generator.run(messages)
+print(result)
+```
+
+#### With the serverless inference API (Inference Providers) and text+image input
+
+```python
+from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack.utils import Secret
+from haystack.utils.hf 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("")
+)
+
+result = generator.run(messages)
+print(result)
+```
+
+#### With paid inference endpoints
+
+```python
+from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
+ ChatMessage.from_user("What's Natural Language Processing?")]
+
+generator = HuggingFaceAPIChatGenerator(api_type="inference_endpoints",
+ api_params={"url": ""},
+ token=Secret.from_token(""))
+
+result = generator.run(messages)
+print(result)
+
+#### With self-hosted text generation inference
+
+```python
+from haystack.components.generators.chat 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)
+```
+
+
+
+#### HuggingFaceAPIChatGenerator.\_\_init\_\_
+
+```python
+def __init__(api_type: Union[HFGenerationAPIType, str],
+ api_params: dict[str, str],
+ token: Optional[Secret] = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False),
+ generation_kwargs: Optional[dict[str, Any]] = None,
+ stop_words: Optional[list[str]] = None,
+ streaming_callback: Optional[StreamingCallbackT] = None,
+ tools: Optional[ToolsType] = None)
+```
+
+Initialize the HuggingFaceAPIChatGenerator instance.
+
+**Arguments**:
+
+- `api_type`: 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`: 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`: 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`: 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`: An optional list of strings representing the stop words.
+- `streaming_callback`: An optional callable for handling streaming responses.
+- `tools`: 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.
+
+
+
+#### HuggingFaceAPIChatGenerator.warm\_up
+
+```python
+def warm_up()
+```
+
+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.
+
+
+
+#### HuggingFaceAPIChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns**:
+
+A dictionary containing the serialized component.
+
+
+
+#### HuggingFaceAPIChatGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceAPIChatGenerator"
+```
+
+Deserialize this component from a dictionary.
+
+
+
+#### HuggingFaceAPIChatGenerator.run
+
+```python
+@component.output_types(replies=list[ChatMessage])
+def run(
+ messages: list[ChatMessage],
+ generation_kwargs: Optional[dict[str, Any]] = None,
+ tools: Optional[ToolsType] = None,
+ streaming_callback: Optional[StreamingCallbackT] = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Invoke the text generation inference based on the provided messages and generation parameters.
+
+**Arguments**:
+
+- `messages`: A list of ChatMessage objects representing the input messages.
+- `generation_kwargs`: Additional keyword arguments for text generation.
+- `tools`: 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`: An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
+parameter set during component initialization.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list containing the generated responses as ChatMessage objects.
+
+
+
+#### HuggingFaceAPIChatGenerator.run\_async
+
+```python
+@component.output_types(replies=list[ChatMessage])
+async def run_async(
+ messages: list[ChatMessage],
+ generation_kwargs: Optional[dict[str, Any]] = None,
+ tools: Optional[ToolsType] = None,
+ streaming_callback: Optional[StreamingCallbackT] = 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.
+
+**Arguments**:
+
+- `messages`: A list of ChatMessage objects representing the input messages.
+- `generation_kwargs`: Additional keyword arguments for text generation.
+- `tools`: 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`: An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
+parameter set during component initialization.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list containing the generated responses as ChatMessage objects.
+
## Module chat/hugging\_face\_local
@@ -1548,253 +1357,6 @@ If set, it will override the `tools` parameter provided during initialization.
A dictionary with the following keys:
- `replies`: A list containing the generated responses as ChatMessage instances.
-
-
-## Module chat/hugging\_face\_api
-
-
-
-### HuggingFaceAPIChatGenerator
-
-Completes chats using Hugging Face APIs.
-
-HuggingFaceAPIChatGenerator uses the [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage)
-format for input and output. Use it to generate text with Hugging Face APIs:
-- [Serverless Inference API (Inference Providers)](https://huggingface.co/docs/inference-providers)
-- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
-- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
-
-### Usage examples
-
-#### With the serverless inference API (Inference Providers) - free tier available
-
-```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
-from haystack.dataclasses import ChatMessage
-from haystack.utils import Secret
-from haystack.utils.hf import HFGenerationAPIType
-
-messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
- ChatMessage.from_user("What's Natural Language Processing?")]
-
-# the api_type can be expressed using the HFGenerationAPIType enum or as a string
-api_type = HFGenerationAPIType.SERVERLESS_INFERENCE_API
-api_type = "serverless_inference_api" # this is equivalent to the above
-
-generator = HuggingFaceAPIChatGenerator(api_type=api_type,
- api_params={"model": "Qwen/Qwen2.5-7B-Instruct",
- "provider": "together"},
- token=Secret.from_token(""))
-
-result = generator.run(messages)
-print(result)
-```
-
-#### With the serverless inference API (Inference Providers) and text+image input
-
-```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
-from haystack.dataclasses import ChatMessage, ImageContent
-from haystack.utils import Secret
-from haystack.utils.hf 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("")
-)
-
-result = generator.run(messages)
-print(result)
-```
-
-#### With paid inference endpoints
-
-```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
-from haystack.dataclasses import ChatMessage
-from haystack.utils import Secret
-
-messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
- ChatMessage.from_user("What's Natural Language Processing?")]
-
-generator = HuggingFaceAPIChatGenerator(api_type="inference_endpoints",
- api_params={"url": ""},
- token=Secret.from_token(""))
-
-result = generator.run(messages)
-print(result)
-
-#### With self-hosted text generation inference
-
-```python
-from haystack.components.generators.chat 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)
-```
-
-
-
-#### HuggingFaceAPIChatGenerator.\_\_init\_\_
-
-```python
-def __init__(api_type: Union[HFGenerationAPIType, str],
- api_params: dict[str, str],
- token: Optional[Secret] = Secret.from_env_var(
- ["HF_API_TOKEN", "HF_TOKEN"], strict=False),
- generation_kwargs: Optional[dict[str, Any]] = None,
- stop_words: Optional[list[str]] = None,
- streaming_callback: Optional[StreamingCallbackT] = None,
- tools: Optional[ToolsType] = None)
-```
-
-Initialize the HuggingFaceAPIChatGenerator instance.
-
-**Arguments**:
-
-- `api_type`: 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`: 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`: 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`: 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`: An optional list of strings representing the stop words.
-- `streaming_callback`: An optional callable for handling streaming responses.
-- `tools`: 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.
-
-
-
-#### HuggingFaceAPIChatGenerator.warm\_up
-
-```python
-def warm_up()
-```
-
-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.
-
-
-
-#### HuggingFaceAPIChatGenerator.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Serialize this component to a dictionary.
-
-**Returns**:
-
-A dictionary containing the serialized component.
-
-
-
-#### HuggingFaceAPIChatGenerator.from\_dict
-
-```python
-@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceAPIChatGenerator"
-```
-
-Deserialize this component from a dictionary.
-
-
-
-#### HuggingFaceAPIChatGenerator.run
-
-```python
-@component.output_types(replies=list[ChatMessage])
-def run(
- messages: list[ChatMessage],
- generation_kwargs: Optional[dict[str, Any]] = None,
- tools: Optional[ToolsType] = None,
- streaming_callback: Optional[StreamingCallbackT] = None
-) -> dict[str, list[ChatMessage]]
-```
-
-Invoke the text generation inference based on the provided messages and generation parameters.
-
-**Arguments**:
-
-- `messages`: A list of ChatMessage objects representing the input messages.
-- `generation_kwargs`: Additional keyword arguments for text generation.
-- `tools`: 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`: An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
-parameter set during component initialization.
-
-**Returns**:
-
-A dictionary with the following keys:
-- `replies`: A list containing the generated responses as ChatMessage objects.
-
-
-
-#### HuggingFaceAPIChatGenerator.run\_async
-
-```python
-@component.output_types(replies=list[ChatMessage])
-async def run_async(
- messages: list[ChatMessage],
- generation_kwargs: Optional[dict[str, Any]] = None,
- tools: Optional[ToolsType] = None,
- streaming_callback: Optional[StreamingCallbackT] = 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.
-
-**Arguments**:
-
-- `messages`: A list of ChatMessage objects representing the input messages.
-- `generation_kwargs`: Additional keyword arguments for text generation.
-- `tools`: 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`: An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
-parameter set during component initialization.
-
-**Returns**:
-
-A dictionary with the following keys:
-- `replies`: A list containing the generated responses as ChatMessage objects.
-
## Module chat/openai
@@ -2283,155 +1845,593 @@ If set, it will override the `tools_strict` parameter set during component initi
A dictionary with the following key:
- `replies`: A list containing the generated responses as ChatMessage instances.
-
+
-## Module chat/fallback
+## Module hugging\_face\_api
-
+
-### FallbackChatGenerator
+### HuggingFaceAPIGenerator
-A chat generator wrapper that tries multiple chat generators sequentially.
+Generates text using Hugging Face APIs.
-It forwards all parameters transparently to the underlying chat generators and returns the first successful result.
-Calls chat generators sequentially until one succeeds. Falls back on any exception raised by a generator.
-If all chat generators fail, it raises a RuntimeError with details.
+Use it with the following Hugging Face APIs:
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
-Timeout enforcement is fully delegated to the underlying chat generators. The fallback mechanism will only
-work correctly if the underlying chat generators implement proper timeout handling and raise exceptions
-when timeouts occur. For predictable latency guarantees, ensure your chat generators:
-- Support a `timeout` parameter in their initialization
-- Implement timeout as total wall-clock time (shared deadline for both streaming and non-streaming)
-- Raise timeout exceptions (e.g., TimeoutError, asyncio.TimeoutError, httpx.TimeoutException) when exceeded
+**Note:** As of July 2025, the Hugging Face Inference API no longer offers generative models through the
+`text_generation` endpoint. Generative models are now only available through providers supporting the
+`chat_completion` endpoint. As a result, this component might no longer work with the Hugging Face Inference API.
+Use the `HuggingFaceAPIChatGenerator` component, which supports the `chat_completion` endpoint.
-Note: Most well-implemented chat generators (OpenAI, Anthropic, Cohere, etc.) support timeout parameters
-with consistent semantics. For HTTP-based LLM providers, a single timeout value (e.g., `timeout=30`)
-typically applies to all connection phases: connection setup, read, write, and pool. For streaming
-responses, read timeout is the maximum gap between chunks. For non-streaming, it's the time limit for
-receiving the complete response.
+### Usage examples
-Failover is automatically triggered when a generator raises any exception, including:
-- Timeout errors (if the generator implements and raises them)
-- Rate limit errors (429)
-- Authentication errors (401)
-- Context length errors (400)
-- Server errors (500+)
-- Any other exception
+#### With Hugging Face Inference Endpoints
-
-#### FallbackChatGenerator.\_\_init\_\_
+#### With self-hosted text generation inference
+
+#### With the free serverless inference API
+
+Be aware that this example might not work as the Hugging Face Inference API no longer offer models that support the
+`text_generation` endpoint. Use the `HuggingFaceAPIChatGenerator` for generative models through the
+`chat_completion` endpoint.
```python
-def __init__(chat_generators: list[ChatGenerator]) -> None
+from haystack.components.generators import HuggingFaceAPIGenerator
+from haystack.utils import Secret
+
+generator = HuggingFaceAPIGenerator(api_type="inference_endpoints",
+ api_params={"url": ""},
+ token=Secret.from_token(""))
+
+result = generator.run(prompt="What's Natural Language Processing?")
+print(result)
+```
+```python
+from haystack.components.generators import HuggingFaceAPIGenerator
+
+generator = HuggingFaceAPIGenerator(api_type="text_generation_inference",
+ api_params={"url": "http://localhost:8080"})
+
+result = generator.run(prompt="What's Natural Language Processing?")
+print(result)
+```
+```python
+from haystack.components.generators import HuggingFaceAPIGenerator
+from haystack.utils import Secret
+
+generator = HuggingFaceAPIGenerator(api_type="serverless_inference_api",
+ api_params={"model": "HuggingFaceH4/zephyr-7b-beta"},
+ token=Secret.from_token(""))
+
+result = generator.run(prompt="What's Natural Language Processing?")
+print(result)
```
-Creates an instance of FallbackChatGenerator.
+
+
+#### HuggingFaceAPIGenerator.\_\_init\_\_
+
+```python
+def __init__(api_type: Union[HFGenerationAPIType, str],
+ api_params: dict[str, str],
+ token: Optional[Secret] = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False),
+ generation_kwargs: Optional[dict[str, Any]] = None,
+ stop_words: Optional[list[str]] = None,
+ streaming_callback: Optional[StreamingCallbackT] = None)
+```
+
+Initialize the HuggingFaceAPIGenerator instance.
**Arguments**:
-- `chat_generators`: A non-empty list of chat generator components to try in order.
+- `api_type`: The type of Hugging Face API to use. Available types:
+- `text_generation_inference`: See [TGI](https://github.com/huggingface/text-generation-inference).
+- `inference_endpoints`: See [Inference Endpoints](https://huggingface.co/inference-endpoints).
+- `serverless_inference_api`: See [Serverless Inference API](https://huggingface.co/inference-api).
+ This might no longer work due to changes in the models offered in the Hugging Face Inference API.
+ Please use the `HuggingFaceAPIChatGenerator` component instead.
+- `api_params`: A dictionary with the following keys:
+- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.
+- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or
+`TEXT_GENERATION_INFERENCE`.
+- Other parameters specific to the chosen API type, such as `timeout`, `headers`, `provider` etc.
+- `token`: 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`: A dictionary with keyword arguments to customize text generation. Some examples: `max_new_tokens`,
+`temperature`, `top_k`, `top_p`.
+For details, see [Hugging Face documentation](https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client#huggingface_hub.InferenceClient.text_generation)
+for more information.
+- `stop_words`: An optional list of strings representing the stop words.
+- `streaming_callback`: An optional callable for handling streaming responses.
-
+
-#### FallbackChatGenerator.to\_dict
+#### HuggingFaceAPIGenerator.to\_dict
```python
def to_dict() -> dict[str, Any]
```
-Serialize the component, including nested chat generators when they support serialization.
+Serialize this component to a dictionary.
-
+**Returns**:
-#### FallbackChatGenerator.from\_dict
+A dictionary containing the serialized component.
+
+
+
+#### HuggingFaceAPIGenerator.from\_dict
```python
@classmethod
-def from_dict(cls, data: dict[str, Any]) -> FallbackChatGenerator
+def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceAPIGenerator"
```
-Rebuild the component from a serialized representation, restoring nested chat generators.
+Deserialize this component from a dictionary.
-
+
-#### FallbackChatGenerator.warm\_up
+#### HuggingFaceAPIGenerator.run
+
+```python
+@component.output_types(replies=list[str], meta=list[dict[str, Any]])
+def run(prompt: str,
+ streaming_callback: Optional[StreamingCallbackT] = None,
+ generation_kwargs: Optional[dict[str, Any]] = None)
+```
+
+Invoke the text generation inference for the given prompt and generation parameters.
+
+**Arguments**:
+
+- `prompt`: A string representing the prompt.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+- `generation_kwargs`: Additional keyword arguments for text generation.
+
+**Returns**:
+
+A dictionary with the generated replies and metadata. Both are lists of length n.
+- replies: A list of strings representing the generated replies.
+
+
+
+## Module hugging\_face\_local
+
+
+
+### HuggingFaceLocalGenerator
+
+Generates text using models from Hugging Face that run locally.
+
+LLMs running locally may need powerful hardware.
+
+### Usage example
+
+```python
+from haystack.components.generators import HuggingFaceLocalGenerator
+
+generator = HuggingFaceLocalGenerator(
+ model="google/flan-t5-large",
+ task="text2text-generation",
+ generation_kwargs={"max_new_tokens": 100, "temperature": 0.9})
+
+generator.warm_up()
+
+print(generator.run("Who is the best American actor?"))
+# {'replies': ['John Cusack']}
+```
+
+
+
+#### HuggingFaceLocalGenerator.\_\_init\_\_
+
+```python
+def __init__(model: str = "google/flan-t5-base",
+ task: Optional[Literal["text-generation",
+ "text2text-generation"]] = None,
+ device: Optional[ComponentDevice] = None,
+ token: Optional[Secret] = Secret.from_env_var(
+ ["HF_API_TOKEN", "HF_TOKEN"], strict=False),
+ generation_kwargs: Optional[dict[str, Any]] = None,
+ huggingface_pipeline_kwargs: Optional[dict[str, Any]] = None,
+ stop_words: Optional[list[str]] = None,
+ streaming_callback: Optional[StreamingCallbackT] = None)
+```
+
+Creates an instance of a HuggingFaceLocalGenerator.
+
+**Arguments**:
+
+- `model`: The Hugging Face text generation model name or path.
+- `task`: The task for the Hugging Face pipeline. Possible options:
+- `text-generation`: Supported by decoder models, like GPT.
+- `text2text-generation`: Supported by encoder-decoder models, like T5.
+If the task is specified in `huggingface_pipeline_kwargs`, this parameter is ignored.
+If not specified, the component calls the Hugging Face API to infer the task from the model name.
+- `device`: The device for loading the model. If `None`, automatically selects the default device.
+If a device or device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter.
+- `token`: The token to use as HTTP bearer authorization for remote files.
+If the token is specified in `huggingface_pipeline_kwargs`, this parameter is ignored.
+- `generation_kwargs`: A dictionary with keyword arguments to customize text generation.
+Some examples: `max_length`, `max_new_tokens`, `temperature`, `top_k`, `top_p`.
+See Hugging Face's documentation for more information:
+- [customize-text-generation](https://huggingface.co/docs/transformers/main/en/generation_strategies#customize-text-generation)
+- [transformers.GenerationConfig](https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationConfig)
+- `huggingface_pipeline_kwargs`: Dictionary with keyword arguments to initialize the
+Hugging Face pipeline for text generation.
+These keyword arguments provide fine-grained control over the Hugging Face pipeline.
+In case of duplication, these kwargs override `model`, `task`, `device`, and `token` init parameters.
+For available kwargs, see [Hugging Face documentation](https://huggingface.co/docs/transformers/en/main_classes/pipelines#transformers.pipeline.task).
+In this dictionary, you can also include `model_kwargs` to specify the kwargs for model initialization:
+[transformers.PreTrainedModel.from_pretrained](https://huggingface.co/docs/transformers/en/main_classes/model#transformers.PreTrainedModel.from_pretrained)
+- `stop_words`: If the model generates a stop word, the generation stops.
+If you provide this parameter, don't specify the `stopping_criteria` in `generation_kwargs`.
+For some chat models, the output includes both the new text and the original prompt.
+In these cases, make sure your prompt has no stop words.
+- `streaming_callback`: An optional callable for handling streaming responses.
+
+
+
+#### HuggingFaceLocalGenerator.warm\_up
+
+```python
+def warm_up()
+```
+
+Initializes the component.
+
+
+
+#### HuggingFaceLocalGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### HuggingFaceLocalGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceLocalGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+
+
+#### HuggingFaceLocalGenerator.run
+
+```python
+@component.output_types(replies=list[str])
+def run(prompt: str,
+ streaming_callback: Optional[StreamingCallbackT] = None,
+ generation_kwargs: Optional[dict[str, Any]] = None)
+```
+
+Run the text generation model on the given prompt.
+
+**Arguments**:
+
+- `prompt`: A string representing the prompt.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+- `generation_kwargs`: Additional keyword arguments for text generation.
+
+**Returns**:
+
+A dictionary containing the generated replies.
+- replies: A list of strings representing the generated replies.
+
+
+
+## Module openai
+
+
+
+### OpenAIGenerator
+
+Generates text using OpenAI's large language models (LLMs).
+
+It works with the gpt-4 and gpt-5 series models and supports streaming responses
+from OpenAI API. It uses strings as input and output.
+
+You can customize how the text is generated by passing parameters to the
+OpenAI API. Use the `**generation_kwargs` argument when you initialize
+the component or when you run it. Any parameter that works with
+`openai.ChatCompletion.create` will work here too.
+
+
+For details on OpenAI API parameters, see
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
+
+### Usage example
+
+```python
+from haystack.components.generators import OpenAIGenerator
+client = OpenAIGenerator()
+response = client.run("What's Natural Language Processing? Be brief.")
+print(response)
+
+>> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on
+>> the interaction between computers and human language. It involves enabling computers to understand, interpret,
+>> and respond to natural human language in a way that is both meaningful and useful.'], 'meta': [{'model':
+>> 'gpt-5-mini', 'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 16,
+>> 'completion_tokens': 49, 'total_tokens': 65}}]}
+```
+
+
+
+#### OpenAIGenerator.\_\_init\_\_
+
+```python
+def __init__(api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
+ model: str = "gpt-5-mini",
+ streaming_callback: Optional[StreamingCallbackT] = None,
+ api_base_url: Optional[str] = None,
+ organization: Optional[str] = None,
+ system_prompt: Optional[str] = None,
+ generation_kwargs: Optional[dict[str, Any]] = None,
+ timeout: Optional[float] = None,
+ max_retries: Optional[int] = None,
+ http_client_kwargs: Optional[dict[str, Any]] = None)
+```
+
+Creates an instance of OpenAIGenerator. Unless specified otherwise in `model`, uses OpenAI's gpt-5-mini
+
+By setting the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES' you can change the timeout and max_retries parameters
+in the OpenAI client.
+
+**Arguments**:
+
+- `api_key`: The OpenAI API key to connect to OpenAI.
+- `model`: The name of the 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`: An optional base URL.
+- `organization`: The Organization ID, defaults to `None`.
+- `system_prompt`: 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`: Other parameters to use for the model. These parameters are all sent directly to
+the OpenAI endpoint. See OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat) for
+more details.
+Some of the supported parameters:
+- `max_completion_tokens`: An upper bound for the number of tokens that can be generated for a completion,
+ including visible output tokens and reasoning tokens.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+ Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+ considers the results of the tokens with top_p probability mass. So, 0.1 means only the tokens
+ comprising the top 10% probability mass are considered.
+- `n`: How many completions to generate for each prompt. For example, if the LLM gets 3 prompts and n is 2,
+ it will generate two completions for each of the three prompts, ending up with 6 completions in total.
+- `stop`: One or more sequences after which the LLM should stop generating tokens.
+- `presence_penalty`: What penalty to apply if a token is already present at all. Bigger values mean
+ the model will be less likely to repeat the same token in the text.
+- `frequency_penalty`: What penalty to apply if a token has already been generated in the text.
+ Bigger values mean the model will be less likely to repeat the same token in the text.
+- `logit_bias`: Add a logit bias to specific tokens. The keys of the dictionary are tokens, and the
+ values are the bias to add to that token.
+- `timeout`: Timeout for OpenAI Client calls, if not set it is inferred from the `OPENAI_TIMEOUT` environment variable
+or set to 30.
+- `max_retries`: Maximum retries to establish contact with OpenAI if it returns an internal error, if not set it is inferred
+from the `OPENAI_MAX_RETRIES` environment variable or set to 5.
+- `http_client_kwargs`: 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`).
+
+
+
+#### OpenAIGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns**:
+
+The serialized component as a dictionary.
+
+
+
+#### OpenAIGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "OpenAIGenerator"
+```
+
+Deserialize this component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary representation of this component.
+
+**Returns**:
+
+The deserialized component instance.
+
+
+
+#### OpenAIGenerator.run
+
+```python
+@component.output_types(replies=list[str], meta=list[dict[str, Any]])
+def run(
+ prompt: str,
+ system_prompt: Optional[str] = None,
+ streaming_callback: Optional[StreamingCallbackT] = None,
+ generation_kwargs: Optional[dict[str, Any]] = None
+) -> dict[str, Union[list[str], list[dict[str, Any]]]]
+```
+
+Invoke the text generation inference based on the provided messages and generation parameters.
+
+**Arguments**:
+
+- `prompt`: The string prompt to use for text generation.
+- `system_prompt`: The system prompt to use for text generation. If this run time system prompt is omitted, the system
+prompt, if defined at initialisation time, is used.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters
+passed in the `__init__` method. For more details on the parameters supported by the OpenAI API, refer to
+the OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat/create).
+
+**Returns**:
+
+A list of strings containing the generated responses and a list of dictionaries containing the metadata
+for each response.
+
+
+
+## Module openai\_dalle
+
+
+
+### DALLEImageGenerator
+
+Generates images using OpenAI's DALL-E model.
+
+For details on OpenAI API parameters, see
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/images/create).
+
+### Usage example
+
+```python
+from haystack.components.generators import DALLEImageGenerator
+image_generator = DALLEImageGenerator()
+response = image_generator.run("Show me a picture of a black cat.")
+print(response)
+```
+
+
+
+#### DALLEImageGenerator.\_\_init\_\_
+
+```python
+def __init__(model: str = "dall-e-3",
+ quality: Literal["standard", "hd"] = "standard",
+ size: Literal["256x256", "512x512", "1024x1024", "1792x1024",
+ "1024x1792"] = "1024x1024",
+ response_format: Literal["url", "b64_json"] = "url",
+ api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
+ api_base_url: Optional[str] = None,
+ organization: Optional[str] = None,
+ timeout: Optional[float] = None,
+ max_retries: Optional[int] = None,
+ http_client_kwargs: Optional[dict[str, Any]] = None)
+```
+
+Creates an instance of DALLEImageGenerator. Unless specified otherwise in `model`, uses OpenAI's dall-e-3.
+
+**Arguments**:
+
+- `model`: The model to use for image generation. Can be "dall-e-2" or "dall-e-3".
+- `quality`: The quality of the generated image. Can be "standard" or "hd".
+- `size`: The size of the generated images.
+Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2.
+Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models.
+- `response_format`: The format of the response. Can be "url" or "b64_json".
+- `api_key`: The OpenAI API key to connect to OpenAI.
+- `api_base_url`: An optional base URL.
+- `organization`: The Organization ID, defaults to `None`.
+- `timeout`: Timeout for OpenAI Client calls. If not set, it is inferred from the `OPENAI_TIMEOUT` environment variable
+or set to 30.
+- `max_retries`: Maximum retries to establish contact with OpenAI if it returns an internal error. If not set, it is inferred
+from the `OPENAI_MAX_RETRIES` environment variable or set to 5.
+- `http_client_kwargs`: 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`).
+
+
+
+#### DALLEImageGenerator.warm\_up
```python
def warm_up() -> None
```
-Warm up all underlying chat generators.
+Warm up the OpenAI client.
-This method calls warm_up() on each underlying generator that supports it.
+
-
-
-#### FallbackChatGenerator.run
+#### DALLEImageGenerator.run
```python
-@component.output_types(replies=list[ChatMessage], meta=dict[str, Any])
-def run(
- messages: list[ChatMessage],
- generation_kwargs: Union[dict[str, Any], None] = None,
- tools: Optional[ToolsType] = None,
- streaming_callback: Union[StreamingCallbackT, None] = None
-) -> dict[str, Union[list[ChatMessage], dict[str, Any]]]
+@component.output_types(images=list[str], revised_prompt=str)
+def run(prompt: str,
+ size: Optional[Literal["256x256", "512x512", "1024x1024", "1792x1024",
+ "1024x1792"]] = None,
+ quality: Optional[Literal["standard", "hd"]] = None,
+ response_format: Optional[Optional[Literal["url",
+ "b64_json"]]] = None)
```
-Execute chat generators sequentially until one succeeds.
+Invokes the image generation inference based on the provided prompt and generation parameters.
**Arguments**:
-- `messages`: The conversation history as a list of ChatMessage instances.
-- `generation_kwargs`: Optional parameters for the chat generator (e.g., temperature, max_tokens).
-- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for function calling capabilities.
-- `streaming_callback`: Optional callable for handling streaming responses.
-
-**Raises**:
-
-- `RuntimeError`: If all chat generators fail.
+- `prompt`: The prompt to generate the image.
+- `size`: If provided, overrides the size provided during initialization.
+- `quality`: If provided, overrides the quality provided during initialization.
+- `response_format`: If provided, overrides the response format provided during initialization.
**Returns**:
-A dictionary with:
-- "replies": Generated ChatMessage instances from the first successful generator.
-- "meta": Execution metadata including successful_chat_generator_index, successful_chat_generator_class,
- total_attempts, failed_chat_generators, plus any metadata from the successful generator.
+A dictionary containing the generated list of images and the revised prompt.
+Depending on the `response_format` parameter, the list of images can be URLs or base64 encoded JSON strings.
+The revised prompt is the prompt that was used to generate the image, if there was any revision
+to the prompt made by OpenAI.
-
+
-#### FallbackChatGenerator.run\_async
+#### DALLEImageGenerator.to\_dict
```python
-@component.output_types(replies=list[ChatMessage], meta=dict[str, Any])
-async def run_async(
- messages: list[ChatMessage],
- generation_kwargs: Union[dict[str, Any], None] = None,
- tools: Optional[ToolsType] = None,
- streaming_callback: Union[StreamingCallbackT, None] = None
-) -> dict[str, Union[list[ChatMessage], dict[str, Any]]]
+def to_dict() -> dict[str, Any]
```
-Asynchronously execute chat generators sequentially until one succeeds.
+Serialize this component to a dictionary.
+
+**Returns**:
+
+The serialized component as a dictionary.
+
+
+
+#### DALLEImageGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "DALLEImageGenerator"
+```
+
+Deserialize this component from a dictionary.
**Arguments**:
-- `messages`: The conversation history as a list of ChatMessage instances.
-- `generation_kwargs`: Optional parameters for the chat generator (e.g., temperature, max_tokens).
-- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for function calling capabilities.
-- `streaming_callback`: Optional callable for handling streaming responses.
-
-**Raises**:
-
-- `RuntimeError`: If all chat generators fail.
+- `data`: The dictionary representation of this component.
**Returns**:
-A dictionary with:
-- "replies": Generated ChatMessage instances from the first successful generator.
-- "meta": Execution metadata including successful_chat_generator_index, successful_chat_generator_class,
- total_attempts, failed_chat_generators, plus any metadata from the successful generator.
+The deserialized component instance.
diff --git a/docs-website/reference/haystack-api/tools_api.md b/docs-website/reference/haystack-api/tools_api.md
index 3dfd060715..221236f0eb 100644
--- a/docs-website/reference/haystack-api/tools_api.md
+++ b/docs-website/reference/haystack-api/tools_api.md
@@ -5,274 +5,6 @@ description: "Unified abstractions to represent tools across the framework."
slug: "/tools-api"
---
-
-
-## Module tool
-
-
-
-### Tool
-
-Data class representing a Tool that Language Models can prepare a call for.
-
-Accurate definitions of the textual attributes such as `name` and `description`
-are important for the Language Model to correctly prepare the call.
-
-For resource-intensive operations like establishing connections to remote services or
-loading models, override the `warm_up()` method. This method is called before the Tool
-is used and should be idempotent, as it may be called multiple times during
-pipeline/agent setup.
-
-**Arguments**:
-
-- `name`: Name of the Tool.
-- `description`: Description of the Tool.
-- `parameters`: A JSON schema defining the parameters expected by the Tool.
-- `function`: The function that will be invoked when the Tool is called.
-- `outputs_to_string`: Optional dictionary defining how a 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:
-```python
-{
- "source": "docs", "handler": format_documents
-}
-```
-- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names.
-Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
-- `outputs_to_state`: Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
-If the source is provided only the specified output key is sent to the handler.
-Example:
-```python
-{
- "documents": {"source": "docs", "handler": custom_handler}
-}
-```
-If the source is omitted the whole tool result is sent to the handler.
-Example:
-```python
-{
- "documents": {"handler": custom_handler}
-}
-```
-
-
-
-#### Tool.tool\_spec
-
-```python
-@property
-def tool_spec() -> dict[str, Any]
-```
-
-Return the Tool specification to be used by the Language Model.
-
-
-
-#### Tool.warm\_up
-
-```python
-def warm_up() -> None
-```
-
-Prepare the Tool for use.
-
-Override this method to establish connections to remote services, load models,
-or perform other resource-intensive initialization. This method should be idempotent,
-as it may be called multiple times.
-
-
-
-#### Tool.invoke
-
-```python
-def invoke(**kwargs: Any) -> Any
-```
-
-Invoke the Tool with the provided keyword arguments.
-
-
-
-#### Tool.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Serializes the Tool to a dictionary.
-
-**Returns**:
-
-Dictionary with serialized data.
-
-
-
-#### Tool.from\_dict
-
-```python
-@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "Tool"
-```
-
-Deserializes the Tool from a dictionary.
-
-**Arguments**:
-
-- `data`: Dictionary to deserialize from.
-
-**Returns**:
-
-Deserialized Tool.
-
-
-
-## Module from\_function
-
-
-
-#### create\_tool\_from\_function
-
-```python
-def create_tool_from_function(
- function: Callable,
- name: Optional[str] = None,
- description: Optional[str] = None,
- inputs_from_state: Optional[dict[str, str]] = None,
- outputs_to_state: Optional[dict[str, dict[str,
- Any]]] = None) -> "Tool"
-```
-
-Create a Tool instance from a function.
-
-Allows customizing the Tool name and description.
-For simpler use cases, consider using the `@tool` decorator.
-
-### Usage example
-
-```python
-from typing import Annotated, Literal
-from haystack.tools import create_tool_from_function
-
-def get_weather(
- city: Annotated[str, "the city for which to get the weather"] = "Munich",
- unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
- '''A simple function to get the current weather for a location.'''
- return f"Weather report for {city}: 20 {unit}, sunny"
-
-tool = create_tool_from_function(get_weather)
-
-print(tool)
->>> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
->>> parameters={
->>> 'type': 'object',
->>> 'properties': {
->>> 'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
->>> 'unit': {
->>> 'type': 'string',
->>> 'enum': ['Celsius', 'Fahrenheit'],
->>> 'description': 'the unit for the temperature',
->>> 'default': 'Celsius',
->>> },
->>> }
->>> },
->>> function=)
-```
-
-**Arguments**:
-
-- `function`: The function to be converted into a Tool.
-The function must include type hints for all parameters.
-The function is expected to have basic python input types (str, int, float, bool, list, dict, tuple).
-Other input types may work but are not guaranteed.
-If a parameter is annotated using `typing.Annotated`, its metadata will be used as parameter description.
-- `name`: The name of the Tool. If not provided, the name of the function will be used.
-- `description`: The description of the Tool. If not provided, the docstring of the function will be used.
-To intentionally leave the description empty, pass an empty string.
-- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names.
-Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
-- `outputs_to_state`: Optional dictionary defining how tool outputs map to state and message handling.
-Example:
-```python
-{
- "documents": {"source": "docs", "handler": custom_handler},
- "message": {"source": "summary", "handler": format_summary}
-}
-```
-
-**Raises**:
-
-- `ValueError`: If any parameter of the function lacks a type hint.
-- `SchemaGenerationError`: If there is an error generating the JSON schema for the Tool.
-
-**Returns**:
-
-The Tool created from the function.
-
-
-
-#### tool
-
-```python
-def tool(
- function: Optional[Callable] = None,
- *,
- name: Optional[str] = None,
- description: Optional[str] = None,
- inputs_from_state: Optional[dict[str, str]] = None,
- outputs_to_state: Optional[dict[str, dict[str, Any]]] = None
-) -> Union[Tool, Callable[[Callable], Tool]]
-```
-
-Decorator to convert a function into a Tool.
-
-Can be used with or without parameters:
-@tool # without parameters
-def my_function(): ...
-
-@tool(name="custom_name") # with parameters
-def my_function(): ...
-
-### Usage example
-```python
-from typing import Annotated, Literal
-from haystack.tools import tool
-
-@tool
-def get_weather(
- city: Annotated[str, "the city for which to get the weather"] = "Munich",
- unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
- '''A simple function to get the current weather for a location.'''
- return f"Weather report for {city}: 20 {unit}, sunny"
-
-print(get_weather)
->>> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
->>> parameters={
->>> 'type': 'object',
->>> 'properties': {
->>> 'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
->>> 'unit': {
->>> 'type': 'string',
->>> 'enum': ['Celsius', 'Fahrenheit'],
->>> 'description': 'the unit for the temperature',
->>> 'default': 'Celsius',
->>> },
->>> }
->>> },
->>> function=)
-```
-
-**Arguments**:
-
-- `function`: The function to decorate (when used without parameters)
-- `name`: Optional custom name for the tool
-- `description`: Optional custom description
-- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names
-- `outputs_to_state`: Optional dictionary defining how tool outputs map to state and message handling
-
-**Returns**:
-
-Either a Tool instance or a decorator function that will create one
-
## Module component\_tool
@@ -450,6 +182,274 @@ def invoke(**kwargs: Any) -> Any
Invoke the Tool with the provided keyword arguments.
+
+
+## Module from\_function
+
+
+
+#### create\_tool\_from\_function
+
+```python
+def create_tool_from_function(
+ function: Callable,
+ name: Optional[str] = None,
+ description: Optional[str] = None,
+ inputs_from_state: Optional[dict[str, str]] = None,
+ outputs_to_state: Optional[dict[str, dict[str,
+ Any]]] = None) -> "Tool"
+```
+
+Create a Tool instance from a function.
+
+Allows customizing the Tool name and description.
+For simpler use cases, consider using the `@tool` decorator.
+
+### Usage example
+
+```python
+from typing import Annotated, Literal
+from haystack.tools import create_tool_from_function
+
+def get_weather(
+ city: Annotated[str, "the city for which to get the weather"] = "Munich",
+ unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
+ '''A simple function to get the current weather for a location.'''
+ return f"Weather report for {city}: 20 {unit}, sunny"
+
+tool = create_tool_from_function(get_weather)
+
+print(tool)
+>>> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
+>>> parameters={
+>>> 'type': 'object',
+>>> 'properties': {
+>>> 'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
+>>> 'unit': {
+>>> 'type': 'string',
+>>> 'enum': ['Celsius', 'Fahrenheit'],
+>>> 'description': 'the unit for the temperature',
+>>> 'default': 'Celsius',
+>>> },
+>>> }
+>>> },
+>>> function=)
+```
+
+**Arguments**:
+
+- `function`: The function to be converted into a Tool.
+The function must include type hints for all parameters.
+The function is expected to have basic python input types (str, int, float, bool, list, dict, tuple).
+Other input types may work but are not guaranteed.
+If a parameter is annotated using `typing.Annotated`, its metadata will be used as parameter description.
+- `name`: The name of the Tool. If not provided, the name of the function will be used.
+- `description`: The description of the Tool. If not provided, the docstring of the function will be used.
+To intentionally leave the description empty, pass an empty string.
+- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names.
+Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- `outputs_to_state`: Optional dictionary defining how tool outputs map to state and message handling.
+Example:
+```python
+{
+ "documents": {"source": "docs", "handler": custom_handler},
+ "message": {"source": "summary", "handler": format_summary}
+}
+```
+
+**Raises**:
+
+- `ValueError`: If any parameter of the function lacks a type hint.
+- `SchemaGenerationError`: If there is an error generating the JSON schema for the Tool.
+
+**Returns**:
+
+The Tool created from the function.
+
+
+
+#### tool
+
+```python
+def tool(
+ function: Optional[Callable] = None,
+ *,
+ name: Optional[str] = None,
+ description: Optional[str] = None,
+ inputs_from_state: Optional[dict[str, str]] = None,
+ outputs_to_state: Optional[dict[str, dict[str, Any]]] = None
+) -> Union[Tool, Callable[[Callable], Tool]]
+```
+
+Decorator to convert a function into a Tool.
+
+Can be used with or without parameters:
+@tool # without parameters
+def my_function(): ...
+
+@tool(name="custom_name") # with parameters
+def my_function(): ...
+
+### Usage example
+```python
+from typing import Annotated, Literal
+from haystack.tools import tool
+
+@tool
+def get_weather(
+ city: Annotated[str, "the city for which to get the weather"] = "Munich",
+ unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
+ '''A simple function to get the current weather for a location.'''
+ return f"Weather report for {city}: 20 {unit}, sunny"
+
+print(get_weather)
+>>> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
+>>> parameters={
+>>> 'type': 'object',
+>>> 'properties': {
+>>> 'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
+>>> 'unit': {
+>>> 'type': 'string',
+>>> 'enum': ['Celsius', 'Fahrenheit'],
+>>> 'description': 'the unit for the temperature',
+>>> 'default': 'Celsius',
+>>> },
+>>> }
+>>> },
+>>> function=)
+```
+
+**Arguments**:
+
+- `function`: The function to decorate (when used without parameters)
+- `name`: Optional custom name for the tool
+- `description`: Optional custom description
+- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names
+- `outputs_to_state`: Optional dictionary defining how tool outputs map to state and message handling
+
+**Returns**:
+
+Either a Tool instance or a decorator function that will create one
+
+
+
+## Module tool
+
+
+
+### Tool
+
+Data class representing a Tool that Language Models can prepare a call for.
+
+Accurate definitions of the textual attributes such as `name` and `description`
+are important for the Language Model to correctly prepare the call.
+
+For resource-intensive operations like establishing connections to remote services or
+loading models, override the `warm_up()` method. This method is called before the Tool
+is used and should be idempotent, as it may be called multiple times during
+pipeline/agent setup.
+
+**Arguments**:
+
+- `name`: Name of the Tool.
+- `description`: Description of the Tool.
+- `parameters`: A JSON schema defining the parameters expected by the Tool.
+- `function`: The function that will be invoked when the Tool is called.
+- `outputs_to_string`: Optional dictionary defining how a 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:
+```python
+{
+ "source": "docs", "handler": format_documents
+}
+```
+- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names.
+Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- `outputs_to_state`: Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
+If the source is provided only the specified output key is sent to the handler.
+Example:
+```python
+{
+ "documents": {"source": "docs", "handler": custom_handler}
+}
+```
+If the source is omitted the whole tool result is sent to the handler.
+Example:
+```python
+{
+ "documents": {"handler": custom_handler}
+}
+```
+
+
+
+#### Tool.tool\_spec
+
+```python
+@property
+def tool_spec() -> dict[str, Any]
+```
+
+Return the Tool specification to be used by the Language Model.
+
+
+
+#### Tool.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Prepare the Tool for use.
+
+Override this method to establish connections to remote services, load models,
+or perform other resource-intensive initialization. This method should be idempotent,
+as it may be called multiple times.
+
+
+
+#### Tool.invoke
+
+```python
+def invoke(**kwargs: Any) -> Any
+```
+
+Invoke the Tool with the provided keyword arguments.
+
+
+
+#### Tool.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the Tool to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### Tool.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "Tool"
+```
+
+Deserializes the Tool from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized Tool.
+
## Module toolset
diff --git a/docs-website/reference/haystack-api/utils_api.md b/docs-website/reference/haystack-api/utils_api.md
index 001fb21179..5773fe5c58 100644
--- a/docs-website/reference/haystack-api/utils_api.md
+++ b/docs-website/reference/haystack-api/utils_api.md
@@ -5,328 +5,196 @@ description: "Utility functions and classes used across the library."
slug: "/utils-api"
---
-
+
-## Module requests\_utils
+## Module asynchronous
-
+
-#### request\_with\_retry
+#### is\_callable\_async\_compatible
```python
-def request_with_retry(attempts: int = 3,
- status_codes_to_retry: Optional[list[int]] = None,
- **kwargs: Any) -> requests.Response
+def is_callable_async_compatible(func: Callable) -> bool
```
-Executes an HTTP request with a configurable exponential backoff retry on failures.
+Returns if the given callable is usable inside a component's `run_async` method.
+
+**Arguments**:
+
+- `callable`: The callable to check.
+
+**Returns**:
+
+True if the callable is compatible, False otherwise.
+
+
+
+## Module auth
+
+
+
+### SecretType
+
+
+
+#### SecretType.from\_str
+
+```python
+@staticmethod
+def from_str(string: str) -> "SecretType"
+```
+
+Convert a string to a SecretType.
+
+**Arguments**:
+
+- `string`: The string to convert.
+
+
+
+### Secret
+
+Encapsulates a secret used for authentication.
Usage example:
```python
-from haystack.utils import request_with_retry
+from haystack.components.generators import OpenAIGenerator
+from haystack.utils import Secret
-# Sending an HTTP request with default retry configs
-res = request_with_retry(method="GET", url="https://example.com")
-
-# Sending an HTTP request with custom number of attempts
-res = request_with_retry(method="GET", url="https://example.com", attempts=10)
-
-# Sending an HTTP request with custom HTTP codes to retry
-res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=[408, 503])
-
-# Sending an HTTP request with custom timeout in seconds
-res = request_with_retry(method="GET", url="https://example.com", timeout=5)
-
-# Sending an HTTP request with custom authorization handling
-class CustomAuth(requests.auth.AuthBase):
- def __call__(self, r):
- r.headers["authorization"] = "Basic "
- return r
-
-res = request_with_retry(method="GET", url="https://example.com", auth=CustomAuth())
-
-# All of the above combined
-res = request_with_retry(
- method="GET",
- url="https://example.com",
- auth=CustomAuth(),
- attempts=10,
- status_codes_to_retry=[408, 503],
- timeout=5
-)
-
-# Sending a POST request
-res = request_with_retry(method="POST", url="https://example.com", data={"key": "value"}, attempts=10)
-
-# Retry all 5xx status codes
-res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=list(range(500, 600)))
+generator = OpenAIGenerator(api_key=Secret.from_token(""))
```
+
+
+#### Secret.from\_token
+
+```python
+@staticmethod
+def from_token(token: str) -> "Secret"
+```
+
+Create a token-based secret. Cannot be serialized.
+
**Arguments**:
-- `attempts`: Maximum number of attempts to retry the request.
-- `status_codes_to_retry`: List of HTTP status codes that will trigger a retry.
-When param is `None`, HTTP 408, 418, 429 and 503 will be retried.
-- `kwargs`: Optional arguments that `request` accepts.
+- `token`: The token to use for authentication.
+
+
+
+#### Secret.from\_env\_var
+
+```python
+@staticmethod
+def from_env_var(env_vars: Union[str, list[str]],
+ *,
+ strict: bool = True) -> "Secret"
+```
+
+Create an environment variable-based secret. Accepts one or more environment variables.
+
+Upon resolution, it returns a string token from the first environment variable that is set.
+
+**Arguments**:
+
+- `env_vars`: A single environment variable or an ordered list of
+candidate environment variables.
+- `strict`: Whether to raise an exception if none of the environment
+variables are set.
+
+
+
+#### Secret.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Convert the secret to a JSON-serializable dictionary.
+
+Some secrets may not be serializable.
**Returns**:
-The `Response` object.
+The serialized policy.
-
+
-#### async\_request\_with\_retry
+#### Secret.from\_dict
```python
-async def async_request_with_retry(attempts: int = 3,
- status_codes_to_retry: Optional[
- list[int]] = None,
- **kwargs: Any) -> httpx.Response
+@staticmethod
+def from_dict(dict: dict[str, Any]) -> "Secret"
```
-Executes an asynchronous HTTP request with a configurable exponential backoff retry on failures.
-
-Usage example:
-```python
-import asyncio
-from haystack.utils import async_request_with_retry
-
-# Sending an async HTTP request with default retry configs
-async def example():
- res = await async_request_with_retry(method="GET", url="https://example.com")
- return res
-
-# Sending an async HTTP request with custom number of attempts
-async def example_with_attempts():
- res = await async_request_with_retry(method="GET", url="https://example.com", attempts=10)
- return res
-
-# Sending an async HTTP request with custom HTTP codes to retry
-async def example_with_status_codes():
- res = await async_request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=[408, 503])
- return res
-
-# Sending an async HTTP request with custom timeout in seconds
-async def example_with_timeout():
- res = await async_request_with_retry(method="GET", url="https://example.com", timeout=5)
- return res
-
-# Sending an async HTTP request with custom headers
-async def example_with_headers():
- headers = {"Authorization": "Bearer "}
- res = await async_request_with_retry(method="GET", url="https://example.com", headers=headers)
- return res
-
-# All of the above combined
-async def example_combined():
- headers = {"Authorization": "Bearer "}
- res = await async_request_with_retry(
- method="GET",
- url="https://example.com",
- headers=headers,
- attempts=10,
- status_codes_to_retry=[408, 503],
- timeout=5
- )
- return res
-
-# Sending an async POST request
-async def example_post():
- res = await async_request_with_retry(
- method="POST",
- url="https://example.com",
- json={"key": "value"},
- attempts=10
- )
- return res
-
-# Retry all 5xx status codes
-async def example_5xx():
- res = await async_request_with_retry(
- method="GET",
- url="https://example.com",
- status_codes_to_retry=list(range(500, 600))
- )
- return res
-```
+Create a secret from a JSON-serializable dictionary.
**Arguments**:
-- `attempts`: Maximum number of attempts to retry the request.
-- `status_codes_to_retry`: List of HTTP status codes that will trigger a retry.
-When param is `None`, HTTP 408, 418, 429 and 503 will be retried.
-- `kwargs`: Optional arguments that `httpx.AsyncClient.request` accepts.
+- `dict`: The dictionary with the serialized data.
**Returns**:
-The `httpx.Response` object.
+The deserialized secret.
-
+
-## Module filters
-
-
-
-#### raise\_on\_invalid\_filter\_syntax
+#### Secret.resolve\_value
```python
-def raise_on_invalid_filter_syntax(
- filters: Optional[dict[str, Any]] = None) -> None
+@abstractmethod
+def resolve_value() -> Optional[Any]
```
-Raise an error if the filter syntax is invalid.
-
-
-
-#### document\_matches\_filter
-
-```python
-def document_matches_filter(filters: dict[str, Any],
- document: Union[Document, ByteStream]) -> bool
-```
-
-Return whether `filters` match the Document or the ByteStream.
-
-For a detailed specification of the filters, refer to the
-`DocumentStore.filter_documents()` protocol documentation.
-
-
-
-## Module jupyter
-
-
-
-#### is\_in\_jupyter
-
-```python
-def is_in_jupyter() -> bool
-```
-
-Returns `True` if in Jupyter or Google Colab, `False` otherwise.
-
-
-
-## Module jinja2\_extensions
-
-
-
-### Jinja2TimeExtension
-
-
-
-#### Jinja2TimeExtension.\_\_init\_\_
-
-```python
-def __init__(environment: Environment)
-```
-
-Initializes the JinjaTimeExtension object.
-
-**Arguments**:
-
-- `environment`: The Jinja2 environment to initialize the extension with.
-It provides the context where the extension will operate.
-
-
-
-#### Jinja2TimeExtension.parse
-
-```python
-def parse(parser: Any) -> Union[nodes.Node, list[nodes.Node]]
-```
-
-Parse the template expression to determine how to handle the datetime formatting.
-
-**Arguments**:
-
-- `parser`: The parser object that processes the template expressions and manages the syntax tree.
-It's used to interpret the template's structure.
-
-
-
-## Module jinja2\_chat\_extension
-
-
-
-### ChatMessageExtension
-
-A Jinja2 extension for creating structured chat messages with mixed content types.
-
-This extension provides a custom `{% message %}` tag that allows creating chat messages
-with different attributes (role, name, meta) and mixed content types (text, images, etc.).
-
-Inspired by [Banks](https://github.com/masci/banks).
-
-**Example**:
-
-```
-{% message role="system" %}
-You are a helpful assistant. You like to talk with {{user_name}}.
-{% endmessage %}
-
-{% message role="user" %}
-Hello! I am {{user_name}}. Please describe the images.
-{% for image in images %}
-{{ image | templatize_part }}
-{% endfor %}
-{% endmessage %}
-```
-
- ### How it works
- 1. The `{% message %}` tag is used to define a chat message.
- 2. The message can contain text and other structured content parts.
- 3. To include a structured content part in the message, the `| templatize_part` filter is used.
- The filter serializes the content part into a JSON string and wraps it in a `` tag.
- 4. The `_build_chat_message_json` method of the extension parses the message content parts,
- converts them into a ChatMessage object and serializes it to a JSON string.
- 5. The obtained JSON string is usable in the ChatPromptBuilder component, where templates are rendered to actual
- ChatMessage objects.
-
-
-
-#### ChatMessageExtension.parse
-
-```python
-def parse(parser: Any) -> Union[nodes.Node, list[nodes.Node]]
-```
-
-Parse the message tag and its attributes in the Jinja2 template.
-
-This method handles the parsing of role (mandatory), name (optional), meta (optional) and message body content.
-
-**Arguments**:
-
-- `parser`: The Jinja2 parser instance
-
-**Raises**:
-
-- `TemplateSyntaxError`: If an invalid role is provided
+Resolve the secret to an atomic value. The semantics of the value is secret-dependent.
**Returns**:
-A CallBlock node containing the parsed message configuration
+The value of the secret, if any.
-
+
-#### templatize\_part
+#### Secret.type
```python
-def templatize_part(value: ChatMessageContentT) -> str
+@property
+@abstractmethod
+def type() -> SecretType
```
-Jinja filter to convert an ChatMessageContentT object into JSON string wrapped in special XML content tags.
+The type of the secret.
+
+
+
+#### deserialize\_secrets\_inplace
+
+```python
+def deserialize_secrets_inplace(data: dict[str, Any],
+ keys: Iterable[str],
+ *,
+ recursive: bool = False) -> None
+```
+
+Deserialize secrets in a dictionary inplace.
**Arguments**:
-- `value`: The ChatMessageContentT object to convert
+- `data`: The dictionary with the serialized data.
+- `keys`: The keys of the secrets to deserialize.
+- `recursive`: Whether to recursively deserialize nested dictionaries.
-**Raises**:
+
-- `ValueError`: If the value is not an instance of ChatMessageContentT
+## Module azure
-**Returns**:
+
-A JSON string wrapped in special XML content tags
+#### default\_azure\_ad\_token\_provider
+
+```python
+def default_azure_ad_token_provider() -> str
+```
+
+Get a Azure AD token using the DefaultAzureCredential and the "https://cognitiveservices.azure.com/.default" scope.
@@ -377,19 +245,49 @@ class does not have a `from_dict` method.
The deserialized object.
-
+
-## Module azure
+## Module callable\_serialization
-
+
-#### default\_azure\_ad\_token\_provider
+#### serialize\_callable
```python
-def default_azure_ad_token_provider() -> str
+def serialize_callable(callable_handle: Callable) -> str
```
-Get a Azure AD token using the DefaultAzureCredential and the "https://cognitiveservices.azure.com/.default" scope.
+Serializes a callable to its full path.
+
+**Arguments**:
+
+- `callable_handle`: The callable to serialize
+
+**Returns**:
+
+The full path of the callable
+
+
+
+#### deserialize\_callable
+
+```python
+def deserialize_callable(callable_handle: str) -> Callable
+```
+
+Deserializes a callable given its full import path as a string.
+
+**Arguments**:
+
+- `callable_handle`: The full path of the callable_handle
+
+**Raises**:
+
+- `DeserializationError`: If the callable cannot be found
+
+**Returns**:
+
+The callable
@@ -461,32 +359,6 @@ Deserialize a Component in a dictionary inplace.
- `DeserializationError`: If the key is missing in the serialized data, the value is not a dictionary,
the type key is missing, the class cannot be imported, or the class lacks a 'from_dict' method.
-
-
-## Module http\_client
-
-
-
-#### init\_http\_client
-
-```python
-def init_http_client(
- http_client_kwargs: Optional[dict[str, Any]] = None,
- async_client: bool = False
-) -> Union[httpx.Client, httpx.AsyncClient, None]
-```
-
-Initialize an httpx client based on the http_client_kwargs.
-
-**Arguments**:
-
-- `http_client_kwargs`: The kwargs to pass to the httpx client.
-- `async_client`: Whether to initialize an async client.
-
-**Returns**:
-
-A httpx client or an async httpx client.
-
## Module device
@@ -953,6 +825,394 @@ Create a component device representation from a JSON-serialized dictionary.
The deserialized component device.
+
+
+## Module filters
+
+
+
+#### raise\_on\_invalid\_filter\_syntax
+
+```python
+def raise_on_invalid_filter_syntax(
+ filters: Optional[dict[str, Any]] = None) -> None
+```
+
+Raise an error if the filter syntax is invalid.
+
+
+
+#### document\_matches\_filter
+
+```python
+def document_matches_filter(filters: dict[str, Any],
+ document: Union[Document, ByteStream]) -> bool
+```
+
+Return whether `filters` match the Document or the ByteStream.
+
+For a detailed specification of the filters, refer to the
+`DocumentStore.filter_documents()` protocol documentation.
+
+
+
+## Module http\_client
+
+
+
+#### init\_http\_client
+
+```python
+def init_http_client(
+ http_client_kwargs: Optional[dict[str, Any]] = None,
+ async_client: bool = False
+) -> Union[httpx.Client, httpx.AsyncClient, None]
+```
+
+Initialize an httpx client based on the http_client_kwargs.
+
+**Arguments**:
+
+- `http_client_kwargs`: The kwargs to pass to the httpx client.
+- `async_client`: Whether to initialize an async client.
+
+**Returns**:
+
+A httpx client or an async httpx client.
+
+
+
+## Module jinja2\_chat\_extension
+
+
+
+### ChatMessageExtension
+
+A Jinja2 extension for creating structured chat messages with mixed content types.
+
+This extension provides a custom `{% message %}` tag that allows creating chat messages
+with different attributes (role, name, meta) and mixed content types (text, images, etc.).
+
+Inspired by [Banks](https://github.com/masci/banks).
+
+**Example**:
+
+```
+{% message role="system" %}
+You are a helpful assistant. You like to talk with {{user_name}}.
+{% endmessage %}
+
+{% message role="user" %}
+Hello! I am {{user_name}}. Please describe the images.
+{% for image in images %}
+{{ image | templatize_part }}
+{% endfor %}
+{% endmessage %}
+```
+
+ ### How it works
+ 1. The `{% message %}` tag is used to define a chat message.
+ 2. The message can contain text and other structured content parts.
+ 3. To include a structured content part in the message, the `| templatize_part` filter is used.
+ The filter serializes the content part into a JSON string and wraps it in a `` tag.
+ 4. The `_build_chat_message_json` method of the extension parses the message content parts,
+ converts them into a ChatMessage object and serializes it to a JSON string.
+ 5. The obtained JSON string is usable in the ChatPromptBuilder component, where templates are rendered to actual
+ ChatMessage objects.
+
+
+
+#### ChatMessageExtension.parse
+
+```python
+def parse(parser: Any) -> Union[nodes.Node, list[nodes.Node]]
+```
+
+Parse the message tag and its attributes in the Jinja2 template.
+
+This method handles the parsing of role (mandatory), name (optional), meta (optional) and message body content.
+
+**Arguments**:
+
+- `parser`: The Jinja2 parser instance
+
+**Raises**:
+
+- `TemplateSyntaxError`: If an invalid role is provided
+
+**Returns**:
+
+A CallBlock node containing the parsed message configuration
+
+
+
+#### templatize\_part
+
+```python
+def templatize_part(value: ChatMessageContentT) -> str
+```
+
+Jinja filter to convert an ChatMessageContentT object into JSON string wrapped in special XML content tags.
+
+**Arguments**:
+
+- `value`: The ChatMessageContentT object to convert
+
+**Raises**:
+
+- `ValueError`: If the value is not an instance of ChatMessageContentT
+
+**Returns**:
+
+A JSON string wrapped in special XML content tags
+
+
+
+## Module jinja2\_extensions
+
+
+
+### Jinja2TimeExtension
+
+
+
+#### Jinja2TimeExtension.\_\_init\_\_
+
+```python
+def __init__(environment: Environment)
+```
+
+Initializes the JinjaTimeExtension object.
+
+**Arguments**:
+
+- `environment`: The Jinja2 environment to initialize the extension with.
+It provides the context where the extension will operate.
+
+
+
+#### Jinja2TimeExtension.parse
+
+```python
+def parse(parser: Any) -> Union[nodes.Node, list[nodes.Node]]
+```
+
+Parse the template expression to determine how to handle the datetime formatting.
+
+**Arguments**:
+
+- `parser`: The parser object that processes the template expressions and manages the syntax tree.
+It's used to interpret the template's structure.
+
+
+
+## Module jupyter
+
+
+
+#### is\_in\_jupyter
+
+```python
+def is_in_jupyter() -> bool
+```
+
+Returns `True` if in Jupyter or Google Colab, `False` otherwise.
+
+
+
+## Module misc
+
+
+
+#### expand\_page\_range
+
+```python
+def expand_page_range(page_range: list[Union[str, int]]) -> list[int]
+```
+
+Takes a list of page numbers and ranges and expands them into a list of page numbers.
+
+For example, given a page_range=['1-3', '5', '8', '10-12'] the function will return [1, 2, 3, 5, 8, 10, 11, 12]
+
+**Arguments**:
+
+- `page_range`: List of page numbers and ranges
+
+**Returns**:
+
+An expanded list of page integers
+
+
+
+#### expit
+
+```python
+def expit(
+ x: Union[float, ndarray[Any, Any]]) -> Union[float, ndarray[Any, Any]]
+```
+
+Compute logistic sigmoid function. Maps input values to a range between 0 and 1
+
+**Arguments**:
+
+- `x`: input value. Can be a scalar or a numpy array.
+
+
+
+## Module requests\_utils
+
+
+
+#### request\_with\_retry
+
+```python
+def request_with_retry(attempts: int = 3,
+ status_codes_to_retry: Optional[list[int]] = None,
+ **kwargs: Any) -> requests.Response
+```
+
+Executes an HTTP request with a configurable exponential backoff retry on failures.
+
+Usage example:
+```python
+from haystack.utils import request_with_retry
+
+# Sending an HTTP request with default retry configs
+res = request_with_retry(method="GET", url="https://example.com")
+
+# Sending an HTTP request with custom number of attempts
+res = request_with_retry(method="GET", url="https://example.com", attempts=10)
+
+# Sending an HTTP request with custom HTTP codes to retry
+res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=[408, 503])
+
+# Sending an HTTP request with custom timeout in seconds
+res = request_with_retry(method="GET", url="https://example.com", timeout=5)
+
+# Sending an HTTP request with custom authorization handling
+class CustomAuth(requests.auth.AuthBase):
+ def __call__(self, r):
+ r.headers["authorization"] = "Basic "
+ return r
+
+res = request_with_retry(method="GET", url="https://example.com", auth=CustomAuth())
+
+# All of the above combined
+res = request_with_retry(
+ method="GET",
+ url="https://example.com",
+ auth=CustomAuth(),
+ attempts=10,
+ status_codes_to_retry=[408, 503],
+ timeout=5
+)
+
+# Sending a POST request
+res = request_with_retry(method="POST", url="https://example.com", data={"key": "value"}, attempts=10)
+
+# Retry all 5xx status codes
+res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=list(range(500, 600)))
+```
+
+**Arguments**:
+
+- `attempts`: Maximum number of attempts to retry the request.
+- `status_codes_to_retry`: List of HTTP status codes that will trigger a retry.
+When param is `None`, HTTP 408, 418, 429 and 503 will be retried.
+- `kwargs`: Optional arguments that `request` accepts.
+
+**Returns**:
+
+The `Response` object.
+
+
+
+#### async\_request\_with\_retry
+
+```python
+async def async_request_with_retry(attempts: int = 3,
+ status_codes_to_retry: Optional[
+ list[int]] = None,
+ **kwargs: Any) -> httpx.Response
+```
+
+Executes an asynchronous HTTP request with a configurable exponential backoff retry on failures.
+
+Usage example:
+```python
+import asyncio
+from haystack.utils import async_request_with_retry
+
+# Sending an async HTTP request with default retry configs
+async def example():
+ res = await async_request_with_retry(method="GET", url="https://example.com")
+ return res
+
+# Sending an async HTTP request with custom number of attempts
+async def example_with_attempts():
+ res = await async_request_with_retry(method="GET", url="https://example.com", attempts=10)
+ return res
+
+# Sending an async HTTP request with custom HTTP codes to retry
+async def example_with_status_codes():
+ res = await async_request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=[408, 503])
+ return res
+
+# Sending an async HTTP request with custom timeout in seconds
+async def example_with_timeout():
+ res = await async_request_with_retry(method="GET", url="https://example.com", timeout=5)
+ return res
+
+# Sending an async HTTP request with custom headers
+async def example_with_headers():
+ headers = {"Authorization": "Bearer "}
+ res = await async_request_with_retry(method="GET", url="https://example.com", headers=headers)
+ return res
+
+# All of the above combined
+async def example_combined():
+ headers = {"Authorization": "Bearer "}
+ res = await async_request_with_retry(
+ method="GET",
+ url="https://example.com",
+ headers=headers,
+ attempts=10,
+ status_codes_to_retry=[408, 503],
+ timeout=5
+ )
+ return res
+
+# Sending an async POST request
+async def example_post():
+ res = await async_request_with_retry(
+ method="POST",
+ url="https://example.com",
+ json={"key": "value"},
+ attempts=10
+ )
+ return res
+
+# Retry all 5xx status codes
+async def example_5xx():
+ res = await async_request_with_retry(
+ method="GET",
+ url="https://example.com",
+ status_codes_to_retry=list(range(500, 600))
+ )
+ return res
+```
+
+**Arguments**:
+
+- `attempts`: Maximum number of attempts to retry the request.
+- `status_codes_to_retry`: List of HTTP status codes that will trigger a retry.
+When param is `None`, HTTP 408, 418, 429 and 503 will be retried.
+- `kwargs`: Optional arguments that `httpx.AsyncClient.request` accepts.
+
+**Returns**:
+
+The `httpx.Response` object.
+
## Module type\_serialization
@@ -1022,227 +1282,6 @@ on the performance of the import for single-threaded environments.
- `module_name`: the module to import
-
-
-## Module callable\_serialization
-
-
-
-#### serialize\_callable
-
-```python
-def serialize_callable(callable_handle: Callable) -> str
-```
-
-Serializes a callable to its full path.
-
-**Arguments**:
-
-- `callable_handle`: The callable to serialize
-
-**Returns**:
-
-The full path of the callable
-
-
-
-#### deserialize\_callable
-
-```python
-def deserialize_callable(callable_handle: str) -> Callable
-```
-
-Deserializes a callable given its full import path as a string.
-
-**Arguments**:
-
-- `callable_handle`: The full path of the callable_handle
-
-**Raises**:
-
-- `DeserializationError`: If the callable cannot be found
-
-**Returns**:
-
-The callable
-
-
-
-## Module auth
-
-
-
-### SecretType
-
-
-
-#### SecretType.from\_str
-
-```python
-@staticmethod
-def from_str(string: str) -> "SecretType"
-```
-
-Convert a string to a SecretType.
-
-**Arguments**:
-
-- `string`: The string to convert.
-
-
-
-### Secret
-
-Encapsulates a secret used for authentication.
-
-Usage example:
-```python
-from haystack.components.generators import OpenAIGenerator
-from haystack.utils import Secret
-
-generator = OpenAIGenerator(api_key=Secret.from_token(""))
-```
-
-
-
-#### Secret.from\_token
-
-```python
-@staticmethod
-def from_token(token: str) -> "Secret"
-```
-
-Create a token-based secret. Cannot be serialized.
-
-**Arguments**:
-
-- `token`: The token to use for authentication.
-
-
-
-#### Secret.from\_env\_var
-
-```python
-@staticmethod
-def from_env_var(env_vars: Union[str, list[str]],
- *,
- strict: bool = True) -> "Secret"
-```
-
-Create an environment variable-based secret. Accepts one or more environment variables.
-
-Upon resolution, it returns a string token from the first environment variable that is set.
-
-**Arguments**:
-
-- `env_vars`: A single environment variable or an ordered list of
-candidate environment variables.
-- `strict`: Whether to raise an exception if none of the environment
-variables are set.
-
-
-
-#### Secret.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Convert the secret to a JSON-serializable dictionary.
-
-Some secrets may not be serializable.
-
-**Returns**:
-
-The serialized policy.
-
-
-
-#### Secret.from\_dict
-
-```python
-@staticmethod
-def from_dict(dict: dict[str, Any]) -> "Secret"
-```
-
-Create a secret from a JSON-serializable dictionary.
-
-**Arguments**:
-
-- `dict`: The dictionary with the serialized data.
-
-**Returns**:
-
-The deserialized secret.
-
-
-
-#### Secret.resolve\_value
-
-```python
-@abstractmethod
-def resolve_value() -> Optional[Any]
-```
-
-Resolve the secret to an atomic value. The semantics of the value is secret-dependent.
-
-**Returns**:
-
-The value of the secret, if any.
-
-
-
-#### Secret.type
-
-```python
-@property
-@abstractmethod
-def type() -> SecretType
-```
-
-The type of the secret.
-
-
-
-#### deserialize\_secrets\_inplace
-
-```python
-def deserialize_secrets_inplace(data: dict[str, Any],
- keys: Iterable[str],
- *,
- recursive: bool = False) -> None
-```
-
-Deserialize secrets in a dictionary inplace.
-
-**Arguments**:
-
-- `data`: The dictionary with the serialized data.
-- `keys`: The keys of the secrets to deserialize.
-- `recursive`: Whether to recursively deserialize nested dictionaries.
-
-
-
-## Module asynchronous
-
-
-
-#### is\_callable\_async\_compatible
-
-```python
-def is_callable_async_compatible(func: Callable) -> bool
-```
-
-Returns if the given callable is usable inside a component's `run_async` method.
-
-**Arguments**:
-
-- `callable`: The callable to check.
-
-**Returns**:
-
-True if the callable is compatible, False otherwise.
-
## Module url\_validation
@@ -1257,42 +1296,3 @@ def is_valid_http_url(url: str) -> bool
Check if a URL is a valid HTTP/HTTPS URL.
-
-
-## Module misc
-
-
-
-#### expand\_page\_range
-
-```python
-def expand_page_range(page_range: list[Union[str, int]]) -> list[int]
-```
-
-Takes a list of page numbers and ranges and expands them into a list of page numbers.
-
-For example, given a page_range=['1-3', '5', '8', '10-12'] the function will return [1, 2, 3, 5, 8, 10, 11, 12]
-
-**Arguments**:
-
-- `page_range`: List of page numbers and ranges
-
-**Returns**:
-
-An expanded list of page integers
-
-
-
-#### expit
-
-```python
-def expit(
- x: Union[float, ndarray[Any, Any]]) -> Union[float, ndarray[Any, Any]]
-```
-
-Compute logistic sigmoid function. Maps input values to a range between 0 and 1
-
-**Arguments**:
-
-- `x`: input value. Can be a scalar or a numpy array.
-
diff --git a/docs-website/reference/haystack-api/websearch_api.md b/docs-website/reference/haystack-api/websearch_api.md
index 49782a8bf8..4e4238bcf6 100644
--- a/docs-website/reference/haystack-api/websearch_api.md
+++ b/docs-website/reference/haystack-api/websearch_api.md
@@ -5,6 +5,112 @@ description: "Web search engine for Haystack."
slug: "/websearch-api"
---
+
+
+## Module searchapi
+
+
+
+### SearchApiWebSearch
+
+Uses [SearchApi](https://www.searchapi.io/) to search the web for relevant documents.
+
+Usage example:
+```python
+from haystack.components.websearch import SearchApiWebSearch
+from haystack.utils import Secret
+
+websearch = SearchApiWebSearch(top_k=10, api_key=Secret.from_token("test-api-key"))
+results = websearch.run(query="Who is the boyfriend of Olivia Wilde?")
+
+assert results["documents"]
+assert results["links"]
+```
+
+
+
+#### SearchApiWebSearch.\_\_init\_\_
+
+```python
+def __init__(api_key: Secret = Secret.from_env_var("SEARCHAPI_API_KEY"),
+ top_k: Optional[int] = 10,
+ allowed_domains: Optional[list[str]] = None,
+ search_params: Optional[dict[str, Any]] = None)
+```
+
+Initialize the SearchApiWebSearch component.
+
+**Arguments**:
+
+- `api_key`: API key for the SearchApi API
+- `top_k`: Number of documents to return.
+- `allowed_domains`: List of domains to limit the search to.
+- `search_params`: 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`.
+
+
+
+#### SearchApiWebSearch.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+
+
+#### SearchApiWebSearch.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "SearchApiWebSearch"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+
+
+#### SearchApiWebSearch.run
+
+```python
+@component.output_types(documents=list[Document], links=list[str])
+def run(query: str) -> dict[str, Union[list[Document], list[str]]]
+```
+
+Uses [SearchApi](https://www.searchapi.io/) to search the web.
+
+**Arguments**:
+
+- `query`: Search query.
+
+**Raises**:
+
+- `TimeoutError`: If the request to the SearchApi API times out.
+- `SearchApiError`: If an error occurs while querying the SearchApi API.
+
+**Returns**:
+
+A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+
## Module serper\_dev
@@ -120,109 +226,3 @@ A dictionary with the following keys:
- "documents": List of documents returned by the search engine.
- "links": List of links returned by the search engine.
-
-
-## Module searchapi
-
-
-
-### SearchApiWebSearch
-
-Uses [SearchApi](https://www.searchapi.io/) to search the web for relevant documents.
-
-Usage example:
-```python
-from haystack.components.websearch import SearchApiWebSearch
-from haystack.utils import Secret
-
-websearch = SearchApiWebSearch(top_k=10, api_key=Secret.from_token("test-api-key"))
-results = websearch.run(query="Who is the boyfriend of Olivia Wilde?")
-
-assert results["documents"]
-assert results["links"]
-```
-
-
-
-#### SearchApiWebSearch.\_\_init\_\_
-
-```python
-def __init__(api_key: Secret = Secret.from_env_var("SEARCHAPI_API_KEY"),
- top_k: Optional[int] = 10,
- allowed_domains: Optional[list[str]] = None,
- search_params: Optional[dict[str, Any]] = None)
-```
-
-Initialize the SearchApiWebSearch component.
-
-**Arguments**:
-
-- `api_key`: API key for the SearchApi API
-- `top_k`: Number of documents to return.
-- `allowed_domains`: List of domains to limit the search to.
-- `search_params`: 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`.
-
-
-
-#### SearchApiWebSearch.to\_dict
-
-```python
-def to_dict() -> dict[str, Any]
-```
-
-Serializes the component to a dictionary.
-
-**Returns**:
-
-Dictionary with serialized data.
-
-
-
-#### SearchApiWebSearch.from\_dict
-
-```python
-@classmethod
-def from_dict(cls, data: dict[str, Any]) -> "SearchApiWebSearch"
-```
-
-Deserializes the component from a dictionary.
-
-**Arguments**:
-
-- `data`: The dictionary to deserialize from.
-
-**Returns**:
-
-The deserialized component.
-
-
-
-#### SearchApiWebSearch.run
-
-```python
-@component.output_types(documents=list[Document], links=list[str])
-def run(query: str) -> dict[str, Union[list[Document], list[str]]]
-```
-
-Uses [SearchApi](https://www.searchapi.io/) to search the web.
-
-**Arguments**:
-
-- `query`: Search query.
-
-**Raises**:
-
-- `TimeoutError`: If the request to the SearchApi API times out.
-- `SearchApiError`: If an error occurs while querying the SearchApi API.
-
-**Returns**:
-
-A dictionary with the following keys:
-- "documents": List of documents returned by the search engine.
-- "links": List of links returned by the search engine.
-