- `
+Consider the instructions and the examples below to determine those values.
+
+Examples:
+`
- Documentation @@ -39,17 +50,17 @@ export default function Versions() {
- - - Version {version} + {pastVersions.map((version) => ( +
- + + Version {version.name} ))} diff --git a/docs-website/versioned_docs/version-2.20-unstable/_templates/component-template.mdx b/docs-website/versioned_docs/version-2.20-unstable/_templates/component-template.mdx new file mode 100644 index 0000000000..1aa42e9442 --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/_templates/component-template.mdx @@ -0,0 +1,43 @@ +--- +title: "Component Name" +id: "component-name" +description: "A short description of the component" +slug: "/component-name" +--- + +# Component Name + +
- `
+Consider the instructions and the examples below to determine those values.
+
+Examples:
+`
- `
+Consider the instructions and the examples below to determine those values.
+
+Examples:
+`
Current version (Stable)
-Documentation for the current stable release (v{currentVersion}).
+Documentation for the current stable release (v{lastVersion?.name || lastVersion?.label}).
Past Versions
Here you can find documentation for previous versions of Haystack.
-
- {versions.slice(1).map((version) => (
-
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | |
+| **Mandatory init variables** | |
+| **Mandatory run variables** | |
+| **Output variables** | |
+| **API reference** | |
+| **GitHub link** | |
+
+
+
+## Overview
+
+*What does it do in general? For example,..?*
+
+*How does it work more specifically? Are there any pitfalls to pay attention to?*
+
+*(if applicable) How is it different from this other very similar component? Which one do you choose?*
+
+## Usage
+
+*Any mandatory imports?*
+
+### On its own
+
+*Code snippet on how to run a component*
+
+### In a pipeline
+
+*Code snippet of a component being introduced in a pipeline*
+
+*There can be more than one example. Add examples of pipelines where this component would be most useful, for example RAG, doc retrieval, etc.*
diff --git a/docs-website/versioned_docs/version-2.20-unstable/_templates/document-store-template.mdx b/docs-website/versioned_docs/version-2.20-unstable/_templates/document-store-template.mdx
new file mode 100644
index 0000000000..6418824a44
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/_templates/document-store-template.mdx
@@ -0,0 +1,30 @@
+---
+title: "Document Store Name"
+id: "document-store-name"
+description: "A short description of the document store"
+slug: "/document-store-name"
+---
+
+# Document Store Name
+
+## Description
+
+*What are this Document Store features? When would a user select it, and when not?*
+
+*Are there any limitations?*
+
+*Users are often curious to know if a document store supports metadata filtering and sparse vectors.*
+
+## Initialization
+
+*Describe how to get this Document Store to work, with code samples.*
+
+## Supported Retrievers
+
+*Name of the supported Retriever(s).*
+
+*If several – describe how to choose an appropriate one for user’s goals (perhaps, one is faster and the other is more accurate).*
+
+## Link to GitHub
+
+*for example [https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/gradient](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/gradient)*
diff --git a/docs-website/versioned_docs/version-2.20-unstable/concepts/agents.mdx b/docs-website/versioned_docs/version-2.20-unstable/concepts/agents.mdx
new file mode 100644
index 0000000000..f07dd71d8b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/concepts/agents.mdx
@@ -0,0 +1,205 @@
+---
+title: "Agents"
+id: agents
+slug: "/agents"
+description: "This page explains how to create an AI agent in Haystack capable of retrieving information, generating responses, and taking actions using various Haystack components."
+---
+
+# Agents
+
+This page explains how to create an AI agent in Haystack capable of retrieving information, generating responses, and taking actions using various Haystack components.
+
+## What’s an AI Agent?
+
+An AI agent is a system that can:
+
+- Understand user input (text, image, audio, and other queries),
+- Retrieve relevant information (documents or structured data),
+- Generate intelligent responses (using LLMs like OpenAI or Hugging Face models),
+- Perform actions (calling APIs, fetching live data, executing functions).
+
+### Understanding AI Agents
+
+AI agents are autonomous systems that use large language models (LLMs) to make decisions and solve complex tasks. They interact with their environment using tools, memory, and reasoning.
+
+### What Makes an AI Agent
+
+An AI agent is more than a chatbot. It actively plans, chooses the right tools and executes tasks to achieve a goal. Unlike traditional software, it adapts to new information and refines its process as needed.
+
+1. **LLM as the Brain**: The agent's core is an LLM, which understands context, processes natural language and serves as the central intelligence system.
+2. **Tools for Interaction**: Agents connect to external tools, APIs, and databases to gather information and take action.
+3. **Memory for Context**: Short-term memory helps track conversations, while long-term memory stores knowledge for future interactions.
+4. **Reasoning and Planning**: Agents break down complex problems, come up with step-by-step action plans, and adapt based on new data and feedback.
+
+### How AI Agents Work
+
+An AI agent starts with a prompt that defines its role and objectives. It decides when to use tools, gathers data, and refines its approach through loops of reasoning and action. It evaluates progress and adjusts its strategy to improve results.
+
+For example, a customer service agent answers queries using a database. If it lacks an answer, it fetches real-time data, summarizes it, and provides a response. A coding assistant understands project requirements, suggests solutions, and even writes code.
+
+## Key Components
+
+### Agents
+
+Haystack has a universal [Agent](../pipeline-components/agents-1/agent.mdx) component that interacts with chat-based LLMs and tools to solve complex queries. It requires a Chat Generator that supports tools to work and can be customizable according to your needs. Check out the [Agent](../pipeline-components/agents-1/agent.mdx) documentation, or the [example](#tool-calling-agent) below to see how it works.
+
+### Additional Components
+
+You can build an AI agent in Haystack yourself, using the three main elements in a pipeline:
+
+- [Chat Generators](../pipeline-components/generators.mdx) to generate tool calls (with tool name and arguments) or assistant responses with an LLM,
+- [`Tool`](../tools/tool.mdx) class that allows the LLM to perform actions such as running a pipeline or calling an external API, connecting to the external world,
+- [`ToolInvoker`](../pipeline-components/tools/toolinvoker.mdx) component to execute tool calls generated by an LLM. It parses the LLM's tool-calling responses and invokes the appropriate tool with the correct arguments from the pipeline.
+
+There are three ways of creating a tool in Haystack:
+
+- [`Tool`](../tools/tool.mdx) class – Creates a tool representation for a consistent tool-calling experience across all Generators. It allows for most customization, as you can define its own name and description.
+- [`ComponentTool`](../tools/componenttool.mdx) class – Wraps a Haystack component as a callable tool.
+- [`@tool`](../tools/tool.mdx#tool-decorator) decorator – Creates tools from Python functions and automatically uses their function name and docstring.
+- [Toolset](../tools/toolset.mdx) – A container for grouping multiple tools that can be passed directly to Agents or Generators.
+
+## Example Agents
+
+### Tool-Calling Agent
+
+You can create a similar tool-calling agent with the `Agent` component:
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.dataclasses import Document, ChatMessage
+from haystack.tools.component_tool import ComponentTool
+
+from typing import List
+
+## Create the web search component
+web_search = SerperDevWebSearch(top_k=3)
+
+## Create the ComponentTool with simpler parameters
+web_tool = ComponentTool(
+ component=web_search,
+ name="web_search",
+ description="Search the web for current information like weather, news, or facts."
+)
+
+## Create the agent with the web tool
+tool_calling_agent = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+ system_prompt="""You're a helpful agent. When asked about current information like weather, news, or facts,
+ use the web_search tool to find the information and then summarize the findings.
+ When you get web search results, extract the relevant information and present it in a clear,
+ concise manner.""",
+ tools=[web_tool]
+)
+
+## Run the agent with the user message
+user_message = ChatMessage.from_user("How is the weather in Berlin?")
+result = tool_calling_agent.run(messages=[user_message])
+
+## Print the result - using .text instead of .content
+print(result["messages"][-1].text)
+```
+
+Resulting in:
+
+```python
+>>> The current weather in Berlin is approximately 60°F. The forecast for today includes clouds in the morning with some sunshine later. The high temperature is expected to be around 65°F, and the low tonight will drop to 40°F.
+
+- **Morning**: 49°F
+- **Afternoon**: 57°F
+- **Evening**: 47°F
+- **Overnight**: 39°F
+
+For more details, you can check the full forecasts on [AccuWeather](https://www.accuweather.com/en/de/berlin/10178/current-weather/178087) or [Weather.com](https://weather.com/weather/today/l/5ca23443513a0fdc1d37ae2ffaf5586162c6fe592a66acc9320a0d0536be1bb9).
+```
+
+### Pipeline With Tools
+
+Here’s an example of how you would build a tool-calling agent with the help of `ToolInvoker`.
+
+This is what’s happening in this code example:
+
+1. `OpenAIChatGenerator` uses an LLM to analyze the user's message and determines whether to provide an assistant response or initiate a tool call.
+2. `ConditionalRouter` directs the output from the `OpenAIChatGenerator` to `there_are_tool_calls` branch if it’s a tool call or to `final_replies` to return to the user directly.
+3. `ToolInvoker` executes the tool call generated by the LLM. `ComponentTool` wraps the `SerperDevWebSearch` component that fetches real-time search results, making it accessible for `ToolInvoker` to execute it as a tool.
+4. After the tool provides its output, the `ToolInvoker` sends this information back to the `OpenAIChatGenerator`, along with the original user question stored by the `MessageCollector`.
+
+```python
+from haystack import component, Pipeline
+from haystack.components.tools import ToolInvoker
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.routers import ConditionalRouter
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.core.component.types import Variadic
+from haystack.dataclasses import ChatMessage
+from haystack.tools import ComponentTool
+
+from typing import Any, Dict, List
+
+## helper component to temporarily store last user query before the tool call
+@component()
+class MessageCollector:
+ def __init__(self):
+ self._messages = []
+
+ @component.output_types(messages=List[ChatMessage])
+ def run(self, messages: Variadic[List[ChatMessage]]) -> Dict[str, Any]:
+
+ self._messages.extend([msg for inner in messages for msg in inner])
+ return {"messages": self._messages}
+
+ def clear(self):
+ self._messages = []
+
+## Create a tool from a component
+web_tool = ComponentTool(
+ component=SerperDevWebSearch(top_k=3)
+)
+
+## Define routing conditions
+routes = [
+ {
+ "condition": "{{replies[0].tool_calls | length > 0}}",
+ "output": "{{replies}}",
+ "output_name": "there_are_tool_calls",
+ "output_type": List[ChatMessage],
+ },
+ {
+ "condition": "{{replies[0].tool_calls | length == 0}}",
+ "output": "{{replies}}",
+ "output_name": "final_replies",
+ "output_type": List[ChatMessage],
+ },
+]
+
+## Create the pipeline
+tool_agent = Pipeline()
+tool_agent.add_component("message_collector", MessageCollector())
+tool_agent.add_component("generator", OpenAIChatGenerator(model="gpt-4o-mini", tools=[web_tool]))
+tool_agent.add_component("router", ConditionalRouter(routes, unsafe=True))
+tool_agent.add_component("tool_invoker", ToolInvoker(tools=[web_tool]))
+
+tool_agent.connect("generator.replies", "router")
+tool_agent.connect("router.there_are_tool_calls", "tool_invoker")
+tool_agent.connect("router.there_are_tool_calls", "message_collector")
+tool_agent.connect("tool_invoker.tool_messages", "message_collector")
+tool_agent.connect("message_collector", "generator.messages")
+
+messages = [
+ ChatMessage.from_system("You're a helpful agent choosing the right tool when necessary"),
+ ChatMessage.from_user("How is the weather in Berlin?")]
+result = tool_agent.run({"messages": messages})
+
+print(result["router"]["final_replies"][0].text)
+```
+
+Resulting in:
+
+```python
+>>> The current weather in Berlin is around 46°F (8°C) with cloudy conditions. The high for today is forecasted to reach 48°F (9°C) and the low is expected to be around 37°F (3°C). The humidity is quite high at 92%, and there is a light wind blowing at 4 mph.
+
+For more detailed weather updates, you can check the following links:
+- [AccuWeather](https://www.accuweather.com/en/de/berlin/10178/weather-forecast/178087)
+- [Weather.com](https://weather.com/weather/today/l/5ca23443513a0fdc1d37ae2ffaf5586162c6fe592a66acc9320a0d0536be1bb9)
+```
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.20-unstable/concepts/agents/state.mdx b/docs-website/versioned_docs/version-2.20-unstable/concepts/agents/state.mdx
new file mode 100644
index 0000000000..13c92ae05f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/concepts/agents/state.mdx
@@ -0,0 +1,511 @@
+---
+title: "State"
+id: state
+slug: "/state"
+description: "`State` is a container for storing shared information during Agent and Tool execution. It provides a structured way to store messages during execution, share data between tools, and store intermediate results throughout an agent's workflow."
+---
+
+# State
+
+`State` is a container for storing shared information during Agent and Tool execution. It provides a structured way to store messages during execution, share data between tools, and store intermediate results throughout an agent's workflow.
+
+## Overview
+
+When building agents that use multiple tools, you often need tools to share information with each other. State solves this problem by providing centralized storage that all tools can read from and write to. For example, one tool might retrieve documents while another tool uses those documents to generate an answer.
+
+State uses a schema-based approach where you define:
+
+- What data can be stored,
+- The type of each piece of data,
+- How values are merged when updated.
+
+### Supported Types
+
+State supports standard Python types:
+
+- Basic types: `str`, `int`, `float`, `bool`, `dict`,
+- List types: `list`, `list[str]`, `list[int]`, `list[Document]`,
+- Union types: `Union[str, int]`, `Optional[str]`,
+- Custom classes and data classes.
+
+### Automatic Message Handling
+
+State automatically includes a `messages` field to store messages during execution. You don't need to define this in your schema.
+
+```python
+## State automatically adds messages field
+state = State(schema={"user_id": {"type": str}})
+
+## The messages field is available
+print("messages" in state.schema) # True
+print(state.schema["messages"]["type"]) # list[ChatMessage]
+
+## Access messages
+messages = state.get("messages", [])
+```
+
+The `messages` field uses `list[ChatMessage]` type and `merge_lists` handler by default, which means new messages are appended during execution.
+
+## Usage
+
+### Creating State
+
+Create State by defining a schema that specifies what data can be stored and their types:
+
+```python
+from haystack.components.agents.state import State
+
+## Define the schema
+schema = {
+ "user_name": {"type": str},
+ "documents": {"type": list},
+ "count": {"type": int}
+}
+
+## Create State with initial data
+state = State(
+ schema=schema,
+ data={"user_name": "Alice", "documents": [], "count": 0}
+)
+```
+
+### Reading from State
+
+Use the `get()` method to retrieve values:
+
+```python
+## Get a value
+user_name = state.get("user_name")
+
+## Get a value with a default if key doesn't exist
+documents = state.get("documents", [])
+
+## Check if a key exists
+if state.has("user_name"):
+ print(f"User: {state.get('user_name')}")
+```
+
+### Writing to State
+
+Use the `set()` method to store or merge values:
+
+```python
+## Set a value
+state.set("user_name", "Bob")
+
+## Set list values (these are merged by default)
+state.set("documents", [{"title": "Doc 1", "content": "Content 1"}])
+```
+
+## Schema Definition
+
+The schema defines what data can be stored and how values are updated. Each schema entry consists of:
+
+- `type` (required): The Python type that defines what kind of data can be stored (for example, `str`, `int`, `list`)
+- `handler` (optional): A function that determines how new values are merged with existing values when you call `set()`
+
+```python
+{
+ "parameter_name": {
+ "type": SomeType, # Required: Expected Python type for this field
+ "handler": Optional[Callable[[Any, Any], Any]] # Optional: Function to merge values
+ }
+}
+```
+
+If you don't specify a handler, State automatically assigns a default handler based on the type.
+
+### Default Handlers
+
+Handlers control how values are merged when you call `set()` on an existing key. State provides two default handlers:
+
+- `merge_lists`: Combines the lists together (default for list types)
+- `replace_values`: Overwrites the existing value (default for non-list types)
+
+```python
+from haystack.components.agents.state.state_utils import merge_lists, replace_values
+
+schema = {
+ "documents": {"type": list}, # Uses merge_lists by default
+ "user_name": {"type": str}, # Uses replace_values by default
+ "count": {"type": int} # Uses replace_values by default
+}
+
+state = State(schema=schema)
+
+## Lists are merged by default
+state.set("documents", [1, 2])
+state.set("documents", [3, 4])
+print(state.get("documents")) # Output: [1, 2, 3, 4]
+
+## Other values are replaced
+state.set("user_name", "Alice")
+state.set("user_name", "Bob")
+print(state.get("user_name")) # Output: "Bob"
+
+```
+
+### Custom Handlers
+
+You can define custom handlers for specific merge behavior:
+
+```python
+def custom_merge(current_value, new_value):
+ """Custom handler that merges and sorts lists."""
+ current_list = current_value or []
+ new_list = new_value if isinstance(new_value, list) else [new_value]
+ return sorted(current_list + new_list)
+
+schema = {
+ "numbers": {"type": list, "handler": custom_merge}
+}
+
+state = State(schema=schema)
+state.set("numbers", [3, 1])
+state.set("numbers", [2, 4])
+print(state.get("numbers")) # Output: [1, 2, 3, 4]
+```
+
+You can also override handlers for individual operations:
+
+```python
+def concatenate_strings(current, new):
+ return f"{current}-{new}" if current else new
+
+schema = {"user_name": {"type": str}}
+state = State(schema=schema)
+
+state.set("user_name", "Alice")
+state.set("user_name", "Bob", handler_override=concatenate_strings)
+print(state.get("user_name")) # Output: "Alice-Bob"
+```
+
+## Using State with Agents
+
+To use State with an Agent, define a state schema when creating the Agent. The Agent automatically manages State throughout its execution.
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import Tool
+
+## Define a simple calculation tool
+def calculate(expression: str) -> dict:
+ """Evaluate a mathematical expression."""
+ result = eval(expression, {"__builtins__": {}})
+ return {"result": result}
+
+## Create a tool that writes to state
+calculator_tool = Tool(
+ name="calculator",
+ description="Evaluate basic math expressions",
+ parameters={
+ "type": "object",
+ "properties": {"expression": {"type": "string"}},
+ "required": ["expression"]
+ },
+ function=calculate,
+ outputs_to_state={"calc_result": {"source": "result"}}
+)
+
+## Create agent with state schema
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(),
+ tools=[calculator_tool],
+ state_schema={"calc_result": {"type": int}}
+)
+
+## Run the agent
+result = agent.run(
+ messages=[ChatMessage.from_user("Calculate 15 + 27")]
+)
+
+## Access the state from results
+calc_result = result["calc_result"]
+print(calc_result) # Output: 42
+```
+
+## Tools and State
+
+Tools interact with State through two mechanisms: `inputs_from_state` and `outputs_to_state`.
+
+### Reading from State: `inputs_from_state`
+
+Tools can automatically read values from State and use them as parameters. The `inputs_from_state` parameter maps state keys to tool parameter names.
+
+```python
+def search_documents(query: str, user_context: str) -> dict:
+ """Search documents using query and user context."""
+ return {
+ "results": [f"Found results for '{query}' (user: {user_context})"]
+ }
+
+## Create tool that reads from state
+search_tool = Tool(
+ name="search",
+ description="Search documents",
+ parameters={
+ "type": "object",
+ "properties": {
+ "query": {"type": "string"},
+ "user_context": {"type": "string"}
+ },
+ "required": ["query"]
+ },
+ function=search_documents,
+ inputs_from_state={"user_name": "user_context"} # Maps state's "user_name" to the tool’s input parameter “user_context”
+)
+
+## Define agent with state schema including user_name
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(),
+ tools=[search_tool],
+ state_schema={
+ "user_name": {"type": str},
+ "search_results": {"type": list}
+ }
+)
+
+## Initialize agent with user context
+result = agent.run(
+ messages=[ChatMessage.from_user("Search for Python tutorials")],
+ user_name="Alice" # All additional kwargs passed to Agent at runtime are put into State
+)
+```
+
+When the tool is invoked, the Agent automatically retrieves the value from State and passes it to the tool function.
+
+### Writing to State: `outputs_to_state`
+
+Tools can write their results back to State. The `outputs_to_state` parameter defines mappings from tool outputs to state keys.
+
+The structure of the output is: `{”state_key”: {”source”: “tool_result_key”}}`.
+
+```python
+def retrieve_documents(query: str) -> dict:
+ """Retrieve documents based on query."""
+ return {
+ "documents": [
+ {"title": "Doc 1", "content": "Content about Python"},
+ {"title": "Doc 2", "content": "More about Python"}
+ ],
+ "count": 2,
+ "query": query
+ }
+
+## Create tool that writes to state
+retrieval_tool = Tool(
+ name="retrieve",
+ description="Retrieve relevant documents",
+ parameters={
+ "type": "object",
+ "properties": {"query": {"type": "string"}},
+ "required": ["query"]
+ },
+ function=retrieve_documents,
+ outputs_to_state={
+ "documents": {"source": "documents"}, # Maps tool's "documents" output to state's "documents"
+ "result_count": {"source": "count"}, # Maps tool's "count" output to state's "result_count"
+ "last_query": {"source": "query"} # Maps tool's "query" output to state's "last_query"
+ }
+)
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(),
+ tools=[retrieval_tool],
+ state_schema={
+ "documents": {"type": list},
+ "result_count": {"type": int},
+ "last_query": {"type": str}
+ }
+)
+
+result = agent.run(
+ messages=[ChatMessage.from_user("Find information about Python")]
+)
+
+## Access state values from result
+documents = result["documents"]
+result_count = result["result_count"]
+last_query = result["last_query"]
+print(documents) # List of retrieved documents
+print(result_count) # 2
+print(last_query) # "Find information about Python"
+```
+
+Each mapping can specify:
+
+- `source`: Which field from the tool's output to use
+- `handler`: Optional custom function for merging values
+
+If you omit the `source`, the entire tool result is stored:
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import Tool
+
+def get_user_info() -> dict:
+ """Get user information."""
+ return {"name": "Alice", "email": "alice@example.com", "role": "admin"}
+
+## Tool that stores entire result
+info_tool = Tool(
+ name="get_info",
+ description="Get user information",
+ parameters={"type": "object", "properties": {}},
+ function=get_user_info,
+ outputs_to_state={
+ "user_info": {} # Stores entire result dict in state's "user_info"
+ }
+)
+
+## Create agent with matching state schema
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(),
+ tools=[info_tool],
+ state_schema={
+ "user_info": {"type": dict} # Schema must match the tool's output type
+ }
+)
+
+## Run the agent
+result = agent.run(
+ messages=[ChatMessage.from_user("Get the user information")]
+)
+
+## Access the complete result from state
+user_info = result["user_info"]
+print(user_info) # Output: {"name": "Alice", "email": "alice@example.com", "role": "admin"}
+print(user_info["name"]) # Output: "Alice"
+print(user_info["email"]) # Output: "alice@example.com"
+```
+
+### Combining Inputs and Outputs
+
+Tools can both read from and write to State, enabling tool chaining:
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import Tool
+
+def process_documents(documents: list, max_results: int) -> dict:
+ """Process documents and return filtered results."""
+ processed = documents[:max_results]
+ return {
+ "processed_docs": processed,
+ "processed_count": len(processed)
+ }
+
+processing_tool = Tool(
+ name="process",
+ description="Process retrieved documents",
+ parameters={
+ "type": "object",
+ "properties": {"max_results": {"type": "integer"}},
+ "required": ["max_results"]
+ },
+ function=process_documents,
+ inputs_from_state={"documents": "documents"}, # Reads documents from state
+ outputs_to_state={
+ "final_docs": {"source": "processed_docs"},
+ "final_count": {"source": "processed_count"}
+ }
+)
+
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(),
+ tools=[retrieval_tool, processing_tool], # Chain tools using state
+ state_schema={
+ "documents": {"type": list},
+ "final_docs": {"type": list},
+ "final_count": {"type": int}
+ }
+)
+
+## Run the agent - tools will chain through state
+result = agent.run(
+ messages=[ChatMessage.from_user("Find and process 3 documents about Python")]
+)
+
+## Access the final processed results
+final_docs = result["final_docs"]
+final_count = result["final_count"]
+print(f"Processed {final_count} documents")
+print(final_docs)
+```
+
+## Complete Example
+
+This example shows a multi-tool agent workflow where tools share data through State:
+
+```python
+import math
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import Tool
+
+## Tool 1: Calculate factorial
+def factorial(n: int) -> dict:
+ """Calculate the factorial of a number."""
+ result = math.factorial(n)
+ return {"result": result}
+
+factorial_tool = Tool(
+ name="factorial",
+ description="Calculate the factorial of a number",
+ parameters={
+ "type": "object",
+ "properties": {"n": {"type": "integer"}},
+ "required": ["n"]
+ },
+ function=factorial,
+ outputs_to_state={"factorial_result": {"source": "result"}}
+)
+
+## Tool 2: Perform calculation
+def calculate(expression: str) -> dict:
+ """Evaluate a mathematical expression."""
+ result = eval(expression, {"__builtins__": {}})
+ return {"result": result}
+
+calculator_tool = Tool(
+ name="calculator",
+ description="Evaluate basic math expressions",
+ parameters={
+ "type": "object",
+ "properties": {"expression": {"type": "string"}},
+ "required": ["expression"]
+ },
+ function=calculate,
+ outputs_to_state={"calc_result": {"source": "result"}}
+)
+
+## Create agent with both tools
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(),
+ tools=[calculator_tool, factorial_tool],
+ state_schema={
+ "calc_result": {"type": int},
+ "factorial_result": {"type": int}
+ }
+)
+
+## Run the agent
+result = agent.run(
+ messages=[ChatMessage.from_user("Calculate the factorial of 5, then multiply it by 2")]
+)
+
+## Access state values from result
+factorial_result = result["factorial_result"]
+calc_result = result["calc_result"]
+
+## Access messages from execution
+for message in result["messages"]:
+ print(f"{message.role}: {message.text}")
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/concepts/components.mdx b/docs-website/versioned_docs/version-2.20-unstable/concepts/components.mdx
new file mode 100644
index 0000000000..d70a50be44
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/concepts/components.mdx
@@ -0,0 +1,61 @@
+---
+title: "Components"
+id: components
+slug: "/components"
+description: "Components are the building blocks of a pipeline. They perform tasks such as preprocessing, retrieving, or summarizing text while routing queries through different branches of a pipeline. This page is a summary of all component types available in Haystack."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# Components
+
+Components are the building blocks of a pipeline. They perform tasks such as preprocessing, retrieving, or summarizing text while routing queries through different branches of a pipeline. This page is a summary of all component types available in Haystack.
+
+Components are connected to each other using a [pipeline](pipelines.mdx), and they function like building blocks that can be easily switched out for each other. A component can take the selected outputs of other components as input. You can also provide input to a component when you call `pipeline.run()`.
+
+## Stand-Alone or In a Pipeline
+
+You can integrate components in a pipeline to perform a specific task. But you can also use some of them stand-alone, outside of a pipeline. For example, you can run `DocumentWriter` on its own, to write documents into a Document Store. To check how to use a component and if it's usable outside of a pipeline, check the _Usage_ section on the component's documentation page.
+
+Each component has a `run()` method. When you connect components in a pipeline, and you run the pipeline by calling `Pipeline.run()`, it invokes the `run()` method for each component sequentially.
+
+## Input and Output
+
+To connect components in a pipeline, you need to know the names of the inputs and outputs they accept. The output of one component must be compatible with the input the subsequent component accepts. For example, to connect Retriever and Ranker in a pipeline, you must know that the Retriever outputs `documents` and the Ranker accepts `documents` as input.
+
+The mandatory inputs and outputs are listed in a table at the top of each component's documentation page so that you can quickly check them:
++ +```python +from haystack.dataclasses import ChatMessage + +message = ChatMessage.from_user("Hello!") + +## LEGACY - DOES NOT WORK IN 2.9.0 +print(message.content) + +## Use the appropriate property instead +print(message.text) +``` diff --git a/docs-website/versioned_docs/version-2.20-unstable/concepts/device-management.mdx b/docs-website/versioned_docs/version-2.20-unstable/concepts/device-management.mdx new file mode 100644 index 0000000000..a50008c8f3 --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/concepts/device-management.mdx @@ -0,0 +1,122 @@ +--- +title: "Device Management" +id: device-management +slug: "/device-management" +description: "This page discusses the concept of device management in the context of Haystack." +--- + +# Device Management + +This page discusses the concept of device management in the context of Haystack. + +Many Haystack components, such as `HuggingFaceLocalGenerator` , `AzureOpenAIGenerator`, and others, allow users the ability to pick and choose which language model is to be queried and executed. For components that interface with cloud-based services, the service provider automatically takes care of the details of provisioning the requisite hardware (like GPUs). However, if you wish to use models on your local machine, you’ll need to figure out how to deploy them on your hardware. Further complicating things, different ML libraries have different APIs to launch models on specific devices. + +To make the process of running inference on local models as straightforward as possible, Haystack uses a framework-agnostic device management implementation. Exposing devices through this interface means you no longer need to worry about library-specific invocations and device representations. + +## Concepts + +Haystack’s device management is built on the following abstractions: + +- `DeviceType` - An enumeration that lists all the different types of supported devices. +- `Device` - A generic representation of a device composed of a `DeviceType` and a unique identifier. Together, it represents a single device in the group of all available devices. +- `DeviceMap` - A mapping of strings to `Device` instances. The strings represent model-specific identifiers, usually model parameters. This allows us to map specific parts of a model to specific devices. +- `ComponentDevice` - A tagged union of a single `Device` or a `DeviceMap` instance. Components that support local inference will expose an optional `device` parameter of this type in their constructor. + +With the above abstractions, Haystack can fully address any supported device that’s part of your local machine and can support the usage of multiple devices at the same time. Every component that supports local inference will internally handle the conversion of these generic representations to their backend-specific representations. + +:::info Source Code + +Find the full code for the abstractions above in the Haystack GitHub [repo](https://github.com/deepset-ai/haystack/blob/6a776e672fb69cc4ee42df9039066200f1baf24e/haystack/utils/device.py). +::: + +## Usage + +To use a single device for inference, use either the `ComponentDevice.from_single` or `ComponentDevice.from_str` class method: + +```python +from haystack.utils import ComponentDevice, Device + +device = ComponentDevice.from_single(Device.gpu(id=1)) +## Alternatively, use a PyTorch device string +device = ComponentDevice.from_str("cuda:1") +generator = HuggingFaceLocalGenerator(model="llama2", device=device) +``` + +To use multiple devices, use the `ComponentDevice.from_multiple` class method: + +```python +from haystack.utils import ComponentDevice, Device, DeviceMap + +device_map = DeviceMap({ + "encoder.layer1": Device.gpu(id=0), + "decoder.layer2": Device.gpu(id=1), + "self_attention": Device.disk(), + "lm_head": Device.cpu() +}) +device = ComponentDevice.from_multiple(device_map) +generator = HuggingFaceLocalGenerator(model="llama2", device=device) +``` + +### Integrating Devices in Custom Components + +Components should expose an optional `device` parameter of type `ComponentDevice`. Once exposed, they can determine what to do with it: + +- If `device=None`, the component can pass that to the backend. In this case, the backend decides which device the model will be placed on. +- Alternatively, the component can attempt to automatically pick an available device before passing it to the backend using the `ComponentDevice.resolve_device` class method. + +Once the device has been resolved, the component can use the `ComponentDevice.to_*` methods to get the backend-specific representation of the underlying device, which is then passed to the backend. + +The `ComponentDevice` instance should be serialized in the component’s `to_dict` and `from_dict` methods. + +```python +from haystack.utils import ComponentDevice, Device, DeviceMap + +class MyComponent(Component): + def __init__(self, device: Optional[ComponentDevice] = None): + # If device is None, automatically select a device. + self.device = ComponentDevice.resolve_device(device) + + def warm_up(self): + # Call the framework-specific conversion method. + self.model = AutoModel.from_pretrained("deepset/bert-base-cased-squad2", device=self.device.to_hf()) + + def to_dict(self): + # Serialize the policy like any other (custom) data. + return default_to_dict(self, + device=self.device.to_dict() if self.device else None, + ...) + + @classmethod + def from_dict(cls, data): + # Deserialize the device data inplace before passing + # it to the generic from_dict function. + init_params = data["init_parameters"] + init_params["device"] = ComponentDevice.from_dict(init_params["device"]) + return default_from_dict(cls, data) + +## Automatically selects a device. +c = MyComponent(device=None) + +## Uses the first GPU available. +c = MyComponent(device=ComponentDevice.from_str("cuda:0")) + +## Uses the CPU. +c = MyComponent(device=ComponentDevice.from_single(Device.cpu())) + +## Allow the component to use multiple devices using a device map. +c = MyComponent(device=ComponentDevice.from_multiple(DeviceMap({ + "layer1": Device.cpu(), + "layer2": Device.gpu(1), + "layer3": Device.disk() +}))) +``` + +If the component’s backend provides a more specialized API to manage devices, it could add an additional init parameter that acts as a conduit. For instance, `HuggingFaceLocalGenerator` exposes a `huggingface_pipeline_kwargs` parameter through which Hugging Face-specific `device_map` arguments can be passed: + +```python +generator = HuggingFaceLocalGenerator(model="llama2", huggingface_pipeline_kwargs={ + "device_map": "balanced" +}) +``` + +In such cases, ensure that the parameter precedence and selection behavior is clearly documented. In the case of `HuggingFaceLocalGenerator`, the device map passed through the `huggingface_pipeline_kwargs` parameter overrides the explicit `device` parameter and is documented as such. diff --git a/docs-website/versioned_docs/version-2.20-unstable/concepts/document-store.mdx b/docs-website/versioned_docs/version-2.20-unstable/concepts/document-store.mdx new file mode 100644 index 0000000000..2550f95607 --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/concepts/document-store.mdx @@ -0,0 +1,100 @@ +--- +title: "Document Store" +id: document-store +slug: "/document-store" +description: "You can think of the Document Store as a database that stores your data and provides them to the Retriever at query time. Learn how to use Document Store in a pipeline or how to create your own." +--- + +# Document Store + +You can think of the Document Store as a database that stores your data and provides them to the Retriever at query time. Learn how to use Document Store in a pipeline or how to create your own. + +Document Store is an object that stores your documents. In Haystack, a Document Store is different from a component, as it doesn't have the `run()` method. You can think of it as an interface to your database – you put the information there, or you can look through it. This means that a Document Store is not a piece of a pipeline but rather a tool that the components of a pipeline have access to and can interact with. + +:::tip Work with Retrievers + +The most common way to use a Document Store in Haystack is to fetch documents using a Retriever. A Document Store will often have a corresponding Retriever to get the most out of specific technologies. See more information in our [Retriever](../pipeline-components/retrievers.mdx) documentation. +::: + +:::note How to choose a Document Store? + +To learn about different types of Document Stores and their strengths and disadvantages, head to the [Choosing a Document Store](document-store/choosing-a-document-store.mdx) page. +::: + +### DocumentStore Protocol + +Document Stores in Haystack are designed to use the following methods as part of their protocol: + +- `count_documents` returns the number of documents stored in the given store as an integer. +- `filter_documents` returns a list of documents that match the provided filters. +- `write_documents` writes or overwrites documents into the given store and returns the number of documents that were written as an integer. +- `delete_documents` deletes all documents with given `document_ids` from the Document Store. + +### Initialization + +To use a Document Store in a pipeline, you must initialize it first. + +See the installation and initialization details for each Document Store in the "Document Stores" section in the navigation panel on your left. + +### Work with Documents + +Convert your data into `Document` objects before writing them into a Document Store along with its metadata and document ID. + +The ID field is mandatory, so if you don’t choose a specific ID yourself, Haystack will do its best to come up with a unique ID based on the document’s information and assign it automatically. However, since Haystack uses the document’s contents to create an ID, two identical documents might have identical IDs. Keep it in mind as you update your documents, as the ID will not be updated automatically. + +```python +document_store = ChromaDocumentStore() +documents = [ + Document( + 'meta'={'name': DOCUMENT_NAME, ...} + 'id'="document_unique_id", + 'content'="this is content" + ), + ... +] +document_store.write_documents(documents) +``` + +To write documents into the `InMemoryDocumentStore`, simply call the `.write_documents()` function: + +```python +document_store.write_documents([ + Document(content="My name is Jean and I live in Paris."), + Document(content="My name is Mark and I live in Berlin."), + Document(content="My name is Giorgio and I live in Rome.") +]) +``` + +:::note `DocumentWriter` + +See `DocumentWriter` component [docs](../pipeline-components/writers/documentwriter.mdx) to write your documents into a Document Store in a pipeline. +::: + +### DuplicatePolicy + +The `DuplicatePolicy` is a class that defines the different options for handling documents with the same ID in a `DocumentStore`. It has three possible values: + +- **OVERWRITE**: Indicates that if a document with the same ID already exists in the `DocumentStore`, it should be overwritten with the new document. +- **SKIP**: If a document with the same ID already exists, the new document will be skipped and not added to the `DocumentStore`. +- **FAIL**: Raises an error if a document with the same ID already exists in the `DocumentStore`. It prevents duplicate documents from being added. + +Here is an example of how you could apply the policy to skip the existing document: + +```python +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.components.writers import DocumentWriter +from haystack.document_stores.types import DuplicatePolicy + +document_store = InMemoryDocumentStore() +document_writer = DocumentWriter(document_store = document_store, policy=DuplicatePolicy.SKIP) +``` + +### Custom Document Store + +All custom document stores must implement the [protocol](https://github.com/deepset-ai/haystack/blob/13804293b1bb79743e5a30e980b76a0561dcfaf8/haystack/document_stores/types/protocol.py) with four mandatory methods: `count_documents`,`filter_documents`, `write_documents`, and `delete_documents`. + +The `init` function should indicate all the specifics for the chosen database or vector store. + +We also recommend having a custom corresponding Retriever to get the most out of a specific Document Store. + +See [Creating Custom Document Stores](document-store/creating-custom-document-stores.mdx) page for more details. diff --git a/docs-website/versioned_docs/version-2.20-unstable/concepts/document-store/choosing-a-document-store.mdx b/docs-website/versioned_docs/version-2.20-unstable/concepts/document-store/choosing-a-document-store.mdx new file mode 100644 index 0000000000..50c82cdb1d --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/concepts/document-store/choosing-a-document-store.mdx @@ -0,0 +1,110 @@ +--- +title: "Choosing a Document Store" +id: choosing-a-document-store +slug: "/choosing-a-document-store" +description: "This article goes through different types of Document Stores and explains their advantages and disadvantages." +--- + +import ClickableImage from "@site/src/components/ClickableImage"; + +# Choosing a Document Store + +This article goes through different types of Document Stores and explains their advantages and disadvantages. + +### Introduction + +Whether you are developing a chatbot, a RAG system, or an image captioner, at some point, it’ll be likely for your AI application to compare the input it gets with the information it already knows. Most of the time, this comparison is performed through vector similarity search. + +If you’re unfamiliar with vectors, think about them as a way to represent text, images, or audio/video in a numerical form called vector embeddings. Vector databases are specifically designed to store such vectors efficiently, providing all the functionalities an AI application needs to implement data retrieval and similarity search. + +Document Stores are special objects in Haystack that abstract all the different vector databases into a common interface that can be easily integrated into a pipeline, most commonly through a Retriever component. Normally, you will find specialized Document Store and Retriever objects for each vector database Haystack supports. + +### Types of vector databases + +But why are vector databases so different, and which one should you use in your Haystack pipeline? + +We can group vector databases into five categories, from more specialized to general purpose: + +- Vector libraries +- Pure vector databases +- Vector-capable SQL databases +- Vector-capable NoSQL databases +- Full-text search databases + +We are working on supporting all these types in Haystack. + +In the meantime, here’s the most recent overview of available integrations: +
+
+| | |
+| --- | --- |
+| Type | Best for |
+| Vector libraries | Managing hardware resources effectively. |
+| Pure vector DBs | Managing lots of high-dimensional data. |
+| Vector-capable SQL DBs | Lower maintenance costs with focus on structured data and less on vectors. |
+| Vector-capable NoSQL DBs | Combining vectors with structured data without the limitations of the traditional relational model. |
+| Full-text search DBs | Superior full-text search, reliable for production. |
+| In-memory | Fast, minimal prototypes on small datasets. |
+
+
+
+#### Vector libraries
+
+Vector libraries are often included in the “vector database” category improperly, as they are limited to handling only vectors, are designed to work in-memory, and normally don’t have a clean way to store data on disk. Still, they are the way to go every time performance and speed are the top requirements for your AI application, as these libraries can use hardware resources very effectively.
+
+:::warning In progress
+
+We are currently developing the support for vector libraries in Haystack.
+:::
+
+#### Pure vector databases
+
+Pure vector databases, also known as just “vector databases”, offer efficient similarity search capabilities through advanced indexing techniques. Most of them support metadata, and despite a recent trend to add more text-search features on top of it, you should consider pure vector databases closer to vector libraries than a regular database. Pick a pure vector database when your application needs to manage huge amounts of high-dimensional data effectively: they are designed to be highly scalable and highly available. Most are open source, but companies usually provide them “as a service” through paid subscriptions.
+
+- [Chroma](../../document-stores/chromadocumentstore.mdx)
+- [Pinecone](../../document-stores/pinecone-document-store.mdx)
+- [Qdrant](../../document-stores/qdrant-document-store.mdx)
+- [Weaviate](../../document-stores/weaviatedocumentstore.mdx)
+- [Marqo](https://haystack.deepset.ai/integrations/marqo-document-store) (external integration)
+- [Milvus](https://haystack.deepset.ai/integrations/milvus-document-store) (external integration)
+
+#### Vector-capable SQL databases
+
+This category is relatively small but growing fast and includes well-known relational databases where vector capabilities were added through plugins or extensions. They are not as performant as the previous categories, but the main advantage of these databases is the opportunity to easily combine vectors with structured data, having a one-stop data shop for your application. You should pick a vector-capable SQL database when the performance trade-off is paid off by the lower cost of maintaining a single database instance for your application or when the structured data plays a more fundamental role in your business logic, with vectors being more of a nice-to-have.
+
+- [Pgvector](../../document-stores/pgvectordocumentstore.mdx)
+
+#### Vector-capable NoSQL databases
+
+Historically, the killer features of NoSQL databases were the ability to scale horizontally and the adoption of a flexible data model to overcome certain limitations of the traditional relational model. This stays true for databases in this category, where the vector capabilities are added on top of the existing features. Similarly to the previous category, vector support might not be as good as pure vector databases, but once again, there is a tradeoff that might be convenient to bear depending on the use case. For example, if a certain NoSQL database is already part of the stack of your application and a lower performance is not a show-stopper, you might give it a shot.
+
+- [Astra](../../document-stores/astradocumentstore.mdx)
+- [MongoDB](../../document-stores/mongodbatlasdocumentstore.mdx)
+- [Neo4j](https://haystack.deepset.ai/integrations/neo4j-document-store) (external)
+
+#### Full-text search databases
+
+The main advantage of full-text search databases is they are already designed to work with text, so you can expect a high level of support for text data along with good performance and the opportunity to scale both horizontally and vertically. Initially, vector capabilities were subpar and provided through plugins or extensions, but this is rapidly changing. You can see how the market leaders in this category have recently added first-class support for vectors. Pick a full-text search database if text data plays a central role in your business logic so that you can easily and effectively implement techniques like hybrid search with a good level of support for similarity search and state-of-the-art support for full-text search.
+
+- [Elasticsearch](../../document-stores/elasticsearch-document-store.mdx)
+- [OpenSearch](../../document-stores/opensearch-document-store.mdx)
+
+#### The in-memory Document Store
+
+Haystack ships with an ephemeral document store that relies on pure Python data structures stored in memory, so it doesn’t fall into any of the vector database categories above. This special Document Store is ideal for creating quick prototypes with small datasets. It doesn’t require any special setup, and it can be used right away without installing additional dependencies.
+
+- [InMemory](../../document-stores/inmemorydocumentstore.mdx)
+
+### Final considerations
+
+It can be very challenging to pick one vector database over another by only looking at pure performance, as even the slightest difference in the benchmark can produce a different leaderboard (for example, some benchmarks test the cloud services while others work on a reference machine). Thinking about including features like filtering or not can bring in a whole new set of complexities that make the comparison even harder.
+
+What’s important for you to know is that the Document Store interface doesn’t add much to the costs, and the relative performance of one vector database over another should stay the same when used within Haystack pipelines.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/concepts/document-store/creating-custom-document-stores.mdx b/docs-website/versioned_docs/version-2.20-unstable/concepts/document-store/creating-custom-document-stores.mdx
new file mode 100644
index 0000000000..d670a10036
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/concepts/document-store/creating-custom-document-stores.mdx
@@ -0,0 +1,153 @@
+---
+title: "Creating Custom Document Stores"
+id: creating-custom-document-stores
+slug: "/creating-custom-document-stores"
+description: "Create your own Document Stores to manage your documents."
+---
+
+# Creating Custom Document Stores
+
+Create your own Document Stores to manage your documents.
+
+Custom Document Stores are resources that you can build and leverage in situations where a ready-made solution is not available in Haystack. For example:
+
+- You’re working with a vector store that’s not yet supported in Haystack.
+- You need a very specific retrieval strategy to search for your documents.
+- You want to customize the way Haystack reads and writes documents.
+
+Similar to [custom components](../components/custom-components.mdx), you can use a custom Document Store in a Haystack pipeline as long as you can import its code into your Python program. The best practice is distributing a custom Document Store as a standalone integration package.
+
+## Recommendations
+
+Before you start, there are a few recommendations we provide to ensure a custom Document Store behaves consistently with the rest of the Haystack ecosystem. At the end of the day, a Document Store is just Python code written in a way that Haystack can understand, but the way you name it, organize it, and distribute it can make a difference. None of these recommendations are mandatory, but we encourage you to follow as many as you can.
+
+### Naming Convention
+
+We recommend naming your Document Store following the format `+
+
+| | |
+| --- | --- |
+| Template identifier | `CHAT_WITH_WEBSITE` |
+| Template params | \- |
+| Inputs (**\*** means mandatory) | `'converter': {'meta': {}} `
`'fetcher': {'urls': ["https://example.com"]}`**\***
`'llm': {'generation_kwargs': {}}`
`'prompt': {'query': 'the question to ask'}` | + +
+
+Example code:
+
+```python
+from haystack import Pipeline, PredefinedPipeline
+
+pipeline = Pipeline.from_template(PredefinedPipeline.CHAT_WITH_WEBSITE)
+pipeline.run({"fetcher": {"urls": ["https://haystack.deepset.ai:"]}, "prompt": {"query": "what is Haystack?"}})
+
+```
+
+### Generative QA
+
+Generates a simple pipeline to ask a generic query using an `OpenAIGenerator`.
+
+`'fetcher': {'urls': ["https://example.com"]}`**\***
`'llm': {'generation_kwargs': {}}`
`'prompt': {'query': 'the question to ask'}` | + +
+
+| | |
+| --- | --- |
+| Template identifier | `CHAT_WITH_WEBSITE` |
+| Template params | \- |
+| Inputs (**\*** means mandatory) | `'converter': {'meta': {}} `
`'fetcher': {'urls': ["https://example.com"]}`**\***
`'llm': {'generation_kwargs': {}}`
`'prompt': {'query': 'the question to ask'}` | + +
+
+Example code:
+
+```python
+from haystack import Pipeline, PredefinedPipeline
+
+pipeline = Pipeline.from_template(PredefinedPipeline.GENERATIVE_QA)
+pipeline.run({"prompt_builder":{"question":"Where is Rome?"}})
+```
+
+### Indexing
+
+Generates a pipeline that imports documents from one or more text files, creates the embeddings for each of them, and finally stores them in an [`InMemoryDocumentStore`](../../document-stores/inmemorydocumentstore.mdx).
+
+`'fetcher': {'urls': ["https://example.com"]}`**\***
`'llm': {'generation_kwargs': {}}`
`'prompt': {'query': 'the question to ask'}` | + +
+
+| | |
+| --- | --- |
+| Template identifier | `CHAT_WITH_WEBSITE` |
+| Template params | \- |
+| Inputs (**\*** means mandatory) | `'converter': {'meta': {}} `
`'fetcher': {'urls': ["https://example.com"]}`**\***
`'llm': {'generation_kwargs': {}}`
`'prompt': {'query': 'the question to ask'}` | + +
+
+Example code:
+
+```python
+from haystack import Pipeline, PredefinedPipeline
+
+pipeline = Pipeline.from_template(PredefinedPipeline.INDEXING)
+result = pipeline.run({"converter": {"sources": ["some_file.txt"]}})
+```
+
+### RAG
+
+Generates a RAG pipeline using data that was previously indexed (you can use the Indexing template).
+
+`'fetcher': {'urls': ["https://example.com"]}`**\***
`'llm': {'generation_kwargs': {}}`
`'prompt': {'query': 'the question to ask'}` | + +
+
+| | |
+| --- | --- |
+| Template identifier | `CHAT_WITH_WEBSITE` |
+| Template params | \- |
+| Inputs (**\*** means mandatory) | `'converter': {'meta': {}} `
`'fetcher': {'urls': ["https://example.com"]}`**\***
`'llm': {'generation_kwargs': {}}`
`'prompt': {'query': 'the question to ask'}` | + +
+
+Example code:
+
+```python
+from haystack import Pipeline, PredefinedPipeline
+
+pipeline = Pipeline.from_template(PredefinedPipeline.RAG)
+pipeline.run({"text_embedder": {"text": "A question about your documents"}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/serialization.mdx b/docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/serialization.mdx
new file mode 100644
index 0000000000..4bcf9e06f3
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/serialization.mdx
@@ -0,0 +1,184 @@
+---
+title: "Serializing Pipelines"
+id: serialization
+slug: "/serialization"
+description: "Save your pipelines into a custom format and explore the serialization options."
+---
+
+# Serializing Pipelines
+
+Save your pipelines into a custom format and explore the serialization options.
+
+Serialization means converting a pipeline to a format that you can save on your disk and load later.
+
+:::info Serialization formats
+
+Haystack 2.0 only supports YAML format at this time. We will be rolling out more formats gradually.
+:::
+
+## Converting a Pipeline to YAML
+
+Use the `dumps()` method to convert a Pipeline object to YAML:
+
+```python
+from haystack import Pipeline
+
+pipe = Pipeline()
+print(pipe.dumps())
+
+## Prints:
+##
+## components: {}
+## connections: []
+## max_loops_allowed: 100
+## metadata: {}
+```
+
+You can also use `dump()` method to save the YAML representation of a pipeline in a file:
+
+```python
+with open("/content/test.yml", "w") as file:
+ pipe.dump(file)
+```
+
+## Converting a Pipeline Back to Python
+
+You can convert a YAML pipeline back into Python. Use the `loads()` method to convert a string representation of a pipeline (`str`, `bytes` or `bytearray`) or the `load()` method to convert a pipeline represented in a file-like object into a corresponding Python object.
+
+Both loading methods support callbacks that let you modify components during the deserialization process.
+
+Here is an example script:
+
+```python
+from haystack import Pipeline
+from haystack.core.serialization import DeserializationCallbacks
+from typing import Type, Dict, Any
+
+## This is the YAML you want to convert to Python:
+pipeline_yaml = """
+components:
+ cleaner:
+ init_parameters:
+ remove_empty_lines: true
+ remove_extra_whitespaces: true
+ remove_regex: null
+ remove_repeated_substrings: false
+ remove_substrings: null
+ type: haystack.components.preprocessors.document_cleaner.DocumentCleaner
+ converter:
+ init_parameters:
+ encoding: utf-8
+ type: haystack.components.converters.txt.TextFileToDocument
+connections:
+- receiver: cleaner.documents
+ sender: converter.documents
+max_loops_allowed: 100
+metadata: {}
+"""
+
+def component_pre_init_callback(component_name: str, component_cls: Type, init_params: Dict[str, Any]):
+ # This function gets called every time a component is deserialized.
+ if component_name == "cleaner":
+ assert "DocumentCleaner" in component_cls.__name__
+ # Modify the init parameters. The modified parameters are passed to
+ # the init method of the component during deserialization.
+ init_params["remove_empty_lines"] = False
+ print("Modified 'remove_empty_lines' to False in 'cleaner' component")
+ else:
+ print(f"Not modifying component {component_name} of class {component_cls}")
+
+pipe = Pipeline.loads(pipeline_yaml, callbacks=DeserializationCallbacks(component_pre_init_callback))
+```
+
+## Performing Custom Serialization
+
+Pipelines and components in Haystack can serialize simple components, including custom ones, out of the box. Code like this just works:
+
+```python
+from haystack import component
+
+@component
+class RepeatWordComponent:
+ def __init__(self, times: int):
+ self.times = times
+
+ @component.output_types(result=str)
+ def run(self, word: str):
+ return word * self.times
+```
+
+On the other hand, this code doesn't work if the final format is JSON, as the `set` type is not JSON-serializable:
+
+```python
+from haystack import component
+
+@component
+class SetIntersector:
+ def __init__(self, intersect_with: set):
+ self.intersect_with = intersect_with
+
+ @component.output_types(result=set)
+ def run(self, data: set):
+ return data.intersection(self.intersect_with)
+```
+
+In such cases, you can provide your own implementation `from_dict` and `to_dict` to components:
+
+```python
+from haystack import component, default_from_dict, default_to_dict
+
+class SetIntersector:
+ def __init__(self, intersect_with: set):
+ self.intersect_with = intersect_with
+
+ @component.output_types(result=set)
+ def run(self, data: set):
+ return data.intersect(self.intersect_with)
+
+ def to_dict(self):
+ return default_to_dict(self, intersect_with=list(self.intersect_with))
+
+ @classmethod
+ def from_dict(cls, data):
+ # convert the set into a list for the dict representation,
+ # so it can be converted to JSON
+ data["intersect_with"] = set(data["intersect_with"])
+ return default_from_dict(cls, data)
+```
+
+## Saving a Pipeline to a Custom Format
+
+Once a pipeline is available in its dictionary format, the last step of serialization is to convert that dictionary into a format you can store or send over the wire. Haystack supports YAML out of the box, but if you need a different format, you can write a custom Marshaller.
+
+A `Marshaller` is a Python class responsible for converting text to a dictionary and a dictionary to text according to a certain format. Marshallers must respect the `Marshaller` [protocol](https://github.com/deepset-ai/haystack/blob/main/haystack/marshal/protocol.py), providing the methods `marshal` and `unmarshal`.
+
+This is the code for a custom TOML marshaller that relies on the `rtoml` library:
+
+```python
+## This code requires a `pip install rtoml`
+from typing import Dict, Any, Union
+import rtoml
+
+class TomlMarshaller:
+ def marshal(self, dict_: Dict[str, Any]) -> str:
+ return rtoml.dumps(dict_)
+
+ def unmarshal(self, data_: Union[str, bytes]) -> Dict[str, Any]:
+ return dict(rtoml.loads(data_))
+```
+
+You can then pass a Marshaller instance to the methods `dump`, `dumps`, `load`, and `loads`:
+
+```python
+from haystack import Pipeline
+from my_custom_marshallers import TomlMarshaller
+
+pipe = Pipeline()
+pipe.dumps(TomlMarshaller())
+## prints:
+## 'max_loops_allowed = 100\nconnections = []\n\n[metadata]\n\n[components]\n'
+```
+
+## Additional References
+
+:notebook: Tutorial: [Serializing LLM Pipelines](https://haystack.deepset.ai/tutorials/29_serializing_pipelines)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/visualizing-pipelines.mdx b/docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/visualizing-pipelines.mdx
new file mode 100644
index 0000000000..39761cd750
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/visualizing-pipelines.mdx
@@ -0,0 +1,89 @@
+---
+title: "Visualizing Pipelines"
+id: visualizing-pipelines
+slug: "/visualizing-pipelines"
+description: "You can visualize your pipelines as graphs to better understand how the components are connected."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# Visualizing Pipelines
+
+You can visualize your pipelines as graphs to better understand how the components are connected.
+
+Haystack pipelines have `draw()` and `show()` methods that enable you to visualize the pipeline as a graph using Mermaid graphs.
+
+:::note Data Privacy Notice
+
+Exercise caution with sensitive data when using pipeline visualization.
+
+This feature is based on Mermaid graphs web service that doesn't have clear terms of data retention or privacy policy.
+:::
+
+## Prerequisites
+
+To use Mermaid graphs, you must have an internet connection to reach the Mermaid graph renderer at https://mermaid.ink.
+
+## Displaying a Graph
+
+Use the pipeline's `show()` method to display the diagram in Jupyter notebooks.
+
+```python
+my_pipeline.show()
+```
+
+## Saving a Graph
+
+Use the pipeline's `draw()` method passing the path where you want to save the diagram and the diagram format. Possible formats are: `mermaid-text` and `mermaid-image` (default).
+
+```python
+my_pipeline.draw(path=local_path)
+```
+
+## Visualizing SuperComponents
+
+To show the internal structure of [SuperComponents](../components/supercomponents.mdx) in your digram instead of a black box component, set the `super_component_expansion` parameter to `True`:
+
+```python
+my_pipeline.show(super_component_expansion=True)
+
+## or
+
+my_pipeline.draw(path=local_path,
+ super_component_expansion=True)
+```
+
+## Visualizing Locally
+
+If you don't have an internet connection or don't want to send your pipeline data to the remote https://mermaid.ink, you can install a local mermaid.ink server and use it to render your pipeline.
+
+Let's run a local mermaid.ink server using their official Docker images from https://github.com/jihchi/mermaid.ink/pkgs/container/mermaid.ink.
+
+In this case, let's install one for a system running a MacOS M3 chip and expose it on port 3000:
+
+```dockerfile
+docker run --platform linux/amd64 --publish 3000:3000 --cap-add=SYS_ADMIN ghcr.io/jihchi/mermaid.ink
+```
+
+Check that the local mermaid.ink server is running by going to http://localhost:3000/.
+
+You should see a local server running, and now you can simply render the image using your local mermaid.ink server by specifying the URL when calling the`show()`or `draw()` method:
+
+```python
+my_pipeline.show(server_url="http://localhost:3000")
+## or
+my_pipeline.draw("my_pipeline.png", server_url="http://localhost:3000")
+```
+
+## Example
+
+This is an example of what a pipeline graph may look like:
+`'fetcher': {'urls': ["https://example.com"]}`**\***
`'llm': {'generation_kwargs': {}}`
`'prompt': {'query': 'the question to ask'}` | + +
+ +## Importing a Pipeline to deepset Studio + +You can import your Haystack pipeline into deepset Studio and continue visually building your pipeline + +To do that, follow the steps described in our deepset AI Platform [documentation](https://docs.cloud.deepset.ai/docs/import-a-pipeline#import-your-pipeline). diff --git a/docs-website/versioned_docs/version-2.20-unstable/concepts/secret-management.mdx b/docs-website/versioned_docs/version-2.20-unstable/concepts/secret-management.mdx new file mode 100644 index 0000000000..3acab79ca2 --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/concepts/secret-management.mdx @@ -0,0 +1,190 @@ +--- +title: "Secret Management" +id: secret-management +slug: "/secret-management" +description: "This page emphasizes secret management in Haystack components and introduces the `Secret` type for structured secret handling. It explains the drawbacks of hard-coding secrets in code and suggests using environment variables instead." +--- + +# Secret Management + +This page emphasizes secret management in Haystack components and introduces the `Secret` type for structured secret handling. It explains the drawbacks of hard-coding secrets in code and suggests using environment variables instead. + +Many Haystack components interact with third-party frameworks and service providers such as Azure, Google Vertex AI, and OpenAI. Their libraries often require the user to authenticate themselves to ensure they receive access to the underlying product. The authentication process usually works with a secret value that acts as an opaque identifier to the third-party backend. + +This page describes the two main types of secrets: token-based and environment variable-based, and how to handle them when using Haystack. + +You can find additional details for the `Secret` class in our [API reference](/reference/utils-api). + +
+
+
+
+### Import
+
+To use Haystack secrets within the code, first import with:
+
+```python
+from haystack.utils import Secret
+```
+
+### Token-Based Secrets
+
+You can paste tokens directly as a string using the `from_token` method:
+
+```python
+llm = OpenAIGenerator(api_key=Secret.from_token("sk-randomAPIkeyasdsa32ekasd32e"))
+```
+
+Note that this type of code cannot be serialized, meaning you can't convert the above component to a dictionary or save a pipeline containing it to a YAML file. This is a security feature to prevent accidental exposure of sensitive data.
+
+### Environment Variable-Based Secrets
+
+Environment variable-based secrets are more flexible. They allow you to specify one or more environment variables that may contain your secret.
+
+Existing Haystack components that require an API Key (like OpenAIGenerator) have a default value for `Secret.from_env_var` (in this case, `OPENAI_API_KEY`). This means that the `OpenAIGenerator` will look for the value of the environment variable `OPENAI_API_KEY` (if it exists) and use it for authentication. And when pipelines are serialized to YAML, only the name of the environment variable is save to the YAML file. In doing so, this method ensures that there are no security leaks and is therefore strongly recommended.
+
+```bash
+## First, export an environment variable name `OPENAI_API_KEY` with its value
+export OPENAI_API_KEY=sk-randomAPIkeyasdsa32ekasd32e
+
+## or alternatively, using Python
+## import os
+## os.environ[”OPENAI_API_KEY”]=sk-randomAPIkeyasdsa32ekasd32e
+```
+
+```python
+llm_generator = OpenAIGenerator() # Uses the default value from the env var for the component
+```
+
+Alternatively, in components where a Secret is expected, you can customize the name of the environment variable from which the API Key is to be read.
+
+```python
+## Export an environment variable with custom name and its value
+llm_generator = OpenAIGenerator(api_key=Secret.from_env_var("YOUR_ENV_VAR"))
+```
+
+When `OpenAIGenerator` is serialized within a pipeline, this is what the YAML code will look like, using the custom variable name:
+
+```yaml
+components:
+ llm:
+ init_parameters:
+ api_base_url: null
+ api_key:
+ env_vars:
+ - YOUR_ENV_VAR
+ strict: true
+ type: env_var
+ generation_kwargs: {}
+ model: gpt-4o-mini
+ organization: null
+ streaming_callback: null
+ system_prompt: null
+ type: haystack.components.generators.openai.OpenAIGenerator
+ ...
+```
+
+### Serialization
+
+While token-based secrets cannot be serialized, environment variable-based secrets can be converted to and from dictionaries:
+
+```python
+## Convert to dictionary
+env_secret_dict = env_secret.to_dict()
+
+## Create from dictionary
+new_env_secret = Secret.from_dict(env_secret_dict)
+```
+
+### Resolving Secrets
+
+Both types of secrets can be resolved to their actual values using the `resolve_value` method. This method returns the token or the value of the environment variable.
+
+```python
+
+## Resolve the token-based secret
+token_value = api_key_secret.resolve_value()
+
+## Resolve the environment variable-based secret
+env_value = env_secret.resolve_value()
+```
+
+### Custom Component Example
+
+Here is a complete example that shows how to create a component that uses the `Secret` class in Haystack, highlighting the differences between token-based and environment variable-based authentication, and showing that token-based secrets cannot be serialized:
+
+```python
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+@component
+class MyComponent:
+ def __init__(self, api_key: Optional[Secret] = None, **kwargs):
+ self.api_key = api_key
+ self.backend = None
+
+ def warm_up(self):
+ # Call resolve_value to yield a single result. The semantics of the result is policy-dependent.
+ # Currently, all supported policies will return a single string token.
+ self.backend = SomeBackend(api_key=self.api_key.resolve_value() if self.api_key else None, ...)
+
+ def to_dict(self):
+ # Serialize the policy like any other (custom) data. If the policy is token-based, it will
+ # raise an error.
+ return default_to_dict(self, api_key=self.api_key.to_dict() if self.api_key else None, ...)
+
+ @classmethod
+ def from_dict(cls, data):
+ # Deserialize the policy data before passing it to the generic from_dict function.
+ api_key_data = data["init_parameters"]["api_key"]
+ api_key = Secret.from_dict(api_key_data) if api_key_data is not None else None
+ data["init_parameters"]["api_key"] = api_key
+ # Alternatively, use the helper function.
+ # deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+ return default_from_dict(cls, data)
+
+## No authentication.
+component = MyComponent(api_key=None)
+
+## Token based authentication
+component = MyComponent(api_key=Secret.from_token("sk-randomAPIkeyasdsa32ekasd32e"))
+component.to_dict() # Error! Can't serialize authentication tokens
+
+## Environment variable based authentication
+component = MyComponent(api_key=Secret.from_env_var("OPENAI_API_KEY"))
+component.to_dict() # This is fine
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/development/deployment.mdx b/docs-website/versioned_docs/version-2.20-unstable/development/deployment.mdx
new file mode 100644
index 0000000000..fdeebeb2ae
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/development/deployment.mdx
@@ -0,0 +1,35 @@
+---
+title: "Deployment"
+id: deployment
+slug: "/deployment"
+description: "Deploy your Haystack pipelines through various services such as Docker, Kubernetes, Ray, or a variety of Serverless options."
+---
+
+# Deployment
+
+Deploy your Haystack pipelines through various services such as Docker, Kubernetes, Ray, or a variety of Serverless options.
+
+As a framework, Haystack is typically integrated into a variety of applications and environments, and there is no single, specific deployment strategy to follow. However, it is very common to make Haystack pipelines accessible through a service that can be easily called from other software systems.
+
+These guides focus on tools and techniques that can be used to run Haystack pipelines in common scenarios. While these suggestions should not be considered the only way to do so, they should provide inspiration and the ability to customize them according to your needs.
+
+### Guides
+
+Here are the currently available guides on Haystack pipeline deployment:
+
+- [Deploying with Docker](deployment/docker.mdx)
+- [Deploying with Kubernetes](deployment/kubernetes.mdx)
+- [Deploying with OpenShift](deployment/openshift.mdx)
+
+### Hayhooks
+
+Haystack can be easily integrated into any HTTP application, but if you don’t have one, you can use Hayhooks, a ready-made application that serves Haystack pipelines as REST endpoints. We’ll be using Hayhooks throughout this guide to streamline the code examples. Refer to the Hayhooks [documentation](hayhooks.mdx) to get details about how to run the server and deploy your pipelines.
+
+:::note Looking to scale with confidence?
+
+If your team needs **enterprise-grade support, best practices, and deployment guidance** to run Haystack in production, check out **Haystack Enterprise**.
+
+📜 [Learn more about Haystack Enterprise](https://haystack.deepset.ai/blog/announcing-haystack-enterprise)
+
+👉 [Get in touch with our team](https://www.deepset.ai/products-and-services/haystack-enterprise)
+:::
diff --git a/docs-website/versioned_docs/version-2.20-unstable/development/deployment/docker.mdx b/docs-website/versioned_docs/version-2.20-unstable/development/deployment/docker.mdx
new file mode 100644
index 0000000000..2056bbae7b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/development/deployment/docker.mdx
@@ -0,0 +1,117 @@
+---
+title: "Docker"
+id: docker
+slug: "/docker"
+description: "Learn how to deploy your Haystack pipelines through Docker starting from the basic Docker container to a complex application using Hayhooks."
+---
+
+# Docker
+
+Learn how to deploy your Haystack pipelines through Docker starting from the basic Docker container to a complex application using Hayhooks.
+
+## Running Haystack in Docker
+
+The most basic form of Haystack deployment happens through Docker containers. Becoming familiar with running and customizing Haystack Docker images is useful as they form the basis for more advanced deployment.
+
+Haystack releases are officially distributed through the [`deepset/haystack`](https://hub.docker.com/r/deepset/haystack) Docker image. Haystack images come in different flavors depending on the specific components they ship and the Haystack version.
+
+:::info
+At the moment, the only flavor available for Haystack is `base`, which ships exactly what you would get by installing Haystack locally with `pip install haystack-ai`.
+:::
+
+You can pull a specific Haystack flavor using Docker tags: for example, to pull the image containing Haystack `2.12.1`, you can run the command:
+
+```shell
+docker pull deepset/haystack:base-v2.12.1
+```
+
+Although the `base` flavor is meant to be customized, it can also be used to quickly run Haystack scripts locally without the need to set up a Python environment and its dependencies. For example, this is how you would print Haystack’s version running a Docker container:
+
+```shell
+docker run -it --rm deepset/haystack:base-v2.12.1 python -c"from haystack.version import __version__; print(__version__)"
+```
+
+## Customizing the Haystack Docker Image
+
+Chances are your application will be more complex than a simple script, and you’ll need to install additional dependencies inside the Docker image along with Haystack.
+
+For example, you might want to run a simple indexing pipeline using [Chroma](../../document-stores/chromadocumentstore.mdx) as your Document Store using a Docker container. The `base` image only contains a basic install of Haystack, but you need to install the Chroma integration (`chroma-haystack`) package additionally. The best approach would be to create a custom Docker image shipping the extra dependency.
+
+Assuming you have a `main.py` script in your current folder, the Dockerfile would look like this:
+
+```shell
+FROM deepset/haystack:base-v2.12.1
+
+RUN pip install chroma-haystack
+
+COPY ./main.py /usr/src/myapp/main.py
+
+ENTRYPOINT ["python", "/usr/src/myapp/main.py"]
+```
+
+Then you can create your custom Haystack image with:
+
+```shell
+docker build . -t my-haystack-image
+```
+
+## Complex Application with Docker Compose
+
+A Haystack application running in Docker can go pretty far: with an internet connection, the container can reach external services providing vector databases, inference endpoints, and observability features.
+
+Still, you might want to orchestrate additional services for your Haystack container locally, for example, to reduce costs or increase performance. When your application runtime depends on more than one Docker container, [Docker Compose](https://docs.docker.com/compose/) is a great tool to keep everything together.
+
+As an example, let’s say your application wraps two pipelines: one to _index_ documents into a Qdrant instance and the other to _query_ those documents at a later time. This setup would require two Docker containers: one to run the pipelines as REST APIs using [Hayhooks](../hayhooks.mdx) and a second to run a Qdrant instance.
+
+For building the Hayhooks image, we can easily customize the base image of one of the latest versions of Hayhooks, adding required dependencies required by [`QdrantDocumentStore`](../../document-stores/qdrant-document-store.mdx). The Dockerfile would look like this:
+
+```dockerfile Dockerfile
+FROM deepset/hayhooks:v0.6.0
+
+RUN pip install qdrant-haystack sentence-transformers
+
+CMD ["hayhooks", "run", "--host", "0.0.0.0"]
+
+```
+
+We wouldn’t need to customize Qdrant, so their official Docker image would work perfectly. The `docker-compose.yml` file would then look like this:
+
+```yaml
+services:
+ qdrant:
+ image: qdrant/qdrant:latest
+ restart: always
+ container_name: qdrant
+ ports:
+ - 6333:6333
+ - 6334:6334
+ expose:
+ - 6333
+ - 6334
+ - 6335
+ configs:
+ - source: qdrant_config
+ target: /qdrant/config/production.yaml
+ volumes:
+ - ./qdrant_data:/qdrant_data
+
+ hayhooks:
+ build: . # Build from local Dockerfile
+ container_name: hayhooks
+ ports:
+ - "1416:1416"
+ volumes:
+ - ./pipelines:/pipelines
+ environment:
+ - HAYHOOKS_PIPELINES_DIR=/pipelines
+ - LOG=DEBUG
+ depends_on:
+ - qdrant
+
+configs:
+ qdrant_config:
+ content: |
+ log_level: INFO
+```
+
+For a functional example of a Docker Compose deployment, check out the [“Qdrant Indexing”](https://github.com/deepset-ai/haystack-demos/tree/main/qdrant_indexing) demo from GitHub.
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.20-unstable/development/deployment/kubernetes.mdx b/docs-website/versioned_docs/version-2.20-unstable/development/deployment/kubernetes.mdx
new file mode 100644
index 0000000000..159201c427
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/development/deployment/kubernetes.mdx
@@ -0,0 +1,269 @@
+---
+title: "Kubernetes"
+id: kubernetes
+slug: "/kubernetes"
+description: "Learn how to deploy your Haystack pipelines through Kubernetes."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# Kubernetes
+
+Learn how to deploy your Haystack pipelines through Kubernetes.
+
+The best way to get Haystack running as a workload in a container orchestrator like Kubernetes is to create a service to expose one or more [Hayhooks](../hayhooks.mdx) instances.
+
+## Create a Haystack Kubernetes Service using Hayhooks
+
+As a first step, we recommend to create a local [KinD](https://github.com/kubernetes-sigs/kind) or [Minikube](https://github.com/kubernetes/minikube) Kubernetes cluster. You can manage your cluster from CLI, but tools like [k9s](https://k9scli.io/) or [Lens](https://k8slens.dev/) can ease the process.
+
+When done, start with a very simple Kubernetes Service running a single Hayhooks Pod:
+
+```yaml
+kind: Pod
+apiVersion: v1
+metadata:
+ name: hayhooks
+ labels:
+ app: haystack
+spec:
+ containers:
+ - image: deepset/hayhooks:v0.6.0
+ name: hayhooks
+ imagePullPolicy: IfNotPresent
+ resources:
+ limits:
+ memory: "512Mi"
+ cpu: "500m"
+ requests:
+ memory: "256Mi"
+ cpu: "250m"
+
+---
+
+kind: Service
+apiVersion: v1
+metadata:
+ name: haystack-service
+spec:
+ selector:
+ app: haystack
+ type: ClusterIP
+ ports:
+ # Default port used by the Hayhooks Docker image
+ - port: 1416
+
+```
+
+After applying the above to an existing Kubernetes cluster, a `hayhooks` Pod will show up as a Service called `haystack-service`.
+Example Use Case - Problem Statement
+ +### Problem Statement + +Let’s consider an example RAG pipeline that embeds a query, uses a Retriever component to locate documents relevant to the query, and then leverages an LLM to generate an answer based on the retrieved documents. + +The `OpenAIGenerator` component used in the pipeline below expects an API key to authenticate with OpenAI’s servers and perform the generation. Let’s assume that the component accepts a `str` value for it: + +```python +generator = OpenAIGenerator(model="gpt-4", api_key="sk-xxxxxxxxxxxxxxxxxx") +pipeline.add_component("generator", generator) +``` + +This works in a pinch, but this is bad practice - we shouldn’t hard-code such secrets in the codebase. An alternative would be to store the key in an environment variable externally, read from it in Python, and pass that to the component: + +```python +import os + +api_key = os.environ.get("OPENAI_API_KEY") +generator = OpenAIGenerator(model="gpt-4", api_key=api_key) +pipeline.add_component("generator", generator) +``` + +This is better – the pipeline works as intended, and we aren’t hard-coding any secrets in the code. + +Remember that pipelines are serializable. Since the API key is a secret, we should definitely avoid saving it to disk. Let’s modify the component’s `to_dict` method to exclude the key: + +```python +def to_dict(self) -> Dict[str, Any]: + # Do not pass the `api_key` init parameter. + return default_to_dict(self, model=self.model) +``` + +But what happens when the pipeline is loaded from disk? In the best-case scenario, the component’s backend will automatically try to read the key from a hard-coded environment variable, and that key is the same as the one that was passed to the component before it was serialized. But in a worse case, the backend doesn’t look up the key in a hard-coded environment variable and fails when it gets called inside a `pipeline.run()` invocation. + +
+
+| | |
+| --- | --- |
+| Variable | Description |
+| `HAYHOOKS_HOST` | Host address for the server |
+| `HAYHOOKS_PORT` | Port for the server |
+| `HAYHOOKS_PIPELINES_DIR` | Directory containing pipelines |
+| `HAYHOOKS_ROOT_PATH` | Root path of the server |
+| `HAYHOOKS_ADDITIONAL_PYTHON_PATH` | Additional Python paths to include |
+| `HAYHOOKS_DISABLE_SSL` | Disable SSL verification (boolean) |
+| `HAYHOOKS_SHOW_TRACEBACKS` | Show error tracebacks (boolean) |
+
+
+
+### CORS Settings
+
+
+
+| | |
+| --- | --- |
+| Variable | Description |
+| `HAYHOOKS_CORS_ALLOW_ORIGINS` | List of allowed origins (default: `[*]`) |
+| `HAYHOOKS_CORS_ALLOW_METHODS` | List of allowed HTTP methods (default: `[*]`) |
+| `HAYHOOKS_CORS_ALLOW_HEADERS` | List of allowed headers (default: `[*]`) |
+| `HAYHOOKS_CORS_ALLOW_CREDENTIALS` | Allow credentials (default: `false`) |
+| `HAYHOOKS_CORS_ALLOW_ORIGIN_REGEX` | Regex pattern for allowed origins (default: `null`) |
+| `HAYHOOKS_CORS_EXPOSE_HEADERS` | Headers to expose in response (default: `[]`) |
+| `HAYHOOKS_CORS_MAX_AGE` | Max age for preflight responses (default: `600`) |
+
+
+
+## Running Hayhooks
+
+To start the server:
+
+```shell
+hayhooks run
+```
+
+This will launch Hayhooks at `HAYHOOKS_HOST:HAYHOOKS_PORT`.
+
+## Deploying a Pipeline
+
+### Steps
+
+1. Prepare a pipeline definition (`.yml` file) and a `pipeline_wrapper.py` file.
+2. Deploy the pipeline:
+
+ ```shell
+ hayhooks pipeline deploy-files -n my_pipeline my_pipeline_dir
+ ```
+3. Access the pipeline at `{pipeline_name}/run` endpoint.
+
+### Pipeline Wrapper
+
+A `PipelineWrapper` class is required to wrap the pipeline:
+
+```python
+from pathlib import Path
+from haystack import Pipeline
+from hayhooks import BasePipelineWrapper
+
+class PipelineWrapper(BasePipelineWrapper):
+ def setup(self) -> None:
+ pipeline_yaml = (Path(__file__).parent / "pipeline.yml").read_text()
+ self.pipeline = Pipeline.loads(pipeline_yaml)
+
+ def run_api(self, input_text: str) -> str:
+ result = self.pipeline.run({"input": {"text": input_text}})
+ return result["output"]["text"]
+```
+
+## File Uploads
+
+Hayhooks enables handling file uploads in your pipeline wrapper’s `run_api` method by including `files: Optional[List[UploadFile]] = None` as an argument.
+
+```python
+def run_api(self, files: Optional[List[UploadFile]] = None) -> str:
+ if files and len(files) > 0:
+ filenames = [f.filename for f in files if f.filename is not None]
+ file_contents = [f.file.read() for f in files]
+ return f"Received files: {', '.join(filenames)}"
+ return "No files received"
+```
+
+Hayhooks automatically processes uploaded files and passes them to the `run_api` method when present. The HTTP request must be a `multipart/form-data` request.
+
+### Combining Files and Parameters
+
+Hayhooks also supports handling both files and additional parameters in the same request by including them as arguments in `run_api`:
+
+```python
+def run_api(self, files: Optional[List[UploadFile]] = None, additional_param: str = "default") -> str:
+ ...
+```
+
+## Running Pipelines from the CLI
+
+### With JSON-Compatible Parameters
+
+You can execute a pipeline through the command line using the `hayhooks pipeline run` command. Internally, this triggers the `run_api` method of the pipeline wrapper, passing parameters as a JSON payload.
+
+This method is ideal for testing deployed pipelines from the CLI without writing additional code.
+
+```shell
+hayhooks pipeline run
+
+| | |
+| --- | --- |
+| API reference | [Astra](/reference/integrations-astra) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/astra |
+
+
+
+DataStax Astra DB is a serverless vector database built on Apache Cassandra, and it supports vector-based search and auto-scaling. You can deploy it on AWS, GCP, or Azure and easily expand to one or more regions within those clouds for multi-region availability, low latency data access, data sovereignty, and to avoid cloud vendor lock-in. For more information, see the [DataStax documentation](https://docs.datastax.com/en/home/docs/index.html).
+
+### Initialization
+
+Once you have an AstraDB account and have created a database, install the `astra-haystack` integration:
+
+```shell
+pip install astra-haystack
+```
+
+From the configuration in AstraDB’s web UI, you need the database ID and a generated token.
+
+You will additionally need a collection name and a namespace. When you create the collection name, you also need to set the embedding dimensions and the similarity metric. The namespace organizes data in a database and is called a keyspace in Apache Cassandra.
+
+Then, in Haystack, initialize an `AstraDocumentStore` object that’s connected to the AstraDB instance, and write documents to it.
+
+We strongly encourage passing authentication data through environment variables: make sure to populate the environment variables `ASTRA_DB_API_ENDPOINT` and `ASTRA_DB_APPLICATION_TOKEN` before running the following example.
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.astra import AstraDocumentStore
+
+document_store = AstraDocumentStore()
+
+document_store.write_documents([
+ Document(content="This is first"),
+ Document(content="This is second")
+ ])
+print(document_store.count_documents())
+```
+
+### Supported Retrievers
+
+[AstraEmbeddingRetriever](../pipeline-components/retrievers/astraretriever.mdx): An embedding-based Retriever that fetches documents from the Document Store based on a query embedding provided to the Retriever.
+
+### Indexing Warnings
+
+When you create an Astra DB Document Store, you might see one of these warnings:
+
+> Astra DB collection `...` is detected as having indexing turned on for all fields (either created manually or by older versions of this plugin). This implies stricter limitations on the amount of text each string in a document can store. Consider indexing anew on a fresh collection to be able to store longer texts.
+
+Or:
+
+> Astra DB collection `...` is detected as having the following indexing policy: `{...}`. This does not match the requested indexing policy for this object: `{...}`. In particular, there may be stricter limitations on the amount of text each string in a document can store. Consider indexing anew on a fresh collection to be able to store longer texts.
+
+#### Why You See This Warning
+
+The collection already exists and is configured to [index all fields for search](https://docs.datastax.com/en/astra-db-serverless/api-reference/collections.html#the-indexing-option), possibly because you created it earlier or an older plugin did. When Haystack tries to create the collection, it applies an indexing policy optimized for your intended use. This policy lets you store longer texts and avoids indexing fields you won’t filter on, which also reduces write overhead.
+
+#### Common Causes
+
+1. You created the collection outside Haystack (for example, in the Astra UI or with AstraPy’s `Database.create_collection()`).
+2. You created the collection with an older version of the plugin.
+
+#### Impact
+
+This is only a warning. Your application keeps running unless you try to store very long text fields. If you do, Astra DB returns an indexing error.
+
+#### Solutions
+
+- **Recommended:** _Drop and recreate the collection_ if you can repopulate it. Then rerun your Haystack application so it creates the collection with the optimized indexing policy.
+- _Ignore the warning_ if you’re sure you won’t store very long text fields.
+
+## Additional References
+
+🧑🍳 Cookbook: [Using AstraDB as a data store in your Haystack pipelines](https://haystack.deepset.ai/cookbook/astradb_haystack_integration)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/document-stores/azureaisearchdocumentstore.mdx b/docs-website/versioned_docs/version-2.20-unstable/document-stores/azureaisearchdocumentstore.mdx
new file mode 100644
index 0000000000..dc289314ef
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/document-stores/azureaisearchdocumentstore.mdx
@@ -0,0 +1,66 @@
+---
+title: "AzureAISearchDocumentStore"
+id: azureaisearchdocumentstore
+slug: "/azureaisearchdocumentstore"
+description: "A Document Store for storing and retrieval from Azure AI Search Index."
+---
+
+# AzureAISearchDocumentStore
+
+A Document Store for storing and retrieval from Azure AI Search Index.
+
+
+
+| | |
+| --- | --- |
+| **API reference** | [Azure AI Search](/reference/integrations-azure_ai_search) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_ai_search |
+
+
+
+[Azure AI Search](https://learn.microsoft.com/en-us/azure/search/search-what-is-azure-search) is an enterprise-ready search and retrieval system to build RAG-based applications on Azure, with native LLM integrations.
+
+`AzureAISearchDocumentStore` supports semantic reranking and metadata/content filtering. The Document Store is useful for various tasks such as generating knowledge base insights (catalog or document search), information discovery (data exploration), RAG, and automation.
+
+### Initialization
+
+This integration requires you to have an active Azure subscription with a deployed [Azure AI Search](https://azure.microsoft.com/en-us/products/ai-services/ai-search) service.
+
+Once you have the subscription, install the `azure-ai-search-haystack` integration:
+
+```python
+pip install azure-ai-search-haystack
+```
+
+To use the `AzureAISearchDocumentStore`, you need to provide a search service endpoint as an `AZURE_AI_SEARCH_ENDPOINT` and an API key as `AZURE_AI_SEARCH_API_KEY` for authentication. If the API key is not provided, the `DefaultAzureCredential` will attempt to authenticate you through the browser.
+
+During initialization the Document Store will either retrieve the existing search index for the given `index_name` or create a new one if it doesn't already exist. Note that one of the limitations of `AzureAISearchDocumentStore` is that the fields of the Azure search index cannot be modified through the API after creation. Therefore, any additional fields beyond the default ones must be provided as `metadata_fields` during the Document Store's initialization. However, if needed, [Azure AI portal](https://azure.microsoft.com/) can be used to modify the fields without deleting the index.
+
+It is recommended to pass authentication data through `AZURE_AI_SEARCH_API_KEY` and `AZURE_AI_SEARCH_ENDPOINT` before running the following example.
+
+```python
+from haystack_integrations.document_stores.azure_ai_search import AzureAISearchDocumentStore
+from haystack import Document
+
+document_store = AzureAISearchDocumentStore(index_name="haystack-docs")
+document_store.write_documents([
+ Document(content="This is the first document."),
+ Document(content="This is the second document.")
+])
+print(document_store.count_documents())
+```
+
+:::info Latency Notice
+
+Due to Azure search index latency, the document count returned in the example might be zero if executed immediately. To ensure accurate results, be mindful of this latency when retrieving documents from the search index.
+:::
+
+You can enable semantic reranking in `AzureAISearchDocumentStore` by providing [SemanticSearch](https://learn.microsoft.com/en-us/python/api/azure-search-documents/azure.search.documents.indexes.models.semanticsearch?view=azure-python) configuration in `index_creation_kwargs` during initialization and calling it from one of the Retrievers. For more information, refer to the [Azure AI tutorial](https://learn.microsoft.com/en-us/azure/search/search-get-started-semantic) on this feature.
+
+### Supported Retrievers
+
+The Haystack Azure AI Search integration includes three Retriever components. Each Retriever leverages the Azure AI Search API and you can select the one that best suits your pipeline:
+
+- [`AzureAISearchEmbeddingRetriever`](../pipeline-components/retrievers/azureaisearchembeddingretriever.mdx): This Retriever accepts the embeddings of a single query as input and returns a list of matching documents. The query must be embedded beforehand, which can be done using an [Embedder](../pipeline-components/embedders.mdx) component.
+- [`AzureAISearchBM25Retriever`](../pipeline-components/retrievers/azureaisearchbm25retriever.mdx): A keyword-based Retriever that retrieves documents matching a query from the Azure AI Search index.
+- [`AzureAISearchHybridRetriever`](../pipeline-components/retrievers/azureaisearchhybridretriever.mdx): This Retriever combines embedding-based retrieval and keyword search to find matching documents in the search index to get more relevant results.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/document-stores/chromadocumentstore.mdx b/docs-website/versioned_docs/version-2.20-unstable/document-stores/chromadocumentstore.mdx
new file mode 100644
index 0000000000..46ec97faa0
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/document-stores/chromadocumentstore.mdx
@@ -0,0 +1,95 @@
+---
+title: "ChromaDocumentStore"
+id: chromadocumentstore
+slug: "/chromadocumentstore"
+---
+
+# ChromaDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Chroma](/reference/integrations-chroma) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chroma |
+
+
+
+[Chroma](https://docs.trychroma.com/) is an open source vector database capable of storing collections of documents along with their metadata, creating embeddings for documents and queries, and searching the collections filtering by document metadata or content. Additionally, Chroma supports multi-modal embedding functions.
+
+Chroma can be used in-memory, as an embedded database, or in a client-server fashion. When running in-memory, Chroma can still keep its contents on disk across different sessions. This allows users to quickly put together prototypes using the in-memory version and later move to production, where the client-server version is deployed.
+
+## Initialization
+
+First, install the Chroma integration, which will install Haystack and Chroma if they are not already present. The following command is all you need to start:
+
+```shell
+pip install chroma-haystack
+```
+
+To store data in Chroma, create a `ChromaDocumentStore` instance and write documents with:
+
+```python
+from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+from haystack import Document
+
+document_store = ChromaDocumentStore()
+document_store.write_documents([
+ Document(content="This is the first document."),
+ Document(content="This is the second document.")
+])
+print(document_store.count_documents())
+```
+
+In this case, since we didn’t pass any embeddings along with our documents, Chroma will create them for us using its [default embedding function](https://docs.trychroma.com/embeddings#default-all-minilm-l6-v2).
+
+### Connection Options
+
+1. **In-Memory Mode (Local)**: Chroma can be set up as a local Document Store for fast and lightweight usage. You can use this option during development or small-scale experiments. Set up a local in-memory instance of `ChromaDocumentStore` like this:
+
+ ```python
+ from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+
+ document_store = ChromaDocumentStore()
+ ```
+2. **Persistent Storage**: If you need to retain the documents between sessions, Chroma supports persistent storage by specifying a path to store data on disk:
+
+ ```python
+ from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+
+ document_store = ChromaDocumentStore(persist_path="your_directory_path")
+ ```
+3. **Remote Connection**: You can connect to a remote Chroma database through HTTP. This is suitable for distributed setups where multiple clients might interact with the same remote Chroma instance.
+
+ Note that this option is incompatible with in-memory or persistent storage modes.
+
+ First, start a Chroma server:
+
+ ```shell
+ chroma run --path /db_path
+ ```
+
+ Or using docker:
+
+ ```shell
+ docker run -p 8000:8000 chromadb/chroma
+ ```
+
+ Then, initialize the Document Store with `host` and `port` parameters:
+
+ ```python
+ from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+
+ document_store = ChromaDocumentStore(host="localhost", port="8000")
+ ```
+
+## Supported Retrievers
+
+The Haystack Chroma integration comes with three Retriever components. They all rely on the Chroma [query API](https://docs.trychroma.com/reference/Collection#query), but they have different inputs and outputs so that you can pick the one that best fits your pipeline:
+
+- [`ChromaQueryTextRetriever`](../pipeline-components/retrievers/chromaqueryretriever.mdx): This Retriever takes a plain-text query string in input and returns a list of matching documents. Chroma will create the embeddings for the query using its [default embedding function](https://docs.trychroma.com/embeddings#default-all-minilm-l6-v2).
+- [`ChromaEmbeddingRetriever`](../pipeline-components/retrievers/chromaembeddingretriever.mdx): This Retriever takes the embeddings of a single query in input and returns a list of matching documents. The query needs to be embedded before being passed to this component. For example, you can use an [embedder](../pipeline-components/embedders.mdx) component.
+
+## Additional References
+
+🧑🍳 Cookbook: [Use Chroma for RAG and Indexing](https://haystack.deepset.ai/cookbook/chroma-indexing-and-rag-examples)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/document-stores/elasticsearch-document-store.mdx b/docs-website/versioned_docs/version-2.20-unstable/document-stores/elasticsearch-document-store.mdx
new file mode 100644
index 0000000000..2b2ef30d51
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/document-stores/elasticsearch-document-store.mdx
@@ -0,0 +1,66 @@
+---
+title: "ElasticsearchDocumentStore"
+id: elasticsearch-document-store
+slug: "/elasticsearch-document-store"
+description: "Use an Elasticsearch database with Haystack."
+---
+
+# ElasticsearchDocumentStore
+
+Use an Elasticsearch database with Haystack.
+
+
+
+| | |
+| --- | --- |
+| API reference | [Elasticsearch](/reference/integrations-elasticsearch) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/elasticsearch |
+
+
+
+ElasticsearchDocumentStore is excellent if you want to evaluate the performance of different retrieval options (dense vs. sparse) and aim for a smooth transition from PoC to production.
+
+It features the approximate nearest neighbours (ANN) search.
+
+### Initialization
+
+[Install](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html) Elasticsearch and then [start](https://www.elastic.co/guide/en/elasticsearch/reference/current/starting-elasticsearch.html) an instance. Haystack supports Elasticsearch 8.
+
+If you have Docker set up, we recommend pulling the Docker image and running it.
+
+```shell
+docker pull docker.elastic.co/elasticsearch/elasticsearch:8.11.1
+docker run -p 9200:9200 -e "discovery.type=single-node" -e "ES_JAVA_OPTS=-Xms1024m -Xmx1024m" -e "xpack.security.enabled=false" elasticsearch:8.11.1
+```
+
+As an alternative, you can go to [Elasticsearch integration GitHub](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/elasticsearch) and start a Docker container running Elasticsearch using the provided `docker-compose.yml`:
+
+```shell
+docker compose up
+```
+
+Once you have a running Elasticsearch instance, install the `elasticsearch-haystack` integration:
+
+```shell
+pip install elasticsearch-haystack
+```
+
+Then, initialize an `ElasticsearchDocumentStore` object that’s connected to the Elasticsearch instance and writes documents to it:
+
+```python
+from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore
+from haystack import Document
+
+document_store = ElasticsearchDocumentStore(hosts = "http://localhost:9200")
+document_store.write_documents([
+ Document(content="This is first"),
+ Document(content="This is second")
+ ])
+print(document_store.count_documents())
+```
+
+### Supported Retrievers
+
+[`ElasticsearchBM25Retriever`](../pipeline-components/retrievers/elasticsearchbm25retriever.mdx): A keyword-based Retriever that fetches documents matching a query from the Document Store.
+
+[`ElasticsearchEmbeddingRetriever`](../pipeline-components/retrievers/elasticsearchembeddingretriever.mdx): Compares the query and document embeddings and fetches the documents most relevant to the query.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/document-stores/inmemorydocumentstore.mdx b/docs-website/versioned_docs/version-2.20-unstable/document-stores/inmemorydocumentstore.mdx
new file mode 100644
index 0000000000..8e69b44e65
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/document-stores/inmemorydocumentstore.mdx
@@ -0,0 +1,27 @@
+---
+title: "InMemoryDocumentStore"
+id: inmemorydocumentstore
+slug: "/inmemorydocumentstore"
+---
+
+# InMemoryDocumentStore
+
+The `InMemoryDocumentStore` is a very simple document store with no extra services or dependencies.
+
+It is great for experimenting with Haystack, however we do not recommend using it for production.
+
+### Initialization
+
+`InMemoryDocumentStore` requires no external setup. Simply use this code:
+
+```python
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+```
+
+### Supported Retrievers
+
+[`InMemoryBM25Retriever`](../pipeline-components/retrievers/inmemorybm25retriever.mdx): A keyword-based Retriever that fetches documents matching a query from a temporary in-memory database.
+
+[`InMemoryEmbeddingRetriever`](../pipeline-components/retrievers/inmemoryembeddingretriever.mdx): Compares the query and document embeddings and fetches the documents most relevant to the query.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/document-stores/mongodbatlasdocumentstore.mdx b/docs-website/versioned_docs/version-2.20-unstable/document-stores/mongodbatlasdocumentstore.mdx
new file mode 100644
index 0000000000..fc2d21f58d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/document-stores/mongodbatlasdocumentstore.mdx
@@ -0,0 +1,57 @@
+---
+title: "MongoDBAtlasDocumentStore"
+id: mongodbatlasdocumentstore
+slug: "/mongodbatlasdocumentstore"
+---
+
+# MongoDBAtlasDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [MongoDB Atlas](/reference/integrations-mongodb-atlas) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mongodb_atlas |
+
+
+
+`MongoDBAtlasDocumentStore` can be used to manage documents using [MongoDB Atlas](https://www.mongodb.com/atlas), a multi-cloud database service by the same people who build MongoDB. Atlas simplifies deploying and managing your databases while offering the versatility you need to build resilient and performant global applications on the cloud providers of your choice. You can use MongoDB Atlas on cloud providers such as AWS, Azure, or Google Cloud, all without leaving Atlas' web UI.
+
+MongoDB Atlas supports embeddings and can therefore be used for embedding retrieval.
+
+## Installation
+
+To use MongoDB Atlas with Haystack, install the integration first:
+
+```shell
+pip install mongodb-atlas-haystack
+```
+
+## Initialization
+
+To use MongoDB Atlas with Haystack, you will need to create your MongoDB Atlas account: check the [MongoDB Atlas documentation](https://www.mongodb.com/docs/atlas/getting-started/) for help. You also need to [create a vector search index](https://www.mongodb.com/docs/atlas/atlas-vector-search/create-index/#std-label-avs-create-index) and [a full-text search index](https://www.mongodb.com/docs/atlas/atlas-search/manage-indexes/#create-an-atlas-search-index) for the collection you plan to use.
+
+Once you have your connection string, you should export it in an environment variable called `MONGO_CONNECTION_STRING`. It should look something like this:
+
+```python
+export MONGO_CONNECTION_STRING="mongodb+srv://
+
+| | |
+| --- | --- |
+| API reference | [OpenSearch](/reference/integrations-opensearch) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opensearch |
+
+
+
+OpenSearch is a fully open source search and analytics engine for use cases such as log analytics, real-time application monitoring, and clickstream analysis. For more information, see the [OpenSearch documentation](https://opensearch.org/docs/).
+
+This Document Store is great if you want to evaluate the performance of different retrieval options (dense vs. sparse). It’s compatible with the Amazon OpenSearch Service.
+
+OpenSearch provides support for vector similarity comparisons and approximate nearest neighbors algorithms.
+
+### Initialization
+
+[Install](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/index/) and run an OpenSearch instance.
+
+If you have Docker set up, we recommend pulling the Docker image and running it.
+
+```shell
+docker pull opensearchproject/opensearch:2.11.0
+docker run -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" -e "ES_JAVA_OPTS=-Xms1024m -Xmx1024m" opensearchproject/opensearch:2.11.0
+```
+
+As an alternative, you can go to [OpenSearch integration GitHub](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opensearch) and start a Docker container running OpenSearch using the provided `docker-compose.yml`:
+
+```shell
+docker compose up
+```
+
+Once you have a running OpenSearch instance, install the `opensearch-haystack` integration:
+
+```shell
+pip install opensearch-haystack
+```
+
+Then, initialize an `OpenSearchDocumentStore` object that’s connected to the OpenSearch instance and writes documents to it:
+
+```python
+from haystack_integrations.document_stores.opensearch import OpenSearchDocumentStore
+from haystack import Document
+
+document_store = OpenSearchDocumentStore(hosts="http://localhost:9200", use_ssl=True,
+verify_certs=False, http_auth=("admin", "admin"))
+document_store.write_documents([
+ Document(content="This is first"),
+ Document(content="This is second")
+ ])
+print(document_store.count_documents())
+```
+
+### Supported Retrievers
+
+[`OpenSearchBM25Retriever`](../pipeline-components/retrievers/opensearchbm25retriever.mdx): A keyword-based Retriever that fetches documents matching a query from the Document Store.
+
+[`OpenSearchEmbeddingRetriever`](../pipeline-components/retrievers/opensearchembeddingretriever.mdx): Compares the query and document embeddings and fetches the documents most relevant to the query.
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/document-stores/pgvectordocumentstore.mdx b/docs-website/versioned_docs/version-2.20-unstable/document-stores/pgvectordocumentstore.mdx
new file mode 100644
index 0000000000..c24c7d5c94
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/document-stores/pgvectordocumentstore.mdx
@@ -0,0 +1,77 @@
+---
+title: "PgvectorDocumentStore"
+id: pgvectordocumentstore
+slug: "/pgvectordocumentstore"
+---
+
+# PgvectorDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Pgvector](/reference/integrations-pgvector) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/pgvector/ |
+
+
+
+Pgvector is an extension for PostgreSQL that enhances its capabilities with vector similarity search. It builds upon the classic features of PostgreSQL, such as ACID compliance and point-in-time recovery, and introduces the ability to perform exact and approximate nearest neighbor search using vectors.
+
+For more information, see the [pgvector repository](https://github.com/pgvector/pgvector).
+
+Pgvector Document Store supports embedding retrieval and metadata filtering.
+
+## Installation
+
+To quickly set up a PostgreSQL database with pgvector, you can use Docker:
+
+```shell
+docker run -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres ankane/pgvector
+```
+
+For more information on installing pgvector, visit the [pgvector GitHub repository](https://github.com/pgvector/pgvector).
+
+To use pgvector with Haystack, install the `pgvector-haystack` integration:
+
+```shell
+pip install pgvector-haystack
+```
+
+## Usage
+
+Define the connection string to your PostgreSQL database in the `PG_CONN_STR` environment variable. For example:
+
+```shell Shell
+export PG_CONN_STR="postgresql://postgres:postgres@localhost:5432/postgres"
+```
+
+## Initialization
+
+Initialize a `PgvectorDocumentStore` object that’s connected to the PostgreSQL database and writes documents to it:
+
+```python
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack import Document
+
+document_store = PgvectorDocumentStore(
+ embedding_dimension=768,
+ vector_function="cosine_similarity",
+ recreate_table=True,
+ search_strategy="hnsw",
+)
+
+document_store.write_documents([
+ Document(content="This is first", embedding=[0.1]*768),
+ Document(content="This is second", embedding=[0.3]*768)
+ ])
+print(document_store.count_documents())
+```
+
+To learn more about the initialization parameters, see our [API docs](/reference/integrations-pgvector#pgvectordocumentstore).
+
+To properly compute embeddings for your documents, you can use a Document Embedder (for instance, the [`SentenceTransformersDocumentEmbedder`](../pipeline-components/embedders/sentencetransformersdocumentembedder.mdx)).
+
+### Supported Retrievers
+
+- [`PgvectorEmbeddingRetriever`](../pipeline-components/retrievers/pgvectorembeddingretriever.mdx): An embedding-based Retriever that fetches documents from the Document Store based on a query embedding provided to the Retriever.
+- [`PgvectorKeywordRetriever`](../pipeline-components/retrievers/pgvectorembeddingretriever.mdx): A keyword-based Retriever that fetches documents matching a query from the Pgvector Document Store.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/document-stores/pinecone-document-store.mdx b/docs-website/versioned_docs/version-2.20-unstable/document-stores/pinecone-document-store.mdx
new file mode 100644
index 0000000000..17e02fb30a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/document-stores/pinecone-document-store.mdx
@@ -0,0 +1,66 @@
+---
+title: "PineconeDocumentStore"
+id: pinecone-document-store
+slug: "/pinecone-document-store"
+description: "Use a Pinecone vector database with Haystack."
+---
+
+# PineconeDocumentStore
+
+Use a Pinecone vector database with Haystack.
+
+
+
+| | |
+| --- | --- |
+| API reference | [Pinecone](/reference/integrations-pinecone) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/pinecone |
+
+
+
+[Pinecone](https://www.pinecone.io/) is a cloud-based vector database. It is fast and easy to use.
+Unlike other solutions (such as Qdrant and Weaviate), it can’t run locally on the user's machine but provides a generous free tier.
+
+### Installation
+
+You can simply install the Pinecone Haystack integration with:
+
+```shell
+pip install pinecone-haystack
+```
+
+### Initialization
+
+- To use Pinecone as a Document Store in Haystack, sign up for a free Pinecone [account](https://app.pinecone.io/) and get your API key.
+ The Pinecone API key can be explicitly provided or automatically read from the environment variable `PINECONE_API_KEY` (recommended).
+- In Haystack, each `PineconeDocumentStore` operates in a specific namespace of an index. If not provided, both index and namespace are `default`.
+ If the index already exists, the Document Store connects to it. Otherwise, it creates a new index.
+- When creating a new index, you can provide a `spec` in the form of a dictionary. This allows choosing between serverless and pod deployment options and setting additional parameters. Refer to the [Pinecone documentation](https://docs.pinecone.io/reference/api/control-plane/create_index) for more details. If not provided, a default spec with serverless deployment in the `us-east-1` region will be used (compatible with the free tier).
+- You can provide `dimension` and `metric`, but they are only taken into account if the Pinecone index does not already exist.
+
+Then, you can use the Document Store like this:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.pinecone import PineconeDocumentStore
+
+## Make sure you have the PINECONE_API_KEY environment variable set
+document_store = PineconeDocumentStore(
+ index="default",
+ namespace="default",
+ dimension=5,
+ metric="cosine",
+ spec={"serverless": {"region": "us-east-1", "cloud": "aws"}}
+)
+
+document_store.write_documents([
+ Document(content="This is first", embedding=[0.0]*5),
+ Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5])
+ ])
+print(document_store.count_documents())
+
+```
+
+### Supported Retrievers
+
+[`PineconeEmbeddingRetriever`](../pipeline-components/retrievers/pineconedenseretriever.mdx): Retrieves documents from the `PineconeDocumentStore` based on their dense embeddings (vectors).
diff --git a/docs-website/versioned_docs/version-2.20-unstable/document-stores/qdrant-document-store.mdx b/docs-website/versioned_docs/version-2.20-unstable/document-stores/qdrant-document-store.mdx
new file mode 100644
index 0000000000..fe1a257e5d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/document-stores/qdrant-document-store.mdx
@@ -0,0 +1,99 @@
+---
+title: "QdrantDocumentStore"
+id: qdrant-document-store
+slug: "/qdrant-document-store"
+description: "Use the Qdrant vector database with Haystack."
+---
+
+# QdrantDocumentStore
+
+Use the Qdrant vector database with Haystack.
+
+
+
+| | |
+| --- | --- |
+| API reference | [Qdrant](/reference/integrations-qdrant) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/qdrant |
+
+
+
+Qdrant is a powerful high-performance, massive-scale vector database. The `QdrantDocumentStore` can be used with any Qdrant instance, in-memory, locally persisted, hosted, and the official Qdrant Cloud.
+
+### Installation
+
+You can simply install the Qdrant Haystack integration with:
+
+```shell
+pip install qdrant-haystack
+```
+
+### Initialization
+
+The quickest way to use `QdrantDocumentStore` is to create an in-memory instance of it:
+
+```python
+from haystack.dataclasses.document import Document
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ return_embedding=True,
+ wait_result_from_api=True,
+)
+document_store.write_documents([
+ Document(content="This is first", embedding=[0.0]*5),
+ Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5])
+])
+print(document_store.count_documents())
+```
+
+:::warning Collections Created Outside Haystack
+
+When you create a `QdrantDocumentStore` instance, Haystack takes care of setting up the collection. In general, you cannot use a Qdrant collection created without Haystack with Haystack. If you want to migrate your existing collection, see the sample script at https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/qdrant/src/haystack_integrations/document_stores/qdrant/migrate_to_sparse.py.
+:::
+
+You can also connect directly to [Qdrant Cloud](https://cloud.qdrant.io/login) directly. Once you have your API key and your cluster URL from the Qdrant dashboard, you can connect like this:
+
+```python
+from haystack.dataclasses.document import Document
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack.utils import Secret
+
+document_store = QdrantDocumentStore(
+ url="https://XXXXXXXXX.us-east4-0.gcp.cloud.qdrant.io:6333",
+ index="your_index_name",
+ embedding_dim=1024, # based on the embedding model
+ recreate_index=True, # enable only to recreate the index and not connect to the existing one
+ api_key = Secret.from_token("YOUR_TOKEN")
+)
+
+document_store.write_documents([
+ Document(content="This is first", embedding=[0.0]*5),
+ Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5])
+])
+print(document_store.count_documents())
+```
+
+:::tip More information
+
+You can find more ways to initialize and use QdrantDocumentStore on our [integration page](https://haystack.deepset.ai/integrations/qdrant-document-store).
+:::
+
+### Supported Retrievers
+
+- [`QdrantEmbeddingRetriever`](../pipeline-components/retrievers/qdrantembeddingretriever.mdx): Retrieves documents from the `QdrantDocumentStore` based on their dense embeddings (vectors).
+- [`QdrantSparseEmbeddingRetriever`](../pipeline-components/retrievers/qdrantsparseembeddingretriever.mdx): Retrieves documents from the `QdrantDocumentStore` based on their sparse embeddings.
+- [`QdrantHybridRetriever`](../pipeline-components/retrievers/qdranthybridretriever.mdx): Retrieves documents from the `QdrantDocumentStore` based on both dense and sparse embeddings.
+
+:::note Sparse Embedding Support
+
+To use Sparse Embedding support, you need to initialize the `QdrantDocumentStore` with `use_sparse_embeddings=True`, which is `False` by default.
+
+If you want to use Document Store or collection previously created with this feature disabled, you must migrate the existing data. You can do this by taking advantage of the `migrate_to_sparse_embeddings_support` utility function.
+:::
+
+## Additional References
+
+🧑🍳 Cookbook: [Sparse Embedding Retrieval with Qdrant and FastEmbed](https://haystack.deepset.ai/cookbook/sparse_embedding_retrieval)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/document-stores/weaviatedocumentstore.mdx b/docs-website/versioned_docs/version-2.20-unstable/document-stores/weaviatedocumentstore.mdx
new file mode 100644
index 0000000000..087e15f539
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/document-stores/weaviatedocumentstore.mdx
@@ -0,0 +1,148 @@
+---
+title: "WeaviateDocumentStore"
+id: weaviatedocumentstore
+slug: "/weaviatedocumentstore"
+---
+
+# WeaviateDocumentStore
+
+
+
+| | |
+| --- | --- |
+| API reference | [Weaviate](/reference/integrations-weaviate) |
+| GitHub link | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/weaviate |
+
+
+
+Weaviate is a multi-purpose vector DB that can store both embeddings and data objects, making it a good choice for multi-modality.
+
+The `WeaviateDocumentStore` can connect to any Weaviate instance, whether it's running on Weaviate Cloud Services, Kubernetes, or a local Docker container.
+
+## Installation
+
+You can simply install the Weaviate Haystack integration with:
+
+```shell
+pip install weaviate-haystack
+```
+
+## Initialization
+
+### Weaviate Embedded
+
+To use `WeaviateDocumentStore` as a temporary instance, initialize it as ["Embedded"](https://weaviate.io/developers/weaviate/installation/embedded):
+
+```python
+from haystack_integrations.document_stores.weaviate import WeaviateDocumentStore
+from weaviate.embedded import EmbeddedOptions
+
+document_store = WeaviateDocumentStore(embedded_options=EmbeddedOptions())
+```
+
+### Docker
+
+You can use `WeaviateDocumentStore` in a local Docker container. This is what a minimal `docker-compose.yml` could look like:
+
+```yaml
+---
+version: '3.4'
+services:
+ weaviate:
+ command:
+ - --host
+ - 0.0.0.0
+ - --port
+ - '8080'
+ - --scheme
+ - http
+ image: semitechnologies/weaviate:1.30.17
+ ports:
+ - 8080:8080
+ - 50051:50051
+ volumes:
+ - weaviate_data:/var/lib/weaviate
+ restart: 'no'
+ environment:
+ QUERY_DEFAULTS_LIMIT: 25
+ AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
+ PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
+ DEFAULT_VECTORIZER_MODULE: 'none'
+ ENABLE_MODULES: ''
+ CLUSTER_HOSTNAME: 'node1'
+volumes:
+ weaviate_data:
+...
+```
+
+:::warning
+With this example, we explicitly enable access without authentication, so you don't need to set any username, password, or API key to connect to our local instance. That is strongly discouraged for production use. See the [authorization](#authorization) section for detailed information.
+
+:::
+
+Start your container with `docker compose up -d` and then initialize the Document Store with:
+
+```python
+from haystack_integrations.document_stores.weaviate.document_store import WeaviateDocumentStore
+from haystack import Document
+
+document_store = WeaviateDocumentStore(url="http://localhost:8080")
+document_store.write_documents([
+ Document(content="This is first"),
+ Document(content="This is second")
+])
+print(document_store.count_documents())
+```
+
+### Weaviate Cloud Service
+
+To use the [Weaviate managed cloud service](https://weaviate.io/developers/wcs), first, create your Weaviate cluster.
+
+Then, initialize the `WeaviateDocumentStore` using the API Key and URL found in your [Weaviate account](https://console.weaviate.cloud/):
+
+```python
+from haystack_integrations.document_stores.weaviate import WeaviateDocumentStore, AuthApiKey
+from haystack import Document
+
+import os
+os.environ["WEAVIATE_API_KEY"] = "YOUR-API-KEY"
+
+auth_client_secret = AuthApiKey()
+
+document_store = WeaviateDocumentStore(url="YOUR-WEAVIATE-URL",
+ auth_client_secret=auth_client_secret)
+```
+
+## Authorization
+
+We provide some utility classes in the `auth` package to handle authorization using different credentials. Every class stores distinct [secrets](../concepts/secret-management.mdx) and retrieves them from the environment variables when required.
+
+The default environment variables for the classes are:
+
+- **`AuthApiKey`**
+ - `WEAVIATE_API_KEY`
+- **`AuthBearerToken`**
+ - `WEAVIATE_ACCESS_TOKEN`
+ - `WEAVIATE_REFRESH_TOKEN`
+- **`AuthClientCredentials`**
+ - `WEAVIATE_CLIENT_SECRET`
+ - `WEAVIATE_SCOPE`
+- **`AuthClientPassword`**
+ - `WEAVIATE_USERNAME`
+ - `WEAVIATE_PASSWORD`
+ - `WEAVIATE_SCOPE`
+
+You can easily change environment variables if needed. In the following snippet, we instruct `AuthApiKey` to look for `MY_ENV_VAR`.
+
+```python
+from haystack_integrations.document_stores.weaviate.auth import AuthApiKey
+from haystack.utils.auth import Secret
+
+AuthApiKey(api_key=Secret.from_env_var("MY_ENV_VAR"))
+```
+
+## Supported Retrievers
+
+[`WeaviateBM25Retriever`](../pipeline-components/retrievers/weaviatebm25retriever.mdx): A keyword-based Retriever that fetches documents matching a query from the Document Store.
+
+[`WeaviateEmbeddingRetriever`](../pipeline-components/retrievers/weaviateembeddingretriever.mdx): Compares the query and document embeddings and fetches the documents most relevant to the query.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/intro.mdx b/docs-website/versioned_docs/version-2.20-unstable/intro.mdx
new file mode 100644
index 0000000000..a5f722f688
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/intro.mdx
@@ -0,0 +1,31 @@
+---
+title: "Introduction to Haystack"
+id: intro
+description: "Haystack is an **open-source AI framework** for building production-ready **AI Agents**, **retrieval-augmented generative pipelines** and **state-of-the-art multimodal search systems**. Learn more about Haystack and how it works."
+---
+
+# Introduction to Haystack
+
+Haystack is an **open-source AI framework** for building production-ready **AI Agents**, **retrieval-augmented generative pipelines** and **state-of-the-art multimodal search systems**. Learn more about Haystack and how it works.
+
+:::tip Welcome to Haystack
+
+To skip the introductions and go directly to installing and creating a search app, see [Get Started](overview/get-started.mdx).
+:::
+
+Haystack is an open-source AI orchestration framework that you can use to build powerful, production-ready applications with Large Language Models (LLMs) for various use cases. Whether you’re creating autonomous agents, multimodal apps, or scalable RAG systems, Haystack provides the tools to move from idea to production easily.
+
+Haystack is designed in a modular way, allowing you to combine the best technology from OpenAI, Google, Anthropic, and open-source projects like Hugging Face's Transformers or Elasticsearch.
+
+The core foundation of Haystack consists of components and pipelines, along with Document Stores, Agents, Tools, and many integrations. Read more about Haystack concepts in the [Haystack Concepts Overview](concepts/concepts-overview.mdx).
+
+Supported by an engaged community of developers, Haystack has grown into a comprehensive and user-friendly framework for LLM-based development.
+
+:::note Looking to scale with confidence?
+
+If your team needs **enterprise-grade support, best practices, and deployment guidance** to run Haystack in production, check out **Haystack Enterprise**.
+
+📜 [Learn more about Haystack Enterprise](https://haystack.deepset.ai/blog/announcing-haystack-enterprise)
+
+👉 [Get in touch with our team](https://www.deepset.ai/products-and-services/haystack-enterprise)
+:::
diff --git a/docs-website/versioned_docs/version-2.20-unstable/optimization/advanced-rag-techniques.mdx b/docs-website/versioned_docs/version-2.20-unstable/optimization/advanced-rag-techniques.mdx
new file mode 100644
index 0000000000..dc1b2d2454
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/optimization/advanced-rag-techniques.mdx
@@ -0,0 +1,19 @@
+---
+title: "Advanced RAG Techniques"
+id: advanced-rag-techniques
+slug: "/advanced-rag-techniques"
+---
+
+# Advanced RAG Techniques
+
+This section of documentation talks about advanced RAQ techniques you can implement with Haystack.
+
+Read more about [Hypothetical Document Embeddings (HyDE)](advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx),
+
+or check out one of our cookbooks 🧑🍳:
+
+- [Using Hypothetical Document Embedding (HyDE) to Improve Retrieval](https://haystack.deepset.ai/cookbook/using_hyde_for_improved_retrieval)
+- [Query Decomposition and Reasoning](https://haystack.deepset.ai/cookbook/query_decomposition)
+- [Improving Retrieval by Embedding Meaningful Metadata](https://haystack.deepset.ai/cookbook/improve-retrieval-by-embedding-metadata)
+- [Query Expansion](https://haystack.deepset.ai/cookbook/query-expansion)
+- [Automated Structured Metadata Enrichment](https://haystack.deepset.ai/cookbook/metadata_enrichment)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/optimization/advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx b/docs-website/versioned_docs/version-2.20-unstable/optimization/advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx
new file mode 100644
index 0000000000..029dfd9c48
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/optimization/advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx
@@ -0,0 +1,107 @@
+---
+title: "Hypothetical Document Embeddings (HyDE)"
+id: hypothetical-document-embeddings-hyde
+slug: "/hypothetical-document-embeddings-hyde"
+description: "Enhance the retrieval in Haystack using HyDE method by generating a mock-up hypothetical document for an initial query."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# Hypothetical Document Embeddings (HyDE)
+
+Enhance the retrieval in Haystack using HyDE method by generating a mock-up hypothetical document for an initial query.
+
+## When Is It Helpful?
+
+The HyDE method is highly useful when:
+
+- The performance of the retrieval step in your pipeline is not good enough (for example, low Recall metric).
+- Your retrieval step has a query as input and returns documents from a larger document base.
+- Particularly worth a try if your data (documents or queries) come from a special domain that is very different from the typical datasets that Retrievers are trained on.
+
+## How Does It Work?
+
+Many embedding retrievers generalize poorly to new, unseen domains. This approach tries to tackle this problem. Given a query, the Hypothetical Document Embeddings (HyDE) first zero-shot prompts an instruction-following language model to generate a “fake” hypothetical document that captures relevant textual patterns from the initial query - in practice, this is done five times. Then, it encodes each hypothetical document into an embedding vector and averages them. The resulting, single embedding can be used to identify a neighbourhood in the document embedding space from which similar actual documents are retrieved based on vector similarity. As with any other retriever, these retrieved documents can then be used downstream in a pipeline (for example, in a Generator for RAG). Refer to the paper “[Precise Zero-Shot Dense Retrieval without Relevance Labels](https://aclanthology.org/2023.acl-long.99/)” for more details.
+Google VertexAI Models
Azure OpenAI Models
Amazon Bedrock Models | All GPT models from OpenAI | +| Supported metrics | ANSWER_CORRECTNESS, FAITHFULNESS, ANSWER_SIMILARITY, CONTEXT_PRECISION, CONTEXT_UTILIZATION,CONTEXT_RECALL, ASPECT_CRITIQUE, CONTEXT_RELEVANCY, ANSWER_RELEVANCY | ANSWER_RELEVANCY, FAITHFULNESS, CONTEXTUAL_PRECISION, CONTEXTUAL_RECALL, CONTEXTUAL_RELEVANCE | +| Customizable prompt for response evaluation | ✅, with ASPECT_CRITIQUE metric | ❌ | +| Explanations of scores | ❌ | ✅ | +| Monitoring dashboard | ❌ | ❌ | + +:::info Framework Documentation + +You can find more information about the metrics in the documentation of the respective evaluation frameworks: + +- Ragas metrics: https://docs.ragas.io/en/latest/concepts/metrics/index.html +- DeepEval metrics: https://docs.confident-ai.com/docs/metrics-introduction +::: + +## Additional References + +:notebook: Tutorial: [Evaluating RAG Pipelines](https://haystack.deepset.ai/tutorials/35_evaluating_rag_pipelines) diff --git a/docs-website/versioned_docs/version-2.20-unstable/optimization/evaluation/statistical-evaluation.mdx b/docs-website/versioned_docs/version-2.20-unstable/optimization/evaluation/statistical-evaluation.mdx new file mode 100644 index 0000000000..5fc39c80ed --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/optimization/evaluation/statistical-evaluation.mdx @@ -0,0 +1,49 @@ +--- +title: "Statistical Evaluation" +id: statistical-evaluation +slug: "/statistical-evaluation" +description: "Haystack supports various statistical evaluation metrics. This page explains what statistical evaluation is and discusses the various options available within Haystack." +--- + +# Statistical Evaluation + +Haystack supports various statistical evaluation metrics. This page explains what statistical evaluation is and discusses the various options available within Haystack. + +## Introduction + +Statistical evaluation in Haystack compares ground truth labels with pipeline predictions, typically using metrics such as precision or recall. It's often used to evaluate the Retriever component within Retrieval-Augmented Generative (RAG) pipelines, but this methodology can be adapted for any pipeline if ground truth labels of relevant documents are available. + +When evaluating answers, such as those predicted by an extractive question answering pipeline, the ground truth labels of expected answers are compared to the pipeline's predictions. + +For assessing answers generated by LLMs with one of Haystack’s Generator components, we recommend model-based evaluation instead. It can incorporate measures of semantic similarity or coherence and is better suited to evaluate predictions that might differ in wording from the ground truth labels. + +## Statistical Evaluation Pipelines in Haystack + +There are two ways of performing model-based evaluation in Haystack, both of which leverage [pipelines](../../concepts/pipelines.mdx) and [Evaluator](../../pipeline-components/evaluators.mdx) components: + +- You can create and run an evaluation pipeline independently. This means you’ll have to provide the required inputs to the evaluation pipeline manually. We recommend this way because the separation of your RAG pipeline and your evaluation pipeline allows you to store the results of your RAG pipeline and try out different evaluation metrics afterward without needing to re-run your pipeline every time. +- As another option, you can add an Evaluator to the end of a RAG pipeline. This means you run both a RAG pipeline and evaluation on top of it in a single `pipeline.run()` call. + +## Statistical Evaluation of Retrieved Documents + +### [DocumentRecallEvaluator](../../pipeline-components/evaluators/documentrecallevaluator.mdx) + +Recall measures how often the correct document was among the retrieved documents over a set of queries. For a single query, the output is binary: either the correct document is contained in the selection, or it is not. Over the entire dataset, the recall score amounts to a number between zero (no query retrieved the right document) and one (all queries retrieved the right documents). + +In some scenarios, there can be multiple correct documents for one query. The metric `recall_single_hit` considers whether at least one of the correct documents is retrieved, whereas `recall_multi_hit` takes into account how many of the multiple correct documents for one query are retrieved. + +Note that recall is affected by the number of documents that the Retriever returns. If the Retriever returns few documents, it means that it is difficult to retrieve the correct documents. Make sure to set the Retriever's `top_k` to an appropriate value in the pipeline that you're evaluating. + +### [DocumentMRREvaluator](../../pipeline-components/evaluators/documentmrrevaluator.mdx) (Mean Reciprocal Rank) + +In contrast to the recall metric, mean reciprocal rank takes the position of the top correctly retrieved document (the “rank”) into account. It does this to account for the fact that a query elicits multiple responses of varying relevance. Like recall, MRR can be a value between zero (no matches) and one (the system retrieved a correct document for all queries as the top result). For more details, check out [Mean Reciprocal Rank wiki page](https://en.wikipedia.org/wiki/Mean_reciprocal_rank). + +### [DocumentMAPEvaluator](../../pipeline-components/evaluators/documentmapevaluator.mdx) (Mean Average Precision) + +Mean average precision is similar to mean reciprocal rank but takes into account the position of every correctly retrieved document. Like MRR, mAP can be a value between zero (no matches) and one (the system retrieved correct documents for all top results). mAP is particularly useful in cases where there is more than one correct answer to be retrieved. For more details, check out [Mean Average Precision wiki page](https://en.wikipedia.org/wiki/Evaluation_measures_(information_retrieval)#Mean_average_precision). + +## Statistical Evaluation of Extracted or Generated Answers + +### [AnswerExactMatchEvaluator](../../pipeline-components/evaluators/answerexactmatchevaluator.mdx) + +Exact match measures the proportion of cases where the predicted Answer is identical to the correct Answer. For example, for the annotated question-answer pair “What is Haystack?" + "A question answering library in Python”, even a predicted answer like “A Python question answering library” would yield a zero score because it does not match the expected answer 100%. \ No newline at end of file diff --git a/docs-website/versioned_docs/version-2.20-unstable/overview/breaking-change-policy.mdx b/docs-website/versioned_docs/version-2.20-unstable/overview/breaking-change-policy.mdx new file mode 100644 index 0000000000..c3fb3a7e6d --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/overview/breaking-change-policy.mdx @@ -0,0 +1,88 @@ +--- +title: "Breaking Change Policy" +id: breaking-change-policy +slug: "/breaking-change-policy" +description: "This document outlines the breaking change policy for Haystack, including the definition of breaking changes, versioning conventions, and the deprecation process for existing features." +--- + +# Breaking Change Policy + +This document outlines the breaking change policy for Haystack, including the definition of breaking changes, versioning conventions, and the deprecation process for existing features. + +Haystack is under active development, which means that functionalities are being added, deprecated, or removed rather frequently. This policy aims to minimize the impact of these changes on current users and deployments. It provides a clear schedule and outlines the necessary steps before upgrading to a new Haystack version. + +## Breaking Change Definition + +A breaking change occurs when: + +- A Component is removed, renamed, or the Python import path is changed. +- A parameter is renamed, removed, or changed from optional to mandatory. +- A new mandatory parameter is added. + +Existing deployments might break, and the change is deemed a _breaking change_. The decision to declare a change as breaking has nothing to do with its potential impact: while the change might only impact a tiny subset of applications using a specific Haystack feature, it would still be treated as a breaking change. + +The following cases are **not** considered a breaking change: + +- A new functionality is added (for example, a new Component). +- A component, class, or utility function gets a new optional parameter. +- An existing parameter gets changed from mandatory to optional. + +Existing deployments are not impacted, and the change is deemed non-breaking. Release notes will mention the change and possibly provide an upgrade path, but upgrading Haystack won’t break existing applications. + +## Versioning + +Haystack releases are labeled with a series of three numbers separated by dots, for example, `2.0.1`. Each number has a specific meaning: + +- `2` is the Major version +- `0` is the Minor version +- `1` is the Patch version + +:::info +Albeit similar, Haystack DOES NOT follow the principles of [Semantic Versioning](https://semver.org). Read on to see the differences. +::: + +Given a Haystack release with a version number of type `MAJOR.MINOR.PATCH`, you should expect: + +1. **For Major version change:** fundamental, incompatible API changes. In this case, you would most likely need a migration process before being able to update Haystack. Major releases happen no more than once a year, changes are extensively documented, and a migration path is provided. +2. **For Minor version change:** addition or removal of functionalities that might not be backward compatible. Most of the time, you will be able to upgrade your Haystack installation seamlessly, but always refer to the [release notes](https://github.com/deepset-ai/haystack/releases) for guidance. Deprecated components are the most common breaking change shipped in a Minor version release. +3. **For Patch version change:** bugfixes. You can safely upgrade Haystack to the new version without concerns that your program will break. + +## Deprecation of Existing Features + +Haystack strives for robustness. To achieve this, we clean up our code by removing old features that are no longer used. This helps us maintain the codebase, improve security, and make it easier to keep everything running smoothly. Before we remove a feature, component, class, or utility function, we go through a process called deprecation. + +A Major or Minor (but not Patch) version may deprecate certain features from previous releases, and this is what you should expect: + +- If a feature is deprecated in Haystack version `X.Y`, it will continue to work but the Python code will raise warnings detailing the steps to take in order to upgrade. +- Features deprecated in Haystack version `X.Y` will be removed in Haystack `X.Y+1`, giving affected users a timeframe of roughly a month to prepare the upgrade. + +### Example + +To clarify the process, here’s an example: + +At some point, we decide to remove a `FooComponent` and declare it deprecated in Haystack version `2.99.0`. This is what will happen: + +1. `FooComponent` keeps working as usual In Haystack `2.99.0`, but using the component raises a `FutureWarning` message in the code. +2. In Haystack version `2.100.0`, we remove the `FooComponent` from the codebase. Trying to use it produces an error. + +## Discontinuing an Integration + +When existing features are changed or removed, integrations go through the same deprecation process as detailed on this page for Haystack. It’s important to note that integrations are independent and distributed with their own packages. In certain cases, a special form of deprecation may occur where the integration is discontinued and subsequently removed from the Core Integrations repository. + +To give our community the opportunity to take over the integration and keep it maintained before being discontinued Core Integrations gradually go through different states, as detailed below: + +- **Staged** + - The source code of the integration is moved from `main` to a special `staging` branch of the Core Integrations repository. + - The documentation pages are removed from the Haystack documentation website. + - The main README of the Core Integrations repository shows a disclaimer explaining how the integration can be adopted from the community. + - The integration tile is removed (it can be re-added later by the maintainer who adopted the integration). + - The integration package on PyPI remains available. + - A grace period of 3 months starts. +- **Adopted** + - An organization or an individual from the community accepts to take over the ownership of the Staged integration. + - The adopter creates their own repository, and the source code of the discontinued integration is removed from the `staging` branch. + - Ownership of the PyPI package is transferred to the new maintainer. + - The adopter will create a new integration tile in [haystack-integrations](https://github.com/deepset-ai/haystack-integrations). +- **Discontinued** + - If the grace period expires and nobody adopts the Staged Integration, its source code is removed from the `staging` branch. + - The PyPI package of the integration won’t be removed but won’t be further updated. \ No newline at end of file diff --git a/docs-website/versioned_docs/version-2.20-unstable/overview/faq.mdx b/docs-website/versioned_docs/version-2.20-unstable/overview/faq.mdx new file mode 100644 index 0000000000..b522f4c492 --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/overview/faq.mdx @@ -0,0 +1,38 @@ +--- +title: "FAQ" +id: faq +slug: "/faq" +description: "Here are the answers to the questions people frequently ask about Haystack." +--- + +# FAQ + +Here are the answers to the questions people frequently ask about Haystack. + +### How can I make sure that my GPU is being engaged when I use Haystack? + +You will want to ensure that a CUDA enabled GPU is being engaged when Haystack is running (you can check by running `nvidia-smi -l` on your command line). Components which can be sped up by GPU have a `device` argument in their constructor. For more details, check the [Device Management](../concepts/device-management.mdx) page. + +### Are you tracking my Haystack usage? + +We only collect _anonymous_ usage statistics of Haystack pipeline components. Read more about telemetry in Haystack or how you can opt out on the [Telemetry](telemetry.mdx) page. + +### How can I ask my questions around Haystack? + +For general questions, we recommend joining the [Haystack Discord ](https://discord.com/invite/xYvH6drSmA)or using [GitHub discussions](https://github.com/deepset-ai/haystack/discussions), where the community and maintainers can help. You can also explore [tutorials](https://haystack.deepset.ai/tutorials/40_building_chat_application_with_function_calling) and [examples](https://haystack.deepset.ai/cookbook/tools_support) on our website to find more info. + +### How can I get expert support for Haystack? + +If you’re a team running Haystack in production or want to move faster and scale with confidence, we recommend [Haystack Enterprise](https://haystack.deepset.ai/blog/announcing-haystack-enterprise). It gives you direct access to the Haystack team, proven best practices, and hands-on support to help you go from prototype to production smoothly. + +👉 [Get in touch with our team to explore Haystack Enterprise](https://www.deepset.ai/products-and-services/haystack-enterprise) + +### Where can I find tutorials and documentation for Haystack 1.x? + +You can access old tutorials in the [GitHub history](https://github.com/deepset-ai/haystack-tutorials/tree/5917718cbfbb61410aab4121ee6fe754040a5dc7) and download the Haystack 1.x documentation as a [ZIP file](https://core-engineering.s3.eu-central-1.amazonaws.com/public/docs/haystack-v1-docs.zip). + +The ZIP file contains documentation for all minor releases from version 1.0 to 1.26. + +To download documentation for a specific release, replace the version number in the following URL: `https://core-engineering.s3.eu-central-1.amazonaws.com/public/docs/v1.26.zip`. + +Learn how to migrate to Haystack version 2.x with our [migration guide](migration.mdx). \ No newline at end of file diff --git a/docs-website/versioned_docs/version-2.20-unstable/overview/get-started.mdx b/docs-website/versioned_docs/version-2.20-unstable/overview/get-started.mdx new file mode 100644 index 0000000000..b52bb3cced --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/overview/get-started.mdx @@ -0,0 +1,111 @@ +--- +title: "Get Started" +id: get-started +slug: "/get-started" +description: "Have a look at this page to learn how to quickly get up and running with Haystack. It contains instructions for installing, running your first RAG pipeline, adding data and further resources." +--- + +# Get Started + +Have a look at this page to learn how to quickly get up and running with Haystack. It contains instructions for installing, running your first RAG pipeline, adding data and further resources. + +## Build your first RAG application + +Let's build your first Retrieval Augmented Generation (RAG) pipeline and see how Haystack answers questions. + +First, install the minimal form of Haystack: + +```shell +pip install haystack-ai +``` + +
+
+
+
+In the example below, we show how to set an API key using a Haystack [Secret](../concepts/secret-management.mdx). However, for easier use, you can also set an OpenAI key as an `OPENAI_API_KEY` environment variable.
+
+```python
+# import necessary dependencies
+from haystack import Pipeline, Document
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.retrievers import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.builders import ChatPromptBuilder
+from haystack.utils import Secret
+from haystack.dataclasses import ChatMessage
+
+# create a document store and write documents to it
+document_store = InMemoryDocumentStore()
+document_store.write_documents([
+ Document(content="My name is Jean and I live in Paris."),
+ Document(content="My name is Mark and I live in Berlin."),
+ Document(content="My name is Giorgio and I live in Rome.")
+])
+
+# A prompt corresponds to an NLP task and contains instructions for the model. Here, the pipeline will go through each Document to figure out the answer.
+prompt_template = [
+ ChatMessage.from_system(
+ """
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+ Question:
+ """
+ ),
+ ChatMessage.from_user(
+ "{{question}}"
+ ),
+ ChatMessage.from_system("Answer:")
+]
+
+# create the components adding the necessary parameters
+retriever = InMemoryBM25Retriever(document_store=document_store)
+prompt_builder = ChatPromptBuilder(template=prompt_template, required_variables="*")
+llm = OpenAIChatGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY"), model="gpt-4o-mini")
+
+# Create the pipeline and add the components to it. The order doesn't matter.
+# At this stage, the Pipeline validates the components without running them yet.
+rag_pipeline = Pipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+
+# Arrange pipeline components in the order you need them. If a component has more than one inputs or outputs, indicate which input you want to connect to which output using the format ("component_name.output_name", "component_name, input_name").
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+# Run the pipeline by specifying the first component in the pipeline and passing its mandatory inputs. Optionally, you can pass inputs to other components.
+question = "Who lives in Paris?"
+results = rag_pipeline.run(
+ {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ }
+)
+
+print(results["llm"]["replies"])
+
+```
+
+### Adding Your Data
+
+Instead of running the RAG pipeline on example data, learn how you can add your own custom data using [Document Stores](../concepts/document-store.mdx).
diff --git a/docs-website/versioned_docs/version-2.20-unstable/overview/installation.mdx b/docs-website/versioned_docs/version-2.20-unstable/overview/installation.mdx
new file mode 100644
index 0000000000..cd461e684b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/overview/installation.mdx
@@ -0,0 +1,77 @@
+---
+title: "Installation"
+id: installation
+slug: "/installation"
+description: "See how to quickly install Haystack with pip or conda."
+---
+
+# Installation
+
+See how to quickly install Haystack with pip or conda.
+
+## Package Installation
+
+Use [pip](https://github.com/pypa/pip) to install only the Haystack code:
+
+```shell
+pip install haystack-ai
+```
+
+Alternatively, you can use [conda](https://docs.conda.io/projects/conda/en/stable/):
+
+```shell
+conda config --add channels conda-forge/label/haystack-ai_rc
+conda install haystack-ai
+```
+
+Were you already using Haystack 1.x?
+ +:::warning + +Installing `farm-haystack` and `haystack-ai` in the same Python environment (virtualenv, Colab, or system) causes problems. + +Installing both packages in the same environment can somehow work or fail in obscure ways. We suggest installing only one of these packages per Python environment. Make sure that you remove both packages if they are installed in the same environment, followed by installing only one of them: + +```bash +pip uninstall -y farm-haystack haystack-ai +pip install haystack-ai +``` + +If you have any questions, please reach out to us on the [GitHub Discussion](https://github.com/deepset-ai/haystack/discussions) or [Discord](https://discord.com/invite/VBpFzsgRVF). +::: + ++ +
+
+
+
+### Optional Dependencies
+
+Some components in Haystack rely on additional optional dependencies.
+To keep the installation lightweight, these are not included by default – only the essentials are installed.
+If you use a feature that requires an optional dependency that hasn't been installed, Haystack will raise an error that instructs you to install missing dependencies, for example:
+
+```shell
+ImportError: "Haystack failed to import the optional dependency 'pypdf'. Run 'pip install pypdf'.
+```
+
+## Contributing to Haystack
+
+If you would like to contribute to the Haystack, check our [Contributor Guidelines](https://github.com/deepset-ai/haystack/blob/main/CONTRIBUTING.md) first.
+
+To be able to make changes to Haystack code, install with the following commands:
+
+```shell
+## Clone the repo
+git clone https://github.com/deepset-ai/haystack.git
+
+## Move into the cloned folder
+cd haystack
+
+## Upgrade pip
+pip install --upgrade pip
+
+## Install Haystack in editable mode
+pip install -e '.[dev]'
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/overview/migration.mdx b/docs-website/versioned_docs/version-2.20-unstable/overview/migration.mdx
new file mode 100644
index 0000000000..434a0ffd6e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/overview/migration.mdx
@@ -0,0 +1,487 @@
+---
+title: "Migration Guide"
+id: migration
+slug: "/migration"
+description: "Learn how to make the move to Haystack 2.x from Haystack 1.x."
+---
+
+# Migration Guide
+
+Learn how to make the move to Haystack 2.x from Haystack 1.x.
+
+This guide is designed for those with previous experience with Haystack and who are interested in understanding the differences between Haystack 1.x and Haystack 2.x. If you're new to Haystack, skip this page and proceed directly to Haystack 2.x [documentation](get-started.mdx).
+
+## Major Changes
+
+Haystack 2.x represents a significant overhaul of Haystack 1.x, and it's important to note that certain key concepts outlined in this section don't have a direct correlation between the two versions.
+
+### Package Name
+
+Haystack 1.x was distributed with a package called `farm-haystack`. To migrate your application, you must uninstall `farm-haystack` and install the new `haystack-ai` package for Haystack 2.x.
+
+:::warning
+Two versions of the project cannot coexist in the same Python environment.
+
+One of the options is to remove both packages if they are installed in the same environment, followed by installing only one of them:
+
+```bash
+pip uninstall -y farm-haystack haystack-ai
+pip install haystack-ai
+```
+:::
+
+### Nodes
+
+While Haystack 2.x continues to rely on the `Pipeline` abstraction, the elements linked in a pipeline graph are now referred to as just _components_, replacing the terms _nodes_ and _pipeline components_ used in the previous versions. The [_Migrating Components_](#migrating-components) paragraph below outlines which component in Haystack 2.x can be used as a replacement for a specific 1.x node.
+
+### Pipelines
+
+Pipelines continue to serve as the fundamental structure of all Haystack applications. While the concept of `Pipeline` abstraction remains consistent, Haystack 2.x introduces significant enhancements that address various limitations of its predecessor. For instance, the pipelines now support loops. Pipelines also offer greater flexibility in their input, which is no longer restricted to queries. The pipeline now allows to route the output of a component to multiple recipients. This increases flexibility, however, comes with notable differences in the pipeline definition process in Haystack 2.x compared to the previous version.
+
+In Haystack 1.x, a pipeline was built by adding one node after the other. In the resulting pipeline graph, edges are automatically added to connect those nodes in the order they were added.
+
+Building a pipeline in Haystack 2.x is a two-step process:
+
+1. Initially, components are added to the pipeline without any specific order by calling the `add_component` method.
+2. Subsequently, the components must be explicitly connected by calling the `connect` method to define the final graph.
+
+To migrate an existing pipeline, the first step is to go through the nodes and identify their counterparts in Haystack 2.x (see the following section, [_Migrating Components_](#migrating-components), for guidance). If all the nodes can be replaced by corresponding components, they have to be added to the pipeline with `add_component` and explicitly connected with the appropriate calls to `connect`. Here is an example:
+
+**Haystack 1.x**
+
+```python
+pipeline = Pipeline()
+
+node_1 = SomeNode()
+node_2 = AnotherNode()
+
+pipeline.add_node(node_1, name="Node_1", inputs=["Query"])
+pipeline.add_node(node_2, name="Node_2", inputs=["Node_1"])
+```
+
+**Haystack 2.x**
+
+```python
+pipeline = Pipeline()
+
+component_1 = SomeComponent()
+component_2 = AnotherComponent()
+
+pipeline.add_component("Comp_1", component_1)
+pipeline.add_component("Comp_2", component_2)
+
+pipeline.connect("Comp_1", "Comp_2")
+```
+
+In case a specific replacement component is not available for one of your nodes, migrating the pipeline might still be possible by:
+
+- Either [creating a custom component](../concepts/components/custom-components.mdx), or
+- Changing the pipeline logic, as the last resort.
+
+:::info
+Check out the [Pipelines](../concepts/pipelines.mdx) section of our 2.x documentation to understand how new pipelines work more granularly.
+:::
+
+### Document Stores
+
+The fundamental concept of Document Stores as gateways to access text and metadata stored in a database didn’t change in Haystack 2.x, but there are significant differences against Haystack 1.x.
+
+In Haystack 1.x, Document Stores were a special type of node that you can use in two ways:
+
+- As the last node in an indexing pipeline (such as a pipeline whose ultimate goal is storing data in a database).
+- As a normal Python instance passed to a Retriever node.
+
+In Haystack 2.x, the Document Store is not a component, so to migrate the two use cases above to version 2.x, you can respectively:
+
+- Replace the Document Store at the end of the pipeline with a [`DocumentWriter`](../pipeline-components/writers/documentwriter.mdx) component.
+- Identify the right Retriever component and create it passing the Document Store instance, same as it is in Haystack 1.x.
+
+### Retrievers
+
+Haystack 1.x provided a set of nodes that filter relevant documents from different data sources according to a given query. Each of those nodes implements a certain retrieval algorithm and supports one or more types of Document Stores. For example, the `BM25Retriever` node in Haystack 1.x can work seamlessly with OpenSearch and Elasticsearch but not with Qdrant; the `EmbeddingRetriever`, on the contrary, can work with all the three databases.
+
+In Haystack 2.x, the concept is flipped, and each Document Store provides one or more retriever components, depending on which retrieval methods the underlying vector database supports. For example, the `OpenSearchDocumentStore` comes with [two Retriever components](../document-stores/opensearch-document-store.mdx#supported-retrievers), one relying on BM25, and the other on vector similarity.
+
+To migrate a 1.x retrieval pipeline to 2.x, the first step is to identify the Document Store being used and replace the Retriever node with the corresponding Retriever component from Haystack 2.x with the Document Store of choice. For example, a `BM25Retriever` node using Elasticsearch in a Haystack 1.x pipeline should be replaced with the [`ElasticsearchBM25Retriever`](../pipeline-components/retrievers/elasticsearchbm25retriever.mdx) component.
+
+### PromptNode
+
+The `PromptNode` in Haystack 1.x represented the gateway to any Large Language Model (LLM) inference provider, whether it is locally available or remote. Based on the name of the model, Haystack infers the right provider to call and forward the query.
+
+In Haystack 2.x, the task of using LLMs is assigned to [Generators](../pipeline-components/generators.mdx). These are a set of components that are highly specialized and tailored for each inference provider.
+
+The first step when migrating a pipeline with a `PromptNode` is to identify the model provider used and to replace the node with two components:
+
+- A Generator component for the model provider of choice,
+- A `PromptBuilder` or `ChatPromptBuilder` component to build the prompt to be used.
+
+The [_Migration examples_](#migration-examples) section below shows how to port a `PromptNode` using OpenAI with a prompt template to a corresponding Haystack 2.x pipeline using the `OpenAIGenerator` in conjunction with a `PromptBuilder` component.
+
+### Agents
+
+The agentic approach facilitates the answering of questions that are significantly more complex than those typically addressed by extractive or generative question answering techniques.
+
+Haystack 1.x provided Agents, enabling the use of LLMs in a loop.
+
+Currently in Haystack 2.x, you can build Agents using three main elements in a pipeline: Chat Generators, ToolInvoker component, and Tools. A standalone Agent abstraction in Haystack 2.x is in an experimental phase.
+
+:::note Agents Documentation Page
+
+Take a look at our 2.x [Agents](../concepts/agents.mdx) documentation page for more information and detailed examples.
+:::
+
+### REST API
+
+Haystack 1.x enabled the deployment of pipelines through a RESTful API over HTTP. This feature is facilitated by a separate application named `rest_api` which is exclusively accessible in the form of a [source code on GitHub](https://github.com/deepset-ai/haystack/tree/v1.x/rest_api).
+
+Haystack 2.x takes the same RESTful approach, but in this case, the application to be used to deploy pipelines is called [Hayhooks](../development/hayhooks.mdx) and can be installed with `pip install hayhooks`.
+
+At the moment, porting an existing Haystack 1.x deployment using the `rest_api` project to Hayhooks would require a complete rewrite of the application.
+
+## Dependencies
+
+In order to minimize runtime errors, Haystack 1.x was distributed in a package that’s quite large, as it tries to set up the Python environment with as many dependencies as possible.
+
+In contrast, Haystack 2.x strives for a more streamlined approach, offering a minimal set of dependencies right out of the box. It features a system that issues a warning when an additional dependency is required, thereby providing the user with the necessary instructions.
+
+To make sure all the dependencies are satisfied when migrating a Haystack 1.x application to version 2.x, a good strategy is to run end-to-end tests and cover all the execution paths to ensure all the required dependencies are available in the target Python environment.
+
+## Migrating Components
+
+This table outlines which component (or a group of components) can be used to replace a certain node when porting a Haystack 1.x pipeline to the latest 2.x version. It’s important to note that when a Haystack 2.x replacement is not available, this doesn’t necessarily mean we are planning this feature.
+
+If you need help migrating a 1.x node without a 2.x counterpart, open an [issue](https://github.com/deepset-ai/haystack/issues) in Haystack GitHub repository.
+
+### Data Handling
+
+| Haystack 1.x | Description | Haystack 2.x |
+| --- | --- | --- |
+| Crawler | Scrapes text from websites. **Example usage:** To run searches on your website content. | Not Available |
+| DocumentClassifier | Classifies documents by attaching metadata to them. **Example usage:** Labeling documents by their characteristic (for example, sentiment). | [TransformersZeroShotDocumentClassifier](../pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx) |
+| DocumentLanguageClassifier | Detects the language of the documents you pass to it and adds it to the document metadata. | [DocumentLanguageClassifier](../pipeline-components/classifiers/documentlanguageclassifier.mdx) |
+| EntityExtractor | Extracts predefined entities out of a piece of text. **Example usage:** Named entity extraction (NER). | [NamedEntityExtractor](../pipeline-components/extractors/namedentityextractor.mdx) |
+| FileClassifier | Distinguishes between text, PDF, Markdown, Docx, and HTML files. **Example usage:** Routing files to appropriate converters (for example, it routes PDF files to `PDFToTextConverter`). | [FileTypeRouter](../pipeline-components/routers/filetyperouter.mdx) |
+| FileConverter | Cleans and splits documents in different formats. **Example usage:** In indexing pipelines, extracting text from a file and casting it into the Document class format. | [Converters](../pipeline-components/converters.mdx) |
+| PreProcessor | Cleans and splits documents. **Example usage:** Normalizing white spaces, getting rid of headers and footers, splitting documents into smaller ones. | [PreProcessors](../pipeline-components/preprocessors.mdx) |
+
+### Semantic Search
+
+| Haystack 1.x | Description | Haystack 2.x |
+| --- | --- | --- |
+| Ranker | Orders documents based on how relevant they are to the query. **Example usage:** In a query pipeline, after a keyword-based Retriever to rank the documents it returns. | [Rankers](../pipeline-components/rankers.mdx) |
+| Reader | Finds an answer by selecting a text span in documents. **Example usage:** In a query pipeline when you want to know the location of the answer. | [ExtractiveReader](../pipeline-components/readers/extractivereader.mdx) |
+| Retriever | Fetches relevant documents from the Document Store. **Example usage:** Coupling Retriever with a Reader in a query pipeline to speed up the search (the Reader only goes through the documents it gets from the Retriever). | [Retrievers](../pipeline-components/retrievers.mdx) |
+| QuestionGenerator | When given a document, it generates questions this document can answer. **Example usage:** Auto-suggested questions in your search app. | Prompt [Builders](../pipeline-components/builders.mdx) with dedicated prompt, [Generators](../pipeline-components/generators.mdx) |
+
+### Prompts and LLMs
+
+| Haystack 1.x | Description | Haystack 2.x |
+| --- | --- | --- |
+| PromptNode | Uses large language models to perform various NLP tasks in a pipeline or on its own. **Example usage:** It's a very versatile component that can perform tasks like summarization, question answering, translation, and more. | Prompt [Builders](../pipeline-components/builders.mdx),[Generators](../pipeline-components/generators.mdx) |
+
+### Routing
+
+| Haystack 1.x | Description | Haystack 2.x |
+| --- | --- | --- |
+| QueryClassifier | Categorizes queries. **Example usage:** Distinguishing between keyword queries and natural language questions and routing them to the Retrievers that can handle them best. | [TransformersZeroShotTextRouter](../pipeline-components/routers/transformerszeroshottextrouter.mdx) Were you already using Haystack 1.x?
+ +:::warning + +Installing `farm-haystack` and `haystack-ai` in the same Python environment (virtualenv, Colab, or system) causes problems. + +Installing both packages in the same environment can somehow work or fail in obscure ways. We suggest installing only one of these packages per Python environment. Make sure that you remove both packages if they are installed in the same environment, followed by installing only one of them: + +```bash +pip uninstall -y farm-haystack haystack-ai +pip install haystack-ai +``` + +If you have any questions, please reach out to us on the [GitHub Discussion](https://github.com/deepset-ai/haystack/discussions) or [Discord](https://discord.com/invite/VBpFzsgRVF). +::: + +[TransformersTextRouter](../pipeline-components/routers/transformerstextrouter.mdx) | +| RouteDocuments | Routes documents to different branches of your pipeline based on their content type or metadata field. **Example usage:** Routing table data to `TableReader` and text data to `TransfomersReader` for better handling. | [Routers](../pipeline-components/routers.mdx) | + +### Utility Components + +| Haystack 1.x | Description | Haystack 2.x | +| --- | --- | --- | +| DocumentMerger | Concatenates multiple documents into a single one. **Example usage: **Merge the documents to summarize in a summarization pipeline. | Prompt [Builders](../pipeline-components/builders.mdx) | +| Docs2Answers | Converts Documents into Answers. **Example usage:** When using REST API for document retrieval. REST API expects Answer as output, you can use `Doc2Answer` as the last node to convert the retrieved documents to answers. | [AnswerBuilder](../pipeline-components/builders/answerbuilder.mdx) | +| JoinAnswers | Takes answers returned by multiple components and joins them in a single list of answers. **Example usage:** For running queries on different document types (for example, tables and text), where the documents are routed to different readers, and each reader returns a separate list of answers. | [AnswerJoiner](../pipeline-components/joiners/answerjoiner.mdx) | +| JoinDocuments | Takes documents returned by different components and joins them to form one list of documents. **Example usage:** In document retrieval pipelines, where there are different types of documents, each routed to a different Retriever. Each Retriever returns a separate list of documents, and you can join them into one list using `JoinDocuments`. | [DocumentJoiner](../pipeline-components/joiners/documentjoiner.mdx) | +| Shaper | Currently functions mostly as `PromptNode` helper making sure the `PromptNode` input or output is correct. **Example usage:** In a question answering pipeline using `PromptNode`, where the `PromptTemplate` expects questions as input, while Haystack pipelines use query. You can use Shaper to rename queries to questions. | Prompt [Builders](../pipeline-components/builders.mdx) | +| Summarizer | Creates an overview of a document. **Example usage:** To get a glimpse of the documents the Retriever is returning. | Prompt [Builders](../pipeline-components/builders.mdx) with dedicated prompt, [Generators](../pipeline-components/generators.mdx) | +| TransformersImageToText | Generates captions for images. **Example usage:** Automatically generate captions for a list of images that you can later use in your knowledge base. | [VertexAIImageQA](../pipeline-components/generators/vertexaiimageqa.mdx) | +| Translator | Translates text from one language into another. **Example usage:** Running searches on documents in other languages. | Prompt [Builders](../pipeline-components/builders.mdx) with dedicated prompt, [Generators](../pipeline-components/generators.mdx) | + +### Extras + +| Haystack 1.x | Description | Haystack 2.x | +| --- | --- | --- | +| AnswerToSpeech | Converts text answers into speech answers. **Example usage:** Improving accessibility of your search system by providing a way to have the answer and its context read out loud. | [ElevenLabs](https://haystack.deepset.ai/integrations/elevenlabs) Integration | +| DocumentToSpeech | Converts text documents to speech documents. **Example usage:** Improving accessibility of a document retrieval pipeline by providing the option to read documents out loud. | [ElevenLabs](https://haystack.deepset.ai/integrations/elevenlabs) Integration | + +## Migration examples + +:::info +This section might grow as we assist users with their use cases. +::: + +### Indexing Pipeline + +
+
+
+
+Haystack 1.x
+ +```python +from haystack.document_stores import InMemoryDocumentStore +from haystack.nodes.file_classifier import FileTypeClassifier +from haystack.nodes.file_converter import TextConverter +from haystack.nodes.preprocessor import PreProcessor +from haystack.pipelines import Pipeline + +## Initialize a DocumentStore +document_store = InMemoryDocumentStore() + +## Indexing Pipeline +indexing_pipeline = Pipeline() + +## Makes sure the file is a TXT file (FileTypeClassifier node) +classifier = FileTypeClassifier() +indexing_pipeline.add_node(classifier, name="Classifier", inputs=["File"]) + +## Converts a file into text and performs basic cleaning (TextConverter node) +text_converter = TextConverter(remove_numeric_tables=True) +indexing_pipeline.add_node(text_converter, name="Text_converter", inputs=["Classifier.output_1"]) + +## Pre-processes the text by performing splits and adding metadata to the text (Preprocessor node) +preprocessor = PreProcessor( + clean_whitespace=True, + clean_empty_lines=True, + split_length=100, + split_overlap=50, + split_respect_sentence_boundary=True, +) +indexing_pipeline.add_node(preprocessor, name="Preprocessor", inputs=["Text_converter"]) + +## - Writes the resulting documents into the document store +indexing_pipeline.add_node(document_store, name="Document_Store", inputs=["Preprocessor"]) + +## Then we run it with the documents and their metadata as input +result = indexing_pipeline.run(file_paths=file_paths, meta=files_metadata) +``` + +
+
+
+
+### Query Pipeline
+
+Haystack 2.x
+ +```python +from haystack import Pipeline +from haystack.components.routers import FileTypeRouter +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.components.converters import TextFileToDocument +from haystack.components.preprocessors import DocumentCleaner, DocumentSplitter +from haystack.components.writers import DocumentWriter + +## Initialize a DocumentStore +document_store = InMemoryDocumentStore() + +## Indexing Pipeline +indexing_pipeline = Pipeline() + +## Makes sure the file is a TXT file (FileTypeRouter component) +classifier = FileTypeRouter(mime_types=["text/plain"]) +indexing_pipeline.add_component("file_type_router", classifier) + +## Converts a file into a Document (TextFileToDocument component) +text_converter = TextFileToDocument() +indexing_pipeline.add_component("text_converter", text_converter) + +## Performs basic cleaning (DocumentCleaner component) +cleaner = DocumentCleaner( + remove_empty_lines=True, + remove_extra_whitespaces=True, +) +indexing_pipeline.add_component("cleaner", cleaner) + +## Pre-processes the text by performing splits and adding metadata to the text (DocumentSplitter component) +preprocessor = DocumentSplitter( + split_by="passage", + split_length=100, + split_overlap=50 +) +indexing_pipeline.add_component("preprocessor", preprocessor) + +## - Writes the resulting documents into the document store +indexing_pipeline.add_component("writer", DocumentWriter(document_store)) + +## Connect all the components +indexing_pipeline.connect("file_type_router.text/plain", "text_converter") +indexing_pipeline.connect("text_converter", "cleaner") +indexing_pipeline.connect("cleaner", "preprocessor") +indexing_pipeline.connect("preprocessor", "writer") + +## Then we run it with the documents and their metadata as input +result = indexing_pipeline.run({"file_type_router": {"sources": file_paths}}) +``` + +
+
+
+
+Haystack 1.x
+ +```python +from haystack.document_stores import InMemoryDocumentStore +from haystack.pipelines import ExtractiveQAPipeline +from haystack import Document +from haystack.nodes import BM25Retriever +from haystack.nodes import FARMReader + +document_store = InMemoryDocumentStore(use_bm25=True) +document_store.write_documents([ + Document(content="Paris is the capital of France."), + Document(content="Berlin is the capital of Germany."), + Document(content="Rome is the capital of Italy."), + Document(content="Madrid is the capital of Spain."), +]) + +retriever = BM25Retriever(document_store=document_store) +reader = FARMReader(model_name_or_path="deepset/roberta-base-squad2") +extractive_qa_pipeline = ExtractiveQAPipeline(reader, retriever) + +query = "What is the capital of France?" +result = extractive_qa_pipeline.run( + query=query, + params={ + "Retriever": {"top_k": 10}, + "Reader": {"top_k": 5} + } +) +``` + +
+
+
+
+### RAG Pipeline
+
+Haystack 2.x
+ +```python +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack import Document, Pipeline +from haystack.components.retrievers.in_memory import InMemoryBM25Retriever +from haystack.components.readers import ExtractiveReader + +document_store = InMemoryDocumentStore() +document_store.write_documents([ + Document(content="Paris is the capital of France."), + Document(content="Berlin is the capital of Germany."), + Document(content="Rome is the capital of Italy."), + Document(content="Madrid is the capital of Spain."), +]) + +retriever = InMemoryBM25Retriever(document_store) +reader = ExtractiveReader(model="deepset/roberta-base-squad2") +extractive_qa_pipeline = Pipeline() +extractive_qa_pipeline.add_component("retriever", retriever) +extractive_qa_pipeline.add_component("reader", reader) +extractive_qa_pipeline.connect("retriever", "reader") + +query = "What is the capital of France?" +result = extractive_qa_pipeline.run(data={ + "retriever": {"query": query, "top_k": 3}, + "reader": {"query": query, "top_k": 2} +}) +``` + +
+
+
+
+Haystack 1.x
+ +```python +from datasets import load_dataset + +from haystack.pipelines import Pipeline +from haystack.document_stores import InMemoryDocumentStore +from haystack.nodes import EmbeddingRetriever, PromptNode, PromptTemplate, AnswerParser + +document_store = InMemoryDocumentStore(embedding_dim=384) +dataset = load_dataset("bilgeyucel/seven-wonders", split="train") +document_store.write_documents(dataset) +retriever = EmbeddingRetriever(embedding_model="sentence-transformers/all-MiniLM-L6-v2", document_store=document_store, top_k=2) +document_store.update_embeddings(retriever) + +rag_prompt = PromptTemplate( + prompt="""Synthesize a comprehensive answer from the following text for the given question. + Provide a clear and concise response that summarizes the key points and information presented in the text. + Your answer should be in your own words and be no longer than 50 words. + \n\n Related text: {join(documents)} \n\n Question: {query} \n\n Answer:""", + output_parser=AnswerParser(), +) + +prompt_node = PromptNode(model_name_or_path="gpt-3.5-turbo", api_key=OPENAI_API_KEY, default_prompt_template=rag_prompt) + +pipe = Pipeline() +pipe.add_node(component=retriever, name="retriever", inputs=["Query"]) +pipe.add_node(component=prompt_node, name="prompt_node", inputs=["retriever"]) + +output = pipe.run(query="What does Rhodes Statue look like?") +``` + +
+
+
+
+## Documentation and Tutorials for Haystack 1.x
+
+You can access old tutorials in the [GitHub history](https://github.com/deepset-ai/haystack-tutorials/tree/5917718cbfbb61410aab4121ee6fe754040a5dc7) and download the Haystack 1.x documentation as a [ZIP file](https://core-engineering.s3.eu-central-1.amazonaws.com/public/docs/haystack-v1-docs.zip).
+
+The ZIP file contains documentation for all minor releases from version 1.0 to 1.26.
+
+To download documentation for a specific release, replace the version number in the following URL: `https://core-engineering.s3.eu-central-1.amazonaws.com/public/docs/v1.26.zip`.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/overview/telemetry.mdx b/docs-website/versioned_docs/version-2.20-unstable/overview/telemetry.mdx
new file mode 100644
index 0000000000..206d12fa73
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/overview/telemetry.mdx
@@ -0,0 +1,76 @@
+---
+title: "Telemetry"
+id: telemetry
+slug: "/telemetry"
+description: "Haystack relies on anonymous usage statistics to continuously improve. That's why some basic information, like the type of Document Store used, is shared automatically."
+---
+
+# Telemetry
+
+Haystack relies on anonymous usage statistics to continuously improve. That's why some basic information, like the type of Document Store used, is shared automatically.
+
+## What Information Is Shared?
+
+Telemetry in Haystack comprises anonymous usage statistics of base components, such as `DocumentStore`, `Retriever`, `Reader`, or any other pipeline component. We receive an event every time these components are initialized. This way, we know which components are most relevant to our community. For the same reason, an event is also sent when one of the tutorials is executed.
+
+Each event contains an anonymous, randomly generated user ID (`uuid`) and a collection of properties about your execution environment. They **never** contain properties that can be used to identify you, such as:
+
+- IP addresses
+- Hostnames
+- File paths
+- Queries
+- Document contents
+
+By taking the above steps, we ensure that only anonymized data is transmitted to our telemetry server.
+
+Here is an exemplary event that is sent when tutorial 1 is executed by running `Tutorial1_Basic_QA_Pipeline.py`:
+
+```json
+{
+ "event": "tutorial 1 executed",
+ "distinct_id": "9baab867-3bc8-438c-9974-a192c9d53cd1",
+ "properties": {
+ "os_family": "Darwin",
+ "os_machine": "arm64",
+ "os_version": "21.3.0",
+ "haystack_version": "1.0.0",
+ "python_version": "3.9.6",
+ "torch_version": "1.9.0",
+ "transformers_version": "4.13.0",
+ "execution_env": "script",
+ "n_gpu": 0,
+ },
+}
+```
+
+Our telemetry code can be directly inspected on [GitHub](https://github.com/deepset-ai/haystack/blob/5d66d040cc303ab49225587cd61290f1987a5d1f/haystack/telemetry/_telemetry.py).
+
+## How Does Telemetry Help?
+
+Thanks to telemetry, we can understand the needs of the community: _"What pipeline nodes are most popular?", "Should we focus on supporting one specific Document Store?", "How many people use Haystack on Windows?"_ are some of the questions telemetry helps us answer. Metadata about the operating system and installed dependencies allows us to quickly identify and address issues caused by specific setups.
+
+In short, by sharing this information, you enable us to continuously improve Haystack for everyone.
+
+## How Can I Opt Out?
+
+You can disable telemetry with one of the following methods:
+
+### Through an Environment Variable
+
+You can disable telemetry by setting the environment variable `HAYSTACK_TELEMETRY_ENABLED` to `"False"` .
+
+### Using a Bash Shell
+
+If you are using a bash shell, add the following line to the file `~/.bashrc` to disable telemetry: `export HAYSTACK_TELEMETRY_ENABLED=False`.
+
+### Using zsh
+
+If you are using zsh as your shell, for example, on macOS, add the following line to the file `~/.zshrc`: `export HAYSTACK_TELEMETRY_ENABLED=False`.
+
+### On Windows
+
+To disable telemetry on Windows, set a user-level environment variable by running this command in the standard command prompt: `setx HAYSTACK_TELEMETRY_ENABLED "False"`.
+
+Alternatively, run the following command in Windows PowerShell: `[Environment]::SetEnvironmentVariable("HAYSTACK_TELEMETRY_ENABLED","False","User")`.
+
+You might need to restart the operating system for the command to take effect.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/agents-1/agent.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/agents-1/agent.mdx
new file mode 100644
index 0000000000..f4ac0e2fed
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/agents-1/agent.mdx
@@ -0,0 +1,200 @@
+---
+title: "Agent"
+id: agent
+slug: "/agent"
+description: "The `Agent` component is a tool-using agent that interacts with chat-based LLMs and tools to solve complex queries iteratively. It can execute external tools, manage state across multiple LLM calls, and stop execution based on configurable `exit_conditions`."
+---
+
+# Agent
+
+The `Agent` component is a tool-using agent that interacts with chat-based LLMs and tools to solve complex queries iteratively. It can execute external tools, manage state across multiple LLM calls, and stop execution based on configurable `exit_conditions`.
+
+Haystack 2.x
+ +```python +from datasets import load_dataset + +from haystack import Document, Pipeline +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.components.builders import PromptBuilder +from haystack.components.generators import OpenAIGenerator +from haystack.components.embedders import SentenceTransformersDocumentEmbedder +from haystack.components.embedders import SentenceTransformersTextEmbedder +from haystack.components.retrievers import InMemoryEmbeddingRetriever + +document_store = InMemoryDocumentStore() +dataset = load_dataset("bilgeyucel/seven-wonders", split="train") +embedder = SentenceTransformersDocumentEmbedder("sentence-transformers/all-MiniLM-L6-v2") +embedder.warm_up() +output = embedder.run([Document(**ds) for ds in dataset]) +document_store.write_documents(output.get("documents")) + +template = """ +Given the following information, answer the question. + +Context: +{% for document in documents %} + {{ document.content }} +{% endfor %} + +Question: {{question}} +Answer: +""" +prompt_builder = PromptBuilder(template=template) + +retriever = InMemoryEmbeddingRetriever(document_store=document_store, top_k=2) +generator = OpenAIGenerator(model="gpt-3.5-turbo") +query_embedder = SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2") + +basic_rag_pipeline = Pipeline() +basic_rag_pipeline.add_component("text_embedder", query_embedder) +basic_rag_pipeline.add_component("retriever", retriever) +basic_rag_pipeline.add_component("prompt_builder", prompt_builder) +basic_rag_pipeline.add_component("llm", generator) + +basic_rag_pipeline.connect("text_embedder.embedding", "retriever.query_embedding") +basic_rag_pipeline.connect("retriever", "prompt_builder.documents") +basic_rag_pipeline.connect("prompt_builder", "llm") + +query = "What does Rhodes Statue look like?" +output = basic_rag_pipeline.run({"text_embedder": {"text": query}, "prompt_builder": {"question": query}}) +``` + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) or user input |
+| **Mandatory init variables** | `chat_generator`: An instance of a Chat Generator that supports tools |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx)s |
+| **Output variables** | `messages`: Chat history with tool and model responses |
+| **API reference** | [Agents](/reference/agents-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/agents/agent.py |
+
+
+
+## Overview
+
+The `Agent` component is a loop-based system that uses a chat-based large language model (LLM) and external tools to solve complex user queries. It works iteratively—calling tools, updating state, and generating prompts—until one of the configurable `exit_conditions` is met.
+
+It can:
+
+- Dynamically select tools based on user input,
+- Maintain and validate runtime state using a schema,
+- Stream token-level outputs from the LLM.
+
+The `Agent` returns a dictionary containing:
+
+- `messages`: the full conversation history,
+- Additional dynamic keys based on `state_schema`.
+
+### Parameters
+
+To initialize the `Agent` component, you need to provide it with an instance of a Chat Generator that supports tools. You can pass a list of [tools](../../tools/tool.mdx) or [`ComponentTool`](../../tools/componenttool.mdx) instances, or wrap them in a [`Toolset`](../../tools/toolset.mdx) to manage them as a group.
+
+You can additionally configure:
+
+- A `system_prompt` for your Agent,
+- A list of `exit_conditions` strings that will cause the agent to return. Can be either:
+ - “text”, which means that the Agent will exit as soon as the LLM replies only with a text response,
+ - or specific tool names.
+- A `state_schema` for one agent invocation run. It defines extra information – such as documents or context – that tools can read from or write to during execution. You can use this schema to pass parameters that tools can both produce and consume.
+- `streaming_callback` to stream the tokens from the LLM directly in output.
+
+:::info
+For a complete list of available parameters, refer to the [Agents API Documentation](/reference/agents-api).
+:::
+
+### Streaming
+
+You can stream output as it’s generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+## Configure any `Generator` or `ChatGenerator` with a streaming callback
+component = SomeGeneratorOrChatGenerator(streaming_callback=print_streaming_chunk)
+
+## If this is a `ChatGenerator`, pass a list of messages:
+## from haystack.dataclasses import ChatMessage
+## component.run([ChatMessage.from_user("Your question here")])
+
+## If this is a (non-chat) `Generator`, pass a prompt:
+## component.run({"prompt": "Your prompt here"})
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](../generators/guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools.tool import Tool
+from haystack.components.agents import Agent
+from typing import List
+
+## Tool Function
+def calculate(expression: str) -> dict:
+ try:
+ result = eval(expression, {"__builtins__": {}})
+ return {"result": result}
+ except Exception as e:
+ return {"error": str(e)}
+
+## Tool Definition
+calculator_tool = Tool(
+ name="calculator",
+ description="Evaluate basic math expressions.",
+ parameters={
+ "type": "object",
+ "properties": {
+ "expression": {"type": "string", "description": "Math expression to evaluate"}
+ },
+ "required": ["expression"]
+ },
+ function=calculate,
+ outputs_to_state={"calc_result": {"source": "result"}}
+)
+
+## Agent Setup
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(),
+ tools=[calculator_tool],
+ exit_conditions=["calculator"],
+ state_schema={
+ "calc_result": {"type": int},
+ }
+)
+
+## Run the Agent
+agent.warm_up()
+response = agent.run(messages=[ChatMessage.from_user("What is 7 * (4 + 2)?")])
+
+## Output
+print(response["messages"])
+print("Calc Result:", response.get("calc_result"))
+```
+
+### In a pipeline
+
+The example pipeline below creates a database assistant using `OpenAIChatGenerator`, `LinkContentFetcher`, and custom database tool. It reads the given URL and processes the page content, then builds a prompt for the AI. The assistant uses this information to write people's names and titles from the given page to the database.
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.converters.html import HTMLToDocument
+from haystack.components.fetchers.link_content import LinkContentFetcher
+from haystack.core.pipeline import Pipeline
+from haystack.tools import tool
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from typing import Optional
+from haystack.dataclasses import ChatMessage, Document
+
+document_store = InMemoryDocumentStore() # create a document store or an SQL database
+
+@tool
+def add_database_tool(name: str, surname: str, job_title: Optional[str], other: Optional[str]):
+ """Use this tool to add names to the database with information about them"""
+ document_store.write_documents([Document(content=name + " " + surname + " " + (job_title or ""), meta={"other":other})])
+ return
+
+database_asistant = Agent(
+ chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+ tools=[add_database_tool],
+ system_prompt="""
+ You are a database assistant.
+ Your task is to extract the names of people mentioned in the given context and add them to a knowledge base, along with additional relevant information about them that can be extracted from the context.
+ Do not use you own knowledge, stay grounded to the given context.
+ Do not ask the user for confirmation. Instead, automatically update the knowledge base and return a brief summary of the people added, including the information stored for each.
+ """,
+ exit_conditions=["text"],
+ max_agent_steps=100,
+ raise_on_tool_invocation_failure=False
+)
+
+extraction_agent = Pipeline()
+extraction_agent.add_component("fetcher", LinkContentFetcher())
+extraction_agent.add_component("converter", HTMLToDocument())
+extraction_agent.add_component("builder", ChatPromptBuilder(
+ template=[ChatMessage.from_user("""
+ {% for doc in docs %}
+ {{ doc.content|default|truncate(25000) }}
+ {% endfor %}
+ """)],
+ required_variables=["docs"]
+))
+
+extraction_agent.add_component("database_agent", database_asistant)
+extraction_agent.connect("fetcher.streams", "converter.sources")
+extraction_agent.connect("converter.documents", "builder.docs")
+extraction_agent.connect("builder", "database_agent")
+
+agent_output = extraction_agent.run({"fetcher":{"urls":["https://en.wikipedia.org/wiki/Deepset"]}})
+
+print(agent_output["database_agent"]["messages"][-1].text)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Build a GitHub Issue Resolver Agent](https://haystack.deepset.ai/cookbook/github_issue_resolver_agent)
+
+📓 Tutorial: [Build a Tool-Calling Agent](https://haystack.deepset.ai/tutorials/43_building_a_tool_calling_agent)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio.mdx
new file mode 100644
index 0000000000..4cf9c334ea
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio.mdx
@@ -0,0 +1,15 @@
+---
+title: "Audio"
+id: audio
+slug: "/audio"
+description: "Use these components to work with audio in Haystack by transcribing files or converting text to audio."
+---
+
+# Audio
+
+Use these components to work with audio in Haystack by transcribing files or converting text to audio.
+
+| Name | Description |
+| --- | --- |
+| [LocalWhisperTranscriber](audio/localwhispertranscriber.mdx) | Transcribe audio files using OpenAI's Whisper model using your local installation of Whisper. |
+| [RemoteWhisperTranscriber](audio/remotewhispertranscriber.mdx) | Transcribe audio files using OpenAI's Whisper model. |
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/external-integrations-audio.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/external-integrations-audio.mdx
new file mode 100644
index 0000000000..c1ac4ce894
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/external-integrations-audio.mdx
@@ -0,0 +1,15 @@
+---
+title: "External Integrations"
+id: external-integrations-audio
+slug: "/external-integrations-audio"
+description: "External integrations that enable working with audio in Haystack by transcribing files or converting text to audio."
+---
+
+# External Integrations
+
+External integrations that enable working with audio in Haystack by transcribing files or converting text to audio.
+
+| Name | Description |
+| --- | --- |
+| [AssemblyAI](https://haystack.deepset.ai/integrations/assemblyai) | Perform speech recognition, speaker diarization and summarization. |
+| [Elevenlabs](https://haystack.deepset.ai/integrations/elevenlabs) | Convert text to speech using ElevenLabs’ API. |
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/localwhispertranscriber.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/localwhispertranscriber.mdx
new file mode 100644
index 0000000000..0aa59c3663
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/localwhispertranscriber.mdx
@@ -0,0 +1,81 @@
+---
+title: "LocalWhisperTranscriber"
+id: localwhispertranscriber
+slug: "/localwhispertranscriber"
+description: "Use `LocalWhisperTranscriber` to transcribe audio files using OpenAI's Whisper model using your local installation of Whisper."
+---
+
+# LocalWhisperTranscriber
+
+Use `LocalWhisperTranscriber` to transcribe audio files using OpenAI's Whisper model using your local installation of Whisper.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | As the first component in an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of paths or binary streams that you want to transcribe |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Audio](/reference/audio-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/audio/whisper_local.py |
+
+
+
+## Overview
+
+The component also needs to know which Whisper model to work with. Specify this in the `model` parameter when initializing the component. All transcription is completed on the executing machine, and the audio is never sent to a third-party provider.
+
+See other optional parameters you can specify in our [API documentation](/reference/audio-api).
+
+See the [Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper [GitHub repo](https://github.com/openai/whisper) for the supported audio formats and languages.
+
+To work with the `LocalWhisperTranscriber`, install torch and [Whisper](https://github.com/openai/whisper) first with the following commands:
+
+```python
+pip install 'transformers[torch]'
+pip install -U openai-whisper
+```
+
+## Usage
+
+### On its own
+
+Here’s an example of how to use `LocalWhisperTranscriber` on its own:
+
+```python
+import requests
+from haystack.components.audio import LocalWhisperTranscriber
+
+response = requests.get("https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3")
+with open("kennedy_speech.mp3", "wb") as file:
+ file.write(response.content)
+
+transcriber = LocalWhisperTranscriber(model="tiny")
+transcriber.warm_up()
+
+transcription = transcriber.run(sources=["./kennedy_speech.mp3"])
+print(transcription["documents"][0].content)
+```
+
+### In a pipeline
+
+The pipeline below fetches an audio file from a specified URL and transcribes it. It first retrieves the audio file using `LinkContentFetcher`, then transcribes the audio into text with `LocalWhisperTranscriber`, and finally outputs the transcription text.
+
+```python
+from haystack.components.audio import LocalWhisperTranscriber
+from haystack.components.fetchers import LinkContentFetcher
+from haystack import Pipeline
+
+pipe = Pipeline()
+pipe.add_component("fetcher", LinkContentFetcher())
+pipe.add_component("transcriber", LocalWhisperTranscriber(model="tiny"))
+
+pipe.connect("fetcher", "transcriber")
+result = pipe.run(
+ data={"fetcher": {"urls": ["https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3"]}})
+print(result["transcriber"]["documents"][0].content)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Multilingual RAG from a podcast with Whisper, Qdrant and Mistral](https://haystack.deepset.ai/cookbook/multilingual_rag_podcast)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/remotewhispertranscriber.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/remotewhispertranscriber.mdx
new file mode 100644
index 0000000000..5c002c4795
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/remotewhispertranscriber.mdx
@@ -0,0 +1,89 @@
+---
+title: "RemoteWhisperTranscriber"
+id: remotewhispertranscriber
+slug: "/remotewhispertranscriber"
+description: "Use `RemoteWhisperTranscriber` to transcribe audio files using OpenAI's Whisper model."
+---
+
+# RemoteWhisperTranscriber
+
+Use `RemoteWhisperTranscriber` to transcribe audio files using OpenAI's Whisper model.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | As the first component in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with an environment variable `OPENAI_API_KEY`. |
+| **Mandatory run variables** | `sources`: A list of paths or binary streams that you want to transcribe |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Audio](/reference/audio-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/audio/whisper_remote.py |
+
+
+
+## Overview
+
+`RemoteWhisperTranscriber` works with OpenAI-compatible clients and isn't limited to just OpenAI as a provider. For example, [Groq](https://console.groq.com/docs/speech-text) offers a drop-in replacement that can be used as well. You can set the API key in one of two ways:
+
+1. Through the `api_key` initialization parameter, where the key is resolved using [Secret API](../../concepts/secret-management.mdx).
+2. By setting it in the `OPENAI_API_KEY` environment variable, which the system will use to access the key.
+
+```python
+from haystack.components.audio import RemoteWhisperTranscriber
+
+transcriber = RemoteWhisperTranscriber()
+```
+
+Additionally, the component requires the following parameters to work:
+
+- `model` specifies the Whisper model.
+- `api_base_url` specifies the OpenAI base URL and defaults to `"https://api.openai.com/v1"`. If you are using Whisper provider other than OpenAI set this parameter according to provider's documentation.
+
+See other optional parameters in our [API documentation](/reference/audio-api).
+
+See the [Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper [GitHub repo](https://github.com/openai/whisper) for the supported audio formats and languages.
+
+## Usage
+
+### On its own
+
+Here’s an example of how to use `RemoteWhisperTranscriber` to transcribe a local file:
+
+```python
+import requests
+from haystack.components.audio import RemoteWhisperTranscriber
+
+response = requests.get("https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3")
+with open("kennedy_speech.mp3", "wb") as file:
+ file.write(response.content)
+
+transcriber = RemoteWhisperTranscriber()
+transcription = transcriber.run(sources=["./kennedy_speech.mp3"])
+
+print(transcription["documents"][0].content)
+```
+
+### In a pipeline
+
+The pipeline below fetches an audio file from a specified URL and transcribes it. It first retrieves the audio file using `LinkContentFetcher`, then transcribes the audio into text with `RemoteWhisperTranscriber`, and finally outputs the transcription text.
+
+```python
+from haystack.components.audio import RemoteWhisperTranscriber
+from haystack.components.fetchers import LinkContentFetcher
+from haystack import Pipeline
+
+pipe = Pipeline()
+pipe.add_component("fetcher", LinkContentFetcher())
+pipe.add_component("transcriber", RemoteWhisperTranscriber())
+
+pipe.connect("fetcher", "transcriber")
+result = pipe.run(
+ data={"fetcher": {"urls": ["https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3"]}})
+print(result["transcriber"]["documents"][0].content)
+
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Multilingual RAG from a podcast with Whisper, Qdrant and Mistral](https://haystack.deepset.ai/cookbook/multilingual_rag_podcast)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders.mdx
new file mode 100644
index 0000000000..49b72d883c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders.mdx
@@ -0,0 +1,13 @@
+---
+title: "Builders"
+id: builders
+slug: "/builders"
+---
+
+# Builders
+
+| Component | Description |
+| --- | --- |
+| [AnswerBuilder](builders/answerbuilder.mdx) | Creates `GeneratedAnswer` objects from the query and the answer. |
+| [PromptBuilder](builders/promptbuilder.mdx) | Renders prompt templates with given parameters. |
+| [ChatPromptBuilder](builders/chatpromptbuilder.mdx) | PromptBuilder for chat messages. |
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/answerbuilder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/answerbuilder.mdx
new file mode 100644
index 0000000000..6d3a08836d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/answerbuilder.mdx
@@ -0,0 +1,90 @@
+---
+title: "AnswerBuilder"
+id: answerbuilder
+slug: "/answerbuilder"
+description: "Use this component in pipelines that contain a Generator to parse its replies."
+---
+
+# AnswerBuilder
+
+Use this component in pipelines that contain a Generator to parse its replies.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Use in pipelines (such as a RAG pipeline) after a [Generator](../generators.mdx) component to create [`GeneratedAnswer`](../../concepts/data-classes.mdx#generatedanswer) objects from its replies. |
+| **Mandatory run variables** | `query`: A query string
`replies`: A list of strings, or a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects that are replies from a Generator | +| **Output variables** | `answers`: A list of `GeneratedAnswer` objects | +| **API reference** | [Builders](/reference/builders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/builders/answer_builder.py | + +
+
+## Overview
+
+`AnswerBuilder` takes a query and the replies a Generator returns as input and parses them into `GeneratedAnswer` objects. Optionally, it also takes documents and metadata from the Generator as inputs to enrich the `GeneratedAnswer` objects.
+
+The `AnswerBuilder` works with both Chat and non-Chat Generators.
+
+The optional `pattern` parameter defines how to extract answer texts from replies. It needs to be a regular expression with a maximum of one capture group. If a capture group is present, the text matched by the capture group is used as the answer. If no capture group is present, the whole match is used as the answer. If no `pattern` is set, the whole reply is used as the answer text.
+
+The optional `reference_pattern` parameter can be set to a regular expression that parses referenced documents from the replies so that only those referenced documents are listed in the `GeneratedAnswer` objects. Haystack assumes that documents are referenced by their index in the list of input documents and that indices start at 1. For example, if you set the `reference_pattern` to _`\\[(\\d+)\\]`,_ it finds “1” in a string "This is an answer[1]". If `reference_pattern` is not set, all input documents are listed in the `GeneratedAnswer` objects.
+
+## Usage
+
+### On its own
+
+Below is an example where we’re using the `AnswerBuilder` to parse a string that could be the reply received from a Generator using a custom regular expression. Any text other than the answer will not be included in the `GeneratedAnswer` object constructed by the builder.
+
+```python
+from haystack.components.builders import AnswerBuilder
+
+builder = AnswerBuilder(pattern="Answer: (.*)")
+builder.run(query="What's the answer?", replies=["This is an argument. Answer: This is the answer."])
+```
+
+### In a pipeline
+
+Below is an example of a RAG pipeline where we use an `AnswerBuilder` to create `GeneratedAnswer` objects from the replies returned by a Generator. In addition to the text of the reply, these objects also hold the query, the referenced docs, and metadata returned by the Generator.
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.utils import Secret
+from haystack.dataclasses import ChatMessage
+
+prompt_template = [
+ ChatMessage.from_system("You are a helpful assistant."),
+ ChatMessage.from_user(
+ "Given these documents, answer the question.\nDocuments:\n"
+ "{% for doc in documents %}{{ doc.content }}{% endfor %}\n"
+ "Question: {{query}}\nAnswer:"
+ )
+]
+
+p = Pipeline()
+p.add_component(instance=InMemoryBM25Retriever(document_store=InMemoryDocumentStore()), name="retriever")
+p.add_component(instance=ChatPromptBuilder(template=prompt_template, required_variables={"query", "documents"}), name="prompt_builder")
+p.add_component(instance=OpenAIChatGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")), name="llm")
+p.add_component(instance=AnswerBuilder(), name="answer_builder")
+p.connect("retriever", "prompt_builder.documents")
+p.connect("prompt_builder", "llm.messages")
+p.connect("llm.replies", "answer_builder.replies")
+p.connect("retriever", "answer_builder.documents")
+
+query = "What is the capital of France?"
+result = p.run(
+ {
+ "retriever": {"query": query},
+ "prompt_builder": {"query": query},
+ "answer_builder": {"query": query},
+ }
+)
+
+print(result)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/chatpromptbuilder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/chatpromptbuilder.mdx
new file mode 100644
index 0000000000..f6dea30de1
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/chatpromptbuilder.mdx
@@ -0,0 +1,359 @@
+---
+title: "ChatPromptBuilder"
+id: chatpromptbuilder
+slug: "/chatpromptbuilder"
+description: "This component constructs prompts dynamically by processing chat messages."
+---
+
+# ChatPromptBuilder
+
+This component constructs prompts dynamically by processing chat messages.
+
+`replies`: A list of strings, or a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects that are replies from a Generator | +| **Output variables** | `answers`: A list of `GeneratedAnswer` objects | +| **API reference** | [Builders](/reference/builders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/builders/answer_builder.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [Generator](../generators.mdx) |
+| **Mandatory init variables** | `template`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects or a special string template. Needs to be provided either during init or run. |
+| **Mandatory run variables** | `**kwargs`: Any strings that should be used to render the prompt template. See [Variables](#variables) section for more details. |
+| **Output variables** | `prompt`: A dynamically constructed prompt |
+| **API reference** | [Builders](/reference/builders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/builders/chat_prompt_builder.py |
+
+
+
+## Overview
+
+The `ChatPromptBuilder` component creates prompts using static or dynamic templates written in [Jinja2](https://palletsprojects.com/p/jinja/) syntax, by processing a list of chat messages or a special string template. The templates contain placeholders like `{{ variable }}` that are filled with values provided during runtime. You can use it for static prompts set at initialization or change the templates and variables dynamically while running.
+
+To use it, start by providing a list of `ChatMessage` objects or a special string as the template.
+
+[`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) is a data class that includes message content, a role (who generated the message, such as `user`, `assistant`, `system`, `tool`), and optional metadata.
+
+The builder looks for placeholders in the template and identifies the required variables. You can also list these variables manually. During runtime, the `run` method takes the template and the variables, fills in the placeholders, and returns the completed prompt. If required variables are missing. If the template is invalid, the builder raises an error.
+
+For example, you can create a simple translation prompt:
+
+```python
+template = [ChatMessage.from_user("Translate to {{ target_language }}: {{ text }}")]
+builder = ChatPromptBuilder(template=template)
+result = builder.run(target_language="French", text="Hello, how are you?")
+```
+
+Or you can also replace the template at runtime with a new one:
+
+```python
+new_template = [ChatMessage.from_user("Summarize in {{ target_language }}: {{ content }}")]
+result = builder.run(template=new_template, target_language="English", content="A detailed paragraph.")
+```
+
+### Variables
+
+The template variables found in the init template are used as input types for the component. If there are no `required_vairables` set, all variables are considered optional by default. In this case, any missing variables are replaced with empty strings, which can lead to unintended behavior, especially in complex pipelines.
+
+Use `required_variables` and `variables` to specify the input types and required variables:
+
+- `required_variables`
+ - Defines which template variables must be provided when the component runs.
+ - If any required variable is missing, the component raises an error and halts execution.
+ - You can:
+ - Pass a list of required variable names (such as `["name"]`), or
+ - Use `"*"` to mark all variables in the template as required.
+
+- `variables`
+ - Lists all variables that can appear in the template, whether required or optional.
+ - Optional variables that aren't provided are replaced with an empty string in the rendered prompt.
+ - This allows partial prompts to be constructed without errors, unless a variable is marked as required.
+
+In the example below, only _name_ is required to run the component, while _topic_ is only an optional variable:
+
+```python
+template = [ChatMessage.from_user("Hello, {{ name }}. How can I assist you with {{ topic }}?")]
+
+builder = ChatPromptBuilder(template=template, required_variables=["name"], variables=["name", "topic"])
+
+result = builder.run(name="Alice")
+## Output: "Hello, Alice. How can I assist you with ?"
+```
+
+The components only waits for the required inputs before running.
+
+### Roles
+
+A [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) represents a single message in the conversation and can have one of three class methods that build the chat messages: `from_user`, `from_system`, or `from_assistant`. `from_user` messages are inputs provided by the user, such as a query or request. `from_system` messages provide context or instructions to guide the LLM’s behavior, such as setting a tone or purpose for the conversation. `from_assistant` defines the expected or actual response from the LLM.
+
+Here’s how the roles work together in a `ChatPromptBuilder`:
+
+```python
+system_message = ChatMessage.from_system("You are an assistant helping tourists in {{ language }}.")
+
+user_message = ChatMessage.from_user("What are the best places to visit in {{ city }}?")
+
+assistant_message = ChatMessage.from_assistant("The best places to visit in {{ city }} include the Eiffel Tower, Louvre Museum, and Montmartre.")
+```
+
+### String Templates
+
+Instead of a list of `ChatMessage` objects, you can also express the template as a special string.
+
+This template format allows you to define `ChatMessage` sequences using Jinja2 syntax. Each `{% message %}` block defines a single message with a specific role, and you can insert dynamic content using `{{ variables }}`.
+
+Compared to using a list of `ChatMessage`s, this format is more flexible and allows including structured parts like images in the templatized `ChatMessage`; to better understand this use case, check out the [multimodal example](#multimodal) in the Usage section below.
+
+### Jinja2 Time Extension
+
+`PromptBuilder` supports the Jinja2 TimeExtension, which allows you to work with datetime formats.
+
+The Time Extension provides two main features:
+
+1. A `now` tag that gives you access to the current time,
+2. Date/time formatting capabilities through Python's datetime module.
+
+To use the Jinja2 TimeExtension, you need to install a dependency with:
+
+```shell
+pip install arrow>=1.3.0
+```
+
+#### The `now` Tag
+
+The `now` tag creates a datetime object representing the current time, which you can then store in a variable:
+
+```jinja2
+{% now 'utc' as current_time %}
+The current UTC time is: {{ current_time }}
+```
+
+You can specify different timezones:
+
+```jinja2
+{% now 'America/New_York' as ny_time %}
+The time in New York is: {{ ny_time }}
+```
+
+If you don't specify a timezone, your system's local timezone will be used:
+
+```jinja2
+{% now as local_time %}
+Local time: {{ local_time }}
+```
+
+#### Date Formatting
+
+You can format the datetime objects using Python's `strftime` syntax:
+
+```jinja2
+{% now as current_time %}
+Formatted date: {{ current_time.strftime('%Y-%m-%d %H:%M:%S') }}
+```
+
+The common format codes are:
+
+- `%Y`: 4-digit year (for example, 2025)
+- `%m`: Month as a zero-padded number (01-12)
+- `%d`: Day as a zero-padded number (01-31)
+- `%H`: Hour (24-hour clock) as a zero-padded number (00-23)
+- `%M`: Minute as a zero-padded number (00-59)
+- `%S`: Second as a zero-padded number (00-59)
+
+#### Example
+
+```python
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = [
+ ChatMessage.from_user("Current date is: {% now 'UTC' %}"),
+ ChatMessage.from_assistant("Thank you for providing the date"),
+ ChatMessage.from_user("Yesterday was: {% now 'UTC' - 'days=1' %}"),
+]
+builder = ChatPromptBuilder(template=template)
+
+result = builder.run()["prompt"]
+
+now = f"Current date is: {arrow.now('UTC').strftime('%Y-%m-%d %H:%M:%S')}"
+yesterday = f"Yesterday was: {(arrow.now('UTC').shift(days=-1)).strftime('%Y-%m-%d %H:%M:%S')}"
+```
+
+## Usage
+
+### On its own
+
+#### With static template
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = [ChatMessage.from_user("Translate to {{ target_language }}. Context: {{ snippet }}; Translation:")]
+builder = ChatPromptBuilder(template=template)
+builder.run(target_language="spanish", snippet="I can't speak spanish.")
+```
+
+#### With special string template
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = """
+{% message role="user" %}
+Hello, my name is {{name}}!
+{% endmessage %}
+"""
+
+builder = ChatPromptBuilder(template=template)
+result = builder.run(name="John")
+
+assert result["prompt"] == [ChatMessage.from_user("Hello, my name is John!")]
+```
+
+#### Specifying name and meta in a ChatMessage
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = """
+{% message role="user" name="John" meta={"key": "value"} %}
+Hello from {{country}}!
+{% endmessage %}
+"""
+
+builder = ChatPromptBuilder(template=template)
+result = builder.run(country="Italy")
+assert result["prompt"] == [ChatMessage.from_user("Hello from Italy!", name="John", meta={"key": "value"})]
+```
+
+#### Multiple ChatMessages with different roles
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = """
+{% message role="system" %}
+You are a {{adjective}} assistant.
+{% endmessage %}
+
+{% message role="user" %}
+Hello, my name is {{name}}!
+{% endmessage %}
+
+{% message role="assistant" %}
+Hello, {{name}}! How can I help you today?
+{% endmessage %}
+"""
+
+builder = ChatPromptBuilder(template=template)
+result = builder.run(name="John", adjective="helpful")
+assert result["prompt"] == [
+ ChatMessage.from_system("You are a helpful assistant."),
+ ChatMessage.from_user("Hello, my name is John!"),
+ ChatMessage.from_assistant("Hello, John! How can I help you today?"),
+]
+```
+
+#### Overriding static template at runtime
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = [ChatMessage.from_user("Translate to {{ target_language }}. Context: {{ snippet }}; Translation:")]
+builder = ChatPromptBuilder(template=template)
+builder.run(target_language="spanish", snippet="I can't speak spanish.")
+
+summary_template = [ChatMessage.from_user("Translate to {{ target_language }} and summarize. Context: {{ snippet }}; Summary:")]
+builder.run(target_language="spanish", snippet="I can't speak spanish.", template=summary_template)
+```
+
+#### Multimodal
+
+The `| templatize_part` filter in the example below tells the template engine to insert structured (non-text) objects, such as images, into the message content. These are treated differently from plain text and are rendered as special content parts in the final `ChatMessage`.
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage, ImageContent
+
+template = """
+{% message role="user" %}
+Hello! I am {{user_name}}. What's the difference between the following images?
+{% for image in images %}
+{{ image | templatize_part }}
+{% endfor %}
+{% endmessage %}
+"""
+builder = ChatPromptBuilder(template=template)
+images = [
+ ImageContent.from_file_path("apple.jpg"),
+ ImageContent.from_file_path("kiwi.jpg"),
+]
+result = builder.run(user_name="John", images=images)
+
+assert result["prompt"] == [
+ ChatMessage.from_user(
+ content_parts=["Hello! I am John. What's the difference between the following images?",
+ *images]
+ )
+]
+```
+
+### In a pipeline
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+from haystack.utils import Secret
+
+## no parameter init, we don't use any runtime template variables
+prompt_builder = ChatPromptBuilder()
+llm = OpenAIChatGenerator()
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+location = "Berlin"
+language = "English"
+system_message = ChatMessage.from_system("You are an assistant giving information to tourists in {{language}}")
+messages = [system_message, ChatMessage.from_user("Tell me about {{location}}")]
+
+res = pipe.run(data={"prompt_builder": {"template_variables": {"location": location, "language": language},
+ "template": messages}})
+print(res)
+```
+
+Then, you could ask about the weather forecast for the said location. The `ChatPromptBuilder` fills in the template with the new `day_count` variable and passes it to an LLM once again:
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+from haystack.utils import Secret
+
+## no parameter init, we don't use any runtime template variables
+prompt_builder = ChatPromptBuilder()
+llm = OpenAIChatGenerator()
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+location = "Berlin"
+
+messages = [system_message, ChatMessage.from_user("What's the weather forecast for {{location}} in the next {{day_count}} days?")]
+res = pipe.run(data={"prompt_builder": {"template_variables": {"location": location, "day_count": "5"},
+ "template": messages}})
+
+print(res)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Advanced Prompt Customization for Anthropic](https://haystack.deepset.ai/cookbook/prompt_customization_for_anthropic)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/promptbuilder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/promptbuilder.mdx
new file mode 100644
index 0000000000..9105f3c60b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/promptbuilder.mdx
@@ -0,0 +1,258 @@
+---
+title: "PromptBuilder"
+id: promptbuilder
+slug: "/promptbuilder"
+description: "Use this component in pipelines before a Generator to render a prompt template and fill in variable values."
+---
+
+# PromptBuilder
+
+Use this component in pipelines before a Generator to render a prompt template and fill in variable values.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a querying pipeline, before a [Generator](../generators.mdx) |
+| **Mandatory init variables** | `template`: A prompt template string that uses Jinja2 syntax |
+| **Mandatory run variables** | `**kwargs`: Any strings that should be used to render the prompt template. See [Variables](#variables) section for more details. |
+| **Output variables** | `prompt`: A string that represents the rendered prompt template |
+| **API reference** | [Builders](/reference/builders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/builders/prompt_builder.py |
+
+
+
+## Overview
+
+`PromptBuilder` is initialized with a prompt template and renders it by filling in parameters passed through keyword arguments, `kwargs`. With `kwargs`, you can pass a variable number of keyword arguments so that any variable used in the prompt template can be specified with the desired value. Values for all variables appearing in the prompt template need to be provided through the `kwargs`.
+
+The template that is provided to the `PromptBuilder` during initialization needs to conform to the [Jinja2](https://palletsprojects.com/p/jinja/) template language.
+
+### Variables
+
+The template variables found in the init template are used as input types for the component. If there are no `required_variables` set, all variables are considered optional by default. In this case, any missing variables are replaced with empty strings, which can lead to unintended behavior, especially in complex pipelines.
+
+Use `required_variables` and `variables` to specify the input types and required variables:
+
+- `required_variables`
+ - Defines which template variables must be provided when the component runs.
+ - If any required variable is missing, the component raises an error and halts execution.
+ - You can:
+ - Pass a list of required variable names (such as `["query"]`), or
+ - Use `"*"` to mark all variables in the template as required.
+
+- `variables`
+ - Lists all variables that can appear in the template, whether required or optional.
+ - Optional variables that aren't provided are replaced with an empty string in the rendered prompt.
+ - This allows partial prompts to be constructed without errors, unless a variable is marked as required.
+
+```python
+from haystack.components.builders import PromptBuilder
+
+## All variables optional (default to empty string)
+builder = PromptBuilder(
+ template="Hello {{name}}! {{greeting}}",
+ required_variables=[] # or omit this parameter entirely
+)
+
+## Some variables required
+builder = PromptBuilder(
+ template="Hello {{name}}! {{greeting}}",
+ required_variables=["name"] # 'greeting' remains optional
+)
+```
+
+The component only waits for the required inputs before running.
+
+### Jinja2 Time Extension
+
+`PromptBuilder` supports the Jinja2 TimeExtension, which allows you to work with datetime formats.
+
+The Time Extension provides two main features:
+
+1. A `now` tag that gives you access to the current time,
+2. Date/time formatting capabilities through Python's datetime module.
+
+To use the Jinja2 TimeExtension, you need to install a dependency with:
+
+```shell
+pip install arrow>=1.3.0
+```
+
+#### The `now` Tag
+
+The `now` tag creates a datetime object representing the current time, which you can then store in a variable:
+
+```jinja2
+{% now 'utc' as current_time %}
+The current UTC time is: {{ current_time }}
+```
+
+You can specify different timezones:
+
+```jinja2
+{% now 'America/New_York' as ny_time %}
+The time in New York is: {{ ny_time }}
+```
+
+If you don't specify a timezone, your system's local timezone will be used:
+
+```jinja2
+{% now as local_time %}
+Local time: {{ local_time }}
+```
+
+#### Date Formatting
+
+You can format the datetime objects using Python's `strftime` syntax:
+
+```jinja2
+{% now as current_time %}
+Formatted date: {{ current_time.strftime('%Y-%m-%d %H:%M:%S') }}
+```
+
+The common format codes are:
+
+- `%Y`: 4-digit year (for example, 2025)
+- `%m`: Month as a zero-padded number (01-12)
+- `%d`: Day as a zero-padded number (01-31)
+- `%H`: Hour (24-hour clock) as a zero-padded number (00-23)
+- `%M`: Minute as a zero-padded number (00-59)
+- `%S`: Second as a zero-padded number (00-59)
+
+#### Example
+
+```python
+from haystack.components.builders import PromptBuilder
+
+## Define template using Jinja-style formatting
+template = """
+Current date is: {% now 'UTC' %}
+Thank you for providing the date
+Yesterday was: {% now 'UTC' - 'days=1' %}
+"""
+
+builder = PromptBuilder(template=template)
+
+result = builder.run()["prompt"]
+
+now = f"Current date is: {arrow.now('UTC').strftime('%Y-%m-%d %H:%M:%S')}"
+yesterday = f"Yesterday was: {(arrow.now('UTC').shift(days=-1)).strftime('%Y-%m-%d %H:%M:%S')}"
+```
+
+## Usage
+
+### On its own
+
+Below is an example of using the `PromptBuilder` to render a prompt template and fill it with `target_language` and `snippet`. The PromptBuilder returns a prompt with the string `Translate the following context to spanish. Context: I can't speak spanish.; Translation:`.
+
+```python
+from haystack.components.builders import PromptBuilder
+
+template = "Translate the following context to {{ target_language }}. Context: {{ snippet }}; Translation:"
+builder = PromptBuilder(template=template)
+builder.run(target_language="spanish", snippet="I can't speak spanish.")
+```
+
+### In a pipeline
+
+Below is an example of a RAG pipeline where we use a `PromptBuilder` to render a custom prompt template and fill it with the contents of retrieved documents and a query. The rendered prompt is then sent to a Generator.
+
+```python
+from haystack import Pipeline, Document
+from haystack.utils import Secret
+from haystack.components.generators import OpenAIGenerator
+from haystack.components.builders.prompt_builder import PromptBuilder
+
+## in a real world use case documents could come from a retriever, web, or any other source
+documents = [Document(content="Joe lives in Berlin"), Document(content="Joe is a software engineer")]
+prompt_template = """
+ Given these documents, answer the question.\nDocuments:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ \nQuestion: {{query}}
+ \nAnswer:
+ """
+p = Pipeline()
+p.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+p.add_component(instance=OpenAIGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")), name="llm")
+p.connect("prompt_builder", "llm")
+
+question = "Where does Joe live?"
+result = p.run({"prompt_builder": {"documents": documents, "query": question}})
+print(result)
+```
+
+#### Changing the template at runtime (Prompt Engineering)
+
+`PromptBuilder` allows you to switch the prompt template of an existing pipeline. The example below builds on top of the existing pipeline in the previous section. We are invoking the existing pipeline with a new prompt template:
+
+```python
+documents = [
+ Document(content="Joe lives in Berlin", meta={"name": "doc1"}),
+ Document(content="Joe is a software engineer", meta={"name": "doc1"}),
+]
+new_template = """
+ You are a helpful assistant.
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ Document {{ loop.index }}:
+ Document name: {{ doc.meta['name'] }}
+ {{ doc.content }}
+ {% endfor %}
+
+ Question: {{ query }}
+ Answer:
+ """
+p.run({
+ "prompt_builder": {
+ "documents": documents,
+ "query": question,
+ "template": new_template,
+ },
+ })
+```
+
+If you want to use different variables during prompt engineering than in the default template, you can do so by setting `PromptBuilder`'s variables init parameter accordingly.
+
+#### Overwriting variables at runtime
+
+In case you want to overwrite the values of variables, you can use `template_variables` during runtime, as shown below:
+
+```python
+language_template = """
+ You are a helpful assistant.
+ Given these documents, answer the question.
+ Documents:
+ {% for doc in documents %}
+ Document {{ loop.index }}:
+ Document name: {{ doc.meta['name'] }}
+ {{ doc.content }}
+ {% endfor %}
+
+ Question: {{ query }}
+ Please provide your answer in {{ answer_language | default('English') }}
+ Answer:
+ """
+p.run({
+ "prompt_builder": {
+ "documents": documents,
+ "query": question,
+ "template": language_template,
+ "template_variables": {"answer_language": "German"},
+ },
+ })
+```
+
+Note that `language_template` introduces `answer_language` variable which is not bound to any pipeline variable. If not set otherwise, it would use its default value, "English". In this example, we overwrite its value to "German".
+The `template_variables` allows you to overwrite pipeline variables (such as documents) as well.
+
+## Additional References
+
+🧑🍳 Cookbooks:
+
+- [Advanced Prompt Customization for Anthropic](https://haystack.deepset.ai/cookbook/prompt_customization_for_anthropic)
+- [Prompt Optimization with DSPy](https://haystack.deepset.ai/cookbook/prompt_optimization_with_dspy)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/caching/cachechecker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/caching/cachechecker.mdx
new file mode 100644
index 0000000000..5f0def90a0
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/caching/cachechecker.mdx
@@ -0,0 +1,83 @@
+---
+title: "CacheChecker"
+id: cachechecker
+slug: "/cachechecker"
+description: "This component checks for the presence of documents in a Document Store based on a specified cache field."
+---
+
+# CacheChecker
+
+This component checks for the presence of documents in a Document Store based on a specified cache field.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory init variables** | `document_store`: A Document Store instance
`cache_field`: Name of the document's metadata field | +| **Mandatory run variables** | `items`: A list of values associated with the `cache_field` in documents | +| **Output variables** | `hits`: A list of documents that were found with the specified value in cache
`misses`: A list of values that could not be found | +| **API reference** | [Caching](/reference/caching-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/caching/cache_checker.py | + +
+
+## Overview
+
+`CacheChecker` checks if a Document Store contains any document with a value in the `cache_field` that matches any of the values provided in the `items` input variable. It returns a dictionary with two keys: `"hits"` and `"misses"`. The values are lists of documents that were found in the cache and items that were not, respectively.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.caching import CacheChecker
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+my_doc_store = InMemoryDocumentStore()
+
+## For URL-based caching
+cache_checker = CacheChecker(document_store=my_doc_store, cache_field="url")
+cache_check_results = cache_checker.run(items=["https://example.com/resource", "https://another_example.com/other_resources"])
+print(cache_check_results["hits"]) # List of Documents that were found in the cache: all of these have 'url': `cache_field`: Name of the document's metadata field | +| **Mandatory run variables** | `items`: A list of values associated with the `cache_field` in documents | +| **Output variables** | `hits`: A list of documents that were found with the specified value in cache
`misses`: A list of values that could not be found | +| **API reference** | [Caching](/reference/caching-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/caching/cache_checker.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [`MetadataRouter`](../routers/metadatarouter.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Classifiers](/reference/classifiers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/classifiers/document_language_classifier.py |
+
+
+
+## Overview
+
+`DocumentLanguageClassifier` classifies the language of documents and adds the detected language to their metadata. If a document's text does not match any of the languages specified at initialization, it is classified as "unmatched". By default, the classifier classifies for English (”en”) documents, with the rest being classified as “unmatched”.
+
+The set of supported languages can be specified in the init method with the `languages` variable, using ISO codes.
+
+To route your documents to various branches of the pipeline based on the language, use `MetadataRouter` component right after `DocumentLanguageClassifier`.
+
+For classifying and then routing plain text using the same logic, use the `TextLanguageRouter` component instead.
+
+## Usage
+
+Install the `langdetect`package to use the `DocumentLanguageClassifier`component:
+
+```shell shell
+pip install langdetect
+```
+
+### On its own
+
+Below, we are using the `DocumentLanguageClassifier` to classify English and German documents:
+
+```python
+from haystack.components.classifiers import DocumentLanguageClassifier
+from haystack import Document
+
+documents = [
+ Document(content="Mein Name ist Jean und ich wohne in Paris."),
+ Document(content="Mein Name ist Mark und ich wohne in Berlin."),
+ Document(content="Mein Name ist Giorgio und ich wohne in Rome."),
+ Document(content="My name is Pierre and I live in Paris"),
+ Document(content="My name is Paul and I live in Berlin."),
+ Document(content="My name is Alessia and I live in Rome."),
+]
+
+document_classifier = DocumentLanguageClassifier(languages = ["en", "de"])
+document_classifier.run(documents = documents)
+```
+
+### In a pipeline
+
+Below, we are using the `DocumentLanguageClassifier` in an indexing pipeline that indexes English and German documents into two difference indexes in an `InMemoryDocumentStore`, using embedding models for each language.
+
+```python
+from haystack import Pipeline
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.classifiers import DocumentLanguageClassifier
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+from haystack.components.writers import DocumentWriter
+from haystack.components.routers import MetadataRouter
+
+document_store_en = InMemoryDocumentStore()
+document_store_de = InMemoryDocumentStore()
+
+document_classifier = DocumentLanguageClassifier(languages = ["en", "de"])
+metadata_router = MetadataRouter(rules={"en": {"language": {"$eq": "en"}}, "de": {"language": {"$eq": "de"}}})
+english_embedder = SentenceTransformersDocumentEmbedder()
+german_embedder = SentenceTransformersDocumentEmbedder(model="PM-AI/bi-encoder_msmarco_bert-base_german")
+en_writer = DocumentWriter(document_store = document_store_en)
+de_writer = DocumentWriter(document_store = document_store_de)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(instance=document_classifier, name="document_classifier")
+indexing_pipeline.add_component(instance=metadata_router, name="metadata_router")
+indexing_pipeline.add_component(instance=english_embedder, name="english_embedder")
+indexing_pipeline.add_component(instance=german_embedder, name="german_embedder")
+indexing_pipeline.add_component(instance=en_writer, name="en_writer")
+indexing_pipeline.add_component(instance=de_writer, name="de_writer")
+
+indexing_pipeline.connect("document_classifier.documents", "metadata_router.documents")
+indexing_pipeline.connect("metadata_router.en", "english_embedder.documents")
+indexing_pipeline.connect("metadata_router.de", "german_embedder.documents")
+indexing_pipeline.connect("english_embedder", "en_writer")
+indexing_pipeline.connect("german_embedder", "de_writer")
+
+indexing_pipeline.run({"document_classifier": {"documents": [Document(content="This is an English sentence."), Document(content="Dies ist ein deutscher Satz.")]}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx
new file mode 100644
index 0000000000..cec2e62898
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx
@@ -0,0 +1,99 @@
+---
+title: "TransformersZeroShotDocumentClassifier"
+id: transformerszeroshotdocumentclassifier
+slug: "/transformerszeroshotdocumentclassifier"
+description: "Classifies the documents based on the provided labels and adds them to their metadata."
+---
+
+# TransformersZeroShotDocumentClassifier
+
+Classifies the documents based on the provided labels and adds them to their metadata.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [MetadataRouter](../routers/metadatarouter.mdx) |
+| **Mandatory init variables** | `model`: The name or path of a Hugging Face model for zero shot document classification
`labels`: The set of possible class labels to classify each document into, for example, [`positive`, `negative`]. The labels depend on the selected model. | +| **Mandatory run variables** | `documents`: A list of documents to classify | +| **Output variables** | `documents`: A list of processed documents with an added `classification` metadata field | +| **API reference** | [Classifiers](/reference/classifiers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/classifiers/zero_shot_document_classifier.py | + +
+
+## Overview
+
+The `TransformersZeroShotDocumentClassifier` component performs zero-shot classification of documents based on the labels that you set and adds the predicted label to their metadata.
+
+The component uses a Hugging Face pipeline for zero-shot classification.
+To initialize the component, provide the model and the set of labels to be used for categorization.
+You can additionally configure the component to allow multiple labels to be true with the `multi_label` boolean set to True.
+
+Classification is run on the document's content field by default. If you want it to run on another field, set the`classification_field` to one of the document's metadata fields.
+
+The classification results are stored in the `classification` dictionary within each document's metadata. If `multi_label` is set to `True`, you will find the scores for each label under the `details` key within the `classification` dictionary.
+
+Available models for the task of zero-shot-classification are:
+ - `valhalla/distilbart-mnli-12-3`
+ - `cross-encoder/nli-distilroberta-base`
+ - `cross-encoder/nli-deberta-v3-xsmall`
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.classifiers import TransformersZeroShotDocumentClassifier
+
+documents = [Document(id="0", content="Cats don't get teeth cavities."),
+ Document(id="1", content="Cucumbers can be grown in water.")]
+
+document_classifier = TransformersZeroShotDocumentClassifier(
+ model="cross-encoder/nli-deberta-v3-xsmall",
+ labels=["animals", "food"],
+)
+
+document_classifier.warm_up()
+document_classifier.run(documents = documents)
+```
+
+### In a pipeline
+
+The following is a pipeline that classifies documents based on predefined classification labels
+retrieved from a search pipeline:
+
+```python
+from haystack import Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.core.pipeline import Pipeline
+from haystack.components.classifiers import TransformersZeroShotDocumentClassifier
+
+documents = [Document(id="0", content="Today was a nice day!"),
+ Document(id="1", content="Yesterday was a bad day!")]
+
+document_store = InMemoryDocumentStore()
+retriever = InMemoryBM25Retriever(document_store=document_store)
+document_classifier = TransformersZeroShotDocumentClassifier(
+ model="cross-encoder/nli-deberta-v3-xsmall",
+ labels=["positive", "negative"],
+)
+
+document_store.write_documents(documents)
+
+pipeline = Pipeline()
+pipeline.add_component(instance=retriever, name="retriever")
+pipeline.add_component(instance=document_classifier, name="document_classifier")
+pipeline.connect("retriever", "document_classifier")
+
+queries = ["How was your day today?", "How was your day yesterday?"]
+expected_predictions = ["positive", "negative"]
+
+for idx, query in enumerate(queries):
+ result = pipeline.run({"retriever": {"query": query, "top_k": 1}})
+ assert result["document_classifier"]["documents"][0].to_dict()["id"] == str(idx)
+ assert (result["document_classifier"]["documents"][0].to_dict()["classification"]["label"]
+ == expected_predictions[idx])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors.mdx
new file mode 100644
index 0000000000..faf8975d15
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors.mdx
@@ -0,0 +1,24 @@
+---
+title: "Connectors"
+id: connectors
+slug: "/connectors"
+description: "These are Haystack integrations that connect your pipelines to services by external providers."
+---
+
+# Connectors
+
+These are Haystack integrations that connect your pipelines to services by external providers.
+
+| Component | Description |
+| --- | --- |
+| [GitHubFileEditor](connectors/githubfileeditor.mdx) | Enables editing files in GitHub repositories through the GitHub API. |
+| [GitHubIssueCommenter](connectors/githubissuecommenter.mdx) | Enables posting comments to GitHub issues using the GitHub API. |
+| [GitHubIssueViewer](connectors/githubissueviewer.mdx) | Enables fetching and parsing GitHub issues into Haystack documents. |
+| [GitHubPRCreator](connectors/githubprcreator.mdx) | Enables creating pull requests from a fork back to the original repository through the GitHub API. |
+| [GitHubRepoForker](connectors/githubrepoforker.mdx) | Enables forking a GitHub repository from an issue URL through the GitHub API. |
+| [GitHubRepoViewer](connectors/githubrepoviewer.mdx) | Enables navigating and fetching content from GitHub repositories through the GitHub API. |
+| [JinaReaderConnector](connectors/jinareaderconnector.mdx) | Use Jina AI’s Reader API with Haystack. |
+| [LangfuseConnector](connectors/langfuseconnector.mdx) | Enables tracing in Haystack pipelines using Langfuse. |
+| [OpenAPIConnector](connectors/openapiconnector.mdx) | Acts as an interface between the Haystack ecosystem and OpenAPI services, using explicit input arguments. |
+| [OpenAPIServiceConnector](connectors/openapiserviceconnector.mdx) | Acts as an interface between the Haystack ecosystem and OpenAPI services. |
+| [WeaveConnector](connectors/weaveconnector.mdx) | Connects you to Weights & Biases Weave framework for tracing and monitoring your pipeline components. |
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/external-integrations-connectors.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/external-integrations-connectors.mdx
new file mode 100644
index 0000000000..cb22c9473e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/external-integrations-connectors.mdx
@@ -0,0 +1,18 @@
+---
+title: "External Integrations"
+id: external-integrations-connectors
+slug: "/external-integrations-connectors"
+description: "External integrations that connect your pipelines to services by external providers."
+---
+
+# External Integrations
+
+External integrations that connect your pipelines to services by external providers.
+
+| Name | Description |
+| --- | --- |
+| [Arize AI](https://haystack.deepset.ai/integrations/arize) | Trace and evaluate your Haystack pipelines with Arize AI. |
+| [Arize Phoenix](https://haystack.deepset.ai/integrations/arize-phoenix) | Trace and evaluate your Haystack pipelines with Arize Phoenix. |
+| [Context AI](https://haystack.deepset.ai/integrations/context-ai) | Log conversations for analytics by Context.ai |
+| [Opik](https://haystack.deepset.ai/integrations/opik) | Trace and evaluate your Haystack pipelines with Opik platform. |
+| [Traceloop](https://haystack.deepset.ai/integrations/traceloop) | Evaluate and monitor the quality of your LLM apps and agents |
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubfileeditor.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubfileeditor.mdx
new file mode 100644
index 0000000000..baace8434c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubfileeditor.mdx
@@ -0,0 +1,104 @@
+---
+title: "GitHubFileEditor"
+id: githubfileeditor
+slug: "/githubfileeditor"
+description: "This is a component for editing files in GitHub repositories through the GitHub API."
+---
+
+# GitHubFileEditor
+
+This is a component for editing files in GitHub repositories through the GitHub API.
+
+`labels`: The set of possible class labels to classify each document into, for example, [`positive`, `negative`]. The labels depend on the selected model. | +| **Mandatory run variables** | `documents`: A list of documents to classify | +| **Output variables** | `documents`: A list of processed documents with an added `classification` metadata field | +| **API reference** | [Classifiers](/reference/classifiers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/classifiers/zero_shot_document_classifier.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a Chat Generator, or right at the beginning of a pipeline |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var. |
+| **Mandatory run variables** | `command`: Operation type (edit, create, delete, undo)
`payload`: Command-specific parameters | +| **Output variables** | `result`: String that indicates the operation result | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | + +
+
+## Overview
+
+`GitHubFileEditor` supports multiple file operations, including editing existing files, creating new files, deleting files, and undoing recent changes.
+
+There are four main commands:
+
+- **EDIT**: Edit an existing file by replacing specific content
+- **CREATE**: Create a new file with specified content
+- **DELETE**: Delete an existing file
+- **UNDO**: Revert the last commit if made by the same user
+
+### Authorization
+
+This component requires GitHub authentication with a personal access token. You can set the token using the `GITHUB_TOKEN` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens). Make sure to grant the appropriate permissions for repository access and content management.
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info Repository Placeholder
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Editing an existing file:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubFileEditor, Command
+
+editor = GitHubFileEditor(repo="owner/repo", branch="main")
+
+result = editor.run(
+ command=Command.EDIT,
+ payload={
+ "path": "src/example.py",
+ "original": "def old_function():",
+ "replacement": "def new_function():",
+ "message": "Renamed function for clarity"
+ }
+)
+
+print(result)
+```
+
+```bash
+{'result': 'Edit successful'}
+```
+
+Creating a new file:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubFileEditor, Command
+
+editor = GitHubFileEditor(repo="owner/repo")
+
+result = editor.run(
+ command=Command.CREATE,
+ payload={
+ "path": "docs/new_file.md",
+ "content": "# New Documentation\n\nThis is a new file.",
+ "message": "Add new documentation file"
+ }
+)
+
+print(result)
+```
+
+```bash
+{'result': 'File created successfully'}
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubissuecommenter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubissuecommenter.mdx
new file mode 100644
index 0000000000..e25e5af0c8
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubissuecommenter.mdx
@@ -0,0 +1,128 @@
+---
+title: "GitHubIssueCommenter"
+id: githubissuecommenter
+slug: "/githubissuecommenter"
+description: "This component posts comments to GitHub issues using the GitHub API."
+---
+
+# GitHubIssueCommenter
+
+This component posts comments to GitHub issues using the GitHub API.
+
+`payload`: Command-specific parameters | +| **Output variables** | `result`: String that indicates the operation result | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a Chat Generator that provides the comment text to post or right at the beginning of a pipeline |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var. |
+| **Mandatory run variables** | `url`: A GitHub issue URL
`comment`: Comment text to post | +| **Output variables** | `success`: Boolean indicating whether the comment was posted successfully | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | + +
+
+## Overview
+
+`GitHubIssueCommenter` takes a GitHub issue URL and comment text, then posts the comment to the specified issue.
+
+The component requires authentication with a GitHub personal access token since posting comments is an authenticated operation.
+
+### Authorization
+
+This component requires GitHub authentication with a personal access token. You can set the token using the `GITHUB_TOKEN` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens). Make sure to grant the appropriate permissions for repository access and issue management.
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info Repository Placeholder
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Basic usage with environment variable authentication:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubIssueCommenter
+
+commenter = GitHubIssueCommenter()
+result = commenter.run(
+ url="https://github.com/owner/repo/issues/123",
+ comment="Thanks for reporting this issue! We'll look into it."
+)
+
+print(result)
+```
+
+```bash
+{'success': True}
+```
+
+### In a pipeline
+
+The following pipeline analyzes a GitHub issue and automatically posts a response:
+
+```python
+from haystack import Pipeline
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.converters import OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.connectors.github import GitHubIssueViewer, GitHubIssueCommenter
+
+issue_viewer = GitHubIssueViewer()
+issue_commenter = GitHubIssueCommenter()
+
+prompt_template = [
+ ChatMessage.from_system("You are a helpful assistant that analyzes GitHub issues and creates appropriate responses."),
+ ChatMessage.from_user(
+ "Based on the following GitHub issue:\n"
+ "{% for document in documents %}"
+ "{% if document.meta.type == 'issue' %}"
+ "**Issue Title:** {{ document.meta.title }}\n"
+ "**Issue Description:** {{ document.content }}\n"
+ "{% endif %}"
+ "{% endfor %}\n"
+ "Generate a helpful response comment for this issue. Keep it professional and concise."
+ )
+]
+
+prompt_builder = ChatPromptBuilder(template=prompt_template, required_variables="*")
+llm = OpenAIChatGenerator(model="gpt-4o-mini")
+adapter = OutputAdapter(template="{{ replies[-1].text }}", output_type=str)
+
+pipeline = Pipeline()
+pipeline.add_component("issue_viewer", issue_viewer)
+pipeline.add_component("prompt_builder", prompt_builder)
+pipeline.add_component("llm", llm)
+pipeline.add_component("adapter", adapter)
+pipeline.add_component("issue_commenter", issue_commenter)
+
+pipeline.connect("issue_viewer.documents", "prompt_builder.documents")
+pipeline.connect("prompt_builder.prompt", "llm.messages")
+pipeline.connect("llm.replies", "adapter.replies")
+pipeline.connect("adapter", "issue_commenter.comment")
+
+issue_url = "https://github.com/owner/repo/issues/123"
+result = pipeline.run(data={
+ "issue_viewer": {"url": issue_url},
+ "issue_commenter": {"url": issue_url}
+})
+
+print(f"Comment posted successfully: {result['issue_commenter']['success']}")
+```
+
+```
+Comment posted successfully: True
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubissueviewer.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubissueviewer.mdx
new file mode 100644
index 0000000000..89270c2bff
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubissueviewer.mdx
@@ -0,0 +1,126 @@
+---
+title: "GitHubIssueViewer"
+id: githubissueviewer
+slug: "/githubissueviewer"
+description: "This component fetches and parses GitHub issues into Haystack documents."
+---
+
+# GitHubIssueViewer
+
+This component fetches and parses GitHub issues into Haystack documents.
+
+`comment`: Comment text to post | +| **Output variables** | `success`: Boolean indicating whether the comment was posted successfully | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Right at the beginning of a pipeline and before a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) that expects the content of a GitHub issue as input |
+| **Mandatory run variables** | `url`: A GitHub issue URL |
+| **Output variables** | `documents`: A list of documents containing the main issue and its comments |
+| **API reference** | [GitHub](/reference/integrations-github) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github |
+
+
+
+## Overview
+
+`GitHubIssueViewer` takes a GitHub issue URL and returns a list of documents where:
+
+- The first document contains the main issue content
+- Subsequent documents contain the issue comments (if any)
+
+Each document includes rich metadata such as the issue title, number, state, creation date, author, and more.
+
+### Authorization
+
+The component can work without authentication for public repositories, but for private repositories or to avoid rate limiting, you can provide a GitHub personal access token.
+
+You can set the token using the `GITHUB_API_KEY` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens).
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info Repository Placeholder
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Basic usage without authentication:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubIssueViewer
+
+viewer = GitHubIssueViewer()
+result = viewer.run(url="https://github.com/deepset-ai/haystack/issues/123")
+
+print(result)
+```
+
+```bash
+{'documents': [Document(id=3989459bbd8c2a8420a9ba7f3cd3cf79bb41d78bd0738882e57d509e1293c67a, content: 'sentence-transformers = 0.2.6.1
+haystack = latest
+farm = 0.4.3 latest branch
+
+In the call to Emb...', meta: {'type': 'issue', 'title': 'SentenceTransformer no longer accepts \'gpu" as argument', 'number': 123, 'state': 'closed', 'created_at': '2020-05-28T04:49:31Z', 'updated_at': '2020-05-28T07:11:43Z', 'author': 'predoctech', 'url': 'https://github.com/deepset-ai/haystack/issues/123'}), Document(id=a8a56b9ad119244678804d5873b13da0784587773d8f839e07f644c4d02c167a, content: 'Thanks for reporting!
+Fixed with #124 ', meta: {'type': 'comment', 'issue_number': 123, 'created_at': '2020-05-28T07:11:42Z', 'updated_at': '2020-05-28T07:11:42Z', 'author': 'tholor', 'url': 'https://github.com/deepset-ai/haystack/issues/123#issuecomment-635153940'})]}
+```
+
+### In a pipeline
+
+The following pipeline fetches a GitHub issue, extracts relevant information, and generates a summary:
+
+```python
+from haystack import Pipeline
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.connectors.github import GitHubIssueViewer
+
+## Initialize components
+issue_viewer = GitHubIssueViewer()
+
+prompt_template = [
+ ChatMessage.from_system("You are a helpful assistant that analyzes GitHub issues."),
+ ChatMessage.from_user(
+ "Based on the following GitHub issue and comments:\n"
+ "{% for document in documents %}"
+ "{% if document.meta.type == 'issue' %}"
+ "**Issue Title:** {{ document.meta.title }}\n"
+ "**Issue Description:** {{ document.content }}\n"
+ "{% else %}"
+ "**Comment by {{ document.meta.author }}:** {{ document.content }}\n"
+ "{% endif %}"
+ "{% endfor %}\n"
+ "Please provide a summary of the issue and suggest potential solutions."
+ )
+]
+
+prompt_builder = ChatPromptBuilder(template=prompt_template, required_variables="*")
+llm = OpenAIChatGenerator(model="gpt-4o-mini")
+
+## Create pipeline
+pipeline = Pipeline()
+pipeline.add_component("issue_viewer", issue_viewer)
+pipeline.add_component("prompt_builder", prompt_builder)
+pipeline.add_component("llm", llm)
+
+## Connect components
+pipeline.connect("issue_viewer.documents", "prompt_builder.documents")
+pipeline.connect("prompt_builder.prompt", "llm.messages")
+
+## Run pipeline
+issue_url = "https://github.com/deepset-ai/haystack/issues/123"
+result = pipeline.run(data={"issue_viewer": {"url": issue_url}})
+
+print(result["llm"]["replies"][0])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubprcreator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubprcreator.mdx
new file mode 100644
index 0000000000..597af99367
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubprcreator.mdx
@@ -0,0 +1,78 @@
+---
+title: "GitHubPRCreator"
+id: githubprcreator
+slug: "/githubprcreator"
+description: "This component creates pull requests from a fork back to the original repository through the GitHub API."
+---
+
+# GitHubPRCreator
+
+This component creates pull requests from a fork back to the original repository through the GitHub API.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | At the end of a pipeline, after [GitHubRepoForker](githubrepoforker.mdx), [GitHubFileEditor](githubfileeditor.mdx) and other components that prepare changes for submission |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var. |
+| **Mandatory run variables** | `issue_url`: GitHub issue URL
`title`: PR title
`branch`: Source branch
`base`: Target branch | +| **Output variables** | `result`: String indicating the pull request creation result | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | + +
+
+## Overview
+
+`GitHubPRCreator` takes a GitHub issue URL and creates a pull request from your fork to the original repository, automatically linking it to the specified issue. It's designed to work with existing forks and assumes you have already made changes in a branch.
+
+Key features:
+
+- **Cross-repository PRs**: Creates pull requests from your fork to the original repository
+- **Issue linking**: Automatically links the PR to the specified GitHub issue
+- **Draft support**: Option to create draft pull requests
+- **Fork validation**: Checks that the required fork exists before creating the PR
+
+As optional parameters, you can set `body` to provide a pull request description and the boolean parameter `draft` to open a draft pull request.
+
+### Authorization
+
+This component requires GitHub authentication with a personal access token from the fork owner. You can set the token using the `GITHUB_TOKEN` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens). Make sure to grant the appropriate permissions for repository access and pull request creation.
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info Repository Placeholder
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+```python
+from haystack_integrations.components.connectors.github import GitHubPRCreator
+
+pr_creator = GitHubPRCreator()
+result = pr_creator.run(
+ issue_url="https://github.com/owner/repo/issues/123",
+ title="Fix issue #123",
+ body="This PR addresses issue #123 by implementing the requested changes.",
+ branch="fix-123", # Branch in your fork with the changes
+ base="main" # Branch in original repo to merge into
+)
+
+print(result)
+```
+
+```bash
+{'result': 'Pull request #456 created successfully and linked to issue #123'}
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubrepoforker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubrepoforker.mdx
new file mode 100644
index 0000000000..b19d10abf9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubrepoforker.mdx
@@ -0,0 +1,70 @@
+---
+title: "GitHubRepoForker"
+id: githubrepoforker
+slug: "/githubrepoforker"
+description: "This component forks a GitHub repository from an issue URL through the GitHub API."
+---
+
+# GitHubRepoForker
+
+This component forks a GitHub repository from an issue URL through the GitHub API.
+
+`title`: PR title
`branch`: Source branch
`base`: Target branch | +| **Output variables** | `result`: String indicating the pull request creation result | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Right at the beginning of a pipeline and before an [Agent](../agents-1/agent.mdx) component that expects the name of a GitHub branch as input |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var. |
+| **Mandatory run variables** | `url`: The URL of a GitHub issue in the repository that should be forked |
+| **Output variables** | `repo`: Fork repository path
`issue_branch`: Issue-specific branch name (if created) | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | + +
+
+## Overview
+
+`GitHubRepoForker` takes a GitHub issue URL, extracts the repository information, creates or syncs a fork of that repository, and optionally creates an issue-specific branch. It's particularly useful for automated workflows that need to create pull requests or work with repository forks.
+
+Key features:
+
+- **Auto-sync**: Automatically syncs existing forks with the upstream repository
+- **Branch creation**: Creates issue-specific branches (e.g., "fix-123" for issue #123)
+- **Completion waiting**: Optionally waits for fork creation to complete
+- **Fork management**: Handles existing forks intelligently
+
+### Authorization
+
+This component requires GitHub authentication with a personal access token. You can set the token using the `GITHUB_TOKEN` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens). Make sure to grant the appropriate permissions for repository forking and management.
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info Repository Placeholder
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+```python
+from haystack_integrations.components.connectors.github import GitHubRepoForker
+
+forker = GitHubRepoForker()
+result = forker.run(url="https://github.com/owner/repo/issues/123")
+
+print(result)
+```
+
+```bash
+{'repo': 'owner/repo', 'issue_branch': 'fix-123'}
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubrepoviewer.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubrepoviewer.mdx
new file mode 100644
index 0000000000..f30166b76d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubrepoviewer.mdx
@@ -0,0 +1,91 @@
+---
+title: "GitHubRepoViewer"
+id: githubrepoviewer
+slug: "/githubrepoviewer"
+description: "This component navigates and fetches content from GitHub repositories through the GitHub API."
+---
+
+# GitHubRepoViewer
+
+This component navigates and fetches content from GitHub repositories through the GitHub API.
+
+`issue_branch`: Issue-specific branch name (if created) | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Right at the beginning of a pipeline and before a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) that expects the content of GitHub files as input |
+| **Mandatory run variables** | `path`: Repository path to view
`repo`: Repository in owner/repo format | +| **Output variables** | `documents`: A list of documents containing repository contents | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | + +
+
+## Overview
+
+`GitHubRepoViewer` provides different behavior based on the path type:
+
+- **For directories**: Returns a list of documents, one for each item (files and subdirectories),
+- **For files**: Returns a single document containing the file content.
+
+Each document includes rich metadata such as the path, type, size, and URL.
+
+### Authorization
+
+The component can work without authentication for public repositories, but for private repositories or to avoid rate limiting, you can provide a GitHub personal access token.
+
+You can set the token using the `GITHUB_TOKEN` environment variable, or pass it directly during initialization via the `github_token` parameter.
+
+To create a personal access token, visit [GitHub's token settings page](https://github.com/settings/tokens).
+
+### Installation
+
+Install the GitHub integration with pip:
+
+```shell
+pip install github-haystack
+```
+
+## Usage
+
+:::info Repository Placeholder
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Viewing a directory listing:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubRepoViewer
+
+viewer = GitHubRepoViewer()
+result = viewer.run(
+ repo="deepset-ai/haystack",
+ path="haystack/components",
+ branch="main"
+)
+
+print(result)
+```
+
+```bash
+{'documents': [Document(id=..., content: 'agents', meta: {'path': 'haystack/components/agents', 'type': 'dir', 'size': 0, 'url': 'https://github.com/deepset-ai/haystack/tree/main/haystack/components/agents'}), ...]}
+```
+
+Viewing a specific file:
+
+```python
+from haystack_integrations.components.connectors.github import GitHubRepoViewer
+
+viewer = GitHubRepoViewer(repo="deepset-ai/haystack", branch="main")
+result = viewer.run(path="README.md")
+
+print(result)
+```
+
+```bash
+{'documents': [Document(id=..., content: '
+
+## Overview
+
+`JinaReaderConnector` interacts with Jina AI’s Reader API to process queries and output documents.
+
+You need to select one of the following modes of operations when initializing the component:
+
+- `read`: Processes a URL and extracts the textual content.
+- `search`: Searches the web and returns textual content from the most relevant pages.
+- `ground`: Performs fact-checking using a grounding engine.
+
+You can find more information on these modes in the [Jina Reader documentation](https://jina.ai/reader/).
+
+You can additionally control the response format from the Jina Reader API using the component’s `json_response` parameter:
+
+- `True` (default) requests a JSON response for documents enriched with structured metadata.
+- `False` requests a raw response, resulting in one document with minimal metadata.
+
+### Authorization
+
+The component uses a `JINA_API_KEY` environment variable by default. Otherwise, you can pass a Jina API key at initialization with `api_key` like this:
+
+```python
+ranker = JinaRanker(api_key=Secret.from_token("`repo`: Repository in owner/repo format | +| **Output variables** | `documents`: A list of documents containing repository contents | +| **API reference** | [GitHub](/reference/integrations-github) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Anywhere, as it’s not connected to other components |
+| **Mandatory init variables** | `name`: The name of the pipeline or component to identify the tracing run |
+| **Output variables** | `name`: The name of the tracing component
`trace_url`: A link to the tracing data | +| **API reference** | [langfuse](/reference/integrations-langfuse) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/langfuse | + +
+
+## Overview
+
+`LangfuseConnector` integrates tracing capabilities into Haystack pipelines using [Langfuse](https://langfuse.com/). It captures detailed information about pipeline runs, like API calls, context data, prompts, and more. Use this component to:
+
+- Monitor model performance, such as token usage and cost.
+- Find areas for pipeline improvement by identifying low-quality outputs and collecting user feedback.
+- Create datasets for fine-tuning and testing from your pipeline executions.
+
+To work with the integration, add the `LangfuseConnector` to your pipeline, run the pipeline, and then view the tracing data on the Langfuse website. Don’t connect this component to any other – `LangfuseConnector` will simply run in your pipeline’s background.
+
+You can optionally define two more parameters when working with this component:
+
+- `httpx_client`: An optional custom `httpx.Client` instance for Langfuse API calls. Note that custom clients are discarded when deserializing a pipeline from YAML, as HTTPX clients cannot be serialized. In such cases, Langfuse creates a default client.
+- `span_handler`: An optional custom handler for processing spans. If not provided, the `DefaultSpanHandler` is used. The span handler defines how spans are created and processed, enabling customization of span types based on component types and post-processing of spans. See more details in the [Advanced Usage section](#advanced-usage) below.
+
+### Prerequisites
+
+These are the things that you need before working with LangfuseConnector:
+
+1. Make sure you have an active Langfuse [account](https://cloud.langfuse.com/).
+2. Set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true` – this will enable tracing in your pipelines.
+3. Set the `LANGFUSE_SECRET_KEY` and `LANGFUSE_PUBLIC_KEY` environment variables with your Langfuse secret and public keys found in your account profile.
+
+### Installation
+
+First, install `langfuse-haystack` package to use the `LangfuseConnector`:
+
+```shell
+pip install langfuse-haystack
+```
+
+`trace_url`: A link to the tracing data | +| **API reference** | [langfuse](/reference/integrations-langfuse) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/langfuse | + +
+ +:::info Usage Notice + +To ensure proper tracing, always set environment variables before importing any Haystack components. This is crucial because Haystack initializes its internal tracing components during import. In the example below, we first set the environmental variables and then import the relevant Haystack components. + +Alternatively, an even better practice is to set these environment variables in your shell before running the script. This approach keeps configuration separate from code and allows for easier management of different environments. +::: + +## Usage + +In the example below, we are adding `LangfuseConnector` to the pipeline as a _tracer_. Each pipeline run will produce one trace that includes the entire execution context, including prompts, completions, and metadata. + +You can then view the trace by following a URL link printed in the output. + +```python +import os + +os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" +os.environ["TOKENIZERS_PARALLELISM"] = "false" +os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true" + +from haystack.components.builders import DynamicChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack import Pipeline + +from haystack_integrations.components.connectors.langfuse import LangfuseConnector + +if __name__ == "__main__": + pipe = Pipeline() + pipe.add_component("tracer", LangfuseConnector("Chat example")) + pipe.add_component("prompt_builder", DynamicChatPromptBuilder()) + pipe.add_component("llm", OpenAIChatGenerator(model="gpt-3.5-turbo")) + + pipe.connect("prompt_builder.prompt", "llm.messages") + + messages = [ + ChatMessage.from_system("Always respond in German even if some input data is in other languages."), + ChatMessage.from_user("Tell me about {{location}}"), + ] + + response = pipe.run( + data={"prompt_builder": {"template_variables": {"location": "Berlin"}, "prompt_source": messages}} + ) + print(response["llm"]["replies"][0]) + print(response["tracer"]["trace_url"]) +``` + +### With an Agent + +```python +import os + +os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" +os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true" + +from typing import Annotated + +from haystack.components.agents import Agent +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack.tools import tool +from haystack import Pipeline + +from haystack_integrations.components.connectors.langfuse import LangfuseConnector + +@tool +def get_weather(city: Annotated[str, "The city to get weather for"]) -> str: +"""Get current weather information for a city.""" +weather_data = { + "Berlin": "18°C, partly cloudy", + "New York": "22°C, sunny", + "Tokyo": "25°C, clear skies" +} +return weather_data.get(city, f"Weather information for {city} not available") + +@tool +def calculate(operation: Annotated[str, "Mathematical operation: add, subtract, multiply, divide"], + a: Annotated[float, "First number"], + b: Annotated[float, "Second number"]) -> str: +"""Perform basic mathematical calculations.""" +if operation == "add": + result = a + b + elif operation == "subtract": + result = a - b + elif operation == "multiply": + result = a * b + elif operation == "divide": + if b == 0: + return "Error: Division by zero" + result = a / b + else: + return f"Error: Unknown operation '{operation}'" + +return f"The result of {a} {operation} {b} is {result}" + +if __name__ == "__main__": +## Create components +chat_generator = OpenAIChatGenerator() + +agent = Agent( + chat_generator=chat_generator, + tools=[get_weather, calculate], + system_prompt="You are a helpful assistant with access to weather and calculator tools. Use them when needed.", + exit_conditions=["text"] +) + +langfuse_connector = LangfuseConnector("Agent Example") + +## Create and run pipeline +pipe = Pipeline() +pipe.add_component("tracer", langfuse_connector) +pipe.add_component("agent", agent) + +response = pipe.run( + data={ + "agent": {"messages": [ChatMessage.from_user("What's the weather in Berlin and calculate 15 + 27?")]}, + "tracer": {"invocation_context": {"test": "agent_with_tools"}} + } +) + +print(response["agent"]["last_message"].text) +print(response["tracer"]["trace_url"]) +``` + +## Advanced Usage + +### Customizing Langfuse Traces with SpanHandler + +The `SpanHandler` interface in Haystack allows you to customize how spans are created and processed for Langfuse trace creation. This enables you to log custom metrics, add tags, or integrate metadata. + +By extending `SpanHandler` or its default implementation, `DefaultSpanHandler`, you can define custom logic for span processing, providing precise control over what data is logged to Langfuse for tracking and analyzing pipeline executions. + +Here's an example: + +```python +from haystack_integrations.tracing.langfuse import LangfuseConnector, DefaultSpanHandler, LangfuseSpan +from typing import Optional + +class CustomSpanHandler(DefaultSpanHandler): + def handle(self, span: LangfuseSpan, component_type: Optional[str]) -> None: + # Custom logic to add metadata or modify span + if component_type == "OpenAIChatGenerator": + output = span._data.get("haystack.component.output", {}) + if len(output.get("text", "")) < 10: + span._span.update(level="WARNING", status_message="Response too short") + +## Add the custom handler to the LangfuseConnector +connector = LangfuseConnector(span_handler=CustomSpanHandler()) +``` diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/openapiconnector.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/openapiconnector.mdx new file mode 100644 index 0000000000..4d44f8c5aa --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/openapiconnector.mdx @@ -0,0 +1,101 @@ +--- +title: "OpenAPIConnector" +id: openapiconnector +slug: "/openapiconnector" +description: "`OpenAPIConnector` is a component that acts as an interface between the Haystack ecosystem and OpenAPI services." +--- + +# OpenAPIConnector + +`OpenAPIConnector` is a component that acts as an interface between the Haystack ecosystem and OpenAPI services. + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Anywhere, after components providing input for its run parameters |
+| **Mandatory init variables** | `openapi_spec`: The OpenAPI specification for the service. Can be a URL, file path, or raw string. |
+| **Mandatory run variables** | `operation_id`: The operationId from the OpenAPI spec to invoke. |
+| **Output variables** | `response`: A REST service response |
+| **API reference** | [Connectors](/reference/connectors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/connectors/openapi.py |
+
+
+
+## Overview
+
+The `OpenAPIConnector` is a component within the Haystack ecosystem that allows direct invocation of REST endpoints defined in an OpenAPI (formerly Swagger) specification. It acts as a bridge between Haystack pipelines and any REST API that follows the OpenAPI standard, enabling dynamic method calls, authentication, and parameter handling.
+
+To use the `OpenAPIConnector`, ensure that you have the `openapi-llm` dependency installed:
+
+```shell
+pip install openapi-llm
+```
+
+Unlike [OpenAPIServiceConnector](openapiserviceconnector.mdx), which works with LLMs, `OpenAPIConnector` directly calls REST endpoints using explicit input arguments.
+
+## Usage
+
+### On its own
+
+You can initialize and use the `OpenAPIConnector` on its own by passing an OpenAPI specification and other parameters:
+
+```python
+from haystack.utils import Secret
+from haystack.components.connectors.openapi import OpenAPIConnector
+
+connector = OpenAPIConnector(
+ openapi_spec="https://bit.ly/serperdev_openapi",
+ credentials=Secret.from_env_var("SERPERDEV_API_KEY"),
+ service_kwargs={"config_factory": my_custom_config_factory}
+)
+
+response = connector.run(
+ operation_id="search",
+ arguments={"q": "Who was Nikola Tesla?"}
+)
+```
+
+#### Output
+
+The `OpenAPIConnector` returns a dictionary containing the service response:
+
+```json
+{
+ "response": { // here goes REST endpoint response JSON
+ }
+}
+```
+
+### In a pipeline
+
+The `OpenAPIConnector` can be integrated into a Haystack pipeline to interact with OpenAPI services. For example, here’s how you can link the `OpenAPIConnector` to a pipeline:
+
+```python
+from haystack import Pipeline
+from haystack.components.connectors.openapi import OpenAPIConnector
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack.utils import Secret
+
+## Initialize the OpenAPIConnector
+connector = OpenAPIConnector(
+ openapi_spec="https://bit.ly/serperdev_openapi",
+ credentials=Secret.from_env_var("SERPERDEV_API_KEY")
+)
+
+## Create a ChatMessage from the user
+user_message = ChatMessage.from_user(text="Who was Nikola Tesla?")
+
+## Define the pipeline
+pipeline = Pipeline()
+pipeline.add_component("openapi_connector", connector)
+
+## Run the pipeline
+response = pipeline.run(
+ data={"openapi_connector": {"operation_id": "search", "arguments": {"q": user_message.text}}}
+)
+
+## Extract the answer from the response
+answer = response.get("openapi_connector", {}).get("response", {})
+print(answer)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/openapiserviceconnector.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/openapiserviceconnector.mdx
new file mode 100644
index 0000000000..e743f45806
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/openapiserviceconnector.mdx
@@ -0,0 +1,111 @@
+---
+title: "OpenAPIServiceConnector"
+id: openapiserviceconnector
+slug: "/openapiserviceconnector"
+description: "`OpenAPIServiceConnector` is a component that acts as an interface between the Haystack ecosystem and OpenAPI services."
+---
+
+# OpenAPIServiceConnector
+
+`OpenAPIServiceConnector` is a component that acts as an interface between the Haystack ecosystem and OpenAPI services.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects where the last message is expected to carry parameter invocation payload.
`service_openapi_spec`: OpenAPI specification of the service being invoked. It can be YAML/JSON, and all ref values must be resolved.
`service_credentials`: Authentication credentials for the service. We currently support two OpenAPI spec v3 security schemes:
1. http – for Basic, Bearer, and other HTTP authentication schemes;
2. apiKey – for API keys and cookie authentication. | +| **Output variables** | `service_response`: A dictionary that is a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects where each message corresponds to a function invocation.
If a user specifies multiple function calling requests, there will be multiple responses. | +| **API reference** | [Connectors](/reference/connectors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/connectors/openapi_service.py | + +
+
+## Overview
+
+`OpenAPIServiceConnector` acts as a bridge between Haystack ecosystem and OpenAPI services. This component works by using information from a `ChatMessage` to dynamically invoke service methods. It handles parameter payload parsing from `ChatMessage`, service authentication, method invocation, and response formatting, making it easier to integrate OpenAPI services.
+
+To use `OpenAPIServiceConnector`, you need to install the optional `openapi3` dependency with:
+
+```shell
+pip install openapi3
+```
+
+`OpenAPIServiceConnector` component doesn’t have any init parameters.
+
+## Usage
+
+### On its own
+
+This component is primarily meant to be used in pipelines, as [`OpenAPIServiceToFunctions`](../converters/openapiservicetofunctions.mdx), in tandem with the function calling model, resolves the actual function calling parameters that are injected as invocation parameters for `OpenAPIServiceConnector`.
+
+### In a pipeline
+
+Let's say we're linking the Serper search engine to a pipeline. Here, `OpenAPIServiceConnector` uses the abilities of `OpenAPIServiceToFunctions`. `OpenAPIServiceToFunctions` first fetches and changes the [Serper's OpenAPI specification](https://bit.ly/serper_dev_spec) into a format that OpenAI's function calling mechanism can understand. Then, `OpenAPIServiceConnector` activates the Serper service using this specification.
+
+More precisely, `OpenAPIServiceConnector` dynamically calls methods defined in the Serper OpenAPI specification. This involves reading chat messages or other inputs to extract function call parameters, handling authentication with the Serper service, and making the right API calls. The connector makes sure that the method call follows the Serper API requirements, such as correct formatting requests and handling responses.
+
+Note that we used Serper just as an example here. This could be any OpenAPI-compliant service.
+
+:::info
+To run the following code snippet, note that you have to have your own Serper and OpenAI API keys.
+:::
+
+```python
+import json
+import requests
+
+from typing import Dict, Any, List
+from haystack import Pipeline
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.components.converters import OpenAPIServiceToFunctions, OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.connectors import OpenAPIServiceConnector
+from haystack.components.fetchers import LinkContentFetcher
+from haystack.dataclasses import ChatMessage, ByteStream
+from haystack.utils import Secret
+
+def prepare_fc_params(openai_functions_schema: Dict[str, Any]) -> Dict[str, Any]:
+ return {
+ "tools": [{
+ "type": "function",
+ "function": openai_functions_schema
+ }],
+ "tool_choice": {
+ "type": "function",
+ "function": {"name": openai_functions_schema["name"]}
+ }
+ }
+
+system_prompt = requests.get("https://bit.ly/serper_dev_system_prompt").text
+serper_spec = requests.get("https://bit.ly/serper_dev_spec").text
+
+pipe = Pipeline()
+pipe.add_component("spec_to_functions", OpenAPIServiceToFunctions())
+pipe.add_component("functions_llm", OpenAIChatGenerator(api_key=Secret.from_token(llm_api_key), model="gpt-3.5-turbo-0613"))
+pipe.add_component("openapi_container", OpenAPIServiceConnector())
+pipe.add_component("a1", OutputAdapter("{{functions[0] | prepare_fc}}", Dict[str, Any], {"prepare_fc": prepare_fc_params}))
+pipe.add_component("a2", OutputAdapter("{{specs[0]}}", Dict[str, Any]))
+pipe.add_component("a3", OutputAdapter("{{system_message + service_response}}", List[ChatMessage]))
+pipe.add_component("llm", OpenAIChatGenerator(api_key=Secret.from_token(llm_api_key), model="gpt-4-1106-preview", streaming_callback=print_streaming_chunk))
+
+pipe.connect("spec_to_functions.functions", "a1.functions")
+pipe.connect("spec_to_functions.openapi_specs", "a2.specs")
+pipe.connect("a1", "functions_llm.generation_kwargs")
+pipe.connect("functions_llm.replies", "openapi_container.messages")
+pipe.connect("a2", "openapi_container.service_openapi_spec")
+pipe.connect("openapi_container.service_response", "a3.service_response")
+pipe.connect("a3", "llm.messages")
+
+user_prompt = "Why was Sam Altman ousted from OpenAI?"
+
+result = pipe.run(data={"functions_llm": {"messages":[ChatMessage.from_system("Only do function calling"), ChatMessage.from_user(user_prompt)]},
+ "openapi_container": {"service_credentials": serper_dev_key},
+ "spec_to_functions": {"sources": [ByteStream.from_string(serper_spec)]},
+ "a3": {"system_message": [ChatMessage.from_system(system_prompt)]}})
+
+>Sam Altman was ousted from OpenAI on November 17, 2023, following
+>a "deliberative review process" by the board of directors. The board concluded
+>that he was not "consistently candid in his communications". However, he
+>returned as CEO just days after his ouster.
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/weaveconnector.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/weaveconnector.mdx
new file mode 100644
index 0000000000..072a3d602a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/weaveconnector.mdx
@@ -0,0 +1,171 @@
+---
+title: "WeaveConnector"
+id: weaveconnector
+slug: "/weaveconnector"
+description: "Learn how to use Weights & Biases Weave framework for tracing and monitoring your pipeline components."
+---
+
+# WeaveConnector
+
+Learn how to use Weights & Biases Weave framework for tracing and monitoring your pipeline components.
+
+`service_openapi_spec`: OpenAPI specification of the service being invoked. It can be YAML/JSON, and all ref values must be resolved.
`service_credentials`: Authentication credentials for the service. We currently support two OpenAPI spec v3 security schemes:
1. http – for Basic, Bearer, and other HTTP authentication schemes;
2. apiKey – for API keys and cookie authentication. | +| **Output variables** | `service_response`: A dictionary that is a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects where each message corresponds to a function invocation.
If a user specifies multiple function calling requests, there will be multiple responses. | +| **API reference** | [Connectors](/reference/connectors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/connectors/openapi_service.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Anywhere, as it’s not connected to other components |
+| **Mandatory init variables** | `pipeline_name`: The name of your pipeline, which will also show up in Weaver dashboard. |
+| **Output variables** | `pipeline_name`: The name of the pipeline that just run |
+| **API reference** | [weights and bias](/reference/integrations-weights-bias) |
+| **GitHub link** | [\https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/weights_and_biases_weave](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/weights_and_biases_weave) |
+
+
+
+## Overview
+
+This integration allows you to trace and visualize your pipeline execution in [Weights & Biases](https://wandb.ai/site/).
+
+Information captured by the Haystack tracing tool, such as API calls, context data, and prompts, is sent to Weights & Biases, where you can see the complete trace of your pipeline execution.
+
+### Prerequisites
+
+You need a Weave account to use this feature. You can sign up for free at [Weights & Biases website](https://wandb.ai/site).
+
+You will then need to set the `WANDB_API_KEY` environment variable with your Weights & Biases API key. Once logged in, you can find your API key on [your home page](https://wandb.ai/home).
+
+Then go to `https://wandb.ai/
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory init variables** | `endpoint`: The endpoint of your Azure resource
`api_key`: The API key of your Azure resource. Can be set with `AZURE_AI_API_KEY` environment variable. | +| **Mandatory run variables** | `sources`: A list of file paths | +| **Output variables** | `documents`: A list of documents
`raw_azure_response`: A list of raw responses from Azure | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/azure.py | + +
+
+## Overview
+
+`AzureOCRDocumentConverter` takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and uses Azure services to convert the files to a list of documents. Optionally, metadata can be attached to the documents through the `meta` input parameter. You need an active Azure account and a Document Intelligence or Cognitive Services resource to use this integration. Follow the steps described in the Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/quickstarts/get-started-sdks-rest-api) to set up your resource.
+
+The component uses an `AZURE_AI_API_KEY` environment variable by default. Otherwise, you can pass an `api_key` at initialization – see code examples below.
+
+When you initialize the component, you can optionally set the `model_id`, which refers to the model you want to use. Please refer to [Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/choose-model-feature) for a list of available models. The default model is `"prebuilt-read"`.
+
+The `AzureOCRDocumentConverter` doesn’t extract the tables from a file as plain text but generates separate `Document` objects of type `table` that maintain the two-dimensional structure of the tables.
+
+## Usage
+
+You need to install `azure-ai-formrecognizer` package to use the `AzureOCRDocumentConverter`:
+
+```shell
+pip install "azure-ai-formrecognizer>=3.2.0b2"
+```
+
+### On its own
+
+```python
+from pathlib import Path
+
+from haystack.components.converters import AzureOCRDocumentConverter
+from haystack.utils import Secret
+
+converter = AzureOCRDocumentConverter(
+ endpoint="azure_resource_url",
+ api_key=Secret.from_token("`api_key`: The API key of your Azure resource. Can be set with `AZURE_AI_API_KEY` environment variable. | +| **Mandatory run variables** | `sources`: A list of file paths | +| **Output variables** | `documents`: A list of documents
`raw_azure_response`: A list of raw responses from Azure | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/azure.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/csv.py |
+
+
+
+## Overview
+
+`CSVToDocument` converts one or more CSV files into a text document.
+
+The component uses UTF-8 encoding by default, but you may specify a different encoding if needed during initialization.
+You can optionally attach metadata to each document with a `meta` parameter when running the component.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.converters.csv import CSVToDocument
+
+converter = CSVToDocument()
+results = converter.run(sources=["sample.csv"], meta={"date_added": datetime.now().isoformat()})
+documents = results["documents"]
+
+print(documents[0].content)
+## 'col1,col2\now1,row1\nrow2row2\n'
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import CSVToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", CSVToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/documenttoimagecontent.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/documenttoimagecontent.mdx
new file mode 100644
index 0000000000..440f1db9ae
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/documenttoimagecontent.mdx
@@ -0,0 +1,146 @@
+---
+title: "DocumentToImageContent"
+id: documenttoimagecontent
+slug: "/documenttoimagecontent"
+description: "`DocumentToImageContent` extracts visual data from image or PDF file-based documents and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image question-answering and captioning."
+---
+
+# DocumentToImageContent
+
+`DocumentToImageContent` extracts visual data from image or PDF file-based documents and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image question-answering and captioning.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a `ChatPromptBuilder` in a query pipeline |
+| **Mandatory run variables** | `documents`: A list of documents to process. Each document should have metadata containing at minimum a 'file_path_meta_field' key. PDF documents additionally require a 'page_number' key to specify which page to convert. |
+| **Output variables** | `image_contents`: A list of `ImageContent` objects |
+| **API reference** | [Image Converters](/reference/image-converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/image/document_to_image.py |
+
+
+
+## Overview
+
+`DocumentToImageContent` processes a list of documents containing image or PDF file paths and converts them into `ImageContent` objects.
+
+- For images, it reads and encodes the file directly.
+- For PDFs, it extracts the specified page (through `page_number` in metadata) and converts it to an image.
+
+By default, it looks for the file path in the `file_path` metadata field. You can customize this with the `file_path_meta_field` parameter. The `root_path` lets you specify a common base directory for file resolution.
+
+This component is typically used in query pipelines right before a `ChatPromptBuilder` when you would like to add Images to your user prompt.
+
+If `size` is provided, the images will be resized while maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial when working with models that have resolution constraints or when transmitting images to remote services.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.converters.image.document_to_image import DocumentToImageContent
+
+converter = DocumentToImageContent(
+ file_path_meta_field="file_path",
+ root_path="/data/documents",
+ detail="high",
+ size=(800, 600)
+)
+
+documents = [
+ Document(content="Photo of a mountain", meta={"file_path": "mountain.jpg"}),
+ Document(content="First page of a report", meta={"file_path": "report.pdf", "page_number": 1})
+]
+
+result = converter.run(documents)
+image_contents = result["image_contents"]
+print(image_contents)
+
+## [
+## ImageContent(
+## base64_image="/9j/4A...", mime_type="image/jpeg", detail="high",
+## meta={"file_path": "mountain.jpg"}
+## ),
+## ImageContent(
+## base64_image="/9j/4A...", mime_type="image/jpeg", detail="high",
+## meta={"file_path": "report.pdf", "page_number": 1}
+## )
+## ]
+```
+
+### In a pipeline
+
+You can use `DocumentToImageContent` in multimodal indexing pipelines before passing to an Embedder or captioning model.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.converters.image.document_to_image import DocumentToImageContent
+
+## Query pipeline
+pipeline = Pipeline()
+pipeline.add_component("image_converter", DocumentToImageContent(detail="auto"))
+pipeline.add_component(
+ "chat_prompt_builder",
+ ChatPromptBuilder(
+ required_variables=["question"],
+ template="""{% message role="system" %}
+You are a friendly assistant that answers questions based on provided images.
+{% endmessage %}
+
+{%- message role="user" -%}
+Only provide an answer to the question using the images provided.
+
+Question: {{ question }}
+Answer:
+
+{%- for img in image_contents -%}
+ {{ img | templatize_part }}
+{%- endfor -%}
+{%- endmessage -%}
+""",
+ )
+)
+pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+
+pipeline.connect("image_converter", "chat_prompt_builder.image_contents")
+pipeline.connect("chat_prompt_builder", "llm")
+
+documents = [
+ Document(content="Cat image", meta={"file_path": "cat.jpg"}),
+ Document(content="Doc intro", meta={"file_path": "paper.pdf", "page_number": 1}),
+]
+
+result = pipeline.run(
+ data={
+ "image_converter": {"documents": documents},
+ "chat_prompt_builder": {"question": "What color is the cat?"}
+ }
+)
+print(result)
+
+## {
+## "llm": {
+## "replies": [
+## ChatMessage(
+## _role=
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: DOCX file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/docx.py |
+
+
+
+## Overview
+
+The `DOCXToDocument` component converts DOCX files into documents. It takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. By defining the table format (CSV or Markdown), you can use this component to extract tables in your DOCX files. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+## Usage
+
+First, install the`python-docx` package to start using this converter:
+
+```shell
+pip install python-docx
+```
+
+### On its own
+
+```python
+from haystack.components.converters.docx import DOCXToDocument, DOCXTableFormat
+
+converter = DOCXToDocument()
+## or define the table format
+converter = DOCXToDocument(table_format=DOCXTableFormat.CSV)
+
+results = converter.run(sources=["sample.docx"], meta={"date_added": datetime.now().isoformat()})
+documents = results["documents"]
+
+print(documents[0].content)
+
+## 'This is the text from the DOCX file.'
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import DOCXToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", DOCXToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/external-integrations-converters.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/external-integrations-converters.mdx
new file mode 100644
index 0000000000..44d175312b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/external-integrations-converters.mdx
@@ -0,0 +1,14 @@
+---
+title: "External Integrations"
+id: external-integrations-converters
+slug: "/external-integrations-converters"
+description: "External integrations that enable extracting data from files in different formats and cast it into the unified document format."
+---
+
+# External Integrations
+
+External integrations that enable extracting data from files in different formats and cast it into the unified document format.
+
+| Name | Description |
+| --- | --- |
+| [Docling](https://haystack.deepset.ai/integrations/docling/) | Parse PDF, DOCX, HTML, and other document formats into a rich standardized representation (such as layout, tables..), which it can then export to Markdown, JSON, and other formats. |
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/htmltodocument.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/htmltodocument.mdx
new file mode 100644
index 0000000000..4d26da8e54
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/htmltodocument.mdx
@@ -0,0 +1,67 @@
+---
+title: "HTMLToDocument"
+id: htmltodocument
+slug: "/htmltodocument"
+description: "A component that converts HTML files to documents."
+---
+
+# HTMLToDocument
+
+A component that converts HTML files to documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of HTML file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/html.py |
+
+
+
+## Overview
+
+The `HTMLToDocument` component converts HTML files into documents. It can be used in an indexing pipeline to index the contents of an HTML file into a Document Store or even in a querying pipeline after the [`LinkContentFetcher`](../fetchers/linkcontentfetcher.mdx). The `HTMLToDocument` component takes a list of HTML file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and converts the files to a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+When you initialize the component, you can optionally set `extraction_kwargs`, a dictionary containing keyword arguments to customize the extraction process. These are passed to the underlying Trafilatura `extract` function. For the full list of available arguments, see the [Trafilatura documentation](https://trafilatura.readthedocs.io/en/latest/corefunctions.html#extract).
+
+## Usage
+
+### On its own
+
+```python
+from pathlib import Path
+from haystack.components.converters import HTMLToDocument
+
+converter = HTMLToDocument()
+
+docs = converter.run(sources=[Path("saved_page.html")])
+```
+
+### In a pipeline
+
+Here's an example of an indexing pipeline that writes the contents of an HTML file into an `InMemoryDocumentStore`:
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import HTMLToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", HTMLToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/imagefiletodocument.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/imagefiletodocument.mdx
new file mode 100644
index 0000000000..748d37474d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/imagefiletodocument.mdx
@@ -0,0 +1,100 @@
+---
+title: "ImageFileToDocument"
+id: imagefiletodocument
+slug: "/imagefiletodocument"
+description: "Converts image file references into empty `Document` objects with associated metadata."
+---
+
+# ImageFileToDocument
+
+Converts image file references into empty `Document` objects with associated metadata.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a component that processes images, like `SentenceTransformersImageDocumentEmbedder` or `LLMDocumentContentExtractor` |
+| **Mandatory run variables** | `sources`: A list of image file paths or ByteStreams |
+| **Output variables** | `documents`: A list of empty Document objects with associated metadata |
+| **API reference** | [Image Converters](/reference/image-converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/image/file_to_document.py |
+
+
+
+## Overview
+
+`ImageFileToDocument` converts image file sources into empty `Document` objects with associated metadata.
+
+This component is useful in pipelines where image file paths need to be wrapped in `Document` objects to be processed by downstream components such as `SentenceTransformersImageDocumentEmbedder` or `LLMDocumentContentExtractor`.
+
+It _does not_ extract any content from the image files, but instead creates `Document` objects with `None` as their content and attaches metadata such as file path and any user-provided values.
+
+Each source can be:
+
+- A file path (string or `Path`), or
+- A `ByteStream` object.
+
+Optionally, you can provide metadata using the `meta` parameter. This can be a single dictionary (applied to all documents) or a list matching the length of `sources`.
+
+## Usage
+
+### On its own
+
+This component is primarily meant to be used in pipelines.
+
+```python
+
+from haystack.components.converters.image import ImageFileToDocument
+
+converter = ImageFileToDocument()
+
+sources = ["image.jpg", "another_image.png"]
+
+result = converter.run(sources=sources)
+documents = result["documents"]
+
+print(documents)
+
+## [Document(id=..., content=None, meta={'file_path': 'image.jpg'}),
+## Document(id=..., content=None, meta={'file_path': 'another_image.png'})]
+```
+
+### In a pipeline
+
+In the following Pipeline, image documents are created using the `ImageFileToDocument` component, then they are enriched with image embeddings and saved in the Document Store.
+
+```python
+from haystack import Pipeline
+from haystack.components.converters.image import ImageFileToDocument
+from haystack.components.embedders.image import SentenceTransformersDocumentImageEmbedder
+from haystack.components.writers.document_writer import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+## Create our document store
+doc_store = InMemoryDocumentStore()
+
+## Define pipeline with components
+indexing_pipe = Pipeline()
+indexing_pipe.add_component("image_converter", ImageFileToDocument(store_full_path=True))
+indexing_pipe.add_component("image_doc_embedder", SentenceTransformersDocumentImageEmbedder())
+indexing_pipe.add_component("document_writer", DocumentWriter(doc_store))
+
+indexing_pipe.connect("image_converter.documents", "image_doc_embedder.documents")
+indexing_pipe.connect("image_doc_embedder.documents", "document_writer.documents")
+
+indexing_result = indexing_pipe.run(
+ data={"image_converter": {"sources": [
+ "apple.jpg",
+ "kiwi.png"
+ ]}},
+)
+
+indexed_documents = doc_store.filter_documents()
+print(f"Indexed {len(indexed_documents)} documents")
+## Indexed 2 documents
+
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Introduction to Multimodality](https://haystack.deepset.ai/cookbook/multimodal_intro)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/imagefiletoimagecontent.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/imagefiletoimagecontent.mdx
new file mode 100644
index 0000000000..67a9af6ad2
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/imagefiletoimagecontent.mdx
@@ -0,0 +1,129 @@
+---
+title: "ImageFileToImageContent"
+id: imagefiletoimagecontent
+slug: "/imagefiletoimagecontent"
+description: "`ImageFileToImageContent` reads local image files and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image captioning, visual QA, or prompt-based generation."
+---
+
+# ImageFileToImageContent
+
+`ImageFileToImageContent` reads local image files and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image captioning, visual QA, or prompt-based generation.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a `ChatPromptBuilder` in a query pipeline |
+| **Mandatory run variables** | `sources`: A list of image file paths or ByteStreams |
+| **Output variables** | `image_contents`: A list of ImageContent objects |
+| **API reference** | [Image Converters](/reference/image-converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/image/file_to_image.py |
+
+
+
+## Overview
+
+`ImageFileToImageContent` processes a list of image sources and converts them into `ImageContent` objects. These can be used in multimodal pipelines that require base64-encoded image input.
+
+Each source can be:
+
+- A file path (string or `Path`), or
+- A `ByteStream` object.
+
+Optionally, you can provide metadata using the `meta` parameter. This can be a single dictionary (applied to all images) or a list matching the length of `sources`.
+
+Use the `size` parameter to resize images while preserving aspect ratio. This reduces memory usage and transmission size, which is helpful when working with remote models or limited-resource environments.
+
+This component is often used in query pipelines just before a `ChatPromptBuilder`.
+
+## Usage
+
+### On its own
+
+```python
+
+from haystack.components.converters.image import ImageFileToImageContent
+
+converter = ImageFileToImageContent(detail="high", size=(800, 600))
+
+sources = ["cat.jpg", "scenery.png"]
+
+result = converter.run(sources=sources)
+image_contents = result["image_contents"]
+print(image_contents)
+
+## [
+## ImageContent(
+## base64_image="/9j/4A...", mime_type="image/jpeg", detail="high",
+## meta={"file_path": "cat.jpg"}
+## ),
+## ImageContent(
+## base64_image="/9j/4A...", mime_type="image/png", detail="high",
+## meta={"file_path": "scenery.png"}
+## )
+## ]
+```
+
+### In a pipeline
+
+Use `ImageFileToImageContent` to supply image data to a `ChatPromptBuilder` for multimodal QA or captioning with an LLM.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.converters.image import ImageFileToImageContent
+
+## Query pipeline
+pipeline = Pipeline()
+pipeline.add_component("image_converter", ImageFileToImageContent(detail="auto"))
+pipeline.add_component(
+ "chat_prompt_builder",
+ ChatPromptBuilder(
+ required_variables=["question"],
+ template="""{% message role="system" %}
+You are a helpful assistant that answers questions using the provided images.
+{% endmessage %}
+
+{% message role="user" %}
+Question: {{ question }}
+
+{% for img in image_contents %}
+{{ img | templatize_part }}
+{% endfor %}
+{% endmessage %}
+"""
+ )
+)
+pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+
+pipeline.connect("image_converter", "chat_prompt_builder.image_contents")
+pipeline.connect("chat_prompt_builder", "llm")
+
+sources = ["apple.jpg", "haystack-logo.png"]
+
+result = pipeline.run(
+ data={
+ "image_converter": {"sources": sources},
+ "chat_prompt_builder": {"question": "Describe the Haystack logo."}
+ }
+)
+print(result)
+
+## {
+## "llm": {
+## "replies": [
+## ChatMessage(
+## _role=
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory init variables** | ONE OF, OR BOTH:
`jq_schema`: A jq filter string to extract content
`content_key`: A key string to extract document content | +| **Mandatory run variables** | `sources`: A list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/json.py | + +
+
+## Overview
+
+`JSONConverter` converts one or more JSON files into a text document.
+
+### Parameters Overview
+
+To initialize `JSONConverter`, you must provide either `jq_schema`, or `content_key` parameter, or both.
+
+`jq_schema` parameter filter extracts nested data from JSON files. Refer to the [jq documentation](https://jqlang.github.io/jq/) for filter syntax. If not set, the entire JSON file is used.
+
+The `content_key` parameter lets you specify which key in the extracted data will be the document's content.
+
+- If both `jq_schema` and `content_key` are set, the `content_key` is searched in the data extracted by `jq_schema`. Non-object data will be skipped.
+- If only `jq_schema` is set, the extracted value must be scalar; objects or arrays will be skipped.
+- If only `content_key` is set, the source must be a JSON object, or it will be skipped.
+
+Check out the [API reference](../converters.mdx) for the full list of parameters.
+
+## Usage
+
+You need to install the `jq` package to use this Converter:
+
+```shell
+pip install jq
+```
+
+### Example
+
+Here is an example of simple component usage:
+
+```python
+import json
+
+from haystack.components.converters import JSONConverter
+from haystack.dataclasses import ByteStream
+
+source = ByteStream.from_string(json.dumps({"text": "This is the content of my document"}))
+
+converter = JSONConverter(content_key="text")
+results = converter.run(sources=[source])
+documents = results["documents"]
+print(documents[0].content)
+## 'This is the content of my document'
+```
+
+In the following more complex example, we provide a `jq_schema` string to filter the JSON source files and `extra_meta_fields` to extract from the filtered data:
+
+```python
+import json
+
+from haystack.components.converters import JSONConverter
+from haystack.dataclasses import ByteStream
+
+data = {
+ "laureates": [
+ {
+ "firstname": "Enrico",
+ "surname": "Fermi",
+ "motivation": "for his demonstrations of the existence of new radioactive elements produced "
+ "by neutron irradiation, and for his related discovery of nuclear reactions brought about by"
+ " slow neutrons",
+ },
+ {
+ "firstname": "Rita",
+ "surname": "Levi-Montalcini",
+ "motivation": "for their discoveries of growth factors",
+ },
+ ],
+}
+source = ByteStream.from_string(json.dumps(data))
+converter = JSONConverter(
+ jq_schema=".laureates[]", content_key="motivation", extra_meta_fields={"firstname", "surname"}
+)
+
+results = converter.run(sources=[source])
+documents = results["documents"]
+print(documents[0].content)
+## 'for his demonstrations of the existence of new radioactive elements produced by
+## neutron irradiation, and for his related discovery of nuclear reactions brought
+## about by slow neutrons'
+
+print(documents[0].meta)
+## {'firstname': 'Enrico', 'surname': 'Fermi'}
+
+print(documents[1].content)
+## 'for their discoveries of growth factors'
+
+print(documents[1].meta)
+## {'firstname': 'Rita', 'surname': 'Levi-Montalcini'}
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/markdowntodocument.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/markdowntodocument.mdx
new file mode 100644
index 0000000000..7444a2eb0e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/markdowntodocument.mdx
@@ -0,0 +1,74 @@
+---
+title: "MarkdownToDocument"
+id: markdowntodocument
+slug: "/markdowntodocument"
+description: "A component that converts Markdown files to documents."
+---
+
+# MarkdownToDocument
+
+A component that converts Markdown files to documents.
+
+`jq_schema`: A jq filter string to extract content
`content_key`: A key string to extract document content | +| **Mandatory run variables** | `sources`: A list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/json.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: Markdown file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/markdown.py |
+
+
+
+## Overview
+
+The `MarkdownToDocument` component converts Markdown files into documents. You can use it in an indexing pipeline to index the contents of a Markdown file into a Document Store. It takes a list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+When you initialize the component, you can optionally turn off progress bars by setting `progress_bar` to `False`. If you want to convert the contents of tables into a single line, you can enable that through the `table_to_single_line` parameter.
+
+## Usage
+
+You need to install `markdown-it-py` and `mdit_plain packages` to use the `MarkdownToDocument` component:
+
+```shell
+pip install markdown-it-py mdit_plain
+```
+
+### On its own
+
+```python
+from haystack.components.converters import MarkdownToDocument
+
+converter = MarkdownToDocument()
+
+docs = converter.run(sources=Path("my_file.md"))
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import MarkdownToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", MarkdownToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
+
+## Additional References
+
+:notebook: Tutorial: [Preprocessing Different File Types](https://haystack.deepset.ai/tutorials/30_file_type_preprocessing_index_pipeline)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/mistralocrdocumentconverter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/mistralocrdocumentconverter.mdx
new file mode 100644
index 0000000000..be926a0c35
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/mistralocrdocumentconverter.mdx
@@ -0,0 +1,172 @@
+---
+title: "MistralOCRDocumentConverter"
+id: mistralocrdocumentconverter
+slug: "/mistralocrdocumentconverter"
+description: "`MistralOCRDocumentConverter` extracts text from documents using Mistral's OCR API, with optional structured annotations for both individual image regions and full documents. It supports various input formats including local files, URLs, and Mistral file IDs."
+---
+
+# MistralOCRDocumentConverter
+
+`MistralOCRDocumentConverter` extracts text from documents using Mistral's OCR API, with optional structured annotations for both individual image regions and full documents. It supports various input formats including local files, URLs, and Mistral file IDs.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx), or right at the beginning of an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Mistral API key. Can be set with `MISTRAL_API_KEY` environment variable. |
+| **Mandatory run variables** | `sources`: A list of document sources (file paths, ByteStreams, URLs, or Mistral chunks) |
+| **Output variables** | `documents`: A list of documents
`raw_mistral_response`: A list of raw OCR responses from Mistral API | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | + +
+
+## Overview
+
+The `MistralOCRDocumentConverter` takes a list of document sources and uses Mistral's OCR API to extract text from images and PDFs. It supports multiple input formats:
+
+- **Local files**: File paths (str or Path) or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects
+- **Remote resources**: Document URLs, image URLs using Mistral's `DocumentURLChunk` and `ImageURLChunk`
+- **Mistral storage**: File IDs using Mistral's `FileChunk` for files previously uploaded to Mistral
+
+The component returns one Haystack [`Document`](../../concepts/data-classes.mdx#document) per source, with all pages concatenated using form feed characters (`\f`) as separators. This format ensures compatibility with Haystack's [`DocumentSplitter`](../preprocessors/documentsplitter.mdx) for accurate page-wise splitting and overlap handling. The content is returned in markdown format, with images represented as `` tags.
+
+By default, the component uses the `MISTRAL_API_KEY` environment variable for authentication. You can also pass an `api_key` at initialization. Local files are automatically uploaded to Mistral's storage for processing and deleted afterward (configurable with `cleanup_uploaded_files`).
+
+When you initialize the component, you can optionally specify which pages to process, set limits on image extraction, configure minimum image sizes, or include base64-encoded images in the response. The default model is `"mistral-ocr-2505"`. See the [Mistral models documentation](https://docs.mistral.ai/getting-started/models/models_overview/) for available models.
+
+### Structured Annotations
+
+A unique feature of `MistralOCRDocumentConverter` is its support for structured annotations using Pydantic schemas:
+
+- **Bounding box annotations** (`bbox_annotation_schema`): Annotate individual image regions with structured data (for example, image type, description, summary). These annotations are inserted inline after the corresponding image tags in the markdown content.
+- **Document annotations** (`document_annotation_schema`): Annotate the full document with structured data (for example, language, chapter titles, URLs). These annotations are unpacked into the document's metadata with a `source_` prefix (for example, `source_language`, `source_chapter_titles`).
+
+When annotation schemas are provided, the OCR model first extracts text and structure, then a Vision LLM analyzes the content and generates structured annotations according to your defined Pydantic schemas. Note that document annotation is limited to a maximum of 8 pages. For more details, see the [Mistral documentation on annotations](https://docs.mistral.ai/capabilities/document_ai/annotations/).
+
+## Usage
+
+You need to install the `mistral-haystack` integration to use `MistralOCRDocumentConverter`:
+
+```shell
+pip install mistral-haystack
+```
+
+### On its own
+
+Basic usage with a local file:
+
+```python
+from pathlib import Path
+from haystack.utils import Secret
+from haystack_integrations.components.converters.mistral import MistralOCRDocumentConverter
+
+converter = MistralOCRDocumentConverter(
+ api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+ model="mistral-ocr-2505"
+)
+
+result = converter.run(sources=[Path("my_document.pdf")])
+documents = result["documents"]
+```
+
+Processing multiple sources with different types:
+
+```python
+from pathlib import Path
+from haystack.utils import Secret
+from haystack_integrations.components.converters.mistral import MistralOCRDocumentConverter
+from mistralai.models import DocumentURLChunk, ImageURLChunk
+
+converter = MistralOCRDocumentConverter(
+ api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+ model="mistral-ocr-2505"
+)
+
+sources = [
+ Path("local_document.pdf"),
+ DocumentURLChunk(document_url="https://example.com/document.pdf"),
+ ImageURLChunk(image_url="https://example.com/receipt.jpg"),
+]
+
+result = converter.run(sources=sources)
+documents = result["documents"] # List of 3 Documents
+raw_responses = result["raw_mistral_response"] # List of 3 raw responses
+```
+
+Using structured annotations:
+
+```python
+from pathlib import Path
+from typing import List
+from pydantic import BaseModel, Field
+from haystack.utils import Secret
+from haystack_integrations.components.converters.mistral import MistralOCRDocumentConverter
+from mistralai.models import DocumentURLChunk
+
+# Define schema for image region annotations
+class ImageAnnotation(BaseModel):
+ image_type: str = Field(..., description="The type of image content")
+ short_description: str = Field(..., description="Short natural-language description")
+ summary: str = Field(..., description="Detailed summary of the image content")
+
+# Define schema for document-level annotations
+class DocumentAnnotation(BaseModel):
+ language: str = Field(..., description="Primary language of the document")
+ chapter_titles: List[str] = Field(..., description="Detected chapter or section titles")
+ urls: List[str] = Field(..., description="URLs found in the text")
+
+converter = MistralOCRDocumentConverter(
+ api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+ model="mistral-ocr-2505"
+)
+
+sources = [DocumentURLChunk(document_url="https://example.com/report.pdf")]
+result = converter.run(
+ sources=sources,
+ bbox_annotation_schema=ImageAnnotation,
+ document_annotation_schema=DocumentAnnotation,
+)
+
+documents = result["documents"]
+# Document metadata will include:
+# - source_language: extracted from DocumentAnnotation
+# - source_chapter_titles: extracted from DocumentAnnotation
+# - source_urls: extracted from DocumentAnnotation
+# Document content will include inline image annotations
+```
+
+### In a pipeline
+
+Here's an example of an indexing pipeline that processes PDFs with OCR and writes them to a Document Store:
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.preprocessors import DocumentCleaner, DocumentSplitter
+from haystack.components.writers import DocumentWriter
+from haystack.utils import Secret
+from haystack_integrations.components.converters.mistral import MistralOCRDocumentConverter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component(
+ "converter",
+ MistralOCRDocumentConverter(
+ api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+ model="mistral-ocr-2505"
+ )
+)
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="page", split_length=1))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+file_paths = ["invoice.pdf", "receipt.jpg", "contract.pdf"]
+pipeline.run({"converter": {"sources": file_paths}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/msgtodocument.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/msgtodocument.mdx
new file mode 100644
index 0000000000..e289c3cf34
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/msgtodocument.mdx
@@ -0,0 +1,74 @@
+---
+title: "MSGToDocument"
+id: msgtodocument
+slug: "/msgtodocument"
+description: "Converts Microsoft Outlook .msg files to documents."
+---
+
+# MSGToDocument
+
+Converts Microsoft Outlook .msg files to documents.
+
+`raw_mistral_response`: A list of raw OCR responses from Mistral API | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of .msg file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents
`attachments`: A list of ByteStream objects representing file attachments | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/msg.py | + +
+
+## Overview
+
+The `MSGToDocument` component converts Microsoft Outlook `.msg` files into documents. This component extracts the email metadata (such as sender, recipients, CC, BCC, subject) and body content. Additionally, any file attachments within the `.msg` file are extracted as `ByteStream` objects.
+
+## Usage
+
+First, install the `python-oxmsg` package to start using this converter:
+
+```
+pip install python-oxmsg
+```
+
+### On its own
+
+```python
+from haystack.components.converters.msg import MSGToDocument
+from datetime import datetime
+
+converter = MSGToDocument()
+results = converter.run(sources=["sample.msg"], meta={"date_added": datetime.now().isoformat()})
+documents = results["documents"]
+attachments = results["attachments"]
+
+print(documents[0].content)
+```
+
+### In a pipeline
+
+The following setup enables efficient extraction, preprocessing, and indexing of `.msg` email files within a Haystack pipeline:
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.routers import FileTypeRouter
+from haystack.components.converters import MSGToDocument
+from haystack.components.writers import DocumentWriter
+
+router = FileTypeRouter(mime_types=["application/vnd.ms-outlook"])
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("router", router)
+pipeline.add_component("converter", MSGToDocument())
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+
+pipeline.connect("router.application/vnd.ms-outlook", "converter.sources")
+pipeline.connect("converter.documents", "writer.documents")
+
+file_names = ["email1.msg", "email2.msg"]
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/multifileconverter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/multifileconverter.mdx
new file mode 100644
index 0000000000..2313d4ab04
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/multifileconverter.mdx
@@ -0,0 +1,79 @@
+---
+title: "MultiFileConverter"
+id: multifileconverter
+slug: "/multifileconverter"
+description: "Converts CSV, DOCX, HTML, JSON, MD, PPTX, PDF, TXT, and XSLX files to documents."
+---
+
+# MultiFileConverter
+
+Converts CSV, DOCX, HTML, JSON, MD, PPTX, PDF, TXT, and XSLX files to documents.
+
+`attachments`: A list of ByteStream objects representing file attachments | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/msg.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before PreProcessors , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of file paths or ByteStream objects |
+| **Output variables** | `documents`: A list of converted documents
`unclassified`: A list of uncategorized file paths or byte streams | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/multi_file_converter.py | + +
+
+## Overview
+
+`MultiFileConverter` converts input files of various file types into documents.
+
+It is a SuperComponent that combines a [`FileTypeRouter`](../routers/filetyperouter.mdx), nine converters and a [`DocumentJoiner`](../joiners/documentjoiner.mdx) into a single component.
+
+### Parameters
+
+To initialize `MultiFileConverter`, there are no mandatory parameters. Optionally, you can provide `encoding` and `json_content_key` parameters.
+
+The `json_content_key` parameter lets you specify for the JSON files which key in the extracted data will be the document's content. The parameter is passed on to the underlying [`JSONConverter`](jsonconverter.mdx) component.
+
+The `encoding` parameter lets you specify the default encoding of the TXT, CSV, and MD files. If you don't provide any value, the component uses `utf-8` by default. Note that if the encoding is specified in the metadata of an input ByteStream, it will override this parameter's setting. The parameter is passed on to the underlying [`TextFileToDocument`](textfiletodocument.mdx) and [`CSVToDocument`](csvtodocument.mdx) components.
+
+## Usage
+
+Install dependencies for all supported file types to use the `MultiFileConverter`:
+
+```shell
+pip install pypdf markdown-it-py mdit_plain trafilatura python-pptx python-docx jq openpyxl tabulate pandas
+```
+
+### On its own
+
+```python
+from haystack.components.converters import MultiFileConverter
+
+converter = MultiFileConverter()
+converter.run(sources=["test.txt", "test.pdf"], meta={})
+```
+
+### In a pipeline
+
+You can also use `MultiFileConverter` in your indexing pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.converters import MultiFileConverter
+from haystack.components.preprocessors import DocumentPreprocessor
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", MultiFileConverter())
+pipeline.add_component("preprocessor", DocumentPreprocessor())
+pipeline.add_component("writer", DocumentWriter(document_store = document_store))
+pipeline.connect("converter", "preprocessor")
+pipeline.connect("preprocessor", "writer")
+
+result = pipeline.run(data={"sources": ["test.txt", "test.pdf"]})
+
+print(result)
+## {'writer': {'documents_written': 3}}
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/openapiservicetofunctions.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/openapiservicetofunctions.mdx
new file mode 100644
index 0000000000..aca1d2bfec
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/openapiservicetofunctions.mdx
@@ -0,0 +1,109 @@
+---
+title: "OpenAPIServiceToFunctions"
+id: openapiservicetofunctions
+slug: "/openapiservicetofunctions"
+description: "`OpenAPIServiceToFunctions` is a component that transforms OpenAPI service specifications into a format compatible with OpenAI's function calling mechanism."
+---
+
+# OpenAPIServiceToFunctions
+
+`OpenAPIServiceToFunctions` is a component that transforms OpenAPI service specifications into a format compatible with OpenAI's function calling mechanism.
+
+`unclassified`: A list of uncategorized file paths or byte streams | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/multi_file_converter.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory run variables** | `sources`: A list of OpenAPI specification sources, which can be file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `functions`: A list of JSON OpenAI function calling definitions objects. For each path definition in OpenAPI specification, a corresponding OpenAI function calling definitions is generated.
`openapi_specs`: A list of JSON/YAML objects with references resolved. Such OpenAPI spec (with references resolved) can, in turn, be used as input to OpenAPIServiceConnector. | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/openapi_functions.py | + +
+
+## Overview
+
+`OpenAPIServiceToFunctions` transforms OpenAPI service specifications into an OpenAI function calling format. It takes an OpenAPI specification, processes it to extract function definitions, and formats these definitions to be compatible with OpenAI's function calling JSON format.
+
+`OpenAPIServiceToFunctions` is valuable when used together with [`OpenAPIServiceConnector`](../connectors/openapiserviceconnector.mdx) component. It converts OpenAPI specifications into definitions suitable for OpenAI's function calls, allowing `OpenAPIServiceConnector` to handle input parameters for the OpenAPI specification and facilitate their use in REST API calls through `OpenAPIServiceConnector`.
+
+To use `OpenAPIServiceToFunctions`, you need to install an optional `jsonref` dependency with:
+
+```shell
+pip install jsonref
+```
+
+`OpenAPIServiceToFunctions` component doesn’t have any init parameters.
+
+## Usage
+
+### On its own
+
+This component is primarily meant to be used in pipelines. Using this component alone is useful when you want to convert OpenAPI specification into OpenAI's function call specification and then perhaps save it in a file and subsequently use it in function calling.
+
+### In a pipeline
+
+In a pipeline context, `OpenAPIServiceToFunctions` is most valuable when used alongside `OpenAPIServiceConnector`. For instance, let’s consider integrating [serper.dev](http://serper.dev/) search engine bridge into a pipeline. `OpenAPIServiceToFunctions` retrieves the OpenAPI specification of Serper from https://bit.ly/serper_dev_spec, converts this specification into a format that OpenAI's function calling mechanism can understand, and then seamlessly passes this translated specification as `generation_kwargs` for LLM function calling invocation.
+
+:::info
+To run the following code snippet, note that you have to have your own Serper and OpenAI API keys.
+:::
+
+```python
+import json
+import requests
+
+from typing import Dict, Any, List
+from haystack import Pipeline
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.components.converters import OpenAPIServiceToFunctions, OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.connectors import OpenAPIServiceConnector
+from haystack.components.fetchers import LinkContentFetcher
+from haystack.dataclasses import ChatMessage, ByteStream
+from haystack.utils import Secret
+
+def prepare_fc_params(openai_functions_schema: Dict[str, Any]) -> Dict[str, Any]:
+ return {
+ "tools": [{
+ "type": "function",
+ "function": openai_functions_schema
+ }],
+ "tool_choice": {
+ "type": "function",
+ "function": {"name": openai_functions_schema["name"]}
+ }
+ }
+
+system_prompt = requests.get("https://bit.ly/serper_dev_system_prompt").text
+serper_spec = requests.get("https://bit.ly/serper_dev_spec").text
+
+pipe = Pipeline()
+pipe.add_component("spec_to_functions", OpenAPIServiceToFunctions())
+pipe.add_component("functions_llm", OpenAIChatGenerator(api_key=Secret.from_token(llm_api_key), model="gpt-3.5-turbo-0613"))
+pipe.add_component("openapi_container", OpenAPIServiceConnector())
+pipe.add_component("a1", OutputAdapter("{{functions[0] | prepare_fc}}", Dict[str, Any], {"prepare_fc": prepare_fc_params}))
+pipe.add_component("a2", OutputAdapter("{{specs[0]}}", Dict[str, Any]))
+pipe.add_component("a3", OutputAdapter("{{system_message + service_response}}", List[ChatMessage]))
+pipe.add_component("llm", OpenAIChatGenerator(api_key=Secret.from_token(llm_api_key), model="gpt-4-1106-preview", streaming_callback=print_streaming_chunk))
+
+pipe.connect("spec_to_functions.functions", "a1.functions")
+pipe.connect("spec_to_functions.openapi_specs", "a2.specs")
+pipe.connect("a1", "functions_llm.generation_kwargs")
+pipe.connect("functions_llm.replies", "openapi_container.messages")
+pipe.connect("a2", "openapi_container.service_openapi_spec")
+pipe.connect("openapi_container.service_response", "a3.service_response")
+pipe.connect("a3", "llm.messages")
+
+user_prompt = "Why was Sam Altman ousted from OpenAI?"
+
+result = pipe.run(data={"functions_llm": {"messages":[ChatMessage.from_system("Only do function calling"), ChatMessage.from_user(user_prompt)]},
+ "openapi_container": {"service_credentials": serper_dev_key},
+ "spec_to_functions": {"sources": [ByteStream.from_string(serper_spec)]},
+ "a3": {"system_message": [ChatMessage.from_system(system_prompt)]}})
+
+>Sam Altman was ousted from OpenAI on November 17, 2023, following
+>a "deliberative review process" by the board of directors. The board concluded
+>that he was not "consistently candid in his communications". However, he
+>returned as CEO just days after his ouster.
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/outputadapter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/outputadapter.mdx
new file mode 100644
index 0000000000..3634ef27dd
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/outputadapter.mdx
@@ -0,0 +1,126 @@
+---
+title: "OutputAdapter"
+id: outputadapter
+slug: "/outputadapter"
+description: "This component helps the output of one component fit smoothly into the input of another. It uses Jinja expressions to define how this adaptation occurs."
+---
+
+# OutputAdapter
+
+This component helps the output of one component fit smoothly into the input of another. It uses Jinja expressions to define how this adaptation occurs.
+
+`openapi_specs`: A list of JSON/YAML objects with references resolved. Such OpenAPI spec (with references resolved) can, in turn, be used as input to OpenAPIServiceConnector. | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/openapi_functions.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory init variables** | `template`: A Jinja template string that defines how to adapt the data
`output_type`: Type alias that this instance will return | +| **Mandatory run variables** | `**kwargs`: Input variables to be used in Jinja expression. See [Variables](#variables) section for more details. | +| **Output variables** | The output is specified under the `output` key dictionary | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/output_adapter.py | + +
+
+## Overview
+
+To use `OutputAdapter`, you need to specify the adaptation rule that includes:
+
+- `template`: A Jinja template string that defines how to adapt the input data.
+- `output_type`: The type of the output data (such as `str`, `List[int]`..). This doesn't change the actual output type and is only needed to validate connection with other components.
+- `custom_filters`: An optional dictionary of custom Jinja filters to be used in the template.
+
+### Variables
+
+The `OutputAdapter` requires all template variables to be present before running and raises an error if any template variable is missing at pipeline connect time.
+
+```python
+from haystack.components.converters import OutputAdapter
+
+adapter = OutputAdapter(
+ template="Hello {{name}}!",
+ output_type=str
+)
+```
+
+### Unsafe behavior
+
+The `OutputAdapter` internally renders the `template` using Jinja, and by default, this is safe behavior. However, it limits the output types to strings, bytes, numbers, tuples, lists, dicts, sets, booleans, `None`, and `Ellipsis` (`...`), as well as any combination of these structures.
+
+If you want to use other types such as `ChatMessage`, `Document`, or `Answer`, you must enable unsafe template rendering by setting the `unsafe` init argument to `True`.
+
+Be cautious, as enabling this can be unsafe and may lead to remote code execution if the `template` is a string customizable by the end user.
+
+## Usage
+
+### On its own
+
+This component is primarily meant to be used in pipelines.
+
+In this example, `OutputAdapter` simply outputs the content field of the first document in the arrays of documents:
+
+```python
+from haystack import Document
+from haystack.components.converters import OutputAdapter
+
+adapter = OutputAdapter(template="{{ documents[0].content }}", output_type=str)
+input_data = {"documents": [Document(content="Test content")]}
+expected_output = {"output": "Test content"}
+assert adapter.run(**input_data) == expected_output
+```
+
+### In a pipeline
+
+The example below demonstrates a straightforward pipeline that uses the `OutputAdapter` to capitalize the first document in the list. If needed, you can also utilize the predefined Jinja [filters](https://jinja.palletsprojects.com/en/3.1.x/templates/#builtin-filters).
+
+```python
+from haystack import Pipeline, component, Document
+from haystack.components.converters import OutputAdapter
+
+@component
+class DocumentProducer:
+ @component.output_types(documents=dict)
+ def run(self):
+ return {"documents": [Document(content="haystack")]}
+
+pipe = Pipeline()
+pipe.add_component(
+ name="output_adapter",
+ instance=OutputAdapter(template="{{ documents[0].content | capitalize}}", output_type=str),
+)
+pipe.add_component(name="document_producer", instance=DocumentProducer())
+pipe.connect("document_producer", "output_adapter")
+result = pipe.run(data={})
+
+assert result["output_adapter"]["output"] == "Haystack"
+```
+
+You can also define your own custom filters, which can then be added to an `OutputAdapter` instance through its init method and used in templates. Here’s an example of this approach:
+
+```python
+
+from haystack import Pipeline, component, Document
+from haystack.components.converters import OutputAdapter
+
+def reverse_string(s):
+ return s[::-1]
+
+@component
+class DocumentProducer:
+ @component.output_types(documents=dict)
+ def run(self):
+ return {"documents": [Document(content="haystack")]}
+
+pipe = Pipeline()
+pipe.add_component(
+ name="output_adapter",
+ instance=OutputAdapter(template="{{ documents[0].content | reverse_string}}",
+ output_type=str,
+ custom_filters={"reverse_string": reverse_string}))
+
+pipe.add_component(name="document_producer", instance=DocumentProducer())
+pipe.connect("document_producer", "output_adapter")
+result = pipe.run(data={})
+
+assert result["output_adapter"]["output"] == "kcatsyah"
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pdfminertodocument.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pdfminertodocument.mdx
new file mode 100644
index 0000000000..95d1db8757
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pdfminertodocument.mdx
@@ -0,0 +1,76 @@
+---
+title: "PDFMinerToDocument"
+id: pdfminertodocument
+slug: "/pdfminertodocument"
+description: "A component that converts complex PDF files to documents using pdfminer arguments."
+---
+
+# PDFMinerToDocument
+
+A component that converts complex PDF files to documents using pdfminer arguments.
+
+`output_type`: Type alias that this instance will return | +| **Mandatory run variables** | `**kwargs`: Input variables to be used in Jinja expression. See [Variables](#variables) section for more details. | +| **Output variables** | The output is specified under the `output` key dictionary | +| **API reference** | [Converters](/reference/converters-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/output_adapter.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: PDF file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/pdfminer.py |
+
+
+
+## Overview
+
+The `PDFMinerToDocument` component converts PDF files into documents using [PDFMiner](https://pdfminersix.readthedocs.io/en/latest/) extraction tool arguments.
+
+You can use it in an indexing pipeline to index the contents of a PDF file in a Document Store. It takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream)objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+When initializing the component, you can adjust several parameters to fit your PDF. See the full parameter list and descriptions in our [API reference](/reference/converters-api#pdfminertodocument).
+
+## Usage
+
+First, install `pdfminer` package to start using this converter:
+
+```shell
+pip install pdfminer.six
+```
+
+### On its own
+
+```python
+from haystack.components.converters import PDFMinerToDocument
+
+converter = PDFMinerToDocument()
+results = converter.run(sources=["sample.pdf"], meta={"date_added": datetime.now().isoformat()})
+documents = results["documents"]
+
+print(documents[0].content)
+
+## 'This is a text from the PDF file.'
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import PDFMinerToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", PDFMinerToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pdftoimagecontent.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pdftoimagecontent.mdx
new file mode 100644
index 0000000000..95fc94849a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pdftoimagecontent.mdx
@@ -0,0 +1,117 @@
+---
+title: "PDFToImageContent"
+id: pdftoimagecontent
+slug: "/pdftoimagecontent"
+description: "`PDFToImageContent` reads local PDF files and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image captioning, visual QA, or prompt-based generation."
+---
+
+# PDFToImageContent
+
+`PDFToImageContent` reads local PDF files and converts them into `ImageContent` objects. These are ready for multimodal AI pipelines, including tasks like image captioning, visual QA, or prompt-based generation.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a `ChatPromptBuilder` in a query pipeline |
+| **Mandatory run variables** | `sources`: A list of PDF file paths or ByteStreams |
+| **Output variables** | `image_contents`: A list of ImageContent objects |
+| **API reference** | [Image Converters](/reference/image-converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/image/pdf_to_image.py |
+
+
+
+## Overview
+
+`PDFToImageContent` processes a list of PDF sources and converts them into `ImageContent` objects, one for each page of the PDF. These can be used in multimodal pipelines that require base64-encoded image input.
+
+Each source can be:
+
+- A file path (string or `Path`), or
+- A `ByteStream` object.
+
+Optionally, you can provide metadata using the `meta` parameter. This can be a single dictionary (applied to all images) or a list matching the length of `sources`.
+
+Use the `size` parameter to resize images while preserving aspect ratio. This reduces memory usage and transmission size, which is helpful when working with remote models or limited-resource environments.
+
+This component is often used in query pipelines just before a `ChatPromptBuilder`.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.converters.image import PDFToImageContent
+
+converter = PDFToImageContent()
+
+sources = ["file.pdf", "another_file.pdf"]
+
+image_contents = converter.run(sources=sources)["image_contents"]
+print(image_contents)
+
+## [ImageContent(base64_image='...',
+## mime_type='application/pdf',
+## detail=None,
+## meta={'file_path': 'file.pdf', 'page_number': 1}),
+## ...]
+```
+
+### In a pipeline
+
+Use `ImageFileToImageContent` to supply image data to a `ChatPromptBuilder` for multimodal QA or captioning with an LLM.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.converters.image import PDFToImageContent
+
+## Query pipeline
+pipeline = Pipeline()
+pipeline.add_component("image_converter", PDFToImageContent(detail="auto"))
+pipeline.add_component(
+ "chat_prompt_builder",
+ ChatPromptBuilder(
+ required_variables=["question"],
+ template="""{% message role="system" %}
+You are a helpful assistant that answers questions using the provided images.
+{% endmessage %}
+
+{% message role="user" %}
+Question: {{ question }}
+
+{% for img in image_contents %}
+{{ img | templatize_part }}
+{% endfor %}
+{% endmessage %}
+"""
+ )
+)
+pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+
+pipeline.connect("image_converter", "chat_prompt_builder.image_contents")
+pipeline.connect("chat_prompt_builder", "llm")
+
+sources = ["flan_paper.pdf"]
+
+result = pipeline.run(
+ data={
+ "image_converter": {"sources": ["flan_paper.pdf"], "page_range":"9"},
+ "chat_prompt_builder": {"question": "What is the main takeaway of Figure 6?"}
+ }
+)
+print(result["replies"][0].text)
+
+## ('The main takeaway of Figure 6 is that Flan-PaLM demonstrates improved '
+## 'performance in zero-shot reasoning tasks when utilizing chain-of-thought '
+## '(CoT) reasoning, as indicated by higher accuracy across different model '
+## 'sizes compared to PaLM without finetuning. This highlights the importance of '
+## 'instruction finetuning combined with CoT for enhancing reasoning '
+## 'capabilities in models.')
+
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Introduction to Multimodality](https://haystack.deepset.ai/cookbook/multimodal_intro)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pptxtodocument.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pptxtodocument.mdx
new file mode 100644
index 0000000000..92e7deed6d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pptxtodocument.mdx
@@ -0,0 +1,72 @@
+---
+title: "PPTXToDocument"
+id: pptxtodocument
+slug: "/pptxtodocument"
+description: "Convert PPTX files to documents."
+---
+
+# PPTXToDocument
+
+Convert PPTX files to documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: PPTX file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/pptx.py |
+
+
+
+## Overview
+
+The `PPTXToDocument` component converts PPTX files into documents. It takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+## Usage
+
+First, install the`python-pptx` package to start using this converter:
+
+```shell
+pip install python-pptx
+```
+
+### On its own
+
+```python
+from haystack.components.converters import PPTXToDocument
+
+converter = PPTXToDocument()
+results = converter.run(sources=["sample.pptx"], meta={"date_added": datetime.now().isoformat()})
+documents = results["documents"]
+
+print(documents[0].content)
+
+## 'This is the text from the PPTX file.'
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import PPTXToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", PPTXToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pypdftodocument.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pypdftodocument.mdx
new file mode 100644
index 0000000000..14b3250362
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pypdftodocument.mdx
@@ -0,0 +1,75 @@
+---
+title: "PyPDFToDocument"
+id: pypdftodocument
+slug: "/pypdftodocument"
+description: "A component that converts PDF files to Documents."
+---
+
+# PyPDFToDocument
+
+A component that converts PDF files to Documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: PDF file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/pypdf.py |
+
+
+
+## Overview
+
+The `PyPDFToDocument` component converts PDF files into documents. You can use it in an indexing pipeline to index the contents of a PDF file into a Document Store. It takes a list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+## Usage
+
+You need to install `pypdf` package to use the `PyPDFToDocument` converter:
+
+```shell
+pip install pypdf
+```
+
+### On its own
+
+```python
+from pathlib import Path
+from haystack.components.converters import PyPDFToDocument
+
+converter = PyPDFToDocument()
+
+docs = converter.run(sources=[Path("my_file.pdf")])
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import PyPDFToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", PyPDFToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
+
+📓 Tutorial: [Preprocessing Different File Types](https://haystack.deepset.ai/tutorials/30_file_type_preprocessing_index_pipeline)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/textfiletodocument.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/textfiletodocument.mdx
new file mode 100644
index 0000000000..a6f713e8f8
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/textfiletodocument.mdx
@@ -0,0 +1,69 @@
+---
+title: "TextFileToDocument"
+id: textfiletodocument
+slug: "/textfiletodocument"
+description: "Converts text files to documents."
+---
+
+# TextFileToDocument
+
+Converts text files to documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: A list of paths to text files you want to convert |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/txt.py |
+
+
+
+## Overview
+
+The `TextFileToDocument` component converts text files into documents. You can use it in an indexing pipeline to index the contents of text files into a Document Store. It takes a list of file paths or [ByteStream](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+When you initialize the component, you can optionally set the default encoding of the text files through the `encoding` parameter. If you don't provide any value, the component uses `"utf-8"` by default. Note that if the encoding is specified in the metadata of an input ByteStream, it will override this parameter's setting.
+
+## Usage
+
+### On its own
+
+```python
+from pathlib import Path
+from haystack.components.converters import TextFileToDocument
+
+converter = TextFileToDocument()
+
+docs = converter.run(sources=[Path("my_file.txt")])
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", TextFileToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
+
+## Additional References
+
+:notebook: Tutorial: [Preprocessing Different File Types](https://haystack.deepset.ai/tutorials/30_file_type_preprocessing_index_pipeline)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/tikadocumentconverter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/tikadocumentconverter.mdx
new file mode 100644
index 0000000000..ed819c46f3
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/tikadocumentconverter.mdx
@@ -0,0 +1,76 @@
+---
+title: "TikaDocumentConverter"
+id: tikadocumentconverter
+slug: "/tikadocumentconverter"
+description: "An integration for converting files of different types (PDF, DOCX, HTML, and more) to documents."
+---
+
+# TikaDocumentConverter
+
+An integration for converting files of different types (PDF, DOCX, HTML, and more) to documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) , or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: File paths |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/tika.py |
+
+
+
+## Overview
+
+The `TikaDocumentConverter` component converts files of different types (pdf, docx, html, and others) into documents. You can use it in an indexing pipeline to index the contents of files into a Document Store. It takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+This integration uses [Apache Tika](https://tika.apache.org/) to parse the files and requires a running Tika server.
+
+The easiest way to run Tika is by using Docker: `docker run -d -p 127.0.0.1:9998:9998 apache/tika:latest`.
+For more options on running Tika on Docker, see the [Tika documentation](https://github.com/apache/tika-docker/blob/main/README.md#usage).
+
+When you initialize the `TikaDocumentConverter` component, you can specify a custom URL of the Tika server you are using through the parameter `tika_url`. The default URL is `"http://localhost:9998/tika"`.
+
+## Usage
+
+You need to install `tika` package to use the `TikaDocumentConverter` component:
+
+```shell
+pip install tika
+```
+
+### On its own
+
+```python
+from haystack.components.converters import TikaDocumentConverter
+from pathlib import Path
+
+converter = TikaDocumentConverter()
+
+converter.run(sources=[Path("my_file.pdf")])
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import TikaDocumentConverter
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", TikaDocumentConverter())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_paths}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/unstructuredfileconverter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/unstructuredfileconverter.mdx
new file mode 100644
index 0000000000..37f36e07b9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/unstructuredfileconverter.mdx
@@ -0,0 +1,107 @@
+---
+title: "UnstructuredFileConverter"
+id: unstructuredfileconverter
+slug: "/unstructuredfileconverter"
+description: "Use this component to convert text files and directories to a document."
+---
+
+# UnstructuredFileConverter
+
+Use this component to convert text files and directories to a document.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `paths`: A union of lists of paths |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Unstructured](/reference/integrations-unstructured) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/unstructured |
+
+
+
+## Overview
+
+`UnstructuredFileConverter` converts files and directories into documents using the Unstructured API.
+
+[Unstructured](https://docs.unstructured.io/) provides a series of tools to do ETL for LLMs. The `UnstructuredFileConverter` calls the Unstructured API that extracts text and other information from a vast range of file [formats](https://docs.unstructured.io/api-reference/api-services/overview#supported-file-types).
+
+This Converter supports different modes for creating documents from the elements returned by Unstructured:
+
+- `"one-doc-per-file"`: One Haystack document per file. All elements are concatenated into one text field.
+- `"one-doc-per-page"`: One Haystack document per page. All elements on a page are concatenated into one text field.
+- `"one-doc-per-element"`: One Haystack document per element. Each element is converted to a Haystack document.
+
+## Usage
+
+Install the Unstructured integration to use `UnstructuredFileConverter`component:
+
+```shell
+pip install unstructured-fileconverter-haystack
+```
+
+There are free and paid versions of Unstructured API: **Free Unstructured API** and **Unstructured Serverless API**.
+
+1. **Free Unstructured API**:
+ - API URL: `https://api.unstructured.io/general/v0/general`
+ - This version is free, but comes with certain limitations.
+
+2. **Unstructured Serverless API**:
+ - You'll find your unique API URL in your Unstructured account after signing up for the paid version.
+ - This is a full-tier paid version of Unstructured.
+
+ For more details about the two tiers refer to Unstructured [FAQ](https://docs.unstructured.io/faq/faq).
+
+> ❗️ The API keys for the free and paid versions are different and cannot be used interchangeably.
+
+Regardless of the chosen tier, we recommend to set the Unstructured API key as an environment variable `UNSTRUCTURED_API_KEY`:
+
+```shell
+export UNSTRUCTURED_API_KEY=your_api_key
+```
+
+### On its own
+
+```python
+import os
+from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter
+
+converter = UnstructuredFileConverter()
+documents = converter.run(paths = ["a/file/path.pdf", "a/directory/path"])["documents"]
+```
+
+### In a pipeline
+
+```python
+import os
+from haystack import Pipeline
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter
+
+document_store = InMemoryDocumentStore()
+
+indexing = Pipeline()
+indexing.add_component("converter", UnstructuredFileConverter())
+indexing.add_component("writer", DocumentWriter(document_store))
+indexing.connect("converter", "writer")
+
+indexing.run({"converter": {"paths": ["a/file/path.pdf", "a/directory/path"]}})
+```
+
+### With Docker
+
+To use `UnstructuredFileConverter` through Docker, first, set up an Unstructured Docker container:
+
+```
+docker run -p 8000:8000 -d --rm --name unstructured-api quay.io/unstructured-io/unstructured-api:latest --port 8000 --host 0.0.0.0
+```
+
+When initializing the component, specify the localhost URL:
+
+```python
+from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter
+
+converter = UnstructuredFileConverter(api_url="http://localhost:8000/general/v0/general")
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/xlsxtodocument.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/xlsxtodocument.mdx
new file mode 100644
index 0000000000..e10c4035aa
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/xlsxtodocument.mdx
@@ -0,0 +1,73 @@
+---
+title: "XLSXToDocument"
+id: xlsxtodocument
+slug: "/xlsxtodocument"
+description: "Converts Excel files into documents."
+---
+
+# XLSXToDocument
+
+Converts Excel files into documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [PreProcessors](../preprocessors.mdx) or right at the beginning of an indexing pipeline |
+| **Mandatory run variables** | `sources`: File paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Converters](/reference/converters-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/xlsx.py |
+
+
+
+## Overview
+
+The `XLSXToDocument` component converts XLSX files into Haystack Documents with a CSV (default) or Markdown format. It takes a list of file paths or [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the `meta` input parameter.
+
+To see the additional parameters that you can specify with the component initialization, check out the [API Reference](/reference/converters-api#xlsxtodocument).
+
+## Usage
+
+First, install the openpyxl and tabulate packages to start using this converter:
+
+```shell
+pip install pandas openpyxl
+pip install tabulate
+```
+
+### On its own
+
+```python
+from haystack.components.converters import XLSXToDocument
+
+converter = XLSXToDocument()
+results = converter.run(sources=["sample.xlsx"], meta={"date_added": datetime.now().isoformat()})
+documents = results["documents"]
+print(documents[0].content)
+## ",A,B\n1,col_a,col_b\n2,1.5,test\n"
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import XLSXToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", XLSXToDocument())
+pipeline.add_component("cleaner", DocumentCleaner())
+pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
+pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+pipeline.connect("converter", "cleaner")
+pipeline.connect("cleaner", "splitter")
+pipeline.connect("splitter", "writer")
+
+pipeline.run({"converter": {"sources": file_names}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/downloaders/s3downloader.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/downloaders/s3downloader.mdx
new file mode 100644
index 0000000000..b29c9f11b9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/downloaders/s3downloader.mdx
@@ -0,0 +1,284 @@
+---
+title: "S3Downloader"
+id: s3downloader
+slug: "/s3downloader"
+description: "`S3Downloader` downloads files from AWS S3 buckets to the local filesystem and enriches documents with the local file path."
+---
+
+# S3Downloader
+
+`S3Downloader` downloads files from AWS S3 buckets to the local filesystem and enriches documents with the local file path.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before File Converters or Routers that need local file paths |
+| **Mandatory init variables** | `file_root_path`: Path where files will be downloaded. Can be set with `FILE_ROOT_PATH` env var.
`aws_access_key_id`: AWS access key ID. Can be set with AWS_ACCESS_KEY_ID env var.
`aws_secret_access_key`: AWS secret access key. Can be set with AWS_SECRET_ACCESS_KEY env var.
`aws_region_name`: AWS region name. Can be set with AWS_DEFAULT_REGION env var. | +| **Mandatory run variables** | `documents`: A list of documents containing name of the file to download in metadata. | +| **Output variables** | `documents`: A list of documents enriched with the local file path in `meta['file_path']` | +| **API reference** | [S3Downloader](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+## Overview
+
+`S3Downloader` downloads files from AWS S3 buckets to your local filesystem and enriches Document objects with the local file path. This component is useful for pipelines that need to process files stored in S3, such as PDFs, images, or text files.
+
+The component supports AWS authentication through environment variables by default. You can set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_DEFAULT_REGION` environment variables. Alternatively, you can pass credentials directly at initialization using the [Secret API](../../concepts/secret-management.mdx):
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.downloaders.s3 import S3Downloader
+
+downloader = S3Downloader(
+ aws_access_key_id=Secret.from_token("`aws_access_key_id`: AWS access key ID. Can be set with AWS_ACCESS_KEY_ID env var.
`aws_secret_access_key`: AWS secret access key. Can be set with AWS_SECRET_ACCESS_KEY env var.
`aws_region_name`: AWS region name. Can be set with AWS_DEFAULT_REGION env var. | +| **Mandatory run variables** | `documents`: A list of documents containing name of the file to download in metadata. | +| **Output variables** | `documents`: A list of documents enriched with the local file path in `meta['file_path']` | +| **API reference** | [S3Downloader](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `model`: The embedding model to use
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `documents`: A list of documents to be embedded | +| **Output variables** | `documents`: A list of documents (enriched with embeddings) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+## Overview
+
+[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) is a fully managed service that makes language models from leading AI startups and Amazon available for your use through a unified API.
+
+Supported models are `amazon.titan-embed-text-v1`, `cohere.embed-english-v3`, `cohere.embed-multilingual-v3`, and `amazon.titan-embed-text-v2:0`.
+
+:::info Batch Inference
+
+Note that only Cohere models support batch inference – computing embeddings for more documents with the same request.
+:::
+
+This component should be used to embed a list of documents. To embed a string, you should use the [`AmazonBedrockTextEmbedder`](amazonbedrocktextembedder.mdx).
+
+### Authentication
+
+`AmazonBedrockDocumentEmbedder` uses AWS for authentication. You can either provide credentials as parameters directly to the component or use the AWS CLI and authenticate through your IAM. For more information on how to set up an IAM identity-based policy, see the [official documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html).
+To initialize `AmazonBedrockDocumentEmbedder` and authenticate by providing credentials, provide the `model_name`, as well as `aws_access_key_id`, `aws_secret_access_key` and `aws_region_name`. Other parameters are optional. You can check them out in our [API reference](/reference/integrations-amazon-bedrock#amazonbedrockdocumentembedder).
+
+### Model-specific parameters
+
+Even if Haystack provides a unified interface, each model offered by Bedrock can accept specific parameters. You can pass these parameters at initialization.
+
+For example, Cohere models support `input_type` and `truncate`, as seen in [Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html).
+
+```python
+from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockDocumentEmbedder
+
+embedder = AmazonBedrockDocumentEmbedder(model="cohere.embed-english-v3",
+ input_type="search_document",
+ truncate="LEFT")
+```
+
+### Embedding Metadata
+
+Text documents often come with a set of metadata. If they are distinctive and semantically meaningful, you can embed them along with the text of the document to improve retrieval.
+
+You can do this easily by using the Document Embedder:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockDocumentEmbedder
+
+doc = Document(content="some text",meta={"title": "relevant title", "page number": 18})
+
+embedder = AmazonBedrockDocumentEmbedder(model="cohere.embed-english-v3",
+ meta_fields_to_embed=["title"])
+
+docs_w_embeddings = embedder.run(documents=[doc])["documents"]
+```
+
+## Usage
+
+### Installation
+
+You need to install `amazon-bedrock-haystack` package to use the `AmazonBedrockTextEmbedder`:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import os
+from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockDocumentEmbedder
+from haystack.dataclasses import DOcument
+
+os.environ["AWS_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
+os.environ["AWS_DEFAULT_REGION"] = "us-east-1" # just an example
+
+doc = Document(content="I love pizza!")
+
+embedder = AmazonBedrockDocumentEmbedder(model="cohere.embed-english-v3",
+ input_type="search_document"
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+## [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentEmbedder,
+ AmazonBedrockTextEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities")]
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("embedder", AmazonBedrockDocumentEmbedder(
+ model="cohere.embed-english-v3"))
+indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
+indexing_pipeline.connect("embedder", "writer")
+
+indexing_pipeline.run({"embedder": {"documents": documents}})
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", AmazonBedrockTextEmbedder(model="cohere.embed-english-v3"))
+query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder":{"text": query}})
+
+print(result['retriever']['documents'][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin')
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/amazonbedrockdocumentimageembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/amazonbedrockdocumentimageembedder.mdx
new file mode 100644
index 0000000000..e3b0c9b7d4
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/amazonbedrockdocumentimageembedder.mdx
@@ -0,0 +1,145 @@
+---
+title: "AmazonBedrockDocumentImageEmbedder"
+id: amazonbedrockdocumentimageembedder
+slug: "/amazonbedrockdocumentimageembedder"
+description: "`AmazonBedrockDocumentImageEmbedder` computes image embeddings for documents using models exposed through the Amazon Bedrock API. It stores the obtained vectors in the embedding field of each document."
+---
+
+# AmazonBedrockDocumentImageEmbedder
+
+`AmazonBedrockDocumentImageEmbedder` computes image embeddings for documents using models exposed through the Amazon Bedrock API. It stores the obtained vectors in the embedding field of each document.
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `documents`: A list of documents to be embedded | +| **Output variables** | `documents`: A list of documents (enriched with embeddings) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `model`: The multimodal embedding model to use.
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `documents`: A list of documents, with a meta field containing an image file path | +| **Output variables** | `documents`: A list of documents (enriched with embeddings) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+## Overview
+
+Amazon Bedrock is a fully managed service that provides access to foundation models through a unified API.
+
+`AmazonBedrockDocumentImageEmbedder` expects a list of documents containing an image or a PDF file path in a meta field. The meta field can be specified with the `file_path_meta_field` init parameter of this component.
+
+The embedder efficiently loads the images, computes the embeddings using selected Bedrock model, and stores each of them in the `embedding` field of the document.
+
+Supported models are `amazon.titan-embed-image-v1`, `cohere.embed-english-v3` , and `cohere.embed-multilingual-v3`.
+
+`AmazonBedrockDocumentImageEmbedder` is commonly used in indexing pipelines. At retrieval time, you need to use the same model with `AmazonBedrockTextEmbedder` to embed the query, before using an Embedding Retriever.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### Authentication
+
+`AmazonBedrockDocumentImageEmbedder` uses AWS for authentication. You can either provide credentials as parameters directly to the component or use the AWS CLI and authenticate through your IAM. For more information on how to set up an IAM identity-based policy, see the [official documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html).
+
+To initialize `AmazonBedrockDocumentImageEmbedder` and authenticate by providing credentials, provide the `model` name, as well as `aws_access_key_id`, `aws_secret_access_key`, and `aws_region_name`. Other parameters are optional, you can check them out in our [API reference](/reference/integrations-amazon-bedrock#amazonbedrocktextembedder).
+
+### Model-specific parameters
+
+Even if Haystack provides a unified interface, each model offered by Bedrock can accept specific parameters. You can pass these parameters at initialization.
+
+- **Amazon Titan**: Use `embeddingConfig` to control embedding behavior.
+- **Cohere v3**: Use `embedding_types` to select a single embedding type for images.
+
+```python
+from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockDocumentImageEmbedder
+
+embedder = AmazonBedrockDocumentImageEmbedder(
+ model="cohere.embed-english-v3",
+ embedding_types=["float"] # single value only
+)
+```
+
+Note that only _one_ value in `embedding_types` is supported by this component. Passing multiple values raises an error.
+
+## Usage
+
+### On its own
+
+```python
+import os
+from haystack import Document
+from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockDocumentImageEmbedder
+
+os.environ["AWS_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
+os.environ["AWS_DEFAULT_REGION"] = "us-east-1" # example
+
+## Point Documents to image/PDF files via metadata (default key: "file_path")
+documents = [
+ Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
+ Document(content="Invoice page", meta={"file_path": "invoice.pdf", "mime_type": "application/pdf", "page_number": 1}),
+]
+
+embedder = AmazonBedrockDocumentImageEmbedder(
+ model="amazon.titan-embed-image-v1",
+ image_size=(1024, 1024), # optional downscaling
+)
+
+result = embedder.run(documents=documents)
+embedded_docs = result["documents"]
+
+```
+
+### In a pipeline
+
+In this example, we can see an indexing pipeline with 3 components:
+
+- `ImageFileToDocument` Converter that creates empty documents with a reference to an image in the `meta.file_path` field;
+- `AmazonBedrockDocumentImageEmbedder` that loads the images, computes embeddings and stores them in documents;
+- `DocumentWriter` that write the documents in the `InMemoryDocumentStore`.
+
+There is also a multimodal retrieval pipeline, composed of an `AmazonBedrockTextEmbedder` (using the same model as before) and an `InMemoryEmbeddingRetriever`.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.writers import DocumentWriter
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentImageEmbedder,
+ AmazonBedrockTextEmbedder,
+)
+
+## Document store using vector similarity for retrieval
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+## Sample corpus with file paths in metadata
+documents = [
+ Document(content="A sketch of a horse", meta={"file_path": "horse.png"}),
+ Document(content="A city map", meta={"file_path": "map.jpg"}),
+]
+
+## Indexing pipeline: image embeddings -> write to store
+indexing = Pipeline()
+indexing.add_component("image_embedder", AmazonBedrockDocumentImageEmbedder(model="cohere.embed-english-v3"))
+indexing.add_component("writer", DocumentWriter(document_store=document_store))
+indexing.connect("image_embedder", "writer")
+indexing.run({"image_embedder": {"documents": documents}})
+
+## Query pipeline: text -> embedding -> vector retriever
+query = Pipeline()
+query.add_component("text_embedder", AmazonBedrockTextEmbedder(model="cohere.embed-english-v3"))
+query.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query.connect("text_embedder.embedding", "retriever.query_embedding")
+
+res = query.run({"text_embedder": {"text": "Which document shows a horse?"}})
+```
+
+## Additional References
+
+:notebook: Tutorial: [Creating Vision+Text RAG Pipelines](https://haystack.deepset.ai/tutorials/46_multimodal_rag)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/amazonbedrocktextembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/amazonbedrocktextembedder.mdx
new file mode 100644
index 0000000000..6eda72705f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/amazonbedrocktextembedder.mdx
@@ -0,0 +1,123 @@
+---
+title: "AmazonBedrockTextEmbedder"
+id: amazonbedrocktextembedder
+slug: "/amazonbedrocktextembedder"
+description: "This component computes embeddings for text (such as a query) using models through Amazon Bedrock API."
+---
+
+# AmazonBedrockTextEmbedder
+
+This component computes embeddings for text (such as a query) using models through Amazon Bedrock API.
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `documents`: A list of documents, with a meta field containing an image file path | +| **Output variables** | `documents`: A list of documents (enriched with embeddings) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `model`: The embedding model to use
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers (vector) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+## Overview
+
+[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) is a fully managed service that makes language models from leading AI startups and Amazon available for your use through a unified API.
+
+Supported models are `amazon.titan-embed-text-v1`, `cohere.embed-english-v3` and `cohere.embed-multilingual-v3`.
+
+Use `AmazonBedrockTextEmbedder` to embed a simple string (such as a query) into a vector. Use the [`AmazonBedrockDocumentEmbedder`](amazonbedrockdocumentembedder.mdx) to enrich the documents with the computed embedding, also known as vector.
+
+### Authentication
+
+`AmazonBedrockTextEmbedder` uses AWS for authentication. You can either provide credentials as parameters directly to the component or use the AWS CLI and authenticate through your IAM. For more information on how to set up an IAM identity-based policy, see the [official documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html).
+To initialize `AmazonBedrockTextEmbedder` and authenticate by providing credentials, provide the `model` name, as well as `aws_access_key_id`, `aws_secret_access_key`, and `aws_region_name`. Other parameters are optional, you can check them out in our [API reference](/reference/integrations-amazon-bedrock#amazonbedrocktextembedder).
+
+### Model-specific parameters
+
+Even if Haystack provides a unified interface, each model offered by Bedrock can accept specific parameters. You can pass these parameters at initialization.
+
+For example, the Cohere models support `input_type` and `truncate`, as seen in [Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html).
+
+```python
+from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockTextEmbedder
+
+embedder = AmazonBedrockTextEmbedder(model="cohere.embed-english-v3",
+ input_type="search_query",
+ truncate="LEFT")
+```
+
+## Usage
+
+### Installation
+
+You need to install `amazon-bedrock-haystack` package to use the `AmazonBedrockTextEmbedder`:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import os
+from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockTextEmbedder
+
+os.environ["AWS_ACCESS_KEY_ID"] = "..."
+os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
+os.environ["AWS_DEFAULT_REGION"] = "us-east-1" # just an example
+
+text_to_embed = "I love pizza!"
+
+text_embedder = AmazonBedrockTextEmbedder(model="cohere.embed-english-v3",
+ input_type="search_query")
+
+print(text_embedder.run(text_to_embed))
+## {'embedding': [-0.453125, 1.2236328, 2.0058594, 0.67871094...]}
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.amazon_bedrock import (
+ AmazonBedrockDocumentEmbedder,
+ AmazonBedrockTextEmbedder,
+)
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities")]
+
+document_embedder = AmazonBedrockDocumentEmbedder(model="cohere.embed-english-v3")
+documents_with_embeddings = document_embedder.run(documents)['documents']
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", AmazonBedrockTextEmbedder(model="cohere.embed-english-v3"))
+query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder":{"text": query}})
+
+print(result['retriever']['documents'][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin')
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/azureopenaidocumentembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/azureopenaidocumentembedder.mdx
new file mode 100644
index 0000000000..310e23e8b8
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/azureopenaidocumentembedder.mdx
@@ -0,0 +1,118 @@
+---
+title: "AzureOpenAIDocumentEmbedder"
+id: azureopenaidocumentembedder
+slug: "/azureopenaidocumentembedder"
+description: "This component computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses Azure cognitive services for text and document embedding with models deployed on Azure."
+---
+
+# AzureOpenAIDocumentEmbedder
+
+This component computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses Azure cognitive services for text and document embedding with models deployed on Azure.
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers (vector) | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) |
+| **Mandatory init variables** | `api_key`: The Azure OpenAI API key. Can be set with `AZURE_OPENAI_API_KEY` env var.
`azure_endpoint`: The endpoint of the model deployed on Azure. | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/azure_document_embedder.py | + +
+
+## Overview
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector representing the query is compared with those of the documents to find the most similar or relevant documents.
+
+To see the list of compatible embedding models, head over to Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?source=recommendations). The default model for `AzureOpenAITextEmbedder` is `text-embedding-ada-002`.
+
+This component should be used to embed a list of documents. To embed a string, you should use the [`AzureOpenAITextEmbedder`](azureopenaitextembedder.mdx).
+
+To work with Azure components, you will need an Azure OpenAI API key, as well as an Azure OpenAI Endpoint. You can learn more about them in Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
+
+The component uses `AZURE_OPENAI_API_KEY` or `AZURE_OPENAI_AD_TOKEN` environment variables by default. Otherwise, you can pass `api_key` or `azure_ad_token` at initialization:
+
+```python
+client = AzureOpenAIDocumentEmbedder(azure_endpoint="`azure_endpoint`: The endpoint of the model deployed on Azure. | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/azure_document_embedder.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The Azure OpenAI API key. Can be set with `AZURE_OPENAI_API_KEY` env var.
`azure_endpoint`: The endpoint of the model deployed on Azure. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/azure_text_embedder.py | + +
+
+## Overview
+
+`AzureOpenAITextEmbedder` transforms a string into a vector that captures its semantics using an OpenAI embedding model. It uses Azure cognitive services for text and document embedding with models deployed on Azure.
+
+To see the list of compatible embedding models, head over to Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?source=recommendations). The default model for `AzureOpenAITextEmbedder` is `text-embedding-ada-002`.
+
+Use `AzureOpenAITextEmbedder` to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [`AzureOpenAIDocumentEmbedder`](azureopenaidocumentembedder.mdx), which enriches the documents with the computed embedding, also known as vector.
+
+To work with Azure components, you will need an Azure OpenAI API key, as well as an Azure OpenAI Endpoint. You can learn more about them in Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
+
+The component uses `AZURE_OPENAI_API_KEY` or `AZURE_OPENAI_AD_TOKEN` environment variables by default. Otherwise, you can pass `api_key` or `azure_ad_token` at initialization:
+
+```python
+client = AzureOpenAITextEmbedder(azure_endpoint="`azure_endpoint`: The endpoint of the model deployed on Azure. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/azure_text_embedder.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Cohere API key. Can be set with `COHERE_API_KEY` or `CO_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata strings | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | + +
+
+## Overview
+
+`CohereDocumentEmbedder` enriches the metadata of documents with an embedding of their content. To embed a string, you should use the [`CohereTextEmbedder`](coheretextembedder.mdx).
+
+The component supports the following Cohere models:
+`"embed-english-v3.0"`, `"embed-english-light-v3.0"`, `"embed-multilingual-v3.0"`,
+`"embed-multilingual-light-v3.0"`, `"embed-english-v2.0"`, `"embed-english-light-v2.0"`,
+`"embed-multilingual-v2.0"`. The default model is `embed-english-v2.0`. This list of all supported models can be found in Cohere’s [model documentation](https://docs.cohere.com/docs/models#representation).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install cohere-haystack
+```
+
+The component uses a `COHERE_API_KEY` or `CO_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = CohereDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Cohere API key. Can be set with `COHERE_API_KEY` or `CO_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents, with a meta field containing an image file path |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [Cohere](/reference/integrations-cohere) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere |
+
+
+
+## Overview
+
+`CohereDocumentImageEmbedder` expects a list of documents containing an image or a PDF file path in a meta field. The meta field can be specified with the `file_path_meta_field` init parameter of this component.
+
+The embedder efficiently loads the images, computes the embeddings using a Cohere model, and stores each of them in the `embedding` field of the document.
+
+`CohereDocumentImageEmbedder` is commonly used in indexing pipelines. At retrieval time, you need to use the same model with a `CohereTextEmbedder` to embed the query, before using an Embedding Retriever.
+
+This component is compatible with Cohere Embed models v3 and later. For a complete list of supported models, see the [Cohere documentation](https://docs.cohere.com/docs/models#embed).
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install cohere-haystack
+```
+
+### Authentication
+
+The component uses a `COHERE_API_KEY` or `CO_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` method:
+
+```python
+embedder = CohereTextEmbedder(api_key=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The Cohere API key. Can be set with `COHERE_API_KEY` or `CO_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers (vectors)
`meta`: A dictionary of metadata strings | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | + +
+
+## Overview
+
+`CohereTextEmbedder` embeds a simple string (such as a query) into a vector. For embedding lists of documents, use the use the [`CohereDocumentEmbedder`](coheredocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+The component supports the following Cohere models:
+`"embed-english-v3.0"`, `"embed-english-light-v3.0"`, `"embed-multilingual-v3.0"`,
+`"embed-multilingual-light-v3.0"`, `"embed-english-v2.0"`, `"embed-english-light-v2.0"`,
+`"embed-multilingual-v2.0"`. The default model is `embed-english-v2.0`. This list of all supported models can be found in Cohere’s [model documentation](https://docs.cohere.com/docs/models#representation).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install cohere-haystack
+```
+
+The component uses a `COHERE_API_KEY` or `CO_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` static method:
+
+```python
+embedder = CohereTextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [FastEmbed](/reference/fastembed-embedders) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed |
+
+
+
+This component should be used to embed a list of documents. To embed a string, use the [`FastembedTextEmbedder`](fastembedtextembedder.mdx).
+
+## Overview
+
+`FastembedDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses embedding [models supported by FastEmbed](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents in order to find the most similar or relevant documents.
+
+### Compatible models
+
+You can find the original models in the [FastEmbed documentation](https://qdrant.github.io/fastembed/).
+
+Nowadays, most of the models in the [Massive Text Embedding Benchmark (MTEB) Leaderboard](https://huggingface.co/spaces/mteb/leaderboard) are compatible with FastEmbed. You can look for compatibility in the [supported model list](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install fastembed-haystack
+```
+
+### Parameters
+
+You can set the path where the model will be stored in a cache directory. Also, you can set the number of threads a single `onnxruntime` session can use.
+
+```python
+cache_dir= "/your_cacheDirectory"
+embedder = FastembedDocumentEmbedder(
+ *model="*BAAI/bge-large-en-v1.5",
+ cache_dir=cache_dir,
+ threads=2
+)
+```
+
+If you want to use the data parallel encoding, you can set the parameters `parallel` and `batch_size`.
+
+- If parallel > 1, data-parallel encoding will be used. This is recommended for offline encoding of large datasets.
+- If parallel is 0, use all available cores.
+- If None, don't use data-parallel processing; use default `onnxruntime` threading instead.
+
+:::tip
+If you create a Text Embedder and a Document Embedder based on the same model, Haystack uses the same resource behind the scenes to save resources.
+:::
+
+### Embedding Metadata
+
+Text documents often come with a set of metadata. If they are distinctive and semantically meaningful, you can embed them along with the text of the document to improve retrieval.
+
+You can do this easily by using the Document Embedder:
+
+```python
+from haystack.preview import Document
+from haystack_integrations.components.embedders.fastembed import FastembedDocumentEmbedder
+
+doc = Document(text="some text",
+ metadata={"title": "relevant title",
+ "page number": 18})
+
+embedder = FastembedDocumentEmbedder(
+ model="BAAI/bge-small-en-v1.5",
+ batch_size=256,
+ metadata_fields_to_embed=["title"]
+)
+
+docs_w_embeddings = embedder.run(documents=[doc])["documents"]
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.embedders.fastembed import FastembedDocumentEmbedder
+document_list = [
+ Document(content="I love pizza!"),
+ Document(content="I like spaghetti")
+]
+
+doc_embedder = FastembedDocumentEmbedder()
+doc_embedder.warm_up()
+
+result = doc_embedder.run(document_list)
+print(result['documents'][0].embedding)
+
+## [-0.04235665127635002, 0.021791068837046623, ...]
+```
+
+### In a pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.writers import DocumentWriter
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack_integrations.components.embedders.fastembed import FastembedDocumentEmbedder, FastembedTextEmbedder
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+ Document(content="fastembed is supported by and maintained by Qdrant."),
+]
+
+document_embedder = FastembedDocumentEmbedder()
+writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.OVERWRITE)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("document_embedder", document_embedder)
+indexing_pipeline.add_component("writer", writer)
+indexing_pipeline.connect("document_embedder", "writer")
+
+indexing_pipeline.run({"document_embedder": {"documents": documents}})
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", FastembedTextEmbedder())
+query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who supports fastembed?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0]) # noqa: T201
+
+## Document(id=...,
+## content: 'fastembed is supported by and maintained by Qdrant.',
+## score: 0.758..)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [RAG Pipeline Using FastEmbed for Embeddings Generation](https://haystack.deepset.ai/cookbook/rag_fastembed)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedsparsedocumentembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedsparsedocumentembedder.mdx
new file mode 100644
index 0000000000..c168ea7283
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedsparsedocumentembedder.mdx
@@ -0,0 +1,174 @@
+---
+title: "FastembedSparseDocumentEmbedder"
+id: fastembedsparsedocumentembedder
+slug: "/fastembedsparsedocumentembedder"
+description: "Use this component to enrich a list of documents with their sparse embeddings."
+---
+
+# FastembedSparseDocumentEmbedder
+
+Use this component to enrich a list of documents with their sparse embeddings.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with sparse embeddings) |
+| **API reference** | [FastEmbed](/reference/fastembed-embedders) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed |
+
+
+
+To compute a sparse embedding for a string, use the [`FastembedSparseTextEmbedder`](fastembedsparsetextembedder.mdx).
+
+## Overview
+
+`FastembedSparseDocumentEmbedder` computes the sparse embeddings of a list of documents and stores the obtained vectors in the `sparse_embedding` field of each document. It uses sparse embedding [models](https://qdrant.github.io/fastembed/examples/Supported_Models/#supported-sparse-text-embedding-models) supported by FastEmbed.
+
+The vectors calculated by this component are necessary for performing sparse embedding retrieval on a set of documents. During retrieval, the sparse vector representing the query is compared to those of the documents to identify the most similar or relevant ones.
+
+### Compatible models
+
+You can find the supported models in the [FastEmbed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/#supported-sparse-text-embedding-models).
+
+Currently, supported models are based on SPLADE, a technique for producing sparse representations for text, where each non-zero value in the embedding is the importance weight of a term in the BERT WordPiece vocabulary. For more information, see [our docs](../retrievers.mdx#sparse-embedding-based-retrievers) that explain sparse embedding-based Retrievers further.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install fastembed-haystack
+```
+
+### Parameters
+
+You can set the path where the model will be stored in a cache directory. Also, you can set the number of threads a single `onnxruntime` session can use:
+
+```python
+cache_dir= "/your_cacheDirectory"
+embedder = FastembedSparseDocumentEmbedder(
+ model="prithivida/Splade_PP_en_v1",
+ cache_dir=cache_dir,
+ threads=2
+)
+```
+
+If you want to use the data parallel encoding, you can set the parameters `parallel` and `batch_size`.
+
+- If `parallel` > 1, data-parallel encoding will be used. This is recommended for offline encoding of large datasets.
+- If `parallel` is 0, use all available cores.
+- If None, don't use data-parallel processing; use default `onnxruntime` threading instead.
+
+:::tip
+If you create both a Sparse Text Embedder and a Sparse Document Embedder based on the same model, Haystack utilizes a shared resource behind the scenes to conserve resources.
+:::
+
+### Embedding Metadata
+
+Text documents often include metadata. If the metadata is distinctive and semantically meaningful, you can embed it along with the document's text to improve retrieval.
+
+You can do this easily by using the sparse Document Embedder:
+
+```python
+from haystack.preview import Document
+from haystack_integrations.components.embedders.fastembed import FastembedSparseDocumentEmbedder
+
+doc = Document(text="some text",
+ metadata={"title": "relevant title",
+ "page number": 18})
+
+embedder = FastembedSparseDocumentEmbedder(
+ model="prithivida/Splade_PP_en_v1",
+ metadata_fields_to_embed=["title"]
+)
+
+docs_w_sparse_embeddings = embedder.run(documents=[doc])["documents"]
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.embedders.fastembed import FastembedSparseDocumentEmbedder
+document_list = [
+ Document(content="I love pizza!"),
+ Document(content="I like spaghetti")
+]
+
+doc_embedder = FastembedSparseDocumentEmbedder()
+doc_embedder.warm_up()
+
+result = doc_embedder.run(document_list)
+print(result['documents'][0])
+
+## Document(id=...,
+## content: 'I love pizza!',
+## sparse_embedding: vector with 24 non-zero elements)
+```
+
+### In a pipeline
+
+Currently, sparse embedding retrieval is only supported by `QdrantDocumentStore`.
+First, install the package with:
+
+```shell
+pip install qdrant-haystack
+```
+
+Then, try out this pipeline:
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.writers import DocumentWriter
+from haystack_integrations.components.retrievers.qdrant import QdrantSparseEmbeddingRetriever
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack_integrations.components.embedders.fastembed import FastembedDocumentEmbedder, FastembedTextEmbedder
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ use_sparse_embeddings=True
+)
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+ Document(content="fastembed is supported by and maintained by Qdrant."),
+]
+
+sparse_document_embedder = FastembedSparseDocumentEmbedder()
+writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.OVERWRITE)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("sparse_document_embedder", sparse_document_embedder)
+indexing_pipeline.add_component("writer", writer)
+indexing_pipeline.connect("sparse_document_embedder", "writer")
+
+indexing_pipeline.run({"sparse_document_embedder": {"documents": documents}})
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("sparse_text_embedder", FastembedSparseTextEmbedder())
+query_pipeline.add_component("sparse_retriever", QdrantSparseEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("sparse_text_embedder.sparse_embedding", "sparse_retriever.query_sparse_embedding")
+
+query = "Who supports fastembed?"
+
+result = query_pipeline.run({"sparse_text_embedder": {"text": query}})
+
+print(result["sparse_retriever"]["documents"][0]) # noqa: T201
+
+## Document(id=...,
+## content: 'fastembed is supported by and maintained by Qdrant.',
+## score: 0.758..)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Sparse Embedding Retrieval with Qdrant and FastEmbed](https://haystack.deepset.ai/cookbook/sparse_embedding_retrieval)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedsparsetextembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedsparsetextembedder.mdx
new file mode 100644
index 0000000000..5a4bcf5b3b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedsparsetextembedder.mdx
@@ -0,0 +1,143 @@
+---
+title: "FastembedSparseTextEmbedder"
+id: fastembedsparsetextembedder
+slug: "/fastembedsparsetextembedder"
+description: "Use this component to embed a simple string (such as a query) into a sparse vector."
+---
+
+# FastembedSparseTextEmbedder
+
+Use this component to embed a simple string (such as a query) into a sparse vector.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a sparse embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `sparse_embedding`: A [`SparseEmbedding`](../../concepts/data-classes.mdx#sparseembedding) object |
+| **API reference** | [FastEmbed](/reference/fastembed-embedders) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed |
+
+
+
+For embedding lists of documents, use the [`FastembedSparseDocumentEmbedder`](fastembedsparsedocumentembedder.mdx), which enriches the document with the computed sparse embedding.
+
+## Overview
+
+`FastembedSparseTextEmbedder` transforms a string into a sparse vector using sparse embedding [models](https://qdrant.github.io/fastembed/examples/Supported_Models/#supported-sparse-text-embedding-models) supported by FastEmbed.
+
+When you perform sparse embedding retrieval, use this component first to transform your query into a sparse vector. Then, the sparse embedding Retriever will use the vector to search for similar or relevant documents.
+
+### Compatible Models
+
+You can find the supported models in the [FastEmbed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/#supported-sparse-text-embedding-models).
+
+Currently, supported models are based on SPLADE, a technique for producing sparse representations for text, where each non-zero value in the embedding is the importance weight of a term in the BERT WordPiece vocabulary. For more information, see [our docs](../retrievers.mdx#sparse-embedding-based-retrievers) that explain sparse embedding-based Retrievers further.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install fastembed-haystack
+```
+
+### Parameters
+
+You can set the path where the model will be stored in a cache directory. Also, you can set the number of threads a single `onnxruntime` session can use:
+
+```python
+cache_dir= "/your_cacheDirectory"
+embedder = FastembedSparseTextEmbedder(
+ model="prithivida/Splade_PP_en_v1",
+ cache_dir=cache_dir,
+ threads=2
+)
+```
+
+If you want to use the data parallel encoding, you can set the `parallel` parameter.
+
+- If `parallel` > 1, data-parallel encoding will be used. This is recommended for offline encoding of large datasets.
+- If `parallel` is 0, use all available cores.
+- If None, don't use data-parallel processing; use the default `onnxruntime` threading instead.
+
+:::tip
+If you create both a Sparse Text Embedder and a Sparse Document Embedder based on the same model, Haystack utilizes a shared resource behind the scenes to conserve resources.
+:::
+
+## Usage
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.fastembed import FastembedSparseTextEmbedder
+
+text = """It clearly says online this will work on a Mac OS system.
+The disk comes and it does not, only Windows.
+Do Not order this if you have a Mac!!"""
+
+text_embedder = FastembedSparseTextEmbedder(model="prithivida/Splade_PP_en_v1")
+text_embedder.warm_up()
+
+sparse_embedding = text_embedder.run(text)["sparse_embedding"]
+```
+
+### In a pipeline
+
+Currently, sparse embedding retrieval is only supported by `QdrantDocumentStore`.
+First, install the package with:
+
+```shell
+pip install qdrant-haystack
+```
+
+Then, try out this pipeline:
+
+```python
+from haystack import Document, Pipeline
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack_integrations.components.retrievers.qdrant import QdrantSparseEmbeddingRetriever
+from haystack_integrations.components.embedders.fastembed import FastembedSparseTextEmbedder, FastembedSparseDocumentEmbedder, FastembedTextEmbedder
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ use_sparse_embeddings=True
+)
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+ Document(content="fastembed is supported by and maintained by Qdrant."),
+]
+
+sparse_document_embedder = FastembedSparseDocumentEmbedder(
+ model="prithivida/Splade_PP_en_v1"
+)
+
+sparse_document_embedder.warm_up()
+documents_with_sparse_embeddings = sparse_document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_sparse_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("sparse_text_embedder", FastembedSparseTextEmbedder())
+query_pipeline.add_component("sparse_retriever", QdrantSparseEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("sparse_text_embedder.sparse_embedding",
+ "sparse_retriever.query_sparse_embedding")
+
+query = "Who supports fastembed?"
+
+result = query_pipeline.run({"sparse_text_embedder": {"text": query}})
+
+print(result["sparse_retriever"]["documents"][0]) # noqa: T201
+
+## Document(id=...,
+## content: 'fastembed is supported by and maintained by Qdrant.',
+## score: 0.561..)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Sparse Embedding Retrieval with Qdrant and FastEmbed](https://haystack.deepset.ai/cookbook/sparse_embedding_retrieval)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedtextembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedtextembedder.mdx
new file mode 100644
index 0000000000..e4cfdc82c9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedtextembedder.mdx
@@ -0,0 +1,138 @@
+---
+title: "FastembedTextEmbedder"
+id: fastembedtextembedder
+slug: "/fastembedtextembedder"
+description: "This component computes the embeddings of a string using embedding models supported by FastEmbed."
+---
+
+# FastembedTextEmbedder
+
+This component computes the embeddings of a string using embedding models supported by FastEmbed.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A vector (list of float numbers) |
+| **API reference** | [FastEmbed](/reference/fastembed-embedders) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed |
+
+
+
+This component should be used to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [`FastembedDocumentEmbedder`](fastembeddocumentembedder.mdx), which enriches the document with the computed embedding, known as vector.
+
+## Overview
+
+`FastembedTextEmbedder` transforms a string into a vector that captures its semantics using embedding [models supported by FastEmbed](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+
+When you perform embedding retrieval, use this component first to transform your query into a vector. Then, the embedding Retriever will use the vector to search for similar or relevant documents.
+
+### Compatible models
+
+You can find the original models in the [FastEmbed documentation](https://qdrant.github.io/fastembed/).
+
+Currently, most of the models in the [Massive Text Embedding Benchmark (MTEB) Leaderboard](https://huggingface.co/spaces/mteb/leaderboard) are compatible with FastEmbed. You can look for compatibility in the [supported model list](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```bash
+pip install fastembed-haystack
+```
+
+### Instructions
+
+Some recent models that you can find in MTEB require prepending the text with an instruction to work better for retrieval.
+For example, if you use `[BAAI/bge-large-en-v1.5](https://huggingface.co/BAAI/bge-large-en-v1.5#model-list)` model, you should prefix your query with the `instruction: “passage:”`.
+
+This is how it works with `FastembedTextEmbedder`:
+
+```python
+instruction = "passage:"
+embedder = FastembedTextEmbedder(
+ *model="*BAAI/bge-large-en-v1.5",
+ prefix=instruction)
+```
+
+### Parameters
+
+You can set the path where the model will be stored in a cache directory. Also, you can set the number of threads a single `onnxruntime` session can use.
+
+```python
+cache_dir= "/your_cacheDirectory"
+embedder = FastembedTextEmbedder(
+ *model="*BAAI/bge-large-en-v1.5",
+ cache_dir=cache_dir,
+ threads=2
+)
+```
+
+If you want to use the data parallel encoding, you can set the parameters `parallel` and `batch_size`.
+
+- If parallel > 1, data-parallel encoding will be used. This is recommended for offline encoding of large datasets.
+- If parallel is 0, use all available cores.
+- If None, don't use data-parallel processing; use default `onnxruntime` threading instead.
+
+:::tip
+If you create a Text Embedder and a Document Embedder based on the same model, Haystack uses the same resource behind the scenes to save resources.
+:::
+
+## Usage
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.fastembed import FastembedTextEmbedder
+
+text = """It clearly says online this will work on a Mac OS system.
+The disk comes and it does not, only Windows.
+Do Not order this if you have a Mac!!"""
+text_embedder = FastembedTextEmbedder(model="BAAI/bge-small-en-v1.5")
+text_embedder.warm_up()
+embedding = text_embedder.run(text)["embedding"]
+```
+
+### In a pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.fastembed import FastembedDocumentEmbedder, FastembedTextEmbedder
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+ Document(content="fastembed is supported by and maintained by Qdrant."),
+]
+
+document_embedder = FastembedDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", FastembedTextEmbedder())
+query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who supports FastEmbed?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0]) # noqa: T201
+
+## Document(id=...,
+## content: 'FastEmbed is supported by and maintained by Qdrant.',
+## score: 0.758..)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [RAG Pipeline Using FastEmbed for Embeddings Generation](https://haystack.deepset.ai/cookbook/rag_fastembed)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/googlegenaidocumentembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/googlegenaidocumentembedder.mdx
new file mode 100644
index 0000000000..c31f602f4a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/googlegenaidocumentembedder.mdx
@@ -0,0 +1,160 @@
+---
+title: "GoogleGenAIDocumentEmbedder"
+id: googlegenaidocumentembedder
+slug: "/googlegenaidocumentembedder"
+description: "The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector representing the query is compared with those of the documents to find the most similar or relevant documents."
+---
+
+# GoogleGenAIDocumentEmbedder
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector representing the query is compared with those of the documents to find the most similar or relevant documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [DocumentWriter](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Google API key. Can be set with `GOOGLE_API_KEY` or `GEMINI_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Google AI](/reference/integrations-google-genai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai | + +
+
+## Overview
+
+`GoogleGenAIDocumentEmbedder` enriches the metadata of documents with an embedding of their content. To embed a string, you should use the [`GoogleGenAITextEmbedder`](googlegenaitextembedder.mdx).
+
+The component supports the following Google AI models:
+
+- `text-embedding-004` (default)
+- `text-embedding-004-v2`
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install google-genai-haystack
+```
+
+### Authentication
+
+Google Gen AI is compatible with both the Gemini Developer API and the Vertex AI API.
+
+To use this component with the Gemini Developer API and get an API key, visit [Google AI Studio](https://aistudio.google.com/).
+To use this component with the Vertex AI API, visit [Google Cloud > Vertex AI](https://cloud.google.com/vertex-ai).
+
+The component uses a `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` static method:
+
+```python
+embedder = GoogleGenAIDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Google AI](/reference/integrations-google-genai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The Google API key. Can be set with `GOOGLE_API_KEY` or `GEMINI_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Google AI](/reference/integrations-google-genai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai | + +
+
+## Overview
+
+`GoogleGenAITextEmbedder` embeds a simple string (such as a query) into a vector. For embedding lists of documents, use the [`GoogleGenAIDocumentEmbedder`](googlegenaidocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+The component supports the following Google AI models:
+
+- `text-embedding-004` (default)
+- `text-embedding-004-v2`
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install google-genai-haystack
+```
+
+### Authentication
+
+Google Gen AI is compatible with both the Gemini Developer API and the Vertex AI API.
+
+To use this component with the Gemini Developer API and get an API key, visit [Google AI Studio](https://aistudio.google.com/).
+To use this component with the Vertex AI API, visit [Google Cloud > Vertex AI](https://cloud.google.com/vertex-ai).
+
+The component uses a `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` static method:
+
+```python
+embedder = GoogleGenAITextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Google AI](/reference/integrations-google-genai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_type`: The type of Hugging Face API to use
`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.
`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `documents`: A list of documents to be embedded | +| **Output variables** | `documents`: A list of documents to be embedded (enriched with embeddings) | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_document_embedder.py | + +
+
+## Overview
+
+`HuggingFaceAPIDocumentEmbedder` can be used to compute document embeddings using different Hugging Face APIs:
+
+- [Free Serverless Inference API](https://huggingface.co/inference-api)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+
+:::info
+This component should be used to embed a list of documents. To embed a string, use [`HuggingFaceAPITextEmbedder`](huggingfaceapitextembedder.mdx).
+:::
+
+The component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with `token` – see code examples below.
+The token is needed:
+
+- If you use the Serverless Inference API, or
+- If you use the Inference Endpoints.
+
+## Usage
+
+Similarly to other Document Embedders, this component allows adding prefixes (and postfixes) to include instruction and embedding metadata.
+For more fine-grained details, refer to the component’s [API reference](/reference/embedders-api#huggingfaceapidocumentembedder).
+
+### On its own
+
+#### Using Free Serverless Inference API
+
+Formerly known as (free) Hugging Face Inference API, this API allows you to quickly experiment with many models hosted on the Hugging Face Hub, offloading the inference to Hugging Face servers. It’s rate-limited and not meant for production.
+
+To use this API, you need a [free Hugging Face token](https://huggingface.co/settings/tokens).
+The Embedder expects the `model` in `api_params`.
+
+```python
+from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
+from haystack.utils import Secret
+from haystack.dataclasses import Document
+
+doc = Document(content="I love pizza!")
+
+document_embedder = HuggingFaceAPIDocumentEmbedder(api_type="serverless_inference_api",
+ api_params={"model": "BAAI/bge-small-en-v1.5"},
+ token=Secret.from_token("`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.
`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `documents`: A list of documents to be embedded | +| **Output variables** | `documents`: A list of documents to be embedded (enriched with embeddings) | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_document_embedder.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_type`: The type of Hugging Face API to use
`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.
`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_text_embedder.py | + +
+
+## Overview
+
+`HuggingFaceAPITextEmbedder` can be used to embed strings using different Hugging Face APIs:
+
+- [Free Serverless Inference API](https://huggingface.co/inference-api)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+
+:::info
+This component should be used to embed plain text. To embed a list of documents, use [`HuggingFaceAPIDocumentEmbedder`](huggingfaceapidocumentembedder.mdx).
+:::
+
+The component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with `token` – see code examples below.
+The token is needed:
+
+- If you use the Serverless Inference API, or
+- If you use the Inference Endpoints.
+
+## Usage
+
+Similarly to other text Embedders, this component allows adding prefixes (and postfixes) to include instructions.
+For more fine-grained details, refer to the component’s [API reference](/reference/embedders-api#huggingfaceapitextembedder).
+
+### On its own
+
+#### Using Free Serverless Inference API
+
+Formerly known as (free) Hugging Face Inference API, this API allows you to quickly experiment with many models hosted on the Hugging Face Hub, offloading the inference to Hugging Face servers. It’s rate-limited and not meant for production.
+
+To use this API, you need a [free Hugging Face token](https://huggingface.co/settings/tokens).
+The Embedder expects the `model` in `api_params`.
+
+```python
+from haystack.components.embedders import HuggingFaceAPITextEmbedder
+from haystack.utils import Secret
+
+text_embedder = HuggingFaceAPITextEmbedder(api_type="serverless_inference_api",
+ api_params={"model": "BAAI/bge-small-en-v1.5"},
+ token=Secret.from_token("`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.
`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_text_embedder.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Jina API key. Can be set with `JINA_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Jina](/reference/integrations-jina) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina | + +
+
+## Overview
+
+`JinaDocumentEmbedder` enriches the metadata of documents with an embedding of their content. To embed a string, you should use the [`JinaTextEmbedder`](jinatextembedder.mdx). To see the list of compatible Jina Embeddings models, head to Jina AI’s [website](https://jina.ai/embeddings/). The default model for `JinaDocumentEmbedder` is `jina-embeddings-v2-base-en`.
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install jina-haystack
+```
+
+The component uses a `JINA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = JinaDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Jina](/reference/integrations-jina) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Jina API key. Can be set with `JINA_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents, with a meta field containing an image file path |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [Jina](/reference/integrations-jina) |
+| **GitHub link** | [https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere) |
+
+
+
+## Overview
+
+`JinaDocumentImageEmbedder` expects a list of documents containing an image or a PDF file path in a meta field. The meta field can be specified with the `file_path_meta_field` init parameter of this component.
+
+The embedder efficiently loads the images, computes the embeddings using a Jina model, and stores each of them in the `embedding` field of the document.
+
+`JinaDocumentImageEmbedder` is commonly used in indexing pipelines. At retrieval time, you need to use the same model with a `JinaTextEmbedder` to embed the query, before using an Embedding Retriever.
+
+This component is compatible with Jina multimodal embedding models:
+
+- `jina-clip-v1`
+- `jina-clip-v2` (default)
+- `jina-embeddings-v4` (non-commercial research only)
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install jina-haystack
+```
+
+### Authentication
+
+The component uses a `JINA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` method:
+
+```python
+embedder = JinaDocumentImageEmbedder(api_key=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The Jina API key. Can be set with `JINA_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Jina](/reference/integrations-jina) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina | + +
+
+## Overview
+
+`JinaTextEmbedder` embeds a simple string (such as a query) into a vector. For embedding lists of documents, use the use the [`JinaDocumentEmbedder`](jinadocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector. To see the list of compatible Jina Embeddings models, head to Jina AI’s [website](https://jina.ai/embeddings/). The default model for `JinaTextEmbedder` is `jina-embeddings-v2-base-en`.
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install jina-haystack
+```
+
+The component uses a `JINA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = JinaTextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Jina](/reference/integrations-jina) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The Mistral API key. Can be set with `MISTRAL_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata strings | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | + +
+
+This component should be used to embed a list of Documents. To embed a string, use the [`MistralTextEmbedder`](mistraltextembedder.mdx).
+
+## Overview
+
+`MistralDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses the Mistral API and its embedding models.
+
+The component currently supports the `mistral-embed` embedding model. The list of all supported models can be found in Mistral’s [embedding models documentation](https://docs.mistral.ai/platform/endpoints/#embedding-models).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install mistral-haystack
+```
+
+`MistralDocumentEmbedder` needs a Mistral API key to work. It uses an `MISTRAL_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = MistralDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: The Mistral API key. Can be set with `MISTRAL_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers (vectors)
`meta`: A dictionary of metadata strings | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | + +
+
+Use `MistalTextEmbedder` to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [`MistralDocumentEmbedder`](mistraldocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+## Overview
+
+`MistralTextEmbedder` transforms a string into a vector that captures its semantics using a Mistral embedding model.
+
+The component currently supports the `mistral-embed` embedding model. The list of all supported models can be found in Mistral’s [embedding models documentation](https://docs.mistral.ai/platform/endpoints/#embedding-models).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install mistral-haystack
+```
+
+`MistralTextEmbedder` needs a Mistral API key to work. It uses a `MISTRAL_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = MistralTextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: API key for the NVIDIA NIM. Can be set with `NVIDIA_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Nvidia](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | + +
+
+## Overview
+
+`NvidiaDocumentEmbedder` enriches the metadata of documents with an embedding of their content.
+
+It can be used with self-hosted models with NVIDIA NIM or models hosted on the [NVIDIA API catalog](https://build.nvidia.com/explore/discover).
+
+To embed a string, use the [`NvidiaTextEmbedder`](nvidiatextembedder.mdx).
+
+## Usage
+
+To start using `NvidiaDocumentEmbedder`, first, install the `nvidia-haystack` package:
+
+```shell
+pip install nvidia-haystack
+```
+
+You can use the `NvidiaDocumentEmbedder` with all the embedder models available on the [NVIDIA API catalog](https://docs.api.nvidia.com/nim/reference) or using a model deployed with NVIDIA NIM. Follow the [Deploying Text Embedding Models](https://developer.nvidia.com/docs/nemo-microservices/embedding/source/deploy.html) guide to learn how to deploy the model you want on your infrastructure.
+
+### On its own
+
+To use LLMs from the NVIDIA API catalog, you need to specify the correct `api_url` and your API key. You can get your API key directly from the [catalog website](https://build.nvidia.com/explore/discover).
+
+The `NvidiaDocumentEmbedder` needs an Nvidia API key to work. It uses the `NVIDIA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`, as in the following example.
+
+```python
+from haystack.utils.auth import Secret
+from haystack_integrations.components.embedders.nvidia import NvidiaDocumentEmbedder
+
+embedder = NvidiaDocumentEmbedder(
+ model="nvidia/nv-embedqa-e5-v5",
+ api_url="https://integrate.api.nvidia.com/v1",
+ api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Nvidia](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: API key for the NVIDIA NIM. Can be set with `NVIDIA_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers (vectors)
`meta`: A dictionary of metadata strings | +| **API reference** | [Nvidia](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | + +
+
+## Overview
+
+`NvidiaTextEmbedder` embeds a simple string (such as a query) into a vector.
+
+It can be used with self-hosted models with NVIDIA NIM or models hosted on the [NVIDIA API catalog](https://build.nvidia.com/explore/discover).
+
+To embed a list of documents, use the [`NvidiaDocumentEmbedder`](nvidiadocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+## Usage
+
+To start using `NvidiaTextEmbedder`, first, install the `nvidia-haystack` package:
+
+```shell
+pip install nvidia-haystack
+```
+
+You can use the `NvidiaTextEmbedder` with all the embedder models available on the [NVIDIA API catalog](https://docs.api.nvidia.com/nim/reference) or using a model deployed with NVIDIA NIM. Follow the [Deploying Text Embedding Models](https://developer.nvidia.com/docs/nemo-microservices/embedding/source/deploy.html) guide to learn how to deploy the model you want on your infrastructure.
+
+### On its own
+
+To use LLMs from the NVIDIA API catalog, you need to specify the correct `api_url` and your API key. You can get your API key directly from the [catalog website](https://build.nvidia.com/explore/discover).
+
+The `NvidiaTextEmbedder` needs an Nvidia API key to work. It uses the `NVIDIA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`, as in the following example.
+
+```python
+from haystack.utils.auth import Secret
+from haystack_integrations.components.embedders.nvidia import NvidiaTextEmbedder
+
+embedder = NvidiaTextEmbedder(
+ model="nvidia/nv-embedqa-e5-v5",
+ api_url="https://integrate.api.nvidia.com/v1",
+ api_key=Secret.from_token("`meta`: A dictionary of metadata strings | +| **API reference** | [Nvidia](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata strings | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | + +
+
+`OllamaDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses embedding models compatible with the Ollama Library.
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant documents.
+
+## Overview
+
+`OllamaDocumentEmbedder` should be used to embed a list of documents. For embedding a string only, use the [`OllamaTextEmbedder`](ollamatextembedder.mdx).
+
+The component uses `http://localhost:11434` as the default URL as most available setups (Mac, Linux, Docker) default to port 11434.
+
+### Compatible Models
+
+Unless specified otherwise while initializing this component, the default embedding model is "nomic-embed-text". See other possible pre-built models in Ollama's [library](https://ollama.ai/library). To load your own custom model, follow the [instructions](https://github.com/ollama/ollama/blob/main/docs/modelfile.md) from Ollama.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install ollama-haystack
+```
+
+Make sure that you have a running Ollama model (either through a docker container, or locally hosted). No other configuration is necessary as Ollama has the embedding API built in.
+
+### Embedding Metadata
+
+Most embedded metadata contains information about the model name and type. You can pass [optional arguments](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values), such as temperature, top_p, and others, to the Ollama generation endpoint.
+
+The name of the model used will be automatically appended as part of the document metadata. An example payload using the nomic-embed-text model will look like this:
+
+```python
+{'meta': {'model': 'nomic-embed-text'}}
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.ollama import OllamaDocumentEmbedder
+
+doc = Document(content="What do llamas say once you have thanked them? No probllama!")
+document_embedder = OllamaDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+## Calculating embeddings: 100%|██████████| 1/1 [00:02<00:00, 2.82s/it]
+
+## [-0.16412407159805298, -3.8359334468841553, ... ]
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+
+from haystack_integrations.components.embedders.ollama import OllamaDocumentEmbedder
+
+from haystack.components.preprocessors import DocumentCleaner, DocumentSplitter
+
+from haystack.components.converters import PyPDFToDocument
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+embedder = OllamaDocumentEmbedder(model="nomic-embed-text", url="http://localhost:11434") # This is the default model and URL
+
+cleaner = DocumentCleaner()
+splitter = DocumentSplitter()
+file_converter = PyPDFToDocument()
+writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.OVERWRITE)
+
+indexing_pipeline = Pipeline()
+
+## Add components to pipeline
+indexing_pipeline.add_component("embedder", embedder)
+indexing_pipeline.add_component("converter", file_converter)
+indexing_pipeline.add_component("cleaner", cleaner)
+indexing_pipeline.add_component("splitter", splitter)
+indexing_pipeline.add_component("writer", writer)
+
+## Connect components in pipeline
+indexing_pipeline.connect("converter", "cleaner")
+indexing_pipeline.connect("cleaner", "splitter")
+indexing_pipeline.connect("splitter", "embedder")
+indexing_pipeline.connect("embedder", "writer")
+
+## Run Pipeline
+indexing_pipeline.run({"converter": {"sources": ["files/test_pdf_data.pdf"]}})
+
+## Calculating embeddings: 100%|██████████| 115/115
+## {'embedder': {'meta': {'model': 'nomic-embed-text'}}, 'writer': {'documents_written': 115}}
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/ollamatextembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/ollamatextembedder.mdx
new file mode 100644
index 0000000000..20fe314971
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/ollamatextembedder.mdx
@@ -0,0 +1,102 @@
+---
+title: "OllamaTextEmbedder"
+id: ollamatextembedder
+slug: "/ollamatextembedder"
+description: "This component computes the embeddings of a string using embedding models compatible with the Ollama Library."
+---
+
+# OllamaTextEmbedder
+
+This component computes the embeddings of a string using embedding models compatible with the Ollama Library.
+
+`meta`: A dictionary of metadata strings | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers (vectors)
`meta`: A dictionary of metadata strings | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | + +
+
+`OllamaDocumentEmbedder` computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses embedding models compatible with the Ollama Library.
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant documents.
+
+## Overview
+
+`OllamaTextEmbedder` should be used to embed a string. For embedding a list of documents, use the [`OllamaDocumentEmbedder`](ollamadocumentembedder.mdx).
+
+The component uses `http://localhost:11434` as the default URL as most available setups (Mac, Linux, Docker) default to port 11434.
+
+### Compatible Models
+
+Unless specified otherwise while initializing this component, the default embedding model is "nomic-embed-text". See other possible pre-built models in Ollama's [library](https://ollama.ai/library). To load your own custom model, follow the [instructions](https://github.com/ollama/ollama/blob/main/docs/modelfile.md) from Ollama.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install ollama-haystack
+```
+
+Make sure that you have a running Ollama model (either through a docker container, or locally hosted). No other configuration is necessary as Ollama has the embedding API built in.
+
+### Embedding Metadata
+
+Most embedded metadata contains information about the model name and type. You can pass [optional arguments](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values), such as temperature, top_p, and others, to the Ollama generation endpoint.
+
+The name of the model used will be automatically appended as part of the metadata. An example payload using the nomic-embed-text model will look like this:
+
+```python
+{'meta': {'model': 'nomic-embed-text'}}
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.ollama import OllamaTextEmbedder
+
+embedder = OllamaTextEmbedder()
+
+result = embedder.run(text="What do llamas say once you have thanked them? No probllama!")
+
+print(result['embedding'])
+```
+
+### In a pipeline
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from cohere_haystack.embedders.text_embedder import OllamaTextEmbedder
+from cohere_haystack.embedders.document_embedder import OllamaDocumentEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities")]
+
+document_embedder = OllamaDocumentEmbedder()
+documents_with_embeddings = document_embedder.run(documents)['documents']
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", OllamaTextEmbedder())
+query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder":{"text": query}})
+
+print(result['retriever']['documents'][0])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/openaidocumentembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/openaidocumentembedder.mdx
new file mode 100644
index 0000000000..7697ce3464
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/openaidocumentembedder.mdx
@@ -0,0 +1,114 @@
+---
+title: "OpenAIDocumentEmbedder"
+id: openaidocumentembedder
+slug: "/openaidocumentembedder"
+description: "OpenAIDocumentEmbedder computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses OpenAI embedding models."
+---
+
+# OpenAIDocumentEmbedder
+
+OpenAIDocumentEmbedder computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses OpenAI embedding models.
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector representing the query is compared with those of the documents to find the most similar or relevant documents.
+
+`meta`: A dictionary of metadata strings | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/openai_document_embedder.py | + +
+
+## Overview
+
+To see the list of compatible OpenAI embedding models, head over to OpenAI [documentation](https://platform.openai.com/docs/guides/embeddings/embedding-models). The default model for `OpenAIDocumentEmbedder` is `text-embedding-ada-002`. You can specify another model with the `model` parameter when initializing this component.
+
+This component should be used to embed a list of documents. To embed a string, use the [OpenAITextEmbedder](openaitextembedder.mdx).
+
+The component uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```
+embedder = OpenAIDocumentEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/openai_document_embedder.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/openai_text_embedder.py | + +
+
+## Overview
+
+To see the list of compatible OpenAI embedding models, head over to OpenAI [documentation](https://platform.openai.com/docs/guides/embeddings/embedding-models). The default model for `OpenAITextEmbedder` is `text-embedding-ada-002`. You can specify another model with the `model` parameter when initializing this component.
+
+Use `OpenAITextEmbedder` to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [OpenAIDocumentEmbedder](openaidocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+The component uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+embedder = OpenAITextEmbedder(api_key=Secret.from_token("`meta`: A dictionary of metadata | +| **API reference** | [Embedders](/reference/embedders-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/openai_text_embedder.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents enriched with embeddings |
+| **API reference** | [Optimum](/reference/integrations-optimum) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/optimum |
+
+
+
+## Overview
+
+`OptimumDocumentEmbedder` embeds text strings using models loaded with the [HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library. It uses the [ONNX runtime](https://onnxruntime.ai/) for high-speed inference.
+
+The default model is `sentence-transformers/all-mpnet-base-v2`.
+
+Similarly to other Embedders, this component allows adding prefixes (and suffixes) to include instructions. For more details, refer to the component’s API reference.
+
+There are three useful parameters specific to the Optimum Embedder that you can control with various modes:
+
+- [Pooling](/reference/integrations-optimum#optimumembedderpooling): generate a fixed-sized sentence embedding from a variable-sized sentence embedding
+- [Optimization](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/optimization): apply graph optimization to the model and improve inference speed
+- [Quantization](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/quantization): reduce the computational and memory costs
+
+Find all the available mode details in our Optimum [API Reference](/reference/integrations-optimum).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models through Serverless Inference API or the Inference Endpoints.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+## Usage
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install optimum-haystack
+```
+
+### On its own
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.embedders.optimum import OptimumDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = OptimumDocumentEmbedder(model="sentence-transformers/all-mpnet-base-v2")
+document_embedder.warm_up()
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+## [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack import Document
+from haystack_integrations.components.embedders.optimum import (
+ OptimumDocumentEmbedder,
+ OptimumEmbedderPooling,
+ OptimumEmbedderOptimizationConfig,
+ OptimumEmbedderOptimizationMode,
+)
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+]
+
+embedder = OptimumDocumentEmbedder(
+ model="intfloat/e5-base-v2",
+ normalize_embeddings=True,
+ onnx_execution_provider="CUDAExecutionProvider",
+ optimizer_settings=OptimumEmbedderOptimizationConfig(
+ mode=OptimumEmbedderOptimizationMode.O4,
+ for_gpu=True,
+ ),
+ working_dir="/tmp/optimum",
+ pooling_mode=OptimumEmbedderPooling.MEAN,
+)
+
+pipeline = Pipeline()
+pipeline.add_component("embedder", embedder)
+
+pipeline.run({"embedder": {"documents": documents}})
+
+print(results["embedder"]["embedding"])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/optimumtextembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/optimumtextembedder.mdx
new file mode 100644
index 0000000000..68b00a46e5
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/optimumtextembedder.mdx
@@ -0,0 +1,106 @@
+---
+title: "OptimumTextEmbedder"
+id: optimumtextembedder
+slug: "/optimumtextembedder"
+description: "A component to embed text using models loaded with the Hugging Face Optimum library."
+---
+
+# OptimumTextEmbedder
+
+A component to embed text using models loaded with the Hugging Face Optimum library.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers (vectors) |
+| **API reference** | [Optimum](/reference/integrations-optimum) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/optimum |
+
+
+
+## Overview
+
+`OptimumTextEmbedder` embeds text strings using models loaded with the [HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library. It uses the [ONNX runtime](https://onnxruntime.ai/) for high-speed inference.
+
+The default model is `sentence-transformers/all-mpnet-base-v2`.
+
+Similarly to other Embedders, this component allows adding prefixes (and suffixes) to include instructions. For more details, refer to the component’s API reference.
+
+There are three useful parameters specific to the Optimum Embedder that you can control with various modes:
+
+- [Pooling](/reference/integrations-optimum#optimumembedderpooling): generate a fixed-sized sentence embedding from a variable-sized sentence embedding
+- [Optimization](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/optimization): apply graph optimization to the model and improve inference speed
+- [Quantization](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/quantization): reduce the computational and memory costs
+
+Find all the available mode details in our Optimum [API Reference](/reference/integrations-optimum).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models through Serverless Inference API or the Inference Endpoints.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+## Usage
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install optimum-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.optimum import OptimumTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = OptimumTextEmbedder(model="sentence-transformers/all-mpnet-base-v2")
+text_embedder.warm_up()
+
+print(text_embedder.run(text_to_embed))
+
+## {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]}
+```
+
+### In a pipeline
+
+Note that this example requires GPU support to execute.
+
+```python
+from haystack import Pipeline
+
+from haystack_integrations.components.embedders.optimum import (
+ OptimumTextEmbedder,
+ OptimumEmbedderPooling,
+ OptimumEmbedderOptimizationConfig,
+ OptimumEmbedderOptimizationMode,
+)
+
+pipeline = Pipeline()
+embedder = OptimumTextEmbedder(
+ model="intfloat/e5-base-v2",
+ normalize_embeddings=True,
+ onnx_execution_provider="CUDAExecutionProvider",
+ optimizer_settings=OptimumEmbedderOptimizationConfig(
+ mode=OptimumEmbedderOptimizationMode.O4,
+ for_gpu=True,
+ ),
+ working_dir="/tmp/optimum",
+ pooling_mode=OptimumEmbedderPooling.MEAN,
+)
+pipeline.add_component("embedder", embedder)
+
+results = pipeline.run(
+ {
+ "embedder": {
+ "text": "Ex profunditate antique doctrinae, Ad caelos supra semper, Hoc incantamentum evoco, draco apparet, Incantamentum iam transactum est"
+ },
+ }
+)
+
+print(results["embedder"]["embedding"])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformersdocumentembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformersdocumentembedder.mdx
new file mode 100644
index 0000000000..caacf8b551
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformersdocumentembedder.mdx
@@ -0,0 +1,132 @@
+---
+title: "SentenceTransformersDocumentEmbedder"
+id: sentencetransformersdocumentembedder
+slug: "/sentencetransformersdocumentembedder"
+description: "SentenceTransformersDocumentEmbedder computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses embedding models compatible with the Sentence Transformers library."
+---
+
+# SentenceTransformersDocumentEmbedder
+
+SentenceTransformersDocumentEmbedder computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses embedding models compatible with the Sentence Transformers library.
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [Embedders](/reference/embedders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/sentence_transformers_document_embedder.py |
+
+
+
+## Overview
+
+`SentenceTransformersDocumentEmbedder` should be used to embed a list of documents. To embed a string, use the [SentenceTransformersTextEmbedder](sentencetransformerstextembedder.mdx).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models through Serverless Inference API or the Inference Endpoints.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+```python
+document_embedder = SentenceTransformersDocumentEmbedder(token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `token` (only for private models): The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `documents`: A list of documents, with a meta field containing an image file path |
+| **Output variables** | `documents`: A list of documents (enriched with embeddings) |
+| **API reference** | [Embedders](/reference/embedders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/image/sentence_transformers_doc_image_embedder.py |
+
+
+
+## Overview
+
+`SentenceTransformersDocumentImageEmbedder` expects a list of documents containing an image or a PDF file path in a meta field. The meta field can be specified with the `file_path_meta_field` init parameter of this component.
+
+The embedder efficiently loads the images, computes the embeddings using a Sentence Transformers models, and stores each of them in the `embedding` field of the document.
+
+`SentenceTransformersDocumentImageEmbedder` is commonly used in indexing pipelines. At retrieval time, you need to use the same model with a `SentenceTransformersTextEmbedder` to embed the query before using an Embedding Retriever.
+
+You can set the `device` parameter to use HF models on your CPU or GPU.
+
+Additionally, you can select the backend to use for the Sentence Transformers mode with the `backend` parameterl: `torch` (default), `onnx`, or `openvino`. ONNX and OpenVINO allow specific speed optimizations; for more information, read the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+### Compatible Models
+
+To be used with this component, the model must be compatible with Sentence Transformers and
+
+able to embed images and text into the same vector space. Compatible models include:
+
+- `sentence-transformers/clip-ViT-B-32` (default)
+- `sentence-transformers/clip-ViT-L-14`
+- `sentence-transformers/clip-ViT-B-16`
+- `sentence-transformers/clip-ViT-B-32-multilingual-v1`
+- `jinaai/jina-embeddings-v4`
+- `jinaai/jina-clip-v1`
+- `jinaai/jina-clip-v2`
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.embedders.image import SentenceTransformersDocumentImageEmbedder
+
+embedder = SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32")
+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),
+## ...]
+```
+
+### In a pipeline
+
+In this example, we can see an indexing pipeline with 3 components:
+
+- `ImageFileToDocument` Converter that creates empty documents with a reference to an image in the `meta.file_path` field,
+- `SentenceTransformersDocumentImageEmbedder` that loads the images, computes embeddings and stores them in documents,
+- `DocumentWriter` that writes the documents in the `InMemoryDocumentStore`
+
+There is also a multimodal retrieval pipeline, composed by a `SentenceTransformersTextEmbedder` (using the same model as before) and an `InMemoryEmbeddingRetriever`.
+
+```python
+from haystack import Pipeline
+from haystack.components.converters.image import ImageFileToDocument
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack.components.embedders.image import SentenceTransformersDocumentImageEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+
+## Indexing pipeline
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("image_converter", ImageFileToDocument())
+indexing_pipeline.add_component(
+ "embedder",
+ SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32")
+)
+indexing_pipeline.add_component(
+ "writer", DocumentWriter(document_store=document_store)
+)
+indexing_pipeline.connect("image_converter", "embedder")
+indexing_pipeline.connect("embedder", "writer")
+
+indexing_pipeline.run(data={"image_converter": {"sources": ["dog.jpg", "hyena.jpeg"]}})
+
+## Multimodal retrieval pipeline
+retrieval_pipeline = Pipeline()
+retrieval_pipeline.add_component(
+ "embedder",
+ SentenceTransformersTextEmbedder(model="sentence-transformers/clip-ViT-B-32")
+)
+retrieval_pipeline.add_component(
+ "retriever",
+ InMemoryEmbeddingRetriever(document_store=document_store, top_k=2)
+)
+retrieval_pipeline.connect("embedder", "retriever")
+
+result = retrieval_pipeline.run(data={"text": "man's best friend"})
+print(result)
+
+## {
+## 'retriever': {
+## 'documents': [
+## Document(
+## id=0c96...,
+## meta={
+## 'file_path': 'dog.jpg',
+## 'embedding_source': {
+## 'type': 'image',
+## 'file_path_meta_field': 'file_path'
+## }
+## },
+## score=32.025817780129856
+## ),
+## Document(
+## id=5e76...,
+## meta={
+## 'file_path': 'hyena.jpeg',
+## 'embedding_source': {
+## 'type': 'image',
+## 'file_path_meta_field': 'file_path'
+## }
+## },
+## score=20.648225327085242
+## )
+## ]
+## }
+## }
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Introduction to Multimodality](https://haystack.deepset.ai/cookbook/multimodal_intro)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformerssparsedocumentembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformerssparsedocumentembedder.mdx
new file mode 100644
index 0000000000..d1b0e17b51
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformerssparsedocumentembedder.mdx
@@ -0,0 +1,186 @@
+---
+title: "SentenceTransformersSparseDocumentEmbedder"
+id: sentencetransformerssparsedocumentembedder
+slug: "/sentencetransformerssparsedocumentembedder"
+description: "Use this component to enrich a list of documents with their sparse embeddings using Sentence Transformers models."
+---
+
+# SentenceTransformersSparseDocumentEmbedder
+
+Use this component to enrich a list of documents with their sparse embeddings using Sentence Transformers models.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents (enriched with sparse embeddings) |
+| **API reference** | [Embedders](/reference/embedders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/sentence_transformers_sparse_document_embedder.py |
+
+
+
+To compute a sparse embedding for a string, use the [`SentenceTransformersSparseTextEmbedder`](sentencetransformerssparsetextembedder.mdx).
+
+## Overview
+
+`SentenceTransformersSparseDocumentEmbedder` computes the sparse embeddings of a list of documents and stores the obtained vectors in the `sparse_embedding` field of each document. It uses sparse embedding models supported by the Sentence Transformers library.
+
+The vectors computed by this component are necessary to perform sparse embedding retrieval on a collection of documents. At retrieval time, the sparse vector representing the query is compared with those of the documents to find the most similar or relevant ones.
+
+### Compatible Models
+
+The default embedding model is [`prithivida/Splade_PP_en_v2`](https://huggingface.co/prithivida/Splade_PP_en_v2). You can specify another model with the `model` parameter when initializing this component.
+
+Compatible models are based on SPLADE (SParse Lexical AnD Expansion), a technique for producing sparse representations for text, where each non-zero value in the embedding is the importance weight of a term in the vocabulary. This approach combines the benefits of learned sparse representations with the efficiency of traditional sparse retrieval methods. For more information, see [our docs](../retrievers.mdx#sparse-embedding-based-retrievers) that explain sparse embedding-based Retrievers further.
+
+You can find compatible SPLADE models on the [Hugging Face Model Hub](https://huggingface.co/models?search=splade).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+```python
+from haystack.utils import Secret
+from haystack.components.embedders import SentenceTransformersSparseDocumentEmbedder
+
+document_embedder = SentenceTransformersSparseDocumentEmbedder(
+ token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a sparse embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `sparse_embedding`: A [`SparseEmbedding`](../../concepts/data-classes.mdx#sparseembedding) object |
+| **API reference** | [Embedders](/reference/embedders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/sentence_transformers_sparse_text_embedder.py |
+
+
+
+For embedding lists of documents, use the [`SentenceTransformersSparseDocumentEmbedder`](sentencetransformerssparsedocumentembedder.mdx), which enriches the document with the computed sparse embedding.
+
+## Overview
+
+`SentenceTransformersSparseTextEmbedder` transforms a string into a sparse vector using sparse embedding models supported by the Sentence Transformers library.
+
+When you perform sparse embedding retrieval, use this component first to transform your query into a sparse vector. Then, the Retriever will use the sparse vector to search for similar or relevant documents.
+
+### Compatible Models
+
+The default embedding model is [`prithivida/Splade_PP_en_v2`](https://huggingface.co/prithivida/Splade_PP_en_v2). You can specify another model with the `model` parameter when initializing this component.
+
+Compatible models are based on SPLADE (SParse Lexical AnD Expansion), a technique for producing sparse representations for text, where each non-zero value in the embedding is the importance weight of a term in the vocabulary. This approach combines the benefits of learned sparse representations with the efficiency of traditional sparse retrieval methods. For more information, see [our docs](../retrievers.mdx#sparse-embedding-based-retrievers) that explain sparse embedding-based Retrievers further.
+
+You can find compatible SPLADE models on the [Hugging Face Model Hub](https://huggingface.co/models?search=splade).
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+```python
+from haystack.utils import Secret
+from haystack.components.embedders import SentenceTransformersSparseTextEmbedder
+
+text_embedder = SentenceTransformersSparseTextEmbedder(
+ token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers |
+| **API reference** | [Embedders](/reference/embedders-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/sentence_transformers_text_embedder.py |
+
+
+
+## Overview
+
+This component should be used to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [SentenceTransformersDocumentEmbedder](sentencetransformersdocumentembedder.mdx), which enriches the document with the computed embedding, known as vector.
+
+### Authentication
+
+Authentication with a Hugging Face API Token is only required to access private or gated models through Serverless Inference API or the Inference Endpoints.
+
+The component uses an `HF_API_TOKEN` or `HF_TOKEN` environment variable, or you can pass a Hugging Face API token at initialization. See our [Secret Management](../../concepts/secret-management.mdx) page for more information.
+
+```python
+text_embedder = SentenceTransformersTextEmbedder(token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [DocumentWriter](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `model`: The model used through the STACKIT API |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents enriched with embeddings |
+| **API reference** | [STACKIT](/reference/integrations-stackit) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit |
+
+
+
+## Overview
+
+`STACKITDocumentEmbedder` enables document embedding models served by STACKIT through their API.
+
+### Parameters
+
+To use the `STACKITDocumentEmbedder`, ensure you have set a `STACKIT_API_KEY` as an environment variable. Alternatively, provide the API key as an environment variable with a different name or a token by setting `api_key` and using Haystack’s [secret management](../../concepts/secret-management.mdx).
+
+Set your preferred supported model with the `model` parameter when initializing the component. See the full list of all supported models on the [STACKIT website](https://docs.stackit.cloud/stackit/en/models-licenses-319914532.html).
+
+Optionally, you can change the default `api_base_url`, which is `"https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1"`.
+
+You can pass any text generation parameters valid for the STACKIT Chat Completion API directly to this component with the `generation_kwargs` parameter in the init or run methods.
+
+Then component needs a list of documents as input to operate.
+
+## Usage
+
+Install the `stackit-haystack` package to use the `STACKITDocumentEmbedder` and set an environment variable called `STACKIT_API_KEY` to your API key.
+
+```shell
+pip install stackit-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.stackit import STACKITDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = STACKITDocumentEmbedder(model="intfloat/e5-mistral-7b-instruct")
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+## [0.0215301513671875, 0.01499176025390625, ...]
+```
+
+### In a pipeline
+
+You can also use `STACKITDocumentEmbedder` in your pipeline in a following way.
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.stackit import STACKITTextEmbedder, STACKITDocumentEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore()
+
+documents = [Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities")]
+
+document_embedder = STACKITDocumentEmbedder(model="intfloat/e5-mistral-7b-instruct")
+documents_with_embeddings = document_embedder.run(documents)['documents']
+document_store.write_documents(documents_with_embeddings)
+
+text_embedder = STACKITTextEmbedder(model="intfloat/e5-mistral-7b-instruct")
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", text_embedder)
+query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Where does Wolfgang live?"
+
+result = query_pipeline.run({"text_embedder":{"text": query}})
+
+print(result['retriever']['documents'][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin', score: ...)
+```
+
+You can find more usage examples in the STACKIT integration [repository](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit/examples) and its [integration page](https://haystack.deepset.ai/integrations/stackit).
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/stackittextembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/stackittextembedder.mdx
new file mode 100644
index 0000000000..c6cdb75ec3
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/stackittextembedder.mdx
@@ -0,0 +1,98 @@
+---
+title: "STACKITTextEmbedder"
+id: stackittextembedder
+slug: "/stackittextembedder"
+description: "This component enables text embedding using the STACKIT API."
+---
+
+# STACKITTextEmbedder
+
+This component enables text embedding using the STACKIT API.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `model`: The model used through the STACKIT API |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers |
+| **API reference** | [STACKIT](/reference/integrations-stackit) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit |
+
+
+
+## Overview
+
+`STACKITTextEmbedder` enables text embedding models served by STACKIT through their API.
+
+### Parameters
+
+To use the `STACKITTextEmbedder`, ensure you have set a `STACKIT_API_KEY` as an environment variable. Alternatively, provide the API key as an environment variable with a different name or a token by setting `api_key` and using Haystack’s [secret management](../../concepts/secret-management.mdx).
+
+Set your preferred supported model with the `model` parameter when initializing the component. See the full list of all supported models on the [STACKIT website](https://docs.stackit.cloud/stackit/en/models-licenses-319914532.html).
+
+Optionally, you can change the default `api_base_url`, which is `"https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1"`.
+
+You can pass any text generation parameters valid for the STACKIT Chat Completion API directly to this component with the `generation_kwargs` parameter in the init or run methods.
+
+The component needs a text input to operate.
+
+## Usage
+
+Install the `stackit-haystack` package to use the `STACKITTextEmbedder` and set an environment variable called `STACKIT_API_KEY` to your API key.
+
+```shell
+pip install stackit-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.stackit import STACKITTextEmbedder
+
+text_embedder = STACKITTextEmbedder(model="intfloat/e5-mistral-7b-instruct")
+
+print(text_embedder.run("I love pizza!"))
+
+## {'embedding': [0.0215301513671875, 0.01499176025390625, ...]}
+```
+
+### In a pipeline
+
+You can also use `STACKITTextEmbedder` in your pipeline.
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.stackit import STACKITTextEmbedder, STACKITDocumentEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore()
+
+documents = [Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities")]
+
+document_embedder = STACKITDocumentEmbedder(model="intfloat/e5-mistral-7b-instruct")
+documents_with_embeddings = document_embedder.run(documents)['documents']
+document_store.write_documents(documents_with_embeddings)
+
+text_embedder = STACKITTextEmbedder(model="intfloat/e5-mistral-7b-instruct")
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", text_embedder)
+query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Where does Wolfgang live?"
+
+result = query_pipeline.run({"text_embedder":{"text": query}})
+
+print(result['retriever']['documents'][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin', score: ...)
+```
+
+You can find more usage examples in the STACKIT integration [repository](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit/examples) and its [integration page](https://haystack.deepset.ai/integrations/stackit).
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/vertexaidocumentembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/vertexaidocumentembedder.mdx
new file mode 100644
index 0000000000..d166414e30
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/vertexaidocumentembedder.mdx
@@ -0,0 +1,107 @@
+---
+title: "VertexAIDocumentEmbedder"
+id: vertexaidocumentembedder
+slug: "/vertexaidocumentembedder"
+description: "This component computes embeddings for documents using models through VertexAI Embeddings API."
+---
+
+# VertexAIDocumentEmbedder
+
+This component computes embeddings for documents using models through VertexAI Embeddings API.
+
+:::warning Deprecation Notice
+
+This integration uses the deprecated google-generativeai SDK, which will lose support after August 2025.
+
+We recommend switching to the new [GoogleGenAIDocumentEmbedder](googlegenaidocumentembedder.mdx) integration instead.
+:::
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [DocumentWriter](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `model`: The model used through the VertexAI Embeddings API |
+| **Mandatory run variables** | `documents`: A list of documents to be embedded |
+| **Output variables** | `documents`: A list of documents enriched with embeddings |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+
+
+
+`VertexAIDocumentEmbedder` enriches the metadata of documents with an embedding of their content. To embed a string, use the [`VertexAITextEmbedder`](vertexaitextembedder.mdx).
+
+To use the `VertexAIDocumentEmbedder`, initialize it with:
+
+- `model`: The supported models are:
+ - "text-embedding-004"
+ - "text-embedding-005"
+ - "textembedding-gecko-multilingual@001"
+ - "text-multilingual-embedding-002"
+ - "text-embedding-large-exp-03-07"
+- `task_type`: "RETRIEVAL_DOCUMENT” is the default. You can find all task types in the official [Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#tasktype).
+
+### Authentication
+
+`VertexAIDocumentEmbedder` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+Install the `google-vertex-haystack` package to use this Embedder:
+
+```shell
+pip install google-vertex-haystack
+```
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.google_vertex import VertexAIDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = VertexAIDocumentEmbedder(model="text-embedding-005")
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+## [-0.044606007635593414, 0.02857724390923977, -0.03549133986234665,
+```
+
+### In a pipeline
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.google_vertex import VertexAITextEmbedder
+from haystack_integrations.components.embedders.google_vertex import VertexAIDocumentEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities")]
+
+document_embedder = VertexAIDocumentEmbedder(model="text-embedding-005")
+documents_with_embeddings = document_embedder.run(documents)['documents']
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", VertexAITextEmbedder(model="text-embedding-005"))
+query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder":{"text": query}})
+
+print(result['retriever']['documents'][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin')
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/vertexaitextembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/vertexaitextembedder.mdx
new file mode 100644
index 0000000000..33218675fb
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/vertexaitextembedder.mdx
@@ -0,0 +1,107 @@
+---
+title: "VertexAITextEmbedder"
+id: vertexaitextembedder
+slug: "/vertexaitextembedder"
+description: "This component computes embeddings for text (such as a query) using models through VertexAI Embeddings API."
+---
+
+# VertexAITextEmbedder
+
+This component computes embeddings for text (such as a query) using models through VertexAI Embeddings API.
+
+:::warning Deprecation Notice
+
+This integration uses the deprecated google-generativeai SDK, which will lose support after August 2025.
+
+We recommend switching to the new [GoogleGenAITextEmbedder](googlegenaitextembedder.mdx) integration instead.
+:::
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `model`: The model used through the VertexAI Embeddings API |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `embedding`: A list of float numbers |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+
+
+
+## Overview
+
+`VertexAITextEmbedder` embeds a simple string (such as a query) into a vector. For embedding lists of documents, use the [`VertexAIDocumentEmbedder`](vertexaidocumentembedder.mdx) which enriches the document with the computed embedding, also known as vector.
+
+To start using the `VertexAITextEmbedder`, initialize it with:
+
+- `model`: The supported models are:
+ - "text-embedding-004"
+ - "text-embedding-005"
+ - "textembedding-gecko-multilingual@001"
+ - "text-multilingual-embedding-002"
+ - "text-embedding-large-exp-03-07"
+- `task_type`: "RETRIEVAL_QUERY” is the default. You can find all task types in the official [Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#tasktype).
+
+### Authentication
+
+`VertexAITextEmbedder` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+Install the `google-vertex-haystack` package to use this Embedder:
+
+```shell
+pip install google-vertex-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.embedders.google_vertex import VertexAITextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = VertexAITextEmbedder(model="text-embedding-005")
+
+print(text_embedder.run(text_to_embed))
+## {'embedding': [-0.08127457648515701, 0.03399784862995148, -0.05116401985287666, ...]
+```
+
+### In a pipeline
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.google_vertex import VertexAITextEmbedder
+from haystack_integrations.components.embedders.google_vertex import VertexAIDocumentEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities")]
+
+document_embedder = VertexAIDocumentEmbedder(model="text-embedding-005")
+documents_with_embeddings = document_embedder.run(documents)['documents']
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", VertexAITextEmbedder(model="text-embedding-005"))
+query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "Who lives in Berlin?"
+
+result = query_pipeline.run({"text_embedder":{"text": query}})
+
+print(result['retriever']['documents'][0])
+
+## Document(id=..., content: 'My name is Wolfgang and I live in Berlin')
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/watsonxdocumentembedder.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/watsonxdocumentembedder.mdx
new file mode 100644
index 0000000000..6d62eb843a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/watsonxdocumentembedder.mdx
@@ -0,0 +1,133 @@
+---
+title: "WatsonxDocumentEmbedder"
+id: watsonxdocumentembedder
+slug: "/watsonxdocumentembedder"
+description: "The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant documents."
+---
+
+# WatsonxDocumentEmbedder
+
+The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector that represents the query is compared with those of the documents to find the most similar or relevant documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `api_key`: The IBM Cloud API key. Can be set with `WATSONX_API_KEY` env var.
`project_id`: The IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `documents`: A list of documents to be embedded | +| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata strings | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | + +
+
+## Overview
+
+`WatsonxDocumentEmbedder` enriches the metadata of documents with an embedding of their content. To embed a string, you should use the [`WatsonxTextEmbedder`](watsonxtextembedder.mdx).
+
+The component supports IBM watsonx.ai embedding models such as `ibm/slate-30m-english-rtrvr` and similar. The default model is `ibm/slate-30m-english-rtrvr`. This list of all supported models can be found in IBM's [model documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-embed.html?context=wx).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install watsonx-haystack
+```
+
+The component uses `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` environment variables by default. Otherwise, you can pass API credentials at initialization with `api_key` and `project_id`:
+
+```python
+embedder = WatsonxDocumentEmbedder(
+ api_key=Secret.from_token("`project_id`: The IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `documents`: A list of documents to be embedded | +| **Output variables** | `documents`: A list of documents (enriched with embeddings)
`meta`: A dictionary of metadata strings | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before an embedding [Retriever](../retrievers.mdx) in a query/RAG pipeline |
+| **Mandatory init variables** | `api_key`: An IBM Cloud API key. Can be set with `WATSONX_API_KEY` env var.
`project_id`: An IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | + +
+
+## Overview
+
+To see the list of compatible IBM watsonx.ai embedding models, head over to IBM [documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-embed.html?context=wx). The default model for `WatsonxTextEmbedder` is `ibm/slate-30m-english-rtrvr`. You can specify another model with the `model` parameter when initializing this component.
+
+Use `WatsonxTextEmbedder` to embed a simple string (such as a query) into a vector. For embedding lists of documents, use the [`WatsonxDocumentEmbedder`](watsonxdocumentembedder.mdx), which enriches the document with the computed embedding, also known as vector.
+
+The component uses `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` environment variables by default. Otherwise, you can pass API credentials at initialization with `api_key` and `project_id`:
+
+```python
+embedder = WatsonxTextEmbedder(
+ api_key=Secret.from_token("`project_id`: An IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `text`: A string | +| **Output variables** | `embedding`: A list of float numbers
`meta`: A dictionary of metadata | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `ground_truth_answers`: A list of strings containing the ground truth answers
`predicted_answers`: A list of strings containing the predicted answers to be evaluated | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 representing the proportion of questions in which any predicted answer matched the ground truth answers
- `individual_scores`: A list of 0s and 1s, where 1 means that the predicted answer matched one of the ground truths | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/answer_exact_match.py | + +
+
+## Overview
+
+You can use the `AnswerExactMatchEvaluator` component to evaluate answers predicted by a Haystack pipeline, such as an extractive question answering pipeline, against ground truth labels. As the `AnswerExactMatchEvaluator` checks whether a predicted answer exactly matches the ground truth answer. It is not suited to evaluate answers generated by LLMs, for example, in a RAG pipeline. Use `FaithfulnessEvaluator` or `SASEvaluator` instead.
+
+To initialize an `AnswerExactMatchEvaluator`, there are no parameters required.
+
+Note that only _one_ predicted answer is compared to _one_ ground truth answer at a time. The component does not support multiple ground truth answers for the same question or multiple answers predicted for the same question.
+
+## Usage
+
+### On its own
+
+Below is an example of using an `AnswerExactMatchEvaluator` component to evaluate two answers and compare them to ground truth answers.
+
+```python
+from haystack.components.evaluators import AnswerExactMatchEvaluator
+
+evaluator = AnswerExactMatchEvaluator()
+result = evaluator.run(
+ ground_truth_answers=["Berlin", "Paris"],
+ predicted_answers=["Berlin", "Lyon"],
+)
+
+print(result["individual_scores"])
+## [1, 0]
+print(result["score"])
+## 0.5
+```
+
+### In a pipeline
+
+Below is an example where we use an `AnswerExactMatchEvaluator` and a `SASEvaluator` in a pipeline to evaluate two answers and compare them to ground truth answers. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Pipeline
+from haystack.components.evaluators import AnswerExactMatchEvaluator
+from haystack.components.evaluators import SASEvaluator
+
+pipeline = Pipeline()
+em_evaluator = AnswerExactMatchEvaluator()
+sas_evaluator = SASEvaluator()
+pipeline.add_component("em_evaluator", em_evaluator)
+pipeline.add_component("sas_evaluator", sas_evaluator)
+
+ground_truth_answers = ["Berlin", "Paris"]
+predicted_answers = ["Berlin", "Lyon"]
+
+result = pipeline.run(
+ {
+ "em_evaluator": {"ground_truth_answers": ground_truth_answers,
+ "predicted_answers": predicted_answers},
+ "sas_evaluator": {"ground_truth_answers": ground_truth_answers,
+ "predicted_answers": predicted_answers}
+ }
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1, 0]
+## [array([[0.99999994]], dtype=float32), array([[0.51747656]], dtype=float32)]
+
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 0.5
+## 0.7587383
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/contextrelevanceevaluator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/contextrelevanceevaluator.mdx
new file mode 100644
index 0000000000..7595337ebd
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/contextrelevanceevaluator.mdx
@@ -0,0 +1,122 @@
+---
+title: "ContextRelevanceEvaluator"
+id: contextrelevanceevaluator
+slug: "/contextrelevanceevaluator"
+description: "The `ContextRelevanceEvaluator` uses an LLM to evaluate whether contexts are relevant to a question. It does not require ground truth labels."
+---
+
+# ContextRelevanceEvaluator
+
+The `ContextRelevanceEvaluator` uses an LLM to evaluate whether contexts are relevant to a question. It does not require ground truth labels.
+
+`predicted_answers`: A list of strings containing the predicted answers to be evaluated | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 representing the proportion of questions in which any predicted answer matched the ground truth answers
- `individual_scores`: A list of 0s and 1s, where 1 means that the predicted answer matched one of the ground truths | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/answer_exact_match.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `questions`: A list of questions
`contexts`: A list of a list of contexts, which are the contents of documents. This accounts for one list of contexts per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean average precision
- `individual_scores`: A list of the individual average precision scores ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents
- `results`: A list of dictionaries with keys `statements` and `statement_scores`. They contain the statements extracted by an LLM from each context and the corresponding context relevance scores per statement, which are either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/context_relevance.py | + +
+
+## Overview
+
+You can use the `ContextRelevanceEvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG pipeline, without ground truth labels. The component breaks up the context into multiple statements and checks whether each statement is relevant for answering a question. The final score for the context relevance is a number from 0.0 to 1.0 and represents the proportion of statements that are relevant to the provided question.
+
+### Parameters
+
+The default model for this Evaluator is `gpt-4o-mini`. You can override the model using the `chat_generator` parameter during initialization. This needs to be a Chat Generator instance configured to return a JSON object. For example, when using the [`OpenAIChatGenerator`](../generators/openaichatgenerator.mdx), you should pass `{"response_format": {"type": "json_object"}}` in its `generation_kwargs`.
+
+If you are not initializing the Evaluator with your own Chat Generator other than OpenAI, a valid OpenAI API key must be set as an `OPENAI_API_KEY` environment variable. For details, see our [documentation page on secret management](../../concepts/secret-management.mdx).
+
+Two optional initialization parameters are:
+
+- `raise_on_failure`: If True, raise an exception on an unsuccessful API call.
+- `progress_bar`: Whether to show a progress bar during the evaluation.
+
+`ContextRelevanceEvaluator` has an optional `examples` parameter that can be used to pass few-shot examples conforming to the expected input and output format of `ContextRelevanceEvaluator`. These examples are included in the prompt that is sent to the LLM. Examples, therefore, increase the number of tokens of the prompt and make each request more costly. Adding examples is helpful if you want to improve the quality of the evaluation at the cost of more tokens.
+
+Each example must be a dictionary with keys `inputs` and `outputs`.
+`inputs` must be a dictionary with keys `questions` and `contexts`.
+`outputs` must be a dictionary with `statements` and `statement_scores`.
+Here is the expected format:
+
+```python
+[{
+ "inputs": {
+ "questions": "What is the capital of Italy?", "contexts": ["Rome is the capital of Italy."],
+ },
+ "outputs": {
+ "statements": ["Rome is the capital of Italy.", "Rome has more than 4 million inhabitants."],
+ "statement_scores": [1, 0],
+ },
+}]
+```
+
+## Usage
+
+### On its own
+
+Below is an example where we use a `ContextRelevanceEvaluator` component to evaluate a response generated based on a provided question and context. The `ContextRelevanceEvaluator` returns a score of 1.0 because it detects one statement in the context, which is relevant to the question.
+
+```python
+from haystack.components.evaluators import ContextRelevanceEvaluator
+
+questions = ["Who created the Python language?"]
+contexts = [
+ [
+ "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language. Its design philosophy emphasizes code readability, and its language constructs aim to help programmers write clear, logical code for both small and large-scale software projects."
+ ],
+]
+
+evaluator = ContextRelevanceEvaluator()
+result = evaluator.run(questions=questions, contexts=contexts)
+print(result["score"])
+## 1.0
+print(result["individual_scores"])
+## [1.0]
+print(result["results"])
+## [{'statements': ['Python, created by Guido van Rossum in the late 1980s.'], 'statement_scores': [1], 'score': 1.0}]
+
+```
+
+### In a pipeline
+
+Below is an example where we use a `FaithfulnessEvaluator` and a `ContextRelevanceEvaluator` in a pipeline to evaluate responses and contexts (the content of documents) received by a RAG pipeline based on provided questions. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Pipeline
+from haystack.components.evaluators import ContextRelevanceEvaluator, FaithfulnessEvaluator
+
+pipeline = Pipeline()
+context_relevance_evaluator = ContextRelevanceEvaluator()
+faithfulness_evaluator = FaithfulnessEvaluator()
+pipeline.add_component("context_relevance_evaluator", context_relevance_evaluator)
+pipeline.add_component("faithfulness_evaluator", faithfulness_evaluator)
+
+questions = ["Who created the Python language?"]
+contexts = [
+ [
+ "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language. Its design philosophy emphasizes code readability, and its language constructs aim to help programmers write clear, logical code for both small and large-scale software projects."
+ ],
+]
+responses = ["Python is a high-level general-purpose programming language that was created by George Lucas."]
+
+result = pipeline.run(
+ {
+ "context_relevance_evaluator": {"questions": questions, "contexts": contexts},
+ "faithfulness_evaluator": {"questions": questions, "contexts": contexts, "responses": responses}
+ }
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1.0]
+## [0.5]
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 1.0
+## 0.5
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/deepevalevaluator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/deepevalevaluator.mdx
new file mode 100644
index 0000000000..443de5ac4c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/deepevalevaluator.mdx
@@ -0,0 +1,92 @@
+---
+title: "DeepEvalEvaluator"
+id: deepevalevaluator
+slug: "/deepevalevaluator"
+description: "The DeepEvalEvaluator evaluates Haystack pipelines using LLM-based metrics. It supports metrics like answer relevancy, faithfulness, contextual relevance, and more."
+---
+
+# DeepEvalEvaluator
+
+The DeepEvalEvaluator evaluates Haystack pipelines using LLM-based metrics. It supports metrics like answer relevancy, faithfulness, contextual relevance, and more.
+
+`contexts`: A list of a list of contexts, which are the contents of documents. This accounts for one list of contexts per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean average precision
- `individual_scores`: A list of the individual average precision scores ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents
- `results`: A list of dictionaries with keys `statements` and `statement_scores`. They contain the statements extracted by an LLM from each context and the corresponding context relevance scores per statement, which are either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/context_relevance.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `metric`: One of the DeepEval metrics to use for evaluation |
+| **Mandatory run variables** | `**inputs`: A keyword arguments dictionary containing the expected inputs. The expected inputs will change based on the metric you are evaluating. See below for more details. |
+| **Output variables** | `results`: A nested list of metric results. There can be one or more results, depending on the metric. Each result is a dictionary containing:
- `name` - The name of the metric
- `score` - The score of the metric
- `explanation` - An optional explanation of the score | +| **API reference** | [DeepEval](/reference/integrations-deepeval) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/deepeval | + +
+
+DeepEval is an evaluation framework that provides a number of LLM-based evaluation metrics. You can use the `DeepEvalEvaluator` component to evaluate a Haystack pipeline, such as a retrieval-augmented generated pipeline, against one of the metrics provided by DeepEval.
+
+## Supported Metrics
+
+DeepEval supports a number of metrics, which we expose through the [DeepEval metric enumeration.](/reference/integrations-deepeval#deepevalmetric) [`DeepEvalEvaluator`](/reference/integrations-deepeval#deepevalevaluator) in Haystack supports the metrics listed below with the expected `metric_params` while initializing the Evaluator. Many metrics use OpenAI models and require you to set an environment variable `OPENAI_API_KEY`. For a complete guide on these metrics, visit the [DeepEval documentation](https://docs.confident-ai.com/docs/getting-started).
+
+- `name` - The name of the metric
- `score` - The score of the metric
- `explanation` - An optional explanation of the score | +| **API reference** | [DeepEval](/reference/integrations-deepeval) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/deepeval | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `metric`: One of the DeepEval metrics to use for evaluation |
+| **Mandatory run variables** | “\*\*inputs”: A keyword arguments dictionary containing the expected inputs. The expected inputs will change based on the metric you are evaluating. See below for more details. |
+| **Output variables** | `results`: A nested list of metric results. There can be one or more results, depending on the metric. Each result is a dictionary containing:
- `name` - The name of the metric
- `score` - The score of the metric
- `explanation` - An optional explanation of the score | +| **API reference** | [DeepEval](/reference/integrations-deepeval) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/deepeval | + +
+
+## Parameters Overview
+
+To initialize a `DeepEvalEvaluator`, you need to provide the following parameters :
+
+- `metric`: A `DeepEvalMetric`.
+- `metric_params`: Optionally, if the metric calls for any additional parameters, you should provide them here.
+
+## Usage
+
+To use the `DeepEvalEvaluator`, you first need to install the integration:
+
+```bash
+pip install deepeval-haystack
+```
+
+To use the `DeepEvalEvaluator` you need to follow these steps:
+
+1. Initialize the `DeepEvalEvaluator` while providing the correct `metric_params` for the metric you are using.
+2. Run the `DeepEvalEvaluator` on its own or in a pipeline by providing the expected input for the metric you are using.
+
+### Examples
+
+**Evaluate Faithfulness**
+
+To create a faithfulness evaluation pipeline:
+
+```python
+from haystack import Pipeline
+from haystack_integrations.components.evaluators.deepeval import DeepEvalEvaluator, DeepEvalMetric
+
+pipeline = Pipeline()
+evaluator = DeepEvalEvaluator(
+ metric=DeepEvalMetric.FAITHFULNESS,
+ metric_params={"model": "gpt-4"},
+)
+pipeline.add_component("evaluator", evaluator)
+```
+
+To run the evaluation pipeline, you should have the _expected inputs_ for the metric ready at hand. This metric expects a list of `questions` and `contexts`. These should come from the results of the pipeline you want to evaluate.
+
+```python
+results = pipeline.run({"evaluator": {"questions": ["When was the Rhodes Statue built?", "Where is the Pyramid of Giza?"],
+ "contexts": [["Context for question 1"], ["Context for question 2"]],
+ "responses": ["Response for question 1", "response for question 2"]}})
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [RAG Pipeline Evaluation Using DeepEval](https://haystack.deepset.ai/cookbook/rag_eval_deep_eval)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentmapevaluator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentmapevaluator.mdx
new file mode 100644
index 0000000000..d94acdb8bd
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentmapevaluator.mdx
@@ -0,0 +1,97 @@
+---
+title: "DocumentMAPEvaluator"
+id: documentmapevaluator
+slug: "/documentmapevaluator"
+description: "The `DocumentMAPEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks to what extent the list of retrieved documents contains only relevant documents as specified in the ground truth labels or also non-relevant documents. This metric is called mean average precision (MAP)."
+---
+
+# DocumentMAPEvaluator
+
+The `DocumentMAPEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks to what extent the list of retrieved documents contains only relevant documents as specified in the ground truth labels or also non-relevant documents. This metric is called mean average precision (MAP).
+
+- `name` - The name of the metric
- `score` - The score of the metric
- `explanation` - An optional explanation of the score | +| **API reference** | [DeepEval](/reference/integrations-deepeval) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/deepeval | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `ground_truth_documents`: A list of a list of ground truth documents. This accounts for one list of ground truth documents per question.
`retrieved_documents`: A list of a list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean average precision
- `individual_scores`: A list of the individual average precision scores ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_map.py | + +
+
+## Overview
+
+You can use the `DocumentMAPEvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG pipeline, against ground truth labels. A higher mean average precision is better, indicating that the list of retrieved documents contains many relevant documents and only a few non-relevant documents or none at all.
+
+To initialize a `DocumentMAPEvaluator`, there are no parameters required.
+
+## Usage
+
+### On its own
+
+Below is an example where we use a `DocumentMAPEvaluator` component to evaluate documents retrieved for two queries. For the first query, there is one ground truth document and one retrieved document. For the second query, there are two ground truth documents and three retrieved documents.
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentMAPEvaluator
+
+evaluator = DocumentMAPEvaluator()
+result = evaluator.run(
+ ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+ ],
+ retrieved_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="10th century"), Document(content="9th")],
+ ],
+)
+print(result["individual_scores"])
+## [1.0, 0.8333333333333333]
+print(result["score"])
+## 0.9166666666666666
+```
+
+### In a pipeline
+
+Below is an example where we use a `DocumentMAPEvaluator` and a `DocumentMRREvaluator` in a pipeline to evaluate two answers and compare them to ground truth answers. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.evaluators import DocumentMRREvaluator, DocumentMAPEvaluator
+
+pipeline = Pipeline()
+mrr_evaluator = DocumentMRREvaluator()
+map_evaluator = DocumentMAPEvaluator()
+pipeline.add_component("mrr_evaluator", mrr_evaluator)
+pipeline.add_component("map_evaluator", map_evaluator)
+
+ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+]
+retrieved_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="10th century"), Document(content="9th")],
+]
+
+result = pipeline.run(
+ {
+ "mrr_evaluator": {"ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents},
+ "map_evaluator": {"ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents}
+ }
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1.0, 1.0]
+## [1.0, 0.8333333333333333]
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 1.0
+## 0.9166666666666666
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentmrrevaluator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentmrrevaluator.mdx
new file mode 100644
index 0000000000..e1a0459c95
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentmrrevaluator.mdx
@@ -0,0 +1,97 @@
+---
+title: "DocumentMRREvaluator"
+id: documentmrrevaluator
+slug: "/documentmrrevaluator"
+description: "The `DocumentMRREvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks at what rank ground truth documents appear in the list of retrieved documents. This metric is called mean reciprocal rank (MRR)."
+---
+
+# DocumentMRREvaluator
+
+The `DocumentMRREvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks at what rank ground truth documents appear in the list of retrieved documents. This metric is called mean reciprocal rank (MRR).
+
+`retrieved_documents`: A list of a list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean average precision
- `individual_scores`: A list of the individual average precision scores ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_map.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `ground_truth_documents`: A list containing another list of ground truth documents. This accounts for one list of ground truth documents per question.
`retrieved_documents`: A list containing another list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean reciprocal rank
- `individual_scores`: A list of the individual reciprocal ranks ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_mrr.py | + +
+
+## Overview
+
+You can use the `DocumentMRREvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG pipeline, against ground truth labels. A higher mean reciprocal rank is better and indicates that relevant documents appear at an earlier position in the list of retrieved documents.
+
+To initialize a `DocumentMRREvaluator`, there are no parameters required.
+
+## Usage
+
+### On its own
+
+Below is an example where we use a `DocumentMRREvaluator` component to evaluate documents retrieved for two queries. For the first query, there is one ground truth document and one retrieved document. For the second query, there are two ground truth documents and three retrieved documents.
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentMRREvaluator
+
+evaluator = DocumentMRREvaluator()
+result = evaluator.run(
+ ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+ ],
+ retrieved_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="10th century"), Document(content="9th")],
+ ],
+)
+print(result["individual_scores"])
+## [1.0, 1.0]
+print(result["score"])
+## 1.0
+```
+
+### In a pipeline
+
+Below is an example where we use a `DocumentRecallEvaluator` and a `DocumentMRREvaluator` in a pipeline to evaluate two answers and compare them to ground truth answers. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.evaluators import DocumentMRREvaluator, DocumentRecallEvaluator
+
+pipeline = Pipeline()
+mrr_evaluator = DocumentMRREvaluator()
+recall_evaluator = DocumentRecallEvaluator()
+pipeline.add_component("mrr_evaluator", mrr_evaluator)
+pipeline.add_component("recall_evaluator", recall_evaluator)
+
+ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+]
+retrieved_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="10th century"), Document(content="9th")],
+]
+
+result = pipeline.run(
+ {
+ "mrr_evaluator": {"ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents},
+ "recall_evaluator": {"ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents}
+ }
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1.0, 1.0]
+## [1.0, 1.0]
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 1.0
+## 1.0
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentndcgevaluator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentndcgevaluator.mdx
new file mode 100644
index 0000000000..4884321151
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentndcgevaluator.mdx
@@ -0,0 +1,83 @@
+---
+title: "DocumentNDCGEvaluator"
+id: documentndcgevaluator
+slug: "/documentndcgevaluator"
+description: "The `DocumentNDCGEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks at what rank ground truth documents appear in the list of retrieved documents. This metric is called normalized discounted cumulative gain (NDCG)."
+---
+
+# DocumentNDCGEvaluator
+
+The `DocumentNDCGEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks at what rank ground truth documents appear in the list of retrieved documents. This metric is called normalized discounted cumulative gain (NDCG).
+
+`retrieved_documents`: A list containing another list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean reciprocal rank
- `individual_scores`: A list of the individual reciprocal ranks ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_mrr.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `ground_truth_documents`: A list containing another list of ground truth documents, one list per question
`retrieved_documents`: A list containing another list of retrieved documents, one list per question | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the NDCG
- `individual_scores`: A list of individual NDCG values ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_ndcg.py | + +
+
+## Overview
+
+You can use the `DocumentNDCGEvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG pipeline, against ground truth labels. A higher NDCG is better and indicates that relevant documents appear at an earlier position in the list of retrieved documents.
+
+If the ground truth documents have scores, a higher NDCG indicates that documents with a higher score appear at an earlier position in the list of retrieved documents. If the ground truth documents have no scores, binary relevance is assumed, meaning that all ground truth documents are equally relevant, and the order in which they are in the list of retrieved documents does not matter for the NDCG.
+
+No parameters are required to initialize a `DocumentNDCGEvaluator`.
+
+## Usage
+
+### On its own
+
+Below is an example where we use the `DocumentNDCGEvaluator` to evaluate documents retrieved for a query. There are two ground truth documents and three retrieved documents. All ground truth documents are retrieved, but one non-relevant document is ranked higher than one of the ground truth documents, which lowers the NDCG score.
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentNDCGEvaluator
+
+evaluator = DocumentNDCGEvaluator()
+result = evaluator.run(
+ ground_truth_documents=[[Document(content="France", score=1.0), Document(content="Paris", score=0.5)]],
+ retrieved_documents=[[Document(content="France"), Document(content="Germany"), Document(content="Paris")]],
+)
+print(result["individual_scores"])
+## [0.8869]
+print(result["score"])
+## 0.8869
+```
+
+### In a pipeline
+
+Below is an example of using a `DocumentNDCGEvaluator` and `DocumentMRREvaluator` in a pipeline to evaluate retrieved documents and compare them to ground truth documents. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.evaluators import DocumentMRREvaluator, DocumentNDCGEvaluator
+
+pipeline = Pipeline()
+pipeline.add_component("ndcg_evaluator", DocumentNDCGEvaluator())
+pipeline.add_component("mrr_evaluator", DocumentMRREvaluator())
+
+ground_truth_documents=[[Document(content="France", score=1.0), Document(content="Paris", score=0.5)]]
+retrieved_documents=[[Document(content="France"), Document(content="Germany"), Document(content="Paris")]]
+
+result = pipeline.run({
+ "ndcg_evaluator": {
+ "ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents
+ },
+ "mrr_evaluator": {
+ "ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents
+ },
+})
+
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 0.9502
+## 1.0
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentrecallevaluator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentrecallevaluator.mdx
new file mode 100644
index 0000000000..c0cbeb8e38
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentrecallevaluator.mdx
@@ -0,0 +1,102 @@
+---
+title: "DocumentRecallEvaluator"
+id: documentrecallevaluator
+slug: "/documentrecallevaluator"
+description: "The `DocumentRecallEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks how many of the ground truth documents were retrieved. This metric is called recall."
+---
+
+# DocumentRecallEvaluator
+
+The `DocumentRecallEvaluator` evaluates documents retrieved by Haystack pipelines using ground truth labels. It checks how many of the ground truth documents were retrieved. This metric is called recall.
+
+`retrieved_documents`: A list containing another list of retrieved documents, one list per question | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the NDCG
- `individual_scores`: A list of individual NDCG values ranging from 0.0 to 1.0 for each input pair of a list of retrieved documents and a list of ground truth documents | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_ndcg.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `ground_truth_documents`: A list of a list of ground truth documents. This accounts for one list of ground truth documents per question.
`retrieved_documents`: A list of a list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean recall score over all inputs
- `individual_scores`: A list of the individual recall scores ranging from 0.0 to 1.0 of each input pair of a list of retrieved documents and a list of ground truth documents. If the mode is set to single_hit, each individual score is either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_recall.py | + +
+
+## Overview
+
+You can use the `DocumentRecallEvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG Pipeline, against ground truth labels.
+
+When initializing a `DocumentRecallEvaluator`, you can set the `mode` parameter to
+`RecallMode.SINGLE_HIT` or `RecallMode.MULTI_HIT`. By default, `RecallMode.SINGLE_HIT` is used.
+
+`RecallMode.SINGLE_HIT` means that _any_ of the ground truth documents need to be retrieved to count as a correct retrieval with a recall score of 1. A single retrieved document can achieve the full score.
+
+`RecallMode.MULTI_HIT` means that _all_ of the ground truth documents need to be retrieved to count as a correct retrieval with a recall score of 1. The number of retrieved documents must be at least the number of ground truth documents to achieve the full score.
+
+## Usage
+
+### On its own
+
+Below is an example where we use a `DocumentRecallEvaluator` component to evaluate documents retrieved for two queries. For the first query, there is one ground truth document and one retrieved document. For the second query, there are two ground truth documents and three retrieved documents.
+
+```python
+from haystack import Document
+from haystack.components.evaluators import DocumentRecallEvaluator
+
+evaluator = DocumentRecallEvaluator()
+result = evaluator.run(
+ ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+ ],
+ retrieved_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="10th century"), Document(content="9th")],
+ ],
+)
+print(result["individual_scores"])
+## [1.0, 1.0]
+print(result["score"])
+## 1.0
+```
+
+### In a pipeline
+
+Below is an example where we use a `DocumentRecallEvaluator` and a `DocumentMRREvaluator` in a pipeline to evaluate two answers and compare them to ground truth answers. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.evaluators import DocumentMRREvaluator, DocumentRecallEvaluator
+
+pipeline = Pipeline()
+mrr_evaluator = DocumentMRREvaluator()
+recall_evaluator = DocumentRecallEvaluator()
+pipeline.add_component("mrr_evaluator", mrr_evaluator)
+pipeline.add_component("recall_evaluator", recall_evaluator)
+
+ground_truth_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="9th")],
+]
+retrieved_documents=[
+ [Document(content="France")],
+ [Document(content="9th century"), Document(content="10th century"), Document(content="9th")],
+]
+
+result = pipeline.run(
+ {
+ "mrr_evaluator": {"ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents},
+ "recall_evaluator": {"ground_truth_documents": ground_truth_documents,
+ "retrieved_documents": retrieved_documents}
+ }
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1.0, 1.0]
+## [1.0, 1.0]
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 1.0
+## 1.0
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/external-integrations-evaluators.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/external-integrations-evaluators.mdx
new file mode 100644
index 0000000000..105613e9fb
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/external-integrations-evaluators.mdx
@@ -0,0 +1,11 @@
+---
+title: "External Integrations"
+id: external-integrations-evaluators
+slug: "/external-integrations-evaluators"
+---
+
+# External Integrations
+
+| Name | Description |
+| --- | --- |
+| [Flow Judge](https://haystack.deepset.ai/integrations/flow-judge) | Evaluate Haystack pipelines using Flow Judge model. |
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/faithfulnessevaluator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/faithfulnessevaluator.mdx
new file mode 100644
index 0000000000..e38305f285
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/faithfulnessevaluator.mdx
@@ -0,0 +1,122 @@
+---
+title: "FaithfulnessEvaluator"
+id: faithfulnessevaluator
+slug: "/faithfulnessevaluator"
+description: "The `FaithfulnessEvaluator` uses an LLM to evaluate whether a generated answer can be inferred from the provided contexts. It does not require ground truth labels. This metric is called faithfulness, sometimes also referred to as groundedness or hallucination."
+---
+
+# FaithfulnessEvaluator
+
+The `FaithfulnessEvaluator` uses an LLM to evaluate whether a generated answer can be inferred from the provided contexts. It does not require ground truth labels. This metric is called faithfulness, sometimes also referred to as groundedness or hallucination.
+
+`retrieved_documents`: A list of a list of retrieved documents. This accounts for one list of retrieved documents per question. | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 that represents the mean recall score over all inputs
- `individual_scores`: A list of the individual recall scores ranging from 0.0 to 1.0 of each input pair of a list of retrieved documents and a list of ground truth documents. If the mode is set to single_hit, each individual score is either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/document_recall.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory run variables** | `questions`: A list of questions
`contexts`: A list of a list of contexts, which are the contents of documents. This accounts for one list of contexts per question.
`predicted_answers`: A list of predicted answers, for example, the outputs of a Generator in a RAG pipeline | +| **Output variables** | A dictionary containing:
- `score`: A number from 0.0 to 1.0 that represents the average faithfulness score across all questions
- `individual_scores`: A list of the individual faithfulness scores ranging from 0.0 to 1.0 for each input triple of a question, a list of contexts, and a predicted answer.
- `results`: A list of dictionaries with `statements` and `statement_scores` keys. They contain the statements extracted by an LLM from each predicted answer and the corresponding faithfulness scores per statement, which are either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/faithfulness.py | + +
+
+You can use the `FaithfulnessEvaluator` component to evaluate documents retrieved by a Haystack pipeline, such as a RAG pipeline, without ground truth labels. The component splits the generated answer into statements and checks each of them against the provided contexts with an LLM. A higher faithfulness score is better, and it indicates that a larger number of statements in the generated answers can be inferred from the contexts. The faithfulness score can be used to better understand how often and when the Generator in a RAG pipeline hallucinates.
+
+### Parameters
+
+The default model for this Evaluator is `gpt-4o-mini`. You can override the model using the `chat_generator` parameter during initialization. This needs to be a Chat Generator instance configured to return a JSON object. For example, when using the [`OpenAIChatGenerator`](../generators/openaichatgenerator.mdx), you should pass `{"response_format": {"type": "json_object"}}` in its `generation_kwargs`.
+
+If you are not initializing the Evaluator with your own Chat Generator other than OpenAI, a valid OpenAI API key must be set as an `OPENAI_API_KEY` environment variable. For details, see our [documentation page on secret management](../../concepts/secret-management.mdx).
+
+Two other optional initialization parameters are:
+
+- `raise_on_failure`: If True, raise an exception on an unsuccessful API call.
+- `progress_bar`: Whether to show a progress bar during the evaluation.
+
+`FaithfulnessEvaluator` has an optional `examples` parameter that can be used to pass few-shot examples conforming to the expected input and output format of `FaithfulnessEvaluator`. These examples are included in the prompt that is sent to the LLM. Examples, therefore, increase the number of tokens of the prompt and make each request more costly. Adding examples is helpful if you want to improve the quality of the evaluation at the cost of more tokens.
+
+Each example must be a dictionary with keys `inputs` and `outputs`.
+`inputs` must be a dictionary with keys `questions`, `contexts`, and `predicted_answers`.
+`outputs` must be a dictionary with `statements` and `statement_scores`.
+Here is the expected format:
+
+```python
+[{
+ "inputs": {
+ "questions": "What is the capital of Italy?", "contexts": ["Rome is the capital of Italy."],
+ "predicted_answers": "Rome is the capital of Italy with more than 4 million inhabitants.",
+ },
+ "outputs": {
+ "statements": ["Rome is the capital of Italy.", "Rome has more than 4 million inhabitants."],
+ "statement_scores": [1, 0],
+ },
+}]
+```
+
+## Usage
+
+### On its own
+
+Below is an example of using a `FaithfulnessEvaluator` component to evaluate a predicted answer generated based on a provided question and context. The `FaithfulnessEvaluator` returns a score of 0.5 because it detects two statements in the answer, of which only one is correct.
+
+```python
+from haystack.components.evaluators import FaithfulnessEvaluator
+
+questions = ["Who created the Python language?"]
+contexts = [
+ [
+ "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language. Its design philosophy emphasizes code readability, and its language constructs aim to help programmers write clear, logical code for both small and large-scale software projects."
+ ],
+]
+predicted_answers = ["Python is a high-level general-purpose programming language that was created by George Lucas."]
+evaluator = FaithfulnessEvaluator()
+result = evaluator.run(questions=questions, contexts=contexts, predicted_answers=predicted_answers)
+
+print(result["individual_scores"])
+## [0.5]
+print(result["score"])
+## 0.5
+print(result["results"])
+## [{'statements': ['Python is a high-level general-purpose programming language.',
+## 'Python was created by George Lucas.'], 'statement_scores': [1, 0], 'score': 0.5}]
+```
+
+### In a pipeline
+
+Below is an example where we use a `FaithfulnessEvaluator` and a `ContextRelevanceEvaluator` in a pipeline to evaluate predicted answers and contexts (the content of documents) received by a RAG pipeline based on provided questions. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Pipeline
+from haystack.components.evaluators import ContextRelevanceEvaluator, FaithfulnessEvaluator
+
+pipeline = Pipeline()
+context_relevance_evaluator = ContextRelevanceEvaluator()
+faithfulness_evaluator = FaithfulnessEvaluator()
+pipeline.add_component("context_relevance_evaluator", context_relevance_evaluator)
+pipeline.add_component("faithfulness_evaluator", faithfulness_evaluator)
+
+questions = ["Who created the Python language?"]
+contexts = [
+ [
+ "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language. Its design philosophy emphasizes code readability, and its language constructs aim to help programmers write clear, logical code for both small and large-scale software projects."
+ ],
+]
+predicted_answers = ["Python is a high-level general-purpose programming language that was created by George Lucas."]
+
+result = pipeline.run(
+ {
+ "context_relevance_evaluator": {"questions": questions, "contexts": contexts},
+ "faithfulness_evaluator": {"questions": questions, "contexts": contexts, "predicted_answers": predicted_answers}
+ }
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## ...
+## [0.5]
+for evaluator in result:
+ print(result[evaluator]["score"])
+##
+## 0.5
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/llmevaluator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/llmevaluator.mdx
new file mode 100644
index 0000000000..959c976559
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/llmevaluator.mdx
@@ -0,0 +1,125 @@
+---
+title: "LLMEvaluator"
+id: llmevaluator
+slug: "/llmevaluator"
+description: "This Evaluator uses an LLM to evaluate inputs based on a prompt containing user-defined instructions and examples."
+---
+
+# LLMEvaluator
+
+This Evaluator uses an LLM to evaluate inputs based on a prompt containing user-defined instructions and examples.
+
+`contexts`: A list of a list of contexts, which are the contents of documents. This accounts for one list of contexts per question.
`predicted_answers`: A list of predicted answers, for example, the outputs of a Generator in a RAG pipeline | +| **Output variables** | A dictionary containing:
- `score`: A number from 0.0 to 1.0 that represents the average faithfulness score across all questions
- `individual_scores`: A list of the individual faithfulness scores ranging from 0.0 to 1.0 for each input triple of a question, a list of contexts, and a predicted answer.
- `results`: A list of dictionaries with `statements` and `statement_scores` keys. They contain the statements extracted by an LLM from each predicted answer and the corresponding faithfulness scores per statement, which are either 0 or 1. | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/faithfulness.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `instructions`: The prompt instructions string
`inputs`: The expected inputs
`outputs`: The output names of the evaluation results
`examples`: Few-shot examples conforming to the input and output format | +| **Mandatory run variables** | `inputs`: Defined by the user – for example, questions or responses | +| **Output variables** | `results`: A dictionary containing keys defined by the user, such as score | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/llm_evaluator.py | + +
+
+## Overview
+
+The `LLMEvaluator` component can evaluate answers, documents, or any other outputs of a Haystack pipeline based on a user-defined aspect. The component combines the instructions, examples, and expected output names into one prompt. It is meant for calculating user-defined model-based evaluation metrics. If you are looking for pre-defined model-based evaluators that work out of the box, have a look at Haystack’s [`FaithfulnessEvaluator`](faithfulnessevaluator.mdx) and [`ContextRelevanceEvaluator`](contextrelevanceevaluator.mdx) components instead.
+
+### Parameters
+
+The default model for this Evaluator is `gpt-4o-mini`. You can override the model using the `chat_generator` parameter during initialization. This needs to be a Chat Generator instance configured to return a JSON object. For example, when using the [`OpenAIChatGenerator`](../generators/openaichatgenerator.mdx), you should pass `{"response_format": {"type": "json_object"}}` in its `generation_kwargs`.
+
+If you are not initializing the Evaluator with your own Chat Generator other than OpenAI, a valid OpenAI API key must be set as an `OPENAI_API_KEY` environment variable. For details, see our [documentation page on secret management](../../concepts/secret-management.mdx).
+
+`LLMEvaluator` requires six parameters for initialization:
+
+- `instructions`: The prompt instructions to use for evaluation, such as a question about the inputs that the LLM can answer with _yes,_ _no_, or a score.
+- `inputs`: The inputs that the `LLMEvaluator` expects and that it evaluates. The inputs determine the incoming connections of the component. Each input is a tuple of an input name and input type. Input types must be lists. An example could be `[("responses", List[str])]`.
+- `outputs`: Output names of the evaluation results corresponding to keys in the output dictionary. An example could be a `["score"]`.
+- `examples`: Use this parameter to pass few-shot examples conforming to the expected input and output format. These examples are included in the prompt that is sent to the LLM. Examples increase the number of tokens of the prompt and make each request more costly. Adding more than one or two examples can be helpful if you want to improve the quality of the evaluation at the cost of more tokens.
+- `raise_on_failure`: If True (default), raise an exception on an unsuccessful API call.
+- `progress_bar`: Whether to show a progress bar during the evaluation. None is the default.
+
+Each example must be a dictionary with keys `inputs` and `outputs`.
+`inputs` must be a dictionary with keys `questions` and `contexts`.
+`outputs` must be a dictionary with `statements` and `statement_scores`.
+
+Here is the expected format:
+
+```python
+[{
+ "inputs": {
+ "questions": "What is the capital of Italy?", "contexts": ["Rome is the capital of Italy."],
+ },
+ "outputs": {
+ "statements": ["Rome is the capital of Italy.", "Rome has more than 4 million inhabitants."],
+ "statement_scores": [1, 0],
+ },
+}]
+```
+
+## Usage
+
+### On its own
+
+Below is an example where we use an `LLMEvaluator` component to evaluate a generated response. The aspect we evaluate is whether the response is problematic for children as defined in the instructions. The `LLMEvaluator` returns one binary score per input response with the result that both responses are not problematic.
+
+```python
+from typing import List
+from haystack.components.evaluators import LLMEvaluator
+llm_evaluator = LLMEvaluator(
+ instructions="Is this answer problematic for children?",
+ inputs=[("responses", List[str])],
+ outputs=["score"],
+ examples=[
+ {"inputs": {"responses": "Damn, this is straight outta hell!!!"}, "outputs": {"score": 1}},
+ {"inputs": {"responses": "Football is the most popular sport."}, "outputs": {"score": 0}},
+ ],
+)
+responses = [
+ "Football is the most popular sport with around 4 billion followers worldwide",
+ "Python language was created by Guido van Rossum.",
+]
+results = llm_evaluator.run(responses=responses)
+print(results)
+## {'results': [{'score': 0}, {'score': 0}]}
+```
+
+### In a pipeline
+
+Below is an example where we use an `LLMEvaluator` in a pipeline to evaluate a response.
+
+```python
+from typing import List
+from haystack import Pipeline
+from haystack.components.evaluators import LLMEvaluator
+
+pipeline = Pipeline()
+llm_evaluator = LLMEvaluator(
+ instructions="Is this answer problematic for children?",
+ inputs=[("responses", List[str])],
+ outputs=["score"],
+ examples=[
+ {"inputs": {"responses": "Damn, this is straight outta hell!!!"}, "outputs": {"score": 1}},
+ {"inputs": {"responses": "Football is the most popular sport."}, "outputs": {"score": 0}},
+ ],
+)
+
+pipeline.add_component("llm_evaluator", llm_evaluator)
+
+responses = [
+ "Football is the most popular sport with around 4 billion followers worldwide",
+ "Python language was created by Guido van Rossum.",
+]
+
+result = pipeline.run(
+ {
+ "llm_evaluator": {"responses": responses}
+ }
+)
+
+for evaluator in result:
+ print(result[evaluator]["results"])
+## [{'score': 0}, {'score': 0}]
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/ragasevaluator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/ragasevaluator.mdx
new file mode 100644
index 0000000000..6efe493345
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/ragasevaluator.mdx
@@ -0,0 +1,124 @@
+---
+title: "RagasEvaluator"
+id: ragasevaluator
+slug: "/ragasevaluator"
+description: "This component evaluates Haystack pipelines using LLM-based metrics. It supports metrics like context relevance, factual accuracy, response relevance, and more."
+---
+
+# RagasEvaluator
+
+This component evaluates Haystack pipelines using LLM-based metrics. It supports metrics like context relevance, factual accuracy, response relevance, and more.
+
+`inputs`: The expected inputs
`outputs`: The output names of the evaluation results
`examples`: Few-shot examples conforming to the input and output format | +| **Mandatory run variables** | `inputs`: Defined by the user – for example, questions or responses | +| **Output variables** | `results`: A dictionary containing keys defined by the user, such as score | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/llm_evaluator.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `metric`: A Ragas metric to use for evaluation |
+| **Mandatory run variables** | `inputs`: A keyword arguments dictionary containing the expected inputs. The expected inputs will change based on the metric you are evaluating. See below for more details. |
+| **Output variables** | `results`: A nested list of metric results. There can be one or more results, depending on the metric. Each result is a dictionary containing:
- `name` - The name of the metric.
- `score` - The score of the metric. | +| **API reference** | [Ragas](/reference/integrations-ragas) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ragas | + +
+
+Ragas is an evaluation framework that provides a number of LLM-based evaluation metrics. You can use the `RagasEvaluator` component to evaluate a Haystack pipeline, such as a retrieval-augmented generative pipeline, against one of the metrics provided by Ragas.
+
+## Supported Metrics
+
+Ragas supports a number of metrics, which we expose through the Ragas metric enumeration. Below is the list of metrics supported by the `RagasEvaluator` in Haystack with the expected `metric_params` while initializing the evaluator. Many metrics use OpenAI models and require an environment variable `OPENAI_API_KEY` to be set. For a complete guide on these metrics, visit the [Ragas documentation](https://docs.ragas.io/).
+
+- `name` - The name of the metric.
- `score` - The score of the metric. | +| **API reference** | [Ragas](/reference/integrations-ragas) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ragas | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `metric`: A Ragas metric to use for evaluation |
+| **Mandatory run variables** | `inputs`: A keyword arguments dictionary containing the expected inputs. The expected inputs will change based on the metric you are evaluating. See below for more details. |
+| **Output variables** | `results`: A nested list of metric results. There can be one or more results, depending on the metric. Each result is a dictionary containing:
- `name` - The name of the metric.
- `score` - The score of the metric. | +| **API reference** | [Ragas](/reference/integrations-ragas) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ragas | + +
+
+## Parameters Overview
+
+To initialize a `RagasEvaluator`, you need to provide the following parameters :
+
+- `metric`: A `RagasMetric`.
+- `metric_params`: Optionally, if the metric calls for any additional parameters, you should provide them here.
+
+## Usage
+
+To use the `RagasEvaluator`, you first need to install the integration:
+
+```bash
+pip install ragas-haystack
+```
+
+To use the `RagasEvaluator` you need to follow these steps:
+
+1. Initialize the `RagasEvaluator` while providing the correct `metric_params` for the metric you are using.
+2. Run the `RagasEvaluator`, either on its own or in a pipeline, by providing the expected input for the metric you are using.
+
+### Examples
+
+#### Evaluate Context Relevance
+
+To create a context-relevance evaluation pipeline:
+
+```python
+from haystack import Pipeline
+from haystack_integrations.components.evaluators.ragas import RagasEvaluator, RagasMetric
+
+pipeline = Pipeline()
+evaluator = RagasEvaluator(
+ metric=RagasMetric.ANSWER_RELEVANCY,
+)
+pipeline.add_component("evaluator", evaluator)
+```
+
+To run the evaluation pipeline, you should have the _expected inputs_ for the metric ready at hand. This metric expects a list of `questions` and `contexts`, which should come from the results of the pipeline you want to evaluate.
+
+```python
+results = pipeline.run({"evaluator": {"questions": ["When was the Rhodes Statue built?", "Where is the Pyramid of Giza?"],
+ "contexts": [["Context for question 1"], ["Context for question 2"]]}})
+```
+
+#### Evaluate Context Relevance and Aspect Critique
+
+To create a pipeline that evaluates context relevance and aspect critique:
+
+```python
+from haystack import Pipeline
+from haystack_integrations.components.evaluators.ragas import RagasEvaluator, RagasMetric
+
+pipeline = Pipeline()
+evaluator_context = RagasEvaluator(
+ metric=RagasMetric.CONTEXT_PRECISION,
+)
+evaluator_aspect = RagasEvaluator(
+ metric=RagasMetric.ASPECT_CRITIQUE,
+ metric_params={"name": "custom", "definition": "Is this answer problematic for children?", "strictness": 3},
+)
+pipeline.add_component("evaluator_context", evaluator_context)
+pipeline.add_component("evaluator_aspect", evaluator_aspect)
+```
+
+To run the evaluation pipeline, you should have the _expected inputs_ for the metrics ready at hand. These metrics expect a list of `questions`, `contexts`, `responses`, and `ground_truths`. These should come from the results of the pipeline you want to evaluate.
+
+```python
+QUESTIONS = ["Which is the most popular global sport?", "Who created the Python language?"]
+CONTEXTS = [["The popularity of sports can be measured in various ways, including TV viewership, social media presence, number of participants, and economic impact. Football is undoubtedly the world's most popular sport with major events like the FIFA World Cup and sports personalities like Ronaldo and Messi, drawing a followership of more than 4 billion people."],
+ ["Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language. Its design philosophy emphasizes code readability, and its language constructs aim to help programmers write clear, logical code for both small and large-scale software projects."]]
+RESPONSES = ["Football is the most popular sport with around 4 billion followers worldwide", "Python language was created by Guido van Rossum."]
+GROUND_TRUTHS = ["Football is the most popular sport", "Python language was created by Guido van Rossum."]
+results = pipeline.run({
+ "evaluator_context": {"questions": QUESTIONS, "contexts": CONTEXTS, "ground_truths": GROUND_TRUTHS},
+ "evaluator_aspect": {"questions": QUESTIONS, "contexts": CONTEXTS, "responses": RESPONSES},
+})
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Evaluate a RAG pipeline using Ragas integration](https://haystack.deepset.ai/cookbook/rag_eval_ragas)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/sasevaluator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/sasevaluator.mdx
new file mode 100644
index 0000000000..b3132c132e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/sasevaluator.mdx
@@ -0,0 +1,93 @@
+---
+title: "SASEvaluator"
+id: sasevaluator
+slug: "/sasevaluator"
+description: "The `SASEvaluator` evaluates answers predicted by Haystack pipelines using ground truth labels. It checks the semantic similarity of a predicted answer and the ground truth answer using a fine-tuned language model. This metric is called semantic answer similarity."
+---
+
+# SASEvaluator
+
+The `SASEvaluator` evaluates answers predicted by Haystack pipelines using ground truth labels. It checks the semantic similarity of a predicted answer and the ground truth answer using a fine-tuned language model. This metric is called semantic answer similarity.
+
+- `name` - The name of the metric.
- `score` - The score of the metric. | +| **API reference** | [Ragas](/reference/integrations-ragas) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ragas | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | On its own or in an evaluation pipeline. To be used after a separate pipeline that has generated the inputs for the Evaluator. |
+| **Mandatory init variables** | `token`: A HF API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `ground_truth_answers`: A list of strings containing the ground truth answers
`predicted_answers`: A list of strings containing the predicted answers to be evaluated | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 representing the mean SAS score for all pairs of predicted answers and ground truth answers
- `individual_scores`: A list of the SAS scores ranging from 0.0 to 1.0 of all pairs of predicted answers and ground truth answers | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/sas_evaluator.py | + +
+
+## Overview
+
+You can use the `SASEvaluator` component to evaluate answers predicted by a Haystack pipeline, such as a RAG pipeline, against ground truth labels.
+
+You can provide a bi-encoder or cross-encoder model to initialize a `SASEvaluator`. By default, `sentence-transformers/paraphrase-multilingual-mpnet-base-v2` model is used.
+
+Note that only _one_ predicted answer is compared to _one_ ground truth answer at a time. The component does not support multiple ground truth answers for the same question or multiple answers predicted for the same question.
+
+## Usage
+
+### On its own
+
+Below is an example of using a `SASEvaluator` component to evaluate two answers and compare them to ground truth answers. We need to call `warm_up()` before `run()` to load the model.
+
+```python
+from haystack.components.evaluators import SASEvaluator
+
+sas_evaluator = SASEvaluator()
+sas_evaluator.warm_up()
+result = sas_evaluator.run(
+ ground_truth_answers=["Berlin", "Paris"],
+ predicted_answers=["Berlin", "Lyon"]
+)
+print(result["individual_scores"])
+## [[array([[0.99999994]], dtype=float32), array([[0.51747656]], dtype=float32)]
+print(result["score"])
+## 0.7587383
+```
+
+### In a pipeline
+
+Below is an example where we use an `AnswerExactMatchEvaluator` and a `SASEvaluator` in a pipeline to evaluate two answers and compare them to ground truth answers. Running a pipeline instead of the individual components simplifies calculating more than one metric.
+
+```python
+from haystack import Pipeline
+from haystack.components.evaluators import AnswerExactMatchEvaluator, SASEvaluator
+
+pipeline = Pipeline()
+em_evaluator = AnswerExactMatchEvaluator()
+sas_evaluator = SASEvaluator()
+pipeline.add_component("em_evaluator", em_evaluator)
+pipeline.add_component("sas_evaluator", sas_evaluator)
+
+ground_truth_answers = ["Berlin", "Paris"]
+predicted_answers = ["Berlin", "Lyon"]
+
+result = pipeline.run(
+ {
+ "em_evaluator": {"ground_truth_answers": ground_truth_answers,
+ "predicted_answers": predicted_answers},
+ "sas_evaluator": {"ground_truth_answers": ground_truth_answers,
+ "predicted_answers": predicted_answers}
+ }
+)
+
+for evaluator in result:
+ print(result[evaluator]["individual_scores"])
+## [1, 0]
+## [array([[0.99999994]], dtype=float32), array([[0.51747656]], dtype=float32)]
+
+for evaluator in result:
+ print(result[evaluator]["score"])
+## 0.5
+## 0.7587383
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Prompt Optimization with DSPy](https://haystack.deepset.ai/cookbook/prompt_optimization_with_dspy)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors.mdx
new file mode 100644
index 0000000000..c5ae8c05fd
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors.mdx
@@ -0,0 +1,13 @@
+---
+title: "Extractors"
+id: extractors
+slug: "/extractors"
+---
+
+# Extractors
+
+| Name | Description |
+| --- | --- |
+| [LLMDocumentContentExtractor](extractors/llmdocumentcontentextractor.mdx) | Extracts textual content from image-based documents using a vision-enabled Large Language Model (LLM). |
+| [LLMMetadataExtractor](extractors/llmmetadataextractor.mdx) | Extracts metadata from documents using a Large Language Model. The metadata is extracted by providing a prompt to a LLM that generates it. |
+| [NamedEntityExtractor](extractors/namedentityextractor.mdx) | Extracts predefined entities out of a piece of text and writes them into documents’ meta field. |
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors/llmdocumentcontentextractor.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors/llmdocumentcontentextractor.mdx
new file mode 100644
index 0000000000..051261d9a5
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors/llmdocumentcontentextractor.mdx
@@ -0,0 +1,181 @@
+---
+title: "LLMDocumentContentExtractor"
+id: llmdocumentcontentextractor
+slug: "/llmdocumentcontentextractor"
+description: "Extracts textual content from image-based documents using a vision-enabled Large Language Model (LLM)."
+---
+
+# LLMDocumentContentExtractor
+
+Extracts textual content from image-based documents using a vision-enabled Large Language Model (LLM).
+
+`predicted_answers`: A list of strings containing the predicted answers to be evaluated | +| **Output variables** | A dictionary containing:
\- `score`: A number from 0.0 to 1.0 representing the mean SAS score for all pairs of predicted answers and ground truth answers
- `individual_scores`: A list of the SAS scores ranging from 0.0 to 1.0 of all pairs of predicted answers and ground truth answers | +| **API reference** | [Evaluators](/reference/evaluators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/evaluators/sas_evaluator.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After [Converters](../converters.mdx) in an indexing pipeline to extract text from image-based documents |
+| **Mandatory init variables** | `chat_generator`: A ChatGenerator instance that supports vision-based input
`prompt`: Instructional text for the LLM on how to extract content (no Jinja variables allowed) | +| **Mandatory run variables** | `documents`: A list of documents with file paths in metadata | +| **Output variables** | `documents`: Successfully processed documents with extracted content
`failed_documents`: Documents that failed processing with error metadata | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/image/llm_document_content_extractor.py | + +
+
+## Overview
+
+`LLMDocumentContentExtractor` extracts textual content from image-based documents using a vision-enabled Large Language Model (LLM). This component is particularly useful for processing scanned documents, images containing text, or PDF pages that need to be converted to searchable text.
+
+The component works by:
+
+1. Converting each input document into an image using the `DocumentToImageContent` component,
+2. Using a predefined prompt to instruct the LLM on how to extract content,
+3. Processing the image through a vision-capable ChatGenerator to extract structured textual content.
+
+The prompt must not contain Jinja variables; it should only include instructions for the LLM. Image data and the prompt are passed together to the LLM as a Chat Message.
+
+Documents for which the LLM fails to extract content are returned in a separate `failed_documents` list with a `content_extraction_error` entry in their metadata for debugging or reprocessing.
+
+## Usage
+
+### On its own
+
+Below is an example that uses the `LLMDocumentContentExtractor` to extract text from image-based documents:
+
+```python
+from haystack import Document
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+
+## Initialize the chat generator with vision capabilities
+chat_generator = OpenAIChatGenerator(
+ model="gpt-4o-mini",
+ generation_kwargs={"temperature": 0.0}
+)
+
+## Create the extractor
+extractor = LLMDocumentContentExtractor(
+ chat_generator=chat_generator,
+ file_path_meta_field="file_path",
+ raise_on_failure=False
+)
+
+## Create documents with image file paths
+documents = [
+ Document(content="", meta={"file_path": "image.jpg"}),
+ Document(content="", meta={"file_path": "document.pdf", "page_number": 1}),
+]
+
+## Run the extractor
+result = extractor.run(documents=documents)
+
+## Check results
+print(f"Successfully processed: {len(result['documents'])}")
+print(f"Failed documents: {len(result['failed_documents'])}")
+
+## Access extracted content
+for doc in result["documents"]:
+ print(f"File: {doc.meta['file_path']}")
+ print(f"Extracted content: {doc.content[:100]}...")
+```
+
+### Using custom prompts
+
+You can provide a custom prompt to instruct the LLM on how to extract content:
+
+```python
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+custom_prompt = """
+Extract all text content from this image-based document.
+
+Instructions:
+- Extract text exactly as it appears
+- Preserve the reading order
+- Format tables as markdown
+- Describe any images or diagrams briefly
+- Maintain document structure
+
+Document:"""
+
+chat_generator = OpenAIChatGenerator(model="gpt-4o-mini")
+extractor = LLMDocumentContentExtractor(
+ chat_generator=chat_generator,
+ prompt=custom_prompt,
+ file_path_meta_field="file_path"
+)
+
+documents = [Document(content="", meta={"file_path": "scanned_document.pdf"})]
+result = extractor.run(documents=documents)
+```
+
+### Handling failed documents
+
+The component provides detailed error information for failed documents:
+
+```python
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+chat_generator = OpenAIChatGenerator(model="gpt-4o-mini")
+extractor = LLMDocumentContentExtractor(
+ chat_generator=chat_generator,
+ raise_on_failure=False # Don't raise exceptions, return failed documents
+)
+
+documents = [Document(content="", meta={"file_path": "problematic_image.jpg"})]
+result = extractor.run(documents=documents)
+
+## Check for failed documents
+for failed_doc in result["failed_documents"]:
+ print(f"Failed to process: {failed_doc.meta['file_path']}")
+ print(f"Error: {failed_doc.meta['content_extraction_error']}")
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that uses `LLMDocumentContentExtractor` to process image-based documents and store the extracted text:
+
+```python
+from haystack import Pipeline
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.dataclasses import Document
+
+## Create document store
+document_store = InMemoryDocumentStore()
+
+## Create pipeline
+p = Pipeline()
+p.add_component(instance=LLMDocumentContentExtractor(
+ chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+ file_path_meta_field="file_path"
+), name="content_extractor")
+p.add_component(instance=DocumentSplitter(), name="splitter")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+
+## Connect components
+p.connect("content_extractor.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+## Create test documents
+docs = [
+ Document(content="", meta={"file_path": "scanned_document.pdf"}),
+ Document(content="", meta={"file_path": "image_with_text.jpg"}),
+]
+
+## Run pipeline
+result = p.run({"content_extractor": {"documents": docs}})
+
+## Check results
+print(f"Successfully processed: {len(result['content_extractor']['documents'])}")
+print(f"Failed documents: {len(result['content_extractor']['failed_documents'])}")
+
+## Access documents in the store
+stored_docs = document_store.filter_documents()
+print(f"Documents in store: {len(stored_docs)}")
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors/llmmetadataextractor.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors/llmmetadataextractor.mdx
new file mode 100644
index 0000000000..7fbdba073c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors/llmmetadataextractor.mdx
@@ -0,0 +1,147 @@
+---
+title: "LLMMetadataExtractor"
+id: llmmetadataextractor
+slug: "/llmmetadataextractor"
+description: "Extracts metadata from documents using a Large Language Model. The metadata is extracted by providing a prompt to a LLM that generates it."
+---
+
+# LLMMetadataExtractor
+
+Extracts metadata from documents using a Large Language Model. The metadata is extracted by providing a prompt to a LLM that generates it.
+
+`prompt`: Instructional text for the LLM on how to extract content (no Jinja variables allowed) | +| **Mandatory run variables** | `documents`: A list of documents with file paths in metadata | +| **Output variables** | `documents`: Successfully processed documents with extracted content
`failed_documents`: Documents that failed processing with error metadata | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/image/llm_document_content_extractor.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After [PreProcessors](../preprocessors.mdx) in an indexing pipeline |
+| **Mandatory init variables** | `prompt`: The prompt to instruct the LLM on how to extract metadata from the document
`chat_generator`: A Chat Generator instance which represents the LLM configured to return a JSON object | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/llm_metadata_extractor.py | + +
+
+## Overview
+
+The `LLMMetadataExtractor` extraction relies on an LLM and a prompt to perform the metadata extraction. At initialization time, it expects an LLM, a Haystack Generator, and a prompt describing the metadata extraction process.
+
+The prompt should have a variable called `document` that will point to a single document in the list of documents. So, to access the content of the document, you can use `{{ document.content }}` in the prompt.
+
+At runtime, it expects a list of documents and will run the LLM on each document in the list, extracting metadata from the document. The metadata will be added to the document's metadata field.
+
+If the LLM fails to extract metadata from a document, it will be added to the `failed_documents` list. The failed documents' metadata will contain the keys `metadata_extraction_error` and `metadata_extraction_response`.
+
+These documents can be re-run with another extractor to extract metadata using the `metadata_extraction_response` and `metadata_extraction_error` in the prompt.
+
+The current implementation supports the following Haystack Generators:
+
+- [OpenAIChatGenerator](../generators/openaichatgenerator.mdx)
+- [AzureOpenAIChatGenerator](../generators/azureopenaichatgenerator.mdx)
+- [AmazonBedrockChatGenerator](../generators/amazonbedrockchatgenerator.mdx)
+- [VertexAIGeminiChatGenerator](../generators/vertexaigeminichatgenerator.mdx)
+
+## Usage
+
+Here's an example of using the `LLMMetadataExtractor` to extract named entities and add them to the document's metadata.
+
+First, the mandatory imports:
+
+```python
+from haystack import Document
+from haystack.components.extractors.llm_metadata_extractor import LLMMetadataExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+```
+
+Then, define some documents:
+
+```python
+docs = [
+ Document(content="deepset was founded in 2018 in Berlin, and is known for its Haystack framework"),
+ Document(content="Hugging Face is a company founded in New York, USA and is known for its Transformers library"
+ )
+]
+
+```
+
+And now, a prompt that extracts named entities from the documents:
+
+```python
+NER_PROMPT = '''
+ -Goal-
+ Given text and a list of entity types, identify all entities of those types from the text.
+
+ -Steps-
+ 1. Identify all entities. For each identified entity, extract the following information:
+ - entity_name: Name of the entity, capitalized
+ - entity_type: One of the following types: [organization, product, service, industry]
+ Format each entity as a JSON like: {"entity": `chat_generator`: A Chat Generator instance which represents the LLM configured to return a JSON object | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/llm_metadata_extractor.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After the [PreProcessor](../preprocessors.mdx) in an indexing pipeline or after a [Retriever](../retrievers.mdx) in a query pipeline |
+| **Mandatory init variables** | `backend`: The backend to use for NER
`model`: Name or path of the model to use | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/named_entity_extractor.py | + +
+
+## Overview
+
+`NamedEntityExtractor` looks for entities, which are spans in the text. The extractor automatically recognizes and groups them depending on their class, such as people's names, organizations, locations, and other types. The exact classes are determined by the model that you initialize the component with.
+
+`NamedEntityExtractor` takes a list of documents as input and returns a list of the same documents with their `meta` data enriched with `NamedEntityAnnotations`. A `NamedEntityAnnotation` consists of the type of the entity, the start and end of the span, and a score calculated by the model, for example: `NamedEntityAnnotation(entity='PER', start=11, end=16, score=0.9)`.
+
+When the `NamedEntityExtractor` is initialized, you need to set a `model` and a `backend`. The latter can be either `"hugging_face"` or `"spacy"`. Optionally, you can set `pipeline_kwargs`, which are then passed on to the Hugging Face pipeline or the spaCy pipeline. You can additionally set the `device` that is used to run the component.
+
+## Usage
+
+The current implementation supports two NER backends: Hugging Face and spaCy. These two backends work with any HF or spaCy model that supports token classification or NER.
+
+Here’s an example of how you could initialize different backends:
+
+```python
+## Initialize with HF backend
+extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
+
+## Initialize with spaCy backend
+extractor = NamedEntityExtractor(backend="spacy", model="en_core_web_sm")
+```
+
+`NamedEntityExtractor` accepts a list of `Documents` as its input. The extractor annotates the raw text in the documents and stores the annotations in the document's `meta` dictionary under the `named_entities` key.
+
+```python
+from haystack.dataclasses import Document
+from haystack.components.extractors import NamedEntityExtractor
+
+extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
+
+documents = [Document(content="My name is Clara and I live in Berkeley, California."),
+ Document(content="I'm Merlin, the happy pig!"),
+ Document(content="New York State is home to the Empire State Building.")]
+
+extractor.warm_up()
+extractor.run(documents)
+print(documents)
+```
+
+Here is the example result:
+
+```python
+[Document(id=aec840d1b6c85609f4f16c3e222a5a25fd8c4c53bd981a40c1268ab9c72cee10, content: 'My name is Clara and I live in Berkeley, California.', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=11, end=16, score=0.99641764), NamedEntityAnnotation(entity='LOC', start=31, end=39, score=0.996198), NamedEntityAnnotation(entity='LOC', start=41, end=51, score=0.9990196)]}),
+Document(id=98f1dc5d0ccd9d9950cd191d1076db0f7af40c401dd7608f11c90cb3fc38c0c2, content: 'I'm Merlin, the happy pig!', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=4, end=10, score=0.99054915)]}),
+Document(id=44948ea0eec018b33aceaaedde4616eb9e93ce075e0090ec1613fc145f84b4a9, content: 'New York State is home to the Empire State Building.', meta: {'named_entities': [NamedEntityAnnotation(entity='LOC', start=0, end=14, score=0.9989541), NamedEntityAnnotation(entity='LOC', start=30, end=51, score=0.95746297)]})]
+```
+
+### Get stored annotations
+
+This component includes the `get_stored_annotations` helper class method that allows you to retrieve the annotations stored in a `Document` transparently:
+
+```python
+from haystack.dataclasses import Document
+from haystack.components.extractors import NamedEntityExtractor
+
+extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
+
+documents = [Document(content="My name is Clara and I live in Berkeley, California."),
+ Document(content="I'm Merlin, the happy pig!"),
+ Document(content="New York State is home to the Empire State Building.")]
+
+extractor.warm_up()
+extractor.run(documents)
+
+annotations = [NamedEntityExtractor.get_stored_annotations(doc) for doc in documents]
+print(annotations)
+
+## If a Document doesn't contain any annotations, this returns None.
+new_doc = Document(content="In one of many possible worlds...")
+assert NamedEntityExtractor.get_stored_annotations(new_doc) is None
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers.mdx
new file mode 100644
index 0000000000..e06b360a15
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers.mdx
@@ -0,0 +1,14 @@
+---
+title: "Fetchers"
+id: fetchers
+slug: "/fetchers"
+description: "Currently, there's one Fetcher in Haystack: LinkContentFetcher. It fetches the contents of the URLs you give it."
+---
+
+# Fetchers
+
+Currently, there's one Fetcher in Haystack: LinkContentFetcher. It fetches the contents of the URLs you give it.
+
+| Component | Description |
+| --- | --- |
+| [LinkContentFetcher](fetchers/linkcontentfetcher.mdx) | Fetches the contents of the URLs you give it so you can use them as data for your pipelines. |
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers/external-integrations-fetchers.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers/external-integrations-fetchers.mdx
new file mode 100644
index 0000000000..b066ce7920
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers/external-integrations-fetchers.mdx
@@ -0,0 +1,16 @@
+---
+title: "External Integrations"
+id: external-integrations-fetchers
+slug: "/external-integrations-fetchers"
+description: "External integrations that enable data extraction from different sources."
+---
+
+# External Integrations
+
+External integrations that enable data extraction from different sources.
+
+| Name | Description |
+| --- | --- |
+| [Apify](https://haystack.deepset.ai/integrations/apify) | Extract data from e-commerce websites, social media platforms (such as Facebook, Instagram, and TikTok), search engines, online maps, and more, while automating web tasks. |
+| [Mastodon](https://haystack.deepset.ai/integrations/mastodon-fetcher) | Fetch a Mastodon username's latest posts. |
+| [Notion](https://haystack.deepset.ai/integrations/notion-extractor) | Extract pages from Notion to Haystack Documents. |
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers/linkcontentfetcher.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers/linkcontentfetcher.mdx
new file mode 100644
index 0000000000..b94d9e0087
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers/linkcontentfetcher.mdx
@@ -0,0 +1,75 @@
+---
+title: "LinkContentFetcher"
+id: linkcontentfetcher
+slug: "/linkcontentfetcher"
+description: "With LinkContentFetcher, you can use the contents of several URLs as the data for your pipeline. You can use it in indexing and query pipelines to fetch the contents of the URLs you give it."
+---
+
+# LinkContentFetcher
+
+With LinkContentFetcher, you can use the contents of several URLs as the data for your pipeline. You can use it in indexing and query pipelines to fetch the contents of the URLs you give it.
+
+`model`: Name or path of the model to use | +| **Mandatory run variables** | `documents`: A list of documents | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Extractors](/reference/extractors-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/named_entity_extractor.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing or query pipelines as the data fetching step |
+| **Mandatory run variables** | `urls`: A list of URLs (strings) |
+| **Output variables** | `streams`: A list of [`ByteStream`](../../concepts/data-classes.mdx#bytestream) objects |
+| **API reference** | [Fetchers](/reference/fetchers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/fetchers/link_content.py |
+
+
+
+## Overview
+
+`LinkContentFetcher` fetches the contents of the `urls` you give it and returns a list of content streams. Each item in this list is the content of one link it successfully fetched in the form of a `ByteStream` object. Each of these objects in the returned list has metadata that contains its content type (in the `content_type` key) and its URL (in the `url` key).
+
+For example, if you pass ten URLs to `LinkContentFetcher` and it manages to fetch six of them, then the output will be a list of six `ByteStream` objects, each containing information about its content type and URL.
+
+It may happen that some sites block `LinkContentFetcher` from getting their content. In that case, it logs the error and returns the `ByteStream` objects that it successfully fetched.
+
+Often, to use this component in a pipeline, you must convert the returned list of `ByteStream` objects into a list of `Document` objects. To do so, you can use the `HTMLToDocument` component.
+
+You can use `LinkContentFetcher` at the beginning of an indexing pipeline to index the contents of URLs into a Document Store. You can also use it directly in a query pipeline, such as a retrieval-augmented generative (RAG) pipeline, to use the contents of a URL as the data source.
+
+## Usage
+
+### On its own
+
+Below is an example where `LinkContentFetcher` fetches the contents of a URL. It initializes the component using the default settings. To change the default component settings, such as `retry_attempts`, check out the API reference [docs](/reference/fetchers-api).
+
+```python
+from haystack.components.fetchers import LinkContentFetcher
+
+fetcher = LinkContentFetcher()
+
+fetcher.run(urls=["https://haystack.deepset.ai"])
+```
+
+### In a pipeline
+
+Below is an example of an indexing pipeline that uses the `LinkContentFetcher` to index the contents of the specified URLs into an `InMemoryDocumentStore`. Notice how it uses the `HTMLToDocument` component to convert the list of `ByteStream` objects to `Document` objects.
+
+```python
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.fetchers import LinkContentFetcher
+from haystack.components.converters import HTMLToDocument
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+fetcher = LinkContentFetcher()
+converter = HTMLToDocument()
+writer = DocumentWriter(document_store = document_store)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(instance=fetcher, name="fetcher")
+indexing_pipeline.add_component(instance=converter, name="converter")
+indexing_pipeline.add_component(instance=writer, name="writer")
+
+indexing_pipeline.connect("fetcher.streams", "converter.sources")
+indexing_pipeline.connect("converter.documents", "writer.documents")
+
+indexing_pipeline.run(data={"fetcher": {"urls": ["https://haystack.deepset.ai/blog/guide-to-using-zephyr-with-haystack2"]}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators.mdx
new file mode 100644
index 0000000000..d22d3e1341
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators.mdx
@@ -0,0 +1,56 @@
+---
+title: "Generators"
+id: generators
+slug: "/generators"
+description: "Generators are responsible for generating text after you give them a prompt. They are specific for each LLM technology (OpenAI, local, TGI and others)."
+---
+
+# Generators
+
+Generators are responsible for generating text after you give them a prompt. They are specific for each LLM technology (OpenAI, local, TGI and others).
+
+| Generator | Description | Streaming Support |
+| --- | --- | --- |
+| [AmazonBedrockChatGenerator](generators/amazonbedrockchatgenerator.mdx) | Enables chat completion using models through Amazon Bedrock service. | ✅ |
+| [AmazonBedrockGenerator](generators/amazonbedrockgenerator.mdx) | Enables text generation using models through Amazon Bedrock service. | ✅ |
+| [AnthropicChatGenerator](generators/anthropicchatgenerator.mdx) | This component enables chat completions using Anthropic large language models (LLMs). | ✅ |
+| [AnthropicVertexChatGenerator](generators/anthropicvertexchatgenerator.mdx) | This component enables chat completions using AnthropicVertex API. | ✅ |
+| [AnthropicGenerator](generators/anthropicgenerator.mdx) | This component enables text completions using Anthropic large language models (LLMs). | ✅ |
+| [AzureOpenAIChatGenerator](generators/azureopenaichatgenerator.mdx) | Enables chat completion using OpenAI’s LLMs through Azure services. | ✅ |
+| [AzureOpenAIGenerator](generators/azureopenaigenerator.mdx) | Enables text generation using OpenAI’s LLMs through Azure services. | ✅ |
+| [CohereChatGenerator](generators/coherechatgenerator.mdx) | Enables chat completion using Cohere's LLMs. | ✅ |
+| [CohereGenerator](generators/coheregenerator.mdx) | Queries the LLM using Cohere API. | ✅ |
+| [DALLEImageGenerator](generators/dalleimagegenerator.mdx) | Generate images using OpenAI's DALL-E model. | ❌ |
+| [FallbackChatGenerator](generators/fallbackchatgenerator.mdx) | A ChatGenerator wrapper that tries multiple Chat Generators sequentially until one succeeds. | ✅ |
+| [GoogleAIGeminiChatGenerator](generators/googleaigeminichatgenerator.mdx) | Enables chat completion using Google Gemini models. **_This integration will be deprecated soon. We recommend using [GoogleGenAIChatGenerator](generators/googlegenaichatgenerator.mdx) integration instead._** | ✅ |
+| [GoogleAIGeminiGenerator](generators/googleaigeminigenerator.mdx) | Enables text generation using Google Gemini models. **_This integration will be deprecated soon. We recommend using [GoogleGenAIChatGenerator](generators/googlegenaichatgenerator.mdx) integration instead._** | ✅ |
+| [GoogleGenAIChatGenerator](generators/googlegenaichatgenerator.mdx) | Enables chat completion using Google Gemini models through Google Gen AI SDK. | ✅ |
+| [HuggingFaceAPIChatGenerator](generators/huggingfaceapichatgenerator.mdx) | Enables chat completion using various Hugging Face APIs. | ✅ |
+| [HuggingFaceAPIGenerator](generators/huggingfaceapigenerator.mdx) | Enables text generation using various Hugging Face APIs. | ✅ |
+| [HuggingFaceLocalChatGenerator](generators/huggingfacelocalchatgenerator.mdx) | Provides an interface for chat completion using a Hugging Face model that runs locally. | ✅ |
+| [HuggingFaceLocalGenerator](generators/huggingfacelocalgenerator.mdx) | Provides an interface to generate text using a Hugging Face model that runs locally. | ✅ |
+| [LlamaCppChatGenerator](generators/llamacppchatgenerator.mdx) | Enables chat completion using an LLM running on Llama.cpp. | ❌ |
+| [LlamaCppGenerator](generators/llamacppgenerator.mdx) | Generate text using an LLM running with Llama.cpp. | ❌ |
+| [LlamaStackChatGenerator](generators/llamastackchatgenerator.mdx) | Enables chat completions using an LLM model made available via Llama Stack server | ✅ |
+| [MetaLlamaChatGenerator](generators/metallamachatgenerator.mdx) | Enables chat completion with any model hosted available with Meta Llama API. | ✅ |
+| [MistralChatGenerator](generators/mistralchatgenerator.mdx) | Enables chat completion using Mistral’s text generation models. | ✅ |
+| [NvidiaChatGenerator](generators/nvidiachatgenerator.mdx) | Enables chat completion using Nvidia-hosted models. | ✅ |
+| [NvidiaGenerator](generators/nvidiagenerator.mdx) | Provides an interface for generating text using LLMs self-hosted with NVIDIA NIM or models hosted on the NVIDIA API catalog. | ❌ |
+| [OllamaChatGenerator](generators/ollamachatgenerator.mdx) | Enables chat completion using an LLM running on Ollama. | ✅ |
+| [OllamaGenerator](generators/ollamagenerator.mdx) | Provides an interface to generate text using an LLM running on Ollama. | ✅ |
+| [OpenAIChatGenerator](generators/openaichatgenerator.mdx) | Enables chat completion using OpenAI’s large language models (LLMs). | ✅ |
+| [OpenAIGenerator](generators/openaigenerator.mdx) | Enables text generation using OpenAI's large language models (LLMs). | ✅ |
+| [OpenRouterChatGenerator](generators/openrouterchatgenerator.mdx) | Enables chat completion with any model hosted on OpenRouter. | ✅ |
+| [SagemakerGenerator](generators/sagemakergenerator.mdx) | Enables text generation using LLMs deployed on Amazon Sagemaker. | ❌ |
+| [STACKITChatGenerator](generators/stackitchatgenerator.mdx) | Enables chat completions using the STACKIT API. | ✅ |
+| [TogetherAIChatGenerator](generators/togetheraichatgenerator.mdx) | Enables chat completion using models hosted on Together AI. | ✅ |
+| [TogetherAIGenerator](generators/togetheraigenerator.mdx) | Enables text generation using models hosted on Together AI. | ✅ |
+| [VertexAICodeGenerator](generators/vertexaicodegenerator.mdx) | Enables code generation using Google Vertex AI generative model. | ❌ |
+| [VertexAIGeminiChatGenerator](generators/vertexaigeminichatgenerator.mdx) | Enables chat completion using Google Gemini models with GCP Vertex AI. **_This integration will be deprecated soon. We recommend using [GoogleGenAIChatGenerator](generators/googlegenaichatgenerator.mdx) integration instead._** | ✅ |
+| [VertexAIGeminiGenerator](generators/vertexaigeminigenerator.mdx) | Enables text generation using Google Gemini models with GCP Vertex AI. **_This integration will be deprecated soon. We recommend using [GoogleGenAIChatGenerator](generators/googlegenaichatgenerator.mdx) integration instead._** | ✅ |
+| [VertexAIImageCaptioner](generators/vertexaiimagecaptioner.mdx) | Enables text generation using Google Vertex AI `imagetext` generative model. | ❌ |
+| [VertexAIImageGenerator](generators/vertexaiimagegenerator.mdx) | Enables image generation using Google Vertex AI generative model. | ❌ |
+| [VertexAIImageQA](generators/vertexaiimageqa.mdx) | Enables text generation (image captioning) using Google Vertex AI generative models. | ❌ |
+| [VertexAITextGenerator](generators/vertexaitextgenerator.mdx) | Enables text generation using Google Vertex AI generative models. | ❌ |
+| [WatsonxGenerator](generators/watsonxgenerator.mdx) | Enables text generation with IBM Watsonx models. | ✅ |
+| [WatsonxChatGenerator](generators/watsonxchatgenerator.mdx) | Enables chat completions with IBM Watsonx models. | ✅ |
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/amazonbedrockchatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/amazonbedrockchatgenerator.mdx
new file mode 100644
index 0000000000..262c119980
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/amazonbedrockchatgenerator.mdx
@@ -0,0 +1,140 @@
+---
+title: "AmazonBedrockChatGenerator"
+id: amazonbedrockchatgenerator
+slug: "/amazonbedrockchatgenerator"
+description: "This component enables chat completion using models through Amazon Bedrock service."
+---
+
+# AmazonBedrockChatGenerator
+
+This component enables chat completion using models through Amazon Bedrock service.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The model to use
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) instances | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) is a fully managed service that makes high-performing foundation models from leading AI startups and Amazon available through a unified API. You can choose from various foundation models to find the one best suited for your use case.
+
+`AmazonBedrockChatGenerator` enables chat completion using chat models from Anthropic, Cohere, Meta Llama 2, and Mistral with a single component.
+
+The models that we currently support are Anthropic's _Claude_, Meta's _Llama 2_, and _Mistral_, but as more chat models are added, their support will be provided through `AmazonBedrockChatGenerator`.
+
+## Overview
+
+This component uses AWS for authentication. You can use the AWS CLI to authenticate through your IAM. For more information on setting up an IAM identity-based policy, see the [official documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html).
+
+:::info Using AWS CLI
+
+Consider using AWS CLI as a more straightforward tool to manage your AWS services. With AWS CLI, you can quickly configure your [boto3 credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html). This way, you won't need to provide detailed authentication parameters when initializing Amazon Bedrock Generator in Haystack.
+:::
+
+To use this component for text generation, initialize an AmazonBedrockGenerator with the model name, the AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) should be set as environment variables, be configured as described above or passed as [Secret](../../concepts/secret-management.mdx) arguments. Note, make sure the region you set supports Amazon Bedrock.
+
+### Tool Support
+
+`AmazonBedrockChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = AmazonBedrockChatGenerator(
+ model="anthropic.claude-3-5-sonnet-20240620-v1:0",
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+To start using Amazon Bedrock with Haystack, install the `amazon-bedrock-haystack` package:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = AmazonBedrockChatGenerator(model="meta.llama2-70b-chat-v1")
+messages = [ChatMessage.from_system("You are a helpful assistant that answers question in Spanish only"), ChatMessage.from_user("What's Natural Language Processing? Be brief.")]
+
+response = generator.run(messages)
+print(response)
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator
+
+llm = AmazonBedrockChatGenerator(model="anthropic.claude-3-5-sonnet-20240620-v1:0")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(content_parts=[
+ "What does the image show? Max 5 words.",
+ image
+ ])
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw mat.
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", AmazonBedrockChatGenerator(model="meta.llama2-70b-chat-v1"))
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system("You are an assistant giving out valuable information to language learners.")
+messages = [system_message, ChatMessage.from_user("What's the official language of {{ country }}?")]
+
+res = pipe.run(data={"prompt_builder": {"template_variables": {"country": country}, "template": messages}})
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/amazonbedrockgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/amazonbedrockgenerator.mdx
new file mode 100644
index 0000000000..628b33e310
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/amazonbedrockgenerator.mdx
@@ -0,0 +1,121 @@
+---
+title: "AmazonBedrockGenerator"
+id: amazonbedrockgenerator
+slug: "/amazonbedrockgenerator"
+description: "This component enables text generation using models through Amazon Bedrock service."
+---
+
+# AmazonBedrockGenerator
+
+This component enables text generation using models through Amazon Bedrock service.
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) instances | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The model to use
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `prompt`: The instructions for the Generator | +| **Output variables** | `replies`: A list of strings with all the replies generated by the model | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) is a fully managed service that makes high-performing foundation models from leading AI startups and Amazon available through a unified API. You can choose from various foundation models to find the one best suited for your use case.
+
+`AmazonBedrockGenerator` enables text generation using models from AI21 Labs, Anthropic, Cohere, Meta, Stability AI, and Amazon with a single component.
+
+The models that we currently support are Anthropic's Claude, AI21 Labs' Jurassic-2, Stability AI's Stable Diffusion, Cohere's Command and Embed, Meta's Llama 2, and the Amazon Titan language and embeddings models.
+
+## Overview
+
+This component uses AWS for authentication. You can use the AWS CLI to authenticate through your IAM. For more information on setting up an IAM identity-based policy, see the [official documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html).
+
+:::info Using AWS CLI
+
+Consider using AWS CLI as a more straightforward tool to manage your AWS services. With AWS CLI, you can quickly configure your [boto3 credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html). This way, you won't need to provide detailed authentication parameters when initializing Amazon Bedrock Generator in Haystack.
+:::
+
+To use this component for text generation, initialize an AmazonBedrockGenerator with the model name, the AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) should be set as environment variables, be configured as described above or passed as [Secret](../../concepts/secret-management.mdx) arguments. Note, make sure the region you set supports Amazon Bedrock.
+
+To start using Amazon Bedrock with Haystack, install the `amazon-bedrock-haystack` package:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockGenerator
+
+aws_access_key_id="..."
+aws_secret_access_key="..."
+aws_region_name="eu-central-1"
+
+generator = AmazonBedrockGenerator(model="anthropic.claude-v2")
+result = generator.run("Who is the best American actor?")
+for reply in result["replies"]:
+ print(reply)
+
+## >>> 'There is no definitive "best" American actor, as acting skill and talent a# re subjective. However, some of the most acclaimed and influential American act# ors include Tom Hanks, Daniel Day-Lewis, Denzel Washington, Meryl Streep, Rober# t De Niro, Al Pacino, Marlon Brando, Jack Nicholson, Leonardo DiCaprio and John# ny Depp. Choosing a single "best" actor comes down to personal preference.'
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders import PromptBuilder
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack import Pipeline
+
+from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockGenerator
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: What's the official language of {{ country }}?
+"""
+
+aws_access_key_id="..."
+aws_secret_access_key="..."
+aws_region_name="eu-central-1"
+generator = AmazonBedrockGenerator(model="anthropic.claude-v2")
+docstore = InMemoryDocumentStore()
+
+pipe = Pipeline()
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("generator", generator)
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "generator")
+
+pipe.run({
+ "retriever":{ "query": "France"},
+ "prompt_builder": {
+ "country": "France"
+ }
+})
+
+## {'generator': {'replies': ['Based on the context provided, the official language of France is French.']}}
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicchatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicchatgenerator.mdx
new file mode 100644
index 0000000000..e2946e477d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicchatgenerator.mdx
@@ -0,0 +1,198 @@
+---
+title: "AnthropicChatGenerator"
+id: anthropicchatgenerator
+slug: "/anthropicchatgenerator"
+description: "This component enables chat completions using Anthropic large language models (LLMs)."
+---
+
+# AnthropicChatGenerator
+
+This component enables chat completions using Anthropic large language models (LLMs).
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var.
`aws_region_name`: AWS region name. Can be set with `AWS_DEFAULT_REGION` env var. | +| **Mandatory run variables** | `prompt`: The instructions for the Generator | +| **Output variables** | `replies`: A list of strings with all the replies generated by the model | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An Anthropic API key. Can be set with `ANTHROPIC_API_KEY` env var. |
+| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | + +
+
+## Overview
+
+This integration supports Anthropic `chat` models such as `claude-3-5-sonnet-20240620`,`claude-3-opus-20240229`, `claude-3-haiku-20240307`, and similar. Check out the most recent full list in [Anthropic documentation](https://docs.anthropic.com/en/docs/about-claude/models).
+
+### Parameters
+
+`AnthropicChatGenerator` needs an Anthropic API key to work. You can provide this key in:
+
+- The `ANTHROPIC_API_KEY` environment variable (recommended)
+- The `api_key` init parameter and Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`
+
+Set your preferred Anthropic model with the `model` parameter when initializing the component.
+
+`AnthropicChatGenerator` requires a prompt to generate text, but you can pass any text generation parameters available in the Anthropic [Messaging API](https://docs.anthropic.com/en/api/messages) method directly to this component using the `generation_kwargs` parameter, both at initialization and when running the component. For more details on the parameters supported by the Anthropic API, see the [Anthropic documentation](https://docs.anthropic.com).
+
+Finally, the component needs a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+Only text input modality is supported at this time.
+
+### Tool Support
+
+`AnthropicChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = AnthropicChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+You can stream output as it’s generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+## Configure any `Generator` or `ChatGenerator` with a streaming callback
+component = SomeGeneratorOrChatGenerator(streaming_callback=print_streaming_chunk)
+
+## If this is a `ChatGenerator`, pass a list of messages:
+## from haystack.dataclasses import ChatMessage
+## component.run([ChatMessage.from_user("Your question here")])
+
+## If this is a (non-chat) `Generator`, pass a prompt:
+## component.run({"prompt": "Your prompt here"})
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+### Prompt caching
+
+Prompt caching is a feature for Anthropic LLMs that stores large text inputs for reuse. It allows you to send a large text block once and then refer to it in later requests without resending the entire text.
+This feature is particularly useful for coding assistants that need full codebase context and for processing large documents. It can help reduce costs and improve response times.
+
+Here's an example of an instance of `AnthropicChatGenerator` being initialized with prompt caching and tagging a message to be cached:
+
+```python python
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generation_kwargs = {"extra_headers": {"anthropic-beta": "prompt-caching-2024-07-31"}}
+
+claude_llm = AnthropicChatGenerator(
+ api_key=Secret.from_env_var("ANTHROPIC_API_KEY"), generation_kwargs=generation_kwargs
+)
+
+system_message = ChatMessage.from_system("Replace with some long text documents, code or instructions")
+system_message.meta["cache_control"] = {"type": "ephemeral"}
+
+messages = [system_message, ChatMessage.from_user("A query about the long text for example")]
+result = claude_llm.run(messages)
+
+## and now invoke again with
+
+messages = [system_message, ChatMessage.from_user("Another query about the long text etc")]
+result = claude_llm.run(messages)
+
+## and so on, either invoking component directly or in the pipeline
+```
+
+For more details, refer to Anthropic's [documentation](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) and integration [examples](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic/example).
+
+## Usage
+
+Install the`anthropic-haystack` package to use the `AnthropicChatGenerator`:
+
+```shell
+pip install anthropic-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = AnthropicChatGenerator()
+message = ChatMessage.from_user("What's Natural Language Processing? Be brief.")
+print(generator.run([message]))
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+
+llm = AnthropicChatGenerator()
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(content_parts=[
+ "What does the image show? Max 5 words.",
+ image
+ ])
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+### In a pipeline
+
+You can also use `AnthropicChatGenerator`with the Anthropic chat models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
+from haystack.utils import Secret
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", AnthropicChatGenerator(Secret.from_env_var("ANTHROPIC_API_KEY")))
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system("You are an assistant giving out valuable information to language learners.")
+messages = [system_message, ChatMessage.from_user("What's the official language of {{ country }}?")]
+
+res = pipe.run(data={"prompt_builder": {"template_variables": {"country": country}, "template": messages}})
+print(res)
+
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Advanced Prompt Customization for Anthropic](https://haystack.deepset.ai/cookbook/prompt_customization_for_anthropic)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicgenerator.mdx
new file mode 100644
index 0000000000..10eec5a41f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicgenerator.mdx
@@ -0,0 +1,89 @@
+---
+title: "AnthropicGenerator"
+id: anthropicgenerator
+slug: "/anthropicgenerator"
+description: "This component enables text completions using Anthropic large language models (LLMs)."
+---
+
+# AnthropicGenerator
+
+This component enables text completions using Anthropic large language models (LLMs).
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [PromptBuilder](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An Anthropic API key. Can be set with `ANTHROPIC_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | + +
+
+## Overview
+
+This integration supports Anthropic models such as `claude-3-5-sonnet-20240620`,`claude-3-opus-20240229`, `claude-3-haiku-20240307`, and similar. Although these LLMs are called chat models, the main prompt interface works with the string prompts. Check out the most recent full list in the [Anthropic documentation](https://docs.anthropic.com/en/docs/about-claude/models).
+
+### Parameters
+
+`AnthropicGenerator` needs an Anthropic API key to work. You can provide this key in:
+
+- The `ANTHROPIC_API_KEY` environment variable (recommended)
+- The `api_key` init parameter and Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`
+
+Set your preferred Anthropic model in the `model` parameter when initializing the component.
+
+`AnthropicGenerator` requires a prompt to generate text, but you can pass any text generation parameters available in the Anthropic [Messaging API](https://docs.anthropic.com/en/api/messages) method directly to this component using the `generation_kwargs` parameter, both at initialization and to `run()` method. For more details on the parameters supported by the Anthropic API, see [Anthropic documentation](https://docs.anthropic.com).
+
+Finally, the component run method requires a single string prompt to generate text.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Install the `anthropic-haystack` package to use the `AnthropicGenerator`:
+
+```shell
+pip install anthropic-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicGenerator
+
+generator = AnthropicGenerator()
+print(generator.run("What's Natural Language Processing? Be brief."))
+```
+
+### In a pipeline
+
+You can also use `AnthropicGenerator` with the Anthropic models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import PromptBuilder
+from haystack_integrations.components.generators.anthropic import AnthropicGenerator
+from haystack.utils import Secret
+
+template = """
+You are an assistant giving out valuable information to language learners.
+Answer this question, be brief.
+
+Question: {{ query }}?
+"""
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", PromptBuilder(template))
+pipe.add_component("llm", AnthropicGenerator(Secret.from_env_var("ANTHROPIC_API_KEY")))
+pipe.connect("prompt_builder", "llm")
+
+query = "What language is spoke in Germany?"
+res = pipe.run(data={"prompt_builder": {"query": {query}}})
+print(res)
+
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicvertexchatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicvertexchatgenerator.mdx
new file mode 100644
index 0000000000..41b296b85f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicvertexchatgenerator.mdx
@@ -0,0 +1,156 @@
+---
+title: "AnthropicVertexChatGenerator"
+id: anthropicvertexchatgenerator
+slug: "/anthropicvertexchatgenerator"
+description: "This component enables chat completions using AnthropicVertex API."
+---
+
+# AnthropicVertexChatGenerator
+
+This component enables chat completions using AnthropicVertex API.
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `region`: The region where the Anthropic model is deployed
`project_id`: GCP project ID where the Anthropic model is deployed | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and others | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | + +
+
+## Overview
+
+`AnthropicVertexChatGenerator` enables text generation using state-of-the-art Claude 3 LLMs using the Anthropic Vertex AI API.
+It supports `Claude 3.5 Sonnet`, `Claude 3 Opus`, `Claude 3 Sonnet`, and `Claude 3 Haiku` models, that are accessible through the Vertex AI API endpoint. For more details about the models, refer to [Anthropic Vertex AI documentation](https://docs.anthropic.com/en/api/claude-on-vertex-ai).
+
+### Parameters
+
+To use the `AnthropicVertexChatGenerator`, ensure you have a GCP project with Vertex AI enabled. You need to specify your GCP `project_id` and `region`.
+
+You can provide these keys in the following ways:
+
+- The `REGION` and `PROJECT_ID` environment variables (recommended)
+- The `region` and `project_id` init parameters
+
+Before making requests, you may need to authenticate with GCP using `gcloud auth login`.
+
+Set your preferred supported Anthropic model with the `model` parameter when initializing the component. Additionally, ensure that the desired Anthropic model is activated in the Vertex AI Model Garden.
+
+`AnthropicVertexChatGenerator` requires a prompt to generate text, but you can pass any text generation parameters available in the Anthropic [Messaging API](https://docs.anthropic.com/en/api/messages) method directly to this component using the `generation_kwargs` parameter, both at initialization and when running the component. For more details on the parameters supported by the Anthropic API, see the [Anthropic documentation](https://docs.anthropic.com/).
+
+Finally, the component needs a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+Only text input modality is supported at this time.
+
+### Streaming
+
+You can stream output as it’s generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+## Configure any `Generator` or `ChatGenerator` with a streaming callback
+component = SomeGeneratorOrChatGenerator(streaming_callback=print_streaming_chunk)
+
+## If this is a `ChatGenerator`, pass a list of messages:
+## from haystack.dataclasses import ChatMessage
+## component.run([ChatMessage.from_user("Your question here")])
+
+## If this is a (non-chat) `Generator`, pass a prompt:
+## component.run({"prompt": "Your prompt here"})
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+### Prompt Caching
+
+Prompt caching is a feature for Anthropic LLMs that stores large text inputs for reuse. It allows you to send a large text block once and then refer to it in later requests without resending the entire text.
+
+This feature is particularly useful for coding assistants that need full codebase context and for processing large documents. It can help reduce costs and improve response times.
+
+Here's an example of an instance of `AnthropicVertexChatGenerator` being initialized with prompt caching and tagging a message to be cached:
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicVertexChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generation_kwargs = {"extra_headers": {"anthropic-beta": "prompt-caching-2024-07-31"}}
+
+claude_llm = AnthropicVertexChatGenerator(
+ region="your_region", project_id="test_id", generation_kwargs=generation_kwargs
+)
+
+system_message = ChatMessage.from_system("Replace with some long text documents, code or instructions")
+system_message.meta["cache_control"] = {"type": "ephemeral"}
+
+messages = [system_message, ChatMessage.from_user("A query about the long text for example")]
+result = claude_llm.run(messages)
+
+## and now invoke again with
+
+messages = [system_message, ChatMessage.from_user("Another query about the long text etc")]
+result = claude_llm.run(messages)
+
+## and so on, either invoking component directly or in the pipeline
+```
+
+For more details, refer to Anthropic's [documentation](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) and integration [examples](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic/example).
+
+## Usage
+
+Install the`anthropic-haystack` package to use the `AnthropicVertexChatGenerator`:
+
+```shell
+pip install anthropic-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.anthropic import AnthropicVertexChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+client = AnthropicVertexChatGenerator(
+ model="claude-3-sonnet@20240229",
+ project_id="your-project-id", region="us-central1"
+)
+
+response = client.run(messages)
+print(response)
+```
+
+### In a pipeline
+
+You can also use `AnthropicVertexChatGenerator`with the Anthropic chat models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.anthropic import AnthropicVertexChatGenerator
+from haystack.utils import Secret
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", AnthropicVertexChatGenerator(project_id="test_id", region="us-central1"))
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system("You are an assistant giving out valuable information to language learners.")
+messages = [system_message, ChatMessage.from_user("What's the official language of {{ country }}?")]
+
+res = pipe.run(data={"prompt_builder": {"template_variables": {"country": country}, "template": messages}})
+print(res)
+
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/azureopenaichatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/azureopenaichatgenerator.mdx
new file mode 100644
index 0000000000..647ba25fce
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/azureopenaichatgenerator.mdx
@@ -0,0 +1,195 @@
+---
+title: "AzureOpenAIChatGenerator"
+id: azureopenaichatgenerator
+slug: "/azureopenaichatgenerator"
+description: "This component enables chat completion using OpenAI’s large language models (LLMs) through Azure services."
+---
+
+# AzureOpenAIChatGenerator
+
+This component enables chat completion using OpenAI’s large language models (LLMs) through Azure services.
+
+`project_id`: GCP project ID where the Anthropic model is deployed | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and others | +| **API reference** | [Anthropic](/reference/integrations-anthropic) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/anthropic | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Azure OpenAI API key. Can be set with `AZURE_OPENAI_API_KEY` env var.
`azure_ad_token`: Microsoft Entra ID token. Can be set with `AZURE_OPENAI_AD_TOKEN` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of alternative replies of the LLM to the input chat | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/azure.py | + +
+
+## Overview
+
+`AzureOpenAIChatGenerator` supports OpenAI models deployed through Azure services. To see the list of supported models, head over to Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?source=recommendations). The default model used with the component is `gpt-4o-mini`.
+
+To work with Azure components, you will need an Azure OpenAI API key, as well as an Azure OpenAI Endpoint. You can learn more about them in Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
+
+The component uses `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_AD_TOKEN` environment variables by default. Otherwise, you can pass `api_key` and `azure_ad_token` at initialization:
+
+```python
+client = AzureOpenAIChatGenerator(azure_endpoint="`azure_ad_token`: Microsoft Entra ID token. Can be set with `AZURE_OPENAI_AD_TOKEN` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of alternative replies of the LLM to the input chat | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/azure.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Azure OpenAI API key. Can be set with `AZURE_OPENAI_API_KEY` env var.
`azure_ad_token`: Microsoft Entra ID token. Can be set with `AZURE_OPENAI_AD_TOKEN` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/azure.py | + +
+
+## Overview
+
+`AzureOpenAIGenerator` supports OpenAI models deployed through Azure services. To see the list of supported models, head over to Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?source=recommendations). The default model used with the component is `gpt-4o-mini`.
+
+To work with Azure components, you will need an Azure OpenAI API key, as well as an Azure OpenAI Endpoint. You can learn more about them in Azure [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
+
+The component uses `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_AD_TOKEN` environment variables by default. Otherwise, you can pass `api_key` and `azure_ad_token` at initialization:
+
+```python
+client = AzureOpenAIGenerator(azure_endpoint="`azure_ad_token`: Microsoft Entra ID token. Can be set with `AZURE_OPENAI_AD_TOKEN` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/azure.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Cohere API key. Can be set with `COHERE_API_KEY` or `CO_API_KEY` env var. |
+| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | + +
+
+This integration supports Cohere `chat` models such as `command`,`command-r` and `comman-r-plus`. Check out the most recent full list in [Cohere documentation](https://docs.cohere.com/reference/chat).
+
+## Overview
+
+`CohereChatGenerator` needs a Cohere API key to work. You can set this key in:
+
+- The `api_key` init parameter using [Secret API](../../concepts/secret-management.mdx)
+- The `COHERE_API_KEY` environment variable (recommended)
+
+Then, the component needs a prompt to operate, but you can pass any text generation parameters valid for the `Co.chat` method directly to this component using the `generation_kwargs` parameter, both at initialization and to `run()` method. For more details on the parameters supported by the Cohere API, refer to the [Cohere documentation](https://docs.cohere.com/reference/chat).
+
+Finally, the component needs a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+### Tool Support
+
+`CohereChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.cohere import CohereChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = CohereChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+You need to install `cohere-haystack` package to use the `CohereChatGenerator`:
+
+```shell
+pip install cohere-haystack
+```
+
+#### On its own
+
+```python
+from haystack_integrations.components.generators.cohere import CohereChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = CohereChatGenerator()
+message = ChatMessage.from_user("What's Natural Language Processing? Be brief.")
+print(generator.run([message]))
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.cohere import CohereChatGenerator
+
+# Use a multimodal model like Command A Vision
+llm = CohereChatGenerator(model="command-a-vision-07-2025")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(content_parts=[
+ "What does the image show? Max 5 words.",
+ image
+ ])
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+#### In a Pipeline
+
+You can also use `CohereChatGenerator` to use cohere chat models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.cohere import CohereChatGenerator
+from haystack.utils import Secret
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", CohereChatGenerator())
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system("You are an assistant giving out valuable information to language learners.")
+messages = [system_message, ChatMessage.from_user("What's the official language of {{ country }}?")]
+
+res = pipe.run(data={"prompt_builder": {"template_variables": {"country": country}, "template": messages}})
+print(res)
+
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/coheregenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/coheregenerator.mdx
new file mode 100644
index 0000000000..4393270104
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/coheregenerator.mdx
@@ -0,0 +1,123 @@
+---
+title: "CohereGenerator"
+id: coheregenerator
+slug: "/coheregenerator"
+description: "`CohereGenerator` enables text generation using Cohere's large language models (LLMs)."
+---
+
+# CohereGenerator
+
+`CohereGenerator` enables text generation using Cohere's large language models (LLMs).
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Cohere API key. Can be set with `COHERE_API_KEY` or `CO_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | + +
+
+ This integration supports Cohere models such as `command`, `command-r` and `comman-r-plus`. Check out the most recent full list in [Cohere documentation](https://docs.cohere.com/reference/chat).
+
+## Overview
+
+`CohereGenerator` needs a Cohere API key to work. You can write this key in:
+
+- The `api_key` init parameter using [Secret API](../../concepts/secret-management.mdx)
+- The `COHERE_API_KEY` environment variable (recommended)
+
+Then, the component needs a prompt to operate, but you can pass any text generation parameters directly to this component using the `generation_kwargs` parameter at initialization. For more details on the parameters supported by the Cohere API, refer to the [Cohere documentation](https://docs.cohere.com/reference/chat).
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+You need to install `cohere-haystack` package to use the `CohereGenerator`:
+
+```shell
+pip install cohere-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.cohere import CohereGenerator
+
+client = CohereGenerator()
+response = client.run("Briefly explain what NLP is in one sentence.")
+print(response)
+
+>>> {'replies': ["Natural Language Processing (NLP) is a subfield of artificial intelligence and computational linguistics that focuses on the interaction between computers and human languages..."],
+ 'meta': [{'finish_reason': 'COMPLETE'}]}
+```
+
+With streaming:
+
+```python
+from haystack_integrations.components.generators.cohere import CohereGenerator
+
+client = CohereGenerator(streaming_callback=lambda chunk: print(chunk.content, end="", flush=True))
+response = client.run("Briefly explain what NLP is in one sentence.")
+print(response)
+
+>>> Natural Language Processing (NLP) is the study of natural language and how it can be used to solve problems through computational methods, enabling machines to understand, interpret, and generate human language.
+
+>>>{'replies': [' Natural Language Processing (NLP) is the study of natural language and how it can be used to solve problems through computational methods, enabling machines to understand, interpret, and generate human language.'], 'meta': [{'index': 0, 'finish_reason': 'COMPLETE'}]}
+
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack import Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.generators.cohere import CohereGenerator
+from haystack import Document
+
+docstore = InMemoryDocumentStore()
+docstore.write_documents([Document(content="Rome is the capital of Italy"), Document(content="Paris is the capital of France")])
+
+query = "What is the capital of France?"
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: {{ query }}?
+"""
+pipe = Pipeline()
+
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("llm", CohereGenerator())
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "llm")
+
+res=pipe.run({
+ "prompt_builder": {
+ "query": query
+ },
+ "retriever": {
+ "query": query
+ }
+})
+
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/dalleimagegenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/dalleimagegenerator.mdx
new file mode 100644
index 0000000000..69ab396036
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/dalleimagegenerator.mdx
@@ -0,0 +1,97 @@
+---
+title: "DALLEImageGenerator"
+id: dalleimagegenerator
+slug: "/dalleimagegenerator"
+description: "Generate images using OpenAI's DALL-E model."
+---
+
+# DALLEImageGenerator
+
+Generate images using OpenAI's DALL-E model.
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx), flexible |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the model |
+| **Output variables** | `images`: A list of generated images
`revised_prompt`: A string containing the prompt that was used to generate the image, if there was any revision to the prompt made by OpenAI | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/openai_dalle.py | + +
+
+## Overview
+
+The `DALLEImageGenerator` component generates images using OpenAI's DALL-E model.
+
+By default, the component uses `dall-e-3` model, standard picture quality, and 1024x1024 resolution. You can change these parameters using `model` (during component initialization), `quality`, and `size` (during component initialization or run) parameters.
+
+`DALLEImageGenerator` needs an OpenAI key to work. It uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```
+image_generator = DALLEImageGenerator(api_key=Secret.from_token("`revised_prompt`: A string containing the prompt that was used to generate the image, if there was any revision to the prompt made by OpenAI | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/openai_dalle.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `chat_generators`: A non-empty list of Chat Generator components to try in order |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: Generated ChatMessage instances from the first successful generator
`meta`: Execution metadata including successful generator details | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/fallback.py | + +
+
+## Overview
+
+`FallbackChatGenerator` is a wrapper component that tries multiple Chat Generators sequentially until one succeeds. If a Generator fails, the component tries the next one in the list. This handles provider outages, rate limits, and other transient failures.
+
+The component forwards all parameters to the underlying Chat Generators and returns the first successful result. When a Generator raises any exception, the component tries the next Generator. This includes timeout errors, rate limit errors (429), authentication errors (401), context length errors (400), server errors (500+), and any other exception.
+
+The component returns execution metadata including which Generator succeeded, how many attempts were made, and which Generators failed. All parameters (`messages`, `generation_kwargs`, `tools`, `streaming_callback`) are forwarded to the underlying Generators.
+
+Timeout enforcement is delegated to the underlying Chat Generators. To control latency, configure your Chat Generators with a `timeout` parameter. Chat Generators like OpenAI, Anthropic, and Cohere support timeout parameters that raise exceptions when exceeded.
+
+### Monitoring and Telemetry
+
+The `meta` dictionary in the output contains useful information for monitoring:
+
+```python
+from haystack.components.generators.chat import FallbackChatGenerator, OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+## Set up generators
+primary = OpenAIChatGenerator(model="gpt-4o")
+backup = OpenAIChatGenerator(model="gpt-4o-mini")
+generator = FallbackChatGenerator(chat_generators=[primary, backup])
+
+## Run and inspect metadata
+result = generator.run(messages=[ChatMessage.from_user("Hello")])
+
+meta = result["meta"]
+print(f"Successful generator index: {meta['successful_chat_generator_index']}") # 0 for first, 1 for second, etc.
+print(f"Successful generator class: {meta['successful_chat_generator_class']}") # e.g., "OpenAIChatGenerator"
+print(f"Total attempts made: {meta['total_attempts']}") # How many Generators were tried
+print(f"Failed generators: {meta['failed_chat_generators']}") # List of failed Generator names
+```
+
+You can use this metadata to:
+
+- Track which Generators are being used most frequently
+- Monitor failure rates for each Generator
+- Set up alerts when fallbacks occur
+- Adjust Generator ordering based on success rates
+
+### Streaming
+
+`FallbackChatGenerator` supports streaming through the `streaming_callback` parameter. The callback is passed directly to the underlying Generators.
+
+## Usage
+
+### On its own
+
+Basic usage with fallback from a primary to a backup model:
+
+```python
+from haystack.components.generators.chat import FallbackChatGenerator, OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+## Create primary and backup generators
+primary = OpenAIChatGenerator(model="gpt-4o", timeout=30)
+backup = OpenAIChatGenerator(model="gpt-4o-mini", timeout=30)
+
+## Wrap them in a FallbackChatGenerator
+generator = FallbackChatGenerator(chat_generators=[primary, backup])
+
+## Use it like any other Chat Generator
+messages = [ChatMessage.from_user("What's Natural Language Processing? Be brief.")]
+result = generator.run(messages=messages)
+
+print(result["replies"][0].text)
+print(f"Successful generator: {result['meta']['successful_chat_generator_class']}")
+print(f"Total attempts: {result['meta']['total_attempts']}")
+
+>> Natural Language Processing (NLP) is a field of artificial intelligence that
+>> focuses on the interaction between computers and humans through natural language...
+>> Successful generator: OpenAIChatGenerator
+>> Total attempts: 1
+```
+
+With multiple providers:
+
+```python
+from haystack.components.generators.chat import (
+ FallbackChatGenerator,
+ OpenAIChatGenerator,
+ AzureOpenAIChatGenerator
+)
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+## Create generators from different providers
+openai_gen = OpenAIChatGenerator(
+ model="gpt-4o-mini",
+ api_key=Secret.from_env_var("OPENAI_API_KEY"),
+ timeout=30
+)
+
+azure_gen = AzureOpenAIChatGenerator(
+ azure_endpoint="`meta`: Execution metadata including successful generator details | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/fallback.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Google AI Studio API key. Can be set with `GOOGLE_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of alternative replies of the model to the input chat |
+| **API reference** | [Google AI](/reference/integrations-google-ai) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_ai |
+
+
+
+`GoogleAIGeminiChatGenerator` supports `gemini-2.5-pro-exp-03-25`, `gemini-2.0-flash`, `gemini-1.5-pro`, and `gemini-1.5-flash` models.
+
+For available models, see https://ai.google.dev/gemini-api/docs/models/gemini.
+
+### Parameters Overview
+
+`GoogleAIGeminiChatGenerator` uses a Google Studio API key for authentication. You can write this key in an `api_key` parameter or as a `GOOGLE_API_KEY` environment variable (recommended).
+
+To get an API key, visit the [Google AI Studio](https://aistudio.google.com/) website.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+To begin working with `GoogleAIGeminiChatGenerator`, install the `google-ai-haystack` package:
+
+```shell
+pip install google-ai-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import os
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.google_ai import GoogleAIGeminiChatGenerator
+
+os.environ["GOOGLE_API_KEY"] = "
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Google AI Studio API key. Can be set with `GOOGLE_API_KEY` env var. |
+| **Mandatory run variables** | `parts`: A variadic list containing a mix of images, audio, video, and text to prompt Gemini |
+| **Output variables** | `replies`: A list of strings or dictionaries with all the replies generated by the model |
+| **API reference** | [Google AI](/reference/integrations-google-ai) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_ai |
+
+
+
+`GoogleAIGeminiGenerator` supports `gemini-2.5-pro-exp-03-25`, `gemini-2.0-flash`, `gemini-1.5-pro`, and `gemini-1.5-flash` models.
+
+For available models, see https://ai.google.dev/gemini-api/docs/models/gemini.
+
+### Parameters Overview
+
+`GoogleAIGeminiGenerator` uses a Google AI Studio API key for authentication. You can write this key in an `api_key` parameter or as a `GOOGLE_API_KEY` environment variable (recommended).
+
+To get an API key, visit the [Google AI Studio](https://ai.google.dev/gemini-api/docs/api-key) website.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Start by installing the `google-ai-haystack` package to use the `GoogleAIGeminiGenerator`:
+
+```shell
+pip install google-ai-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import os
+from haystack_integrations.components.generators.google_ai import GoogleAIGeminiGenerator
+
+os.environ["GOOGLE_API_KEY"] = "
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Google API key. Can be set with `GOOGLE_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of alternative replies of the model to the input chat |
+| **API reference** | [Google GenAI](/reference/integrations-google-genai) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_genai |
+
+
+
+## Overview
+
+`GoogleGenAIChatGenerator` supports `gemini-2.0-flash` (default), `gemini-2.5-pro-exp-03-25`, `gemini-1.5-pro`, and `gemini-1.5-flash` models.
+
+### Tool Support
+
+`GoogleGenAIChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = GoogleGenAIChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+### Authentication
+
+Google Gen AI is compatible with both the Gemini Developer API and the Vertex AI API.
+
+To use this component with the Gemini Developer API and get an API key, visit [Google AI Studio](https://aistudio.google.com/).
+To use this component with the Vertex AI API, visit [Google Cloud > Vertex AI](https://cloud.google.com/vertex-ai).
+
+The component uses a `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with a [Secret](../../concepts/secret-management.mdx) and `Secret.from_token` static method:
+
+```python
+embedder = GoogleGenAITextEmbedder(api_key=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_type`: The type of Hugging Face API to use
`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of replies of the LLM to the input chat | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/hugging_face_api.py | + +
+
+## Overview
+
+`HuggingFaceAPIChatGenerator` can be used to generate chat completions using different Hugging Face APIs:
+
+- [Serverless Inference API (Inference Providers)](https://huggingface.co/docs/inference-providers) - free tier available
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
+
+This component's main input is a list of `ChatMessage` objects. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata. For more information, check out our [`ChatMessage` docs](../../concepts/data-classes/chatmessage.mdx).
+
+:::info
+This component is designed for chat completion, so it expects a list of messages, not a single string. If you want to use Hugging Face APIs for simple text generation (such as translation or summarization tasks) or don't want to use the `ChatMessage` object, use [`HuggingFaceAPIGenerator`](huggingfaceapigenerator.mdx) instead.
+:::
+
+The component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with `token` – see code examples below.
+The token is needed:
+
+- If you use the Serverless Inference API, or
+- If you use the Inference Endpoints.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+### On its own
+
+#### Using Serverless Inference API (Inference Providers) - Free Tier Available
+
+This API allows you to quickly experiment with many models hosted on the Hugging Face Hub, offloading the inference to Hugging Face servers. It's rate-limited and not meant for production.
+
+To use this API, you need a [free Hugging Face token](https://huggingface.co/settings/tokens).
+The Generator expects the `model` in `api_params`. It's also recommended to specify a `provider` for better performance and reliability.
+
+```python
+from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack.utils.hf import HFGenerationAPIType
+
+messages = [ChatMessage.from_system("\\nYou are a helpful, respectful and honest assistant"),
+ ChatMessage.from_user("What's Natural Language Processing?")]
+
+## the api_type can be expressed using the HFGenerationAPIType enum or as a string
+api_type = HFGenerationAPIType.SERVERLESS_INFERENCE_API
+api_type = "serverless_inference_api" # this is equivalent to the above
+
+generator = HuggingFaceAPIChatGenerator(api_type=api_type,
+ api_params={"model": "Qwen/Qwen2.5-7B-Instruct",
+ "provider": "together"},
+ token=Secret.from_env_var("HF_API_TOKEN"))
+
+result = generator.run(messages)
+print(result)
+```
+
+#### Using Paid Inference Endpoints
+
+In this case, a private instance of the model is deployed by Hugging Face, and you typically pay per hour.
+
+To understand how to spin up an Inference Endpoint, visit [Hugging Face documentation](https://huggingface.co/inference-endpoints/dedicated).
+
+Additionally, in this case, you need to provide your Hugging Face token.
+The Generator expects the `url` of your endpoint in `api_params`.
+
+```python
+from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+messages = [ChatMessage.from_system("\\nYou are a helpful, respectful and honest assistant"),
+ ChatMessage.from_user("What's Natural Language Processing?")]
+
+generator = HuggingFaceAPIChatGenerator(api_type="inference_endpoints",
+ api_params={"url": "`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of replies of the LLM to the input chat | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/hugging_face_api.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_type`: The type of Hugging Face API to use
`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and others | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/hugging_face_api.py | + +
+
+## Overview
+
+`HuggingFaceAPIGenerator` can be used to generate text using different Hugging Face APIs:
+
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
+
+:::note Important Note
+
+As of July 2025, the Hugging Face Inference API no longer offers generative models through the `text_generation` endpoint. Generative models are now only available through providers supporting the `chat_completion` endpoint. As a result, this component might no longer work with the Hugging Face Inference API.
+
+Use the [`HuggingFaceAPIChatGenerator`](huggingfaceapichatgenerator.mdx) component instead, which supports the `chat_completion` endpoint and works with the free Serverless Inference API.
+:::
+
+:::info
+This component is designed for text generation, not for chat. If you want to use these LLMs for chat, use [`HuggingFaceAPIChatGenerator`](huggingfaceapichatgenerator.mdx) instead.
+:::
+
+The component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with `token` – see code examples below.
+The token is needed when you use the Inference Endpoints.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+### On its own
+
+#### Using Paid Inference Endpoints
+
+In this case, a private instance of the model is deployed by Hugging Face, and you typically pay per hour.
+
+To understand how to spin up an Inference Endpoint, visit [Hugging Face documentation](https://huggingface.co/inference-endpoints/dedicated).
+
+Additionally, in this case, you need to provide your Hugging Face token.
+The Generator expects the `url` of your endpoint in `api_params`.
+
+```python
+from haystack.components.generators import HuggingFaceAPIGenerator
+from haystack.utils import Secret
+
+generator = HuggingFaceAPIGenerator(api_type="inference_endpoints",
+ api_params={"url": "`api_params`: A dictionary with one of the following keys:
- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and others | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/hugging_face_api.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM |
+| **API reference** | [Generators](/reference/generators-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/hugging_face_local.py |
+
+
+
+## Overview
+
+Keep in mind that if LLMs run locally, you may need a powerful machine to run them. This depends strongly on the model you select and its parameter count.
+
+:::info
+This component is designed for chat completion, not for text generation. If you want to use Hugging Face LLMs for text generation, use [`HuggingFaceLocalGenerator`](huggingfacelocalgenerator.mdx) instead.
+:::
+
+For remote file authorization, this component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with `token`:
+
+```python
+local_generator = HuggingFaceLocalChatGenerator(token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM |
+| **API reference** | [Generators](/reference/generators-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/hugging_face_local.py |
+
+
+
+## Overview
+
+Keep in mind that if LLMs run locally, you may need a powerful machine to run them. This depends strongly on the model you select and its parameter count.
+
+:::info Looking for chat completion?
+
+This component is designed for text generation, not for chat. If you want to use Hugging Face LLMs for chat, consider using [`HuggingFaceLocalChatGenerator`](huggingfacelocalchatgenerator.mdx) instead.
+:::
+
+For remote files authorization, this component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with `token`:
+
+```python
+local_generator = HuggingFaceLocalGenerator(token=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The path of the model to use |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) instances representing the input messages |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) instances with all the replies generated by the LLM |
+| **API reference** | [Llama.cpp](/reference/integrations-llama-cpp) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/llama_cpp |
+
+
+
+## Overview
+
+[Llama.cpp](https://github.com/ggerganov/llama.cpp) is a library written in C/C++ for efficient inference of Large Language Models. It leverages the efficient quantized GGUF format, dramatically reducing memory requirements and accelerating inference. This means it is possible to run LLMs efficiently on standard machines (even without GPUs).
+
+`Llama.cpp` uses the quantized binary file of the LLM in GGUF format, which can be downloaded from [Hugging Face](https://huggingface.co/models?library=gguf). `LlamaCppChatGenerator` supports models running on `Llama.cpp` by taking the path to the locally saved GGUF file as `model` parameter at initialization.
+
+### Tool Support
+
+`LlamaCppChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = LlamaCppChatGenerator(
+ model="/path/to/model.gguf",
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+## Installation
+
+Install the `llama-cpp-haystack` package to use this integration:
+
+```shell
+pip install llama-cpp-haystack
+```
+
+### Using a different compute backend
+
+The default installation behavior is to build `llama.cpp` for CPU on Linux and Windows and use Metal on MacOS. To use other compute backends:
+
+1. Follow instructions on the [llama.cpp installation page](https://github.com/abetlen/llama-cpp-python#installation) to install [llama-cpp-python](https://github.com/abetlen/llama-cpp-python) for your preferred compute backend.
+2. Install [llama-cpp-haystack](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/llama_cpp) using the command above.
+
+For example, to use `llama-cpp-haystack` with the **cuBLAS backend**, you have to run the following commands:
+
+```shell
+export GGML_CUDA=1
+CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python
+pip install llama-cpp-haystack
+```
+
+## Usage
+
+1. Download the GGUF version of the desired LLM. The GGUF versions of popular models can be downloaded from [Hugging Face](https://huggingface.co/models?library=gguf).
+2. Initialize `LlamaCppChatGenerator` with the path to the GGUF file and specify the required model and text generation parameters:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+
+generator = LlamaCppChatGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ model_kwargs={"n_gpu_layers": -1},
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+generator.warm_up()
+messages = [ChatMessage.from_user("Who is the best American actor?")]
+result = generator.run(messages)
+```
+
+### Passing additional model parameters
+
+The `model`, `n_ctx`, `n_batch` arguments have been exposed for convenience and can be directly passed to the Generator during initialization as keyword arguments. Note that `model` translates to `llama.cpp`'s `model_path` parameter.
+
+The `model_kwargs` parameter can pass additional arguments when initializing the model. In case of duplication, these parameters override the `model`, `n_ctx`, and `n_batch` initialization parameters.
+
+See [Llama.cpp's LLM documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.__init__) for more information on the available model arguments.
+
+**Note**: Llama.cpp automatically extracts the `chat_template` from the model metadata for applying formatting to ChatMessages. You can override the `chat_template` used by passing in a custom `chat_handler` or `chat_format` as a model parameter.
+
+For example, to offload the model to GPU during initialization:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = LlamaCppChatGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ model_kwargs={"n_gpu_layers": -1}
+)
+generator.warm_up()
+messages = [ChatMessage.from_user("Who is the best American actor?")]
+result = generator.run(messages, generation_kwargs={"max_tokens": 128})
+generated_reply = result["replies"][0].content
+print(generated_reply)
+```
+
+### Passing text generation parameters
+
+The `generation_kwargs` parameter can pass additional generation arguments like `max_tokens`, `temperature`, `top_k`, `top_p`, and others to the model during inference.
+
+See [Llama.cpp's Chat Completion API documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion) for more information on the available generation arguments.
+
+**Note**: JSON mode, Function Calling, and Tools are all supported as `generation_kwargs`. Please see the [llama-cpp-python GitHub README](https://github.com/abetlen/llama-cpp-python?tab=readme-ov-file#json-and-json-schema-mode) for more information on how to use them.
+
+For example, to set the `max_tokens` and `temperature`:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = LlamaCppChatGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+generator.warm_up()
+messages = [ChatMessage.from_user("Who is the best American actor?")]
+result = generator.run(messages)
+```
+
+### With multimodal (image + text) inputs
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+
+# Initialize with multimodal support
+llm = LlamaCppChatGenerator(
+ model="llava-v1.5-7b-q4_0.gguf",
+ chat_handler_name="Llava15ChatHandler", # Use llava-1-5 handler
+ model_clip_path="mmproj-model-f16.gguf", # CLIP model
+ n_ctx=4096 # Larger context for image processing
+)
+llm.warm_up()
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(content_parts=[
+ "What does the image show? Max 5 words.",
+ image
+ ])
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+The `generation_kwargs` can also be passed to the `run` method of the generator directly:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = LlamaCppChatGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+)
+generator.warm_up()
+messages = [ChatMessage.from_user("Who is the best American actor?")]
+result = generator.run(
+ messages,
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+```
+
+### In a pipeline
+
+We use the `LlamaCppChatGenerator` in a Retrieval Augmented Generation pipeline on the [Simple Wikipedia](https://huggingface.co/datasets/pszemraj/simple_wikipedia) Dataset from Hugging Face and generate answers using the [OpenChat-3.5](https://huggingface.co/openchat/openchat-3.5-1210) LLM.
+
+Load the dataset:
+
+```python
+## Install HuggingFace Datasets using "pip install datasets"
+from datasets import load_dataset
+from haystack import Document, Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.dataclasses import ChatMessage
+
+## Import LlamaCppChatGenerator
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+
+## Load first 100 rows of the Simple Wikipedia Dataset from HuggingFace
+dataset = load_dataset("pszemraj/simple_wikipedia", split="validation[:100]")
+
+docs = [
+ Document(
+ content=doc["text"],
+ meta={
+ "title": doc["title"],
+ "url": doc["url"],
+ },
+ )
+ for doc in dataset
+]
+```
+
+Index the documents to the `InMemoryDocumentStore` using the `SentenceTransformersDocumentEmbedder` and `DocumentWriter`:
+
+```python
+doc_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+## Install sentence transformers using "pip install sentence-transformers"
+doc_embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+
+## Indexing Pipeline
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(instance=doc_embedder, name="DocEmbedder")
+indexing_pipeline.add_component(instance=DocumentWriter(document_store=doc_store), name="DocWriter")
+indexing_pipeline.connect("DocEmbedder", "DocWriter")
+
+indexing_pipeline.run({"DocEmbedder": {"documents": docs}})
+```
+
+Create the RAG pipeline and add the `LlamaCppChatGenerator` to it:
+
+```python
+system_message = ChatMessage.from_system(
+ """
+ Answer the question using the provided context.
+ Context:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+ """
+)
+user_message = ChatMessage.from_user("Question: {{question}}")
+assistent_message = ChatMessage.from_assistant("Answer: ")
+
+chat_template = [system_message, user_message, assistent_message]
+
+rag_pipeline = Pipeline()
+
+text_embedder = SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+
+## Load the LLM using LlamaCppChatGenerator
+model_path = "openchat-3.5-1210.Q3_K_S.gguf"
+generator = LlamaCppChatGenerator(model=model_path, n_ctx=4096, n_batch=128)
+
+rag_pipeline.add_component(
+ instance=text_embedder,
+ name="text_embedder",
+)
+rag_pipeline.add_component(instance=InMemoryEmbeddingRetriever(document_store=doc_store, top_k=3), name="retriever")
+rag_pipeline.add_component(instance=ChatPromptBuilder(template=chat_template), name="prompt_builder")
+rag_pipeline.add_component(instance=generator, name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+
+rag_pipeline.connect("text_embedder", "retriever")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+rag_pipeline.connect("llm", "answer_builder")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+```
+
+Run the pipeline:
+
+```python
+question = "Which year did the Joker movie release?"
+result = rag_pipeline.run(
+ {
+ "text_embedder": {"text": question},
+ "prompt_builder": {"question": question},
+ "llm": {"generation_kwargs": {"max_tokens": 128, "temperature": 0.1}},
+ "answer_builder": {"query": question},
+ }
+)
+
+generated_answer = result["answer_builder"]["answers"][0]
+print(generated_answer.data)
+## The Joker movie was released on October 4, 2019.
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/llamacppgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/llamacppgenerator.mdx
new file mode 100644
index 0000000000..3ebedefbef
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/llamacppgenerator.mdx
@@ -0,0 +1,244 @@
+---
+title: "LlamaCppGenerator"
+id: llamacppgenerator
+slug: "/llamacppgenerator"
+description: "`LlamaCppGenerator` provides an interface to generate text using an LLM running on Llama.cpp."
+---
+
+# LlamaCppGenerator
+
+`LlamaCppGenerator` provides an interface to generate text using an LLM running on Llama.cpp.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The path of the model to use |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [Llama.cpp](/reference/integrations-llama-cpp) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/llama_cpp | + +
+
+## Overview
+
+[Llama.cpp](https://github.com/ggerganov/llama.cpp) is a library written in C/C++ for efficient inference of Large Language Models. It leverages the efficient quantized GGUF format, dramatically reducing memory requirements and accelerating inference. This means it is possible to run LLMs efficiently on standard machines (even without GPUs).
+
+`Llama.cpp` uses the quantized binary file of the LLM in GGUF format that can be downloaded from [Hugging Face](https://huggingface.co/models?library=gguf). `LlamaCppGenerator` supports models running on `Llama.cpp` by taking the path to the locally saved GGUF file as `model` parameter at initialization.
+
+## Installation
+
+Install the `llama-cpp-haystack` package:
+
+```bash
+pip install llama-cpp-haystack
+```
+
+### Using a different compute backend
+
+The default installation behavior is to build `llama.cpp` for CPU on Linux and Windows and use Metal on MacOS. To use other compute backends:
+
+1. Follow instructions on the [llama.cpp installation page](https://github.com/abetlen/llama-cpp-python#installation) to install [llama-cpp-python](https://github.com/abetlen/llama-cpp-python) for your preferred compute backend.
+2. Install [llama-cpp-haystack](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/llama_cpp) using the command above.
+
+For example, to use `llama-cpp-haystack` with the **cuBLAS backend**, you have to run the following commands:
+
+```bash
+export GGML_CUDA=1
+CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python
+pip install llama-cpp-haystack
+```
+
+## Usage
+
+1. You need to download the GGUF version of the desired LLM. The GGUF versions of popular models can be downloaded from [Hugging Face](https://huggingface.co/models?library=gguf).
+2. Initialize a `LlamaCppGenerator` with the path to the GGUF file and also specify the required model and text generation parameters:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+
+generator = LlamaCppGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ model_kwargs={"n_gpu_layers": -1},
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+generator.warm_up()
+prompt = f"Who is the best American actor?"
+result = generator.run(prompt)
+```
+
+### Passing additional model parameters
+
+The `model`, `n_ctx`, `n_batch` arguments have been exposed for convenience and can be directly passed to the Generator during initialization as keyword arguments. Note that `model` translates to `llama.cpp`'s `model_path` parameter.
+
+The `model_kwargs` parameter can pass additional arguments when initializing the model. In case of duplication, these parameters override the `model`, `n_ctx`, and `n_batch` initialization parameters.
+
+See [Llama.cpp's LLM documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.__init__) for more information on the available model arguments.
+
+For example, to offload the model to GPU during initialization:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+
+generator = LlamaCppGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ model_kwargs={"n_gpu_layers": -1}
+)
+generator.warm_up()
+prompt = f"Who is the best American actor?"
+result = generator.run(prompt, generation_kwargs={"max_tokens": 128})
+generated_text = result["replies"][0]
+print(generated_text)
+```
+
+### Passing text generation parameters
+
+The `generation_kwargs` parameter can pass additional generation arguments like `max_tokens`, `temperature`, `top_k`, `top_p`, and others to the model during inference.
+
+See [Llama.cpp's Completion API documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_completion) for more information on the available generation arguments.
+
+For example, to set the `max_tokens` and `temperature`:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+
+generator = LlamaCppGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+generator.warm_up()
+prompt = f"Who is the best American actor?"
+result = generator.run(prompt)
+```
+
+The `generation_kwargs` can also be passed to the `run` method of the generator directly:
+
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+
+generator = LlamaCppGenerator(
+ model="/content/openchat-3.5-1210.Q3_K_S.gguf",
+ n_ctx=512,
+ n_batch=128,
+)
+generator.warm_up()
+prompt = f"Who is the best American actor?"
+result = generator.run(
+ prompt,
+ generation_kwargs={"max_tokens": 128, "temperature": 0.1},
+)
+```
+
+### Using in a Pipeline
+
+We use the `LlamaCppGenerator` in a Retrieval Augmented Generation pipeline on the [Simple Wikipedia](https://huggingface.co/datasets/pszemraj/simple_wikipedia) Dataset from HuggingFace and generate answers using the [OpenChat-3.5](https://huggingface.co/openchat/openchat-3.5-1210) LLM.
+
+Load the dataset:
+
+```python
+## Install HuggingFace Datasets using "pip install datasets"
+from datasets import load_dataset
+from haystack import Document, Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder
+from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+## Import LlamaCppGenerator
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+
+## Load first 100 rows of the Simple Wikipedia Dataset from HuggingFace
+dataset = load_dataset("pszemraj/simple_wikipedia", split="validation[:100]")
+
+docs = [
+ Document(
+ content=doc["text"],
+ meta={
+ "title": doc["title"],
+ "url": doc["url"],
+ },
+ )
+ for doc in dataset
+]
+```
+
+Index the documents to the `InMemoryDocumentStore` using the `SentenceTransformersDocumentEmbedder` and `DocumentWriter`:
+
+```python
+doc_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+doc_embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+
+## Indexing Pipeline
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(instance=doc_embedder, name="DocEmbedder")
+indexing_pipeline.add_component(instance=DocumentWriter(document_store=doc_store), name="DocWriter")
+indexing_pipeline.connect(connect_from="DocEmbedder", connect_to="DocWriter")
+
+indexing_pipeline.run({"DocEmbedder": {"documents": docs}})
+```
+
+Create the Retrieval Augmented Generation (RAG) pipeline and add the `LlamaCppGenerator` to it:
+
+```python
+## Prompt Template for the https://huggingface.co/openchat/openchat-3.5-1210 LLM
+prompt_template = """GPT4 Correct User: Answer the question using the provided context.
+Question: {{question}}
+Context:
+{% for doc in documents %}
+ {{ doc.content }}
+{% endfor %}
+<|end_of_turn|>
+GPT4 Correct Assistant:
+"""
+
+rag_pipeline = Pipeline()
+
+text_embedder = SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+
+## Load the LLM using LlamaCppGenerator
+model_path = "openchat-3.5-1210.Q3_K_S.gguf"
+generator = LlamaCppGenerator(model=model_path, n_ctx=4096, n_batch=128)
+
+rag_pipeline.add_component(
+ instance=text_embedder,
+ name="text_embedder",
+)
+rag_pipeline.add_component(instance=InMemoryEmbeddingRetriever(document_store=doc_store, top_k=3), name="retriever")
+rag_pipeline.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+rag_pipeline.add_component(instance=generator, name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+
+rag_pipeline.connect("text_embedder", "retriever")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+rag_pipeline.connect("llm.replies", "answer_builder.replies")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+```
+
+Run the pipeline:
+
+```python
+question = "Which year did the Joker movie release?"
+result = rag_pipeline.run(
+ {
+ "text_embedder": {"text": question},
+ "prompt_builder": {"question": question},
+ "llm": {"generation_kwargs": {"max_tokens": 128, "temperature": 0.1}},
+ "answer_builder": {"query": question},
+ }
+)
+
+generated_answer = result["answer_builder"]["answers"][0]
+print(generated_answer.data)
+## The Joker movie was released on October 4, 2019.
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/llamastackchatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/llamastackchatgenerator.mdx
new file mode 100644
index 0000000000..9b60154551
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/llamastackchatgenerator.mdx
@@ -0,0 +1,147 @@
+---
+title: "LlamaStackChatGenerator"
+id: llamastackchatgenerator
+slug: "/llamastackchatgenerator"
+description: "This component enables chat completions using any model made available by inference providers on a Llama Stack server."
+---
+
+# LlamaStackChatGenerator
+
+This component enables chat completions using any model made available by inference providers on a Llama Stack server.
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [Llama.cpp](/reference/integrations-llama-cpp) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/llama_cpp | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The name of the model to use for chat completion.
This depends on the inference provider used for the Llama Stack Server. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of alternative replies of the model to the input chat | +| **API reference** | [Llama Stack](/reference/integrations-llama-stack) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/llama_stack | + +
+
+## Overview
+
+[Llama Stack](https://llama-stack.readthedocs.io/en/latest/index.html) provides building blocks and unified APIs to streamline the development of AI applications across various environments.
+
+The `LlamaStackChatGenerator` enables you to access any LLMs exposed by inference providers hosted on a Llama Stack server. It abstracts away the underlying provider details, allowing you to reuse the same client-side code regardless of the inference backend. For a list of supported providers and configuration options, refer to the [Llama Stack documentation](https://llama-stack.readthedocs.io/en/latest/providers/inference/index.html).
+
+This component uses the same `ChatMessage` format as other Haystack Chat Generators for structured input and output. For more information, see the [ChatMessage documentation](../../concepts/data-classes/chatmessage.mdx).
+
+### Tool Support
+
+`LlamaStackChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.llama_stack import LlamaStackChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = LlamaStackChatGenerator(
+ model="ollama/llama3.2:3b",
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+## Initialization
+
+To use this integration, you must have:
+
+- A running instance of a Llama Stack server (local or remote)
+- A valid model name supported by your selected inference provider
+
+Then initialize the `LlamaStackChatGenerator` by specifying the `model` name or ID. The value depends on the inference provider running on your server.
+
+**Examples:**
+
+- For Ollama: `model="ollama/llama3.2:3b"`
+- For vLLM: `model="meta-llama/Llama-3.2-3B"`
+
+**Note:** Switching the inference provider only requires updating the model name.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+To start using this integration, install the package with:
+
+```shell
+pip install llama-stack-haystack
+```
+
+### On its own
+
+```python
+import os
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.llama_stack import LlamaStackChatGenerator
+
+client = LlamaStackChatGenerator(model="ollama/llama3.2:3b")
+response = client.run(
+ [ChatMessage.from_user("What are Agentic Pipelines? Be brief.")]
+)
+print(response["replies"])
+```
+
+#### With Streaming
+
+```python
+import os
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.llama_stack import LlamaStackChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+
+client = LlamaStackChatGenerator(model="ollama/llama3.2:3b",
+ streaming_callback=print_streaming_chunk)
+response = client.run(
+ [ChatMessage.from_user("What are Agentic Pipelines? Be brief.")]
+)
+print(response["replies"])
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.llama_stack import LlamaStackChatGenerator
+
+prompt_builder = ChatPromptBuilder()
+llm = LlamaStackChatGenerator(model="ollama/llama3.2:3b")
+
+pipe = Pipeline()
+pipe.add_component("builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("builder.prompt", "llm.messages")
+
+messages = [
+ ChatMessage.from_system("Give brief answers."),
+ ChatMessage.from_user("Tell me about {{city}}")
+]
+
+response = pipe.run(
+ data={"builder": {"template": messages,
+ "template_variables": {"city": "Berlin"}}}
+)
+print(response)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/metallamachatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/metallamachatgenerator.mdx
new file mode 100644
index 0000000000..0ee01d8cd3
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/metallamachatgenerator.mdx
@@ -0,0 +1,199 @@
+---
+title: "MetaLlamaChatGenerator"
+id: metallamachatgenerator
+slug: "/metallamachatgenerator"
+description: "This component enables chat completion with any model hosted available with Meta Llama API."
+---
+
+# MetaLlamaChatGenerator
+
+This component enables chat completion with any model hosted available with Meta Llama API.
+
+This depends on the inference provider used for the Llama Stack Server. | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat | +| **Output variables** | `replies`: A list of alternative replies of the model to the input chat | +| **API reference** | [Llama Stack](/reference/integrations-llama-stack) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/llama_stack | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Meta Llama API key. Can be set with `LLAMA_API_KEY` env variable or passed to `init()` method. |
+| **Mandatory run variables** | `messages`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **API reference** | [Meta Llama API](/reference/integrations-meta-llama) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/meta_llama |
+
+
+
+## Overview
+
+The `MetaLlamaChatGenerator` enables you to use multiple Meta Llama models by making chat completion calls to the Meta [Llama API](https://llama.developer.meta.com/?utm_source=partner-haystack&utm_medium=website). The default model is `Llama-4-Scout-17B-16E-Instruct-FP8`.
+
+Currently available models are:
+
+
+
+| | | | | |
+| --- | --- | --- | --- | --- |
+| Model ID | Input context length | Output context length | Input Modalities | Output Modalities |
+| `Llama-4-Scout-17B-16E-Instruct-FP8` | 128k | 4028 | Text, Image | Text |
+| `Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | Text, Image | Text |
+| `Llama-3.3-70B-Instruct` | 128k | 4028 | Text | Text |
+| `Llama-3.3-8B-Instruct` | 128k | 4028 | Text | Text |
+
+
+This component uses the same `ChatMessage` format as other Haystack Chat Generators for structured input and output. For more information, see the [ChatMessage documentation](../../concepts/data-classes/chatmessage.mdx).
+
+### Tool Support
+
+`MetaLlamaChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.meta_llama import MetaLlamaChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = MetaLlamaChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Initialization
+
+To use this integration, you must have a Meta Llama API key. You can provide it with the `LLAMA_API_KEY` environment variable or by using a [Secret](../../concepts/secret-management.mdx).
+
+Then, install the `meta-llama-haystack` integration:
+
+```shell
+pip install meta-llama-haystack
+```
+
+### Streaming
+
+`MetaLlamaChatGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM, allowing tokens to be emitted as they are generated. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.meta_llama import MetaLlamaChatGenerator
+
+llm = MetaLlamaChatGenerator()
+response = llm.run(
+ [ChatMessage.from_user("What are Agentic Pipelines? Be brief.")]
+)
+print(response["replies"][0].text)
+
+```
+
+With streaming and model routing:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.meta_llama import MetaLlamaChatGenerator
+
+llm = MetaLlamaChatGenerator(model="Llama-3.3-8B-Instruct",
+streaming_callback=lambda chunk: print(chunk.content, end="", flush=True))
+
+response = llm.run(
+ [ChatMessage.from_user("What are Agentic Pipelines? Be brief.")]
+ )
+
+## check the model used for the response
+print("\n\n Model used: ", response["replies"][0].meta["model"])
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.meta_llama import MetaLlamaChatGenerator
+
+llm = MetaLlamaChatGenerator(model="Llama-4-Scout-17B-16E-Instruct-FP8")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(content_parts=[
+ "What does the image show? Max 5 words.",
+ image
+ ])
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+### In a pipeline
+
+```python
+## To run this example, you will need to set a `LLAMA_API_KEY` environment variable.
+
+from haystack import Document, Pipeline
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.utils import Secret
+
+from haystack_integrations.components.generators.meta_llama import MetaLlamaChatGenerator
+
+## Write documents to InMemoryDocumentStore
+document_store = InMemoryDocumentStore()
+document_store.write_documents(
+ [
+ Document(content="My name is Jean and I live in Paris."),
+ Document(content="My name is Mark and I live in Berlin."),
+ Document(content="My name is Giorgio and I live in Rome."),
+ ]
+)
+
+## Build a RAG pipeline
+prompt_template = [
+ ChatMessage.from_user(
+ "Given these documents, answer the question.\n"
+ "Documents:\n{% for doc in documents %}{{ doc.content }}{% endfor %}\n"
+ "Question: {{question}}\n"
+ "Answer:"
+ )
+]
+
+## Define required variables explicitly
+prompt_builder = ChatPromptBuilder(template=prompt_template, required_variables={"question", "documents"})
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+llm = MetaLlamaChatGenerator(
+ api_key=Secret.from_env_var("LLAMA_API_KEY"),
+ streaming_callback=print_streaming_chunk,
+)
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm.messages")
+
+## Ask a question
+question = "Who lives in Paris?"
+rag_pipeline.run(
+ {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ }
+)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/mistralchatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/mistralchatgenerator.mdx
new file mode 100644
index 0000000000..d5fb5b55fd
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/mistralchatgenerator.mdx
@@ -0,0 +1,169 @@
+---
+title: "MistralChatGenerator"
+id: mistralchatgenerator
+slug: "/mistralchatgenerator"
+description: "This component enables chat completion using Mistral’s text generation models."
+---
+
+# MistralChatGenerator
+
+This component enables chat completion using Mistral’s text generation models.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The Mistral API key. Can be set with `MISTRAL_API_KEY` env var. |
+| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | + +
+
+## Overview
+
+This integration supports Mistral’s models provided through the generative endpoint. For a full list of available models, check out the [Mistral documentation](https://docs.mistral.ai/platform/endpoints/#generative-endpoints).
+
+`MistralChatGenerator` needs a Mistral API key to work. You can write this key in:
+
+- The `api_key` init parameter using [Secret API](../../concepts/secret-management.mdx)
+- The `MISTRAL_API_KEY` environment variable (recommended)
+
+Currently, available models are:
+
+- `mistral-tiny` (default)
+- `mistral-small`
+- `mistral-medium`(soon to be deprecated)
+- `mistral-large-latest`
+- `codestral-latest`
+
+This component needs a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+Refer to the [Mistral API documentation](https://docs.mistral.ai/api/#operation/createChatCompletion) for more details on the parameters supported by the Mistral API, which you can provide with `generation_kwargs` when running the component.
+
+### Tool Support
+
+`MistralChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = MistralChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Install the `mistral-haystack` package to use the `MistralChatGenerator`:
+
+```shell
+pip install mistral-haystack
+```
+
+#### On its own
+
+```python
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+generator = MistralChatGenerator(api_key=Secret.from_env_var("MISTRAL_API_KEY"), streaming_callback=print_streaming_chunk)
+message = ChatMessage.from_user("What's Natural Language Processing? Be brief.")
+print(generator.run([message]))
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+
+llm = MistralChatGenerator(model="pixtral-12b-2409")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(content_parts=[
+ "What does the image show? Max 5 words.",
+ image
+ ])
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+#### In a Pipeline
+
+Below is an example RAG Pipeline where we answer questions based on the URL contents. We add the contents of the URL into our `messages` in the `ChatPromptBuilder` and generate an answer with the `MistralChatGenerator`.
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.utils import print_streaming_chunk
+from haystack.components.fetchers import LinkContentFetcher
+from haystack.components.converters import HTMLToDocument
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+
+fetcher = LinkContentFetcher()
+converter = HTMLToDocument()
+prompt_builder = ChatPromptBuilder(variables=["documents"])
+llm = MistralChatGenerator(streaming_callback=print_streaming_chunk, model='mistral-small')
+
+message_template = """Answer the following question based on the contents of the article: {{query}}\n
+ Article: {{documents[0].content}} \n
+ """
+messages = [ChatMessage.from_user(message_template)]
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(name="fetcher", instance=fetcher)
+rag_pipeline.add_component(name="converter", instance=converter)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+
+rag_pipeline.connect("fetcher.streams", "converter.sources")
+rag_pipeline.connect("converter.documents", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder.prompt", "llm.messages")
+
+question = "What are the capabilities of Mixtral?"
+
+result = rag_pipeline.run(
+ {
+ "fetcher": {"urls": ["https://mistral.ai/news/mixtral-of-experts"]},
+ "prompt_builder": {"template_variables": {"query": question}, "template": messages},
+
+ "llm": {"generation_kwargs": {"max_tokens": 165}},
+ },
+)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Web QA with Mixtral-8x7B-Instruct-v0.1](https://haystack.deepset.ai/cookbook/mixtral-8x7b-for-web-qa)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/nvidiachatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/nvidiachatgenerator.mdx
new file mode 100644
index 0000000000..0df6e9715b
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/nvidiachatgenerator.mdx
@@ -0,0 +1,138 @@
+---
+title: "NvidiaChatGenerator"
+id: nvidiachatgenerator
+slug: "/nvidiachatgenerator"
+description: "This Generator enables chat completion using Nvidia-hosted models."
+---
+
+# NvidiaChatGenerator
+
+This Generator enables chat completion using Nvidia-hosted models.
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Mistral](/reference/integrations-mistral) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mistral | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: API key for the NVIDIA NIM. Can be set with `NVIDIA_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **API reference** | [NVIDIA API](https://build.nvidia.com/models) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia |
+
+
+
+## Overview
+
+`NvidiaChatGenerator` enables chat completions using NVIDIA's generative models via the NVIDIA API. It is compatible with the [ChatMessage](../../concepts/data-classes/chatmessage.mdx) format for both input and output, ensuring seamless integration in chat-based pipelines.
+
+You can use LLMs self-hosted with NVIDIA NIM or models hosted on the [NVIDIA API catalog](https://build.nvidia.com/explore/discover). The default model for this component is `meta/llama-3.1-8b-instruct`.
+
+To use this integration, you must have a NVIDIA API key. You can provide it with the `NVIDIA_API_KEY` environment variable or by using a [Secret](../../concepts/secret-management.mdx).
+
+### Tool Support
+
+`NvidiaChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = NvidiaChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+This generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+## Usage
+
+To start using `NvidiaChatGenerator`, first, install the `nvidia-haystack` package:
+
+```shell
+pip install nvidia-haystack
+```
+
+You can use the `NvidiaChatGenerator` with all the LLMs available in the [NVIDIA API catalog](https://docs.api.nvidia.com/nim/reference) or a model deployed with NVIDIA NIM. Follow the [NVIDIA NIM for LLMs Playbook](https://developer.nvidia.com/docs/nemo-microservices/inference/playbooks/nmi_playbook.html) to learn how to deploy your desired model on your infrastructure.
+
+### On its own
+
+ To use LLMs from the NVIDIA API catalog, you need to specify the correct `api_url` if needed (the default one is `https://integrate.api.nvidia.com/v1`), and your API key. You can get your API key directly from the [catalog website](https://build.nvidia.com/explore/discover).
+
+```python
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = NvidiaChatGenerator(
+ model="meta/llama-3.1-8b-instruct", # or any supported NVIDIA model
+ api_key=Secret.from_env_var("NVIDIA_API_KEY")
+)
+
+messages = [ChatMessage.from_user("What's Natural Language Processing? Be brief.")]
+result = generator.run(messages)
+print(result["replies"])
+print(result["meta"])
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+
+llm = NvidiaChatGenerator(model="meta/llama-3.2-11b-vision-instruct")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(content_parts=[
+ "What does the image show? Max 5 words.",
+ image
+ ])
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+### In a Pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+from haystack.utils import Secret
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", NvidiaChatGenerator(
+ model="meta/llama-3.1-8b-instruct",
+ api_key=Secret.from_env_var("NVIDIA_API_KEY")
+))
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system("You are an assistant giving out valuable information to language learners.")
+messages = [system_message, ChatMessage.from_user("What's the official language of {{ country }}?")]
+
+res = pipe.run(data={"prompt_builder": {"template_variables": {"country": country}, "template": messages}})
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/nvidiagenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/nvidiagenerator.mdx
new file mode 100644
index 0000000000..108f146dfb
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/nvidiagenerator.mdx
@@ -0,0 +1,144 @@
+---
+title: "NvidiaGenerator"
+id: nvidiagenerator
+slug: "/nvidiagenerator"
+description: "This Generator enables text generation using Nvidia-hosted models."
+---
+
+# NvidiaGenerator
+
+This Generator enables text generation using Nvidia-hosted models.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: API key for the NVIDIA NIM. Can be set with `NVIDIA_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [Nvidia](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | + +
+
+## Overview
+
+The `NvidiaGenerator` provides an interface for generating text using LLMs self-hosted with NVIDIA NIM or models hosted on the [NVIDIA API catalog](https://build.nvidia.com/explore/discover).
+
+## Usage
+
+To start using `NvidiaGenerator`, first, install the `nvidia-haystack` package:
+
+```shell
+pip install nvidia-haystack
+```
+
+You can use the `NvidiaGenerator` with all the LLMs available in the [NVIDIA API catalog](https://docs.api.nvidia.com/nim/reference) or a model deployed with NVIDIA NIM. Follow the [NVIDIA NIM for LLMs Playbook](https://developer.nvidia.com/docs/nemo-microservices/inference/playbooks/nmi_playbook.html) to learn how to deploy your desired model on your infrastructure.
+
+### On its own
+
+To use LLMs from the NVIDIA API catalog, you need to specify the correct `api_url` and your API key. You can get your API key directly from the [catalog website](https://build.nvidia.com/explore/discover).
+
+The `NvidiaGenerator` needs an Nvidia API key to work. It uses the `NVIDIA_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`, as in the following example.
+
+```python
+from haystack.utils.auth import Secret
+from haystack_integrations.components.generators.nvidia import NvidiaGenerator
+
+generator = NvidiaGenerator(
+ model="meta/llama3-70b-instruct",
+ api_url="https://integrate.api.nvidia.com/v1",
+ api_key=Secret.from_token("`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [Nvidia](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of LLM’s alternative replies |
+| **API reference** | [Ollama](/reference/integrations-ollama) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama |
+
+
+
+## Overview
+
+[Ollama](https://github.com/jmorganca/ollama) is a project focused on running LLMs locally. Internally, it uses the quantized GGUF format by default. This means it is possible to run LLMs on standard machines (even without GPUs) without having to handle complex installation procedures.
+
+`OllamaChatGenerator` supports models running on Ollama, such as `llama2` and `mixtral`. Find the full list of supported models [here](https://ollama.ai/library).
+
+`OllamaChatGenerator` needs a `model` name and a `url` to work. By default, it uses `"orca-mini"` model and `"http://localhost:11434"` url.
+
+The way to operate with `OllamaChatGenerator` is by using `ChatMessage` objects. [ChatMessage](../../concepts/data-classes/chatmessage.mdx) is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata. See the [usage](#usage) section for an example.
+
+### Tool Support
+
+`OllamaChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.ollama import OllamaChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = OllamaChatGenerator(
+ model="llama2",
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+You can stream output as it’s generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+## Configure any `Generator` or `ChatGenerator` with a streaming callback
+component = SomeGeneratorOrChatGenerator(streaming_callback=print_streaming_chunk)
+
+## If this is a `ChatGenerator`, pass a list of messages:
+## from haystack.dataclasses import ChatMessage
+## component.run([ChatMessage.from_user("Your question here")])
+
+## If this is a (non-chat) `Generator`, pass a prompt:
+## component.run({"prompt": "Your prompt here"})
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+## Usage
+
+1. You need a running instance of Ollama. The installation instructions are [in the Ollama GitHub repository](https://github.com/jmorganca/ollama).
+ A fast way to run Ollama is using Docker:
+
+```bash
+docker run -d -p 11434:11434 --name ollama ollama/ollama:latest
+```
+
+2. You need to download or pull the desired LLM. The model library is available on the [Ollama website](https://ollama.ai/library).
+ If you are using Docker, you can, for example, pull the Zephyr model:
+
+```bash
+docker exec ollama ollama pull zephyr
+```
+
+If you already installed Ollama in your system, you can execute:
+
+```bash
+ollama pull zephyr
+```
+
+:::tip Choose a specific version of a model
+
+You can also specify a tag to choose a specific (quantized) version of your model. The available tags are shown in the model card of the Ollama models library. This is an [example](https://ollama.ai/library/zephyr/tags) for Zephyr.
+In this case, simply run
+
+```shell
+# ollama pull model:tag
+ollama pull zephyr:7b-alpha-q3_K_S
+```
+:::
+
+3. You also need to install the `ollama-haystack` package:
+
+```bash
+pip install ollama-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.ollama import OllamaChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = OllamaChatGenerator(model="zephyr",
+ url = "http://localhost:11434",
+ generation_kwargs={
+ "num_predict": 100,
+ "temperature": 0.9,
+ })
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
+ChatMessage.from_user("What's Natural Language Processing?")]
+
+print(generator.run(messages=messages))
+>> {
+ "replies": [
+ ChatMessage(
+ _role=
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | + +
+
+## Overview
+
+`OllamaGenerator` provides an interface to generate text using an LLM running on Ollama.
+
+`OllamaGenerator` needs a `model` name and a `url` to work. By default, it uses `"orca-mini"` model and `"http://localhost:11434"` url.
+
+[Ollama](https://github.com/jmorganca/ollama) is a project focused on running LLMs locally. Internally, it uses the quantized GGUF format by default. This means it is possible to run LLMs on standard machines (even without GPUs) without having to go through complex installation procedures.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+1. You need a running instance of Ollama. You can find the installation instructions [here](https://github.com/jmorganca/ollama).
+ A fast way to run Ollama is using Docker:
+
+```shell
+docker run -d -p 11434:11434 --name ollama ollama/ollama:latest
+```
+
+2. You need to download or pull the desired LLM. The model library is available on the [Ollama website](https://ollama.ai/library).
+ If you are using Docker, you can, for example, pull the Zephyr model:
+
+```shell
+docker exec ollama ollama pull zephyr
+```
+
+If you have already installed Ollama in your system, you can execute:
+
+```shell
+ollama pull zephyr
+```
+
+:::tip Choose a specific version of a model
+
+You can also specify a tag to choose a specific (quantized) version of your model. The available tags are shown in the model card of the Ollama models library. This is an [example](https://ollama.ai/library/zephyr/tags) for Zephyr.
+In this case, simply run
+
+```shell
+# ollama pull model:tag
+ollama pull zephyr:7b-alpha-q3_K_S
+```
+:::
+
+3. You also need to install the `ollama-haystack` package:
+
+```shell
+pip install ollama-haystack
+```
+
+### On its own
+
+Here's how the `OllamaGenerator` would work just on its own:
+
+```python
+from haystack_integrations.components.generators.ollama import OllamaGenerator
+
+generator = OllamaGenerator(model="zephyr",
+ url = "http://localhost:11434",
+ generation_kwargs={
+ "num_predict": 100,
+ "temperature": 0.9,
+ })
+
+print(generator.run("Who is the best American actor?"))
+
+## {'replies': ['I do not have the ability to form opinions or preferences.
+## However, some of the most acclaimed american actors in recent years include
+## denzel washington, tom hanks, leonardo dicaprio, matthew mcconaughey...'],
+## 'meta': [{'model': 'zephyr', ...}]}
+```
+
+### In a Pipeline
+
+```python
+from haystack_integrations.components.generators.ollama import OllamaGenerator
+
+from haystack import Pipeline, Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: {{ query }}?
+"""
+
+docstore = InMemoryDocumentStore()
+docstore.write_documents([Document(content="I really like summer"),
+ Document(content="My favorite sport is soccer"),
+ Document(content="I don't like reading sci-fi books"),
+ Document(content="I don't like crowded places"),])
+
+generator = OllamaGenerator(model="zephyr",
+ url = "http://localhost:11434",
+ generation_kwargs={
+ "num_predict": 100,
+ "temperature": 0.9,
+ })
+
+pipe = Pipeline()
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("llm", generator)
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "llm")
+
+result = pipe.run({"prompt_builder": {"query": query},
+ "retriever": {"query": query}})
+
+print(result)
+
+## {'llm': {'replies': ['Based on the provided context, it seems that you enjoy
+## soccer and summer. Unfortunately, there is no direct information given about
+## what else you enjoy...'],
+## 'meta': [{'model': 'zephyr', ...]}}
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/openaichatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/openaichatgenerator.mdx
new file mode 100644
index 0000000000..41a34d0591
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/openaichatgenerator.mdx
@@ -0,0 +1,236 @@
+---
+title: "OpenAIChatGenerator"
+id: openaichatgenerator
+slug: "/openaichatgenerator"
+description: "`OpenAIChatGenerator` enables chat completion using OpenAI’s large language models (LLMs)."
+---
+
+# OpenAIChatGenerator
+
+`OpenAIChatGenerator` enables chat completion using OpenAI's large language models (LLMs).
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count and others | +| **API reference** | [Ollama](/reference/integrations-ollama) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ollama | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of alternative replies of the LLM to the input chat |
+| **API reference** | [Generators](/reference/generators-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/openai.py |
+
+
+
+## Overview
+
+`OpenAIChatGenerator` supports OpenAI models starting from gpt-3.5-turbo and later (gpt-4, gpt-4-turbo, and so on).
+
+`OpenAIChatGenerator` needs an OpenAI key to work. It uses an ` OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```python
+generator = OpenAIChatGenerator(model="gpt-4o-mini")
+```
+
+Then, the component needs a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata. See the [usage](#usage) section for an example.
+
+You can pass any chat completion parameters valid for the `openai.ChatCompletion.create` method directly to `OpenAIChatGenerator` using the `generation_kwargs` parameter, both at initialization and to `run()` method. For more details on the parameters supported by the OpenAI API, refer to the [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
+
+`OpenAIChatGenerator` can support custom deployments of your OpenAI models through the `api_base_url` init parameter.
+
+### Structured Output
+
+`OpenAIChatGenerator` supports structured output generation, allowing you to receive responses in a predictable format. You can use Pydantic models or JSON schemas to define the structure of the output through the `response_format` parameter in `generation_kwargs`.
+
+This is useful when you need to extract structured data from text or generate responses that match a specific format.
+
+```python
+from pydantic import BaseModel
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+class NobelPrizeInfo(BaseModel):
+ recipient_name: str
+ award_year: int
+ category: str
+ achievement_description: str
+ nationality: str
+
+client = OpenAIChatGenerator(
+ model="gpt-4o-2024-08-06",
+ generation_kwargs={"response_format": NobelPrizeInfo}
+)
+
+response = client.run(messages=[
+ ChatMessage.from_user(
+ "In 2021, American scientist David Julius received the Nobel Prize in"
+ " Physiology or Medicine for his groundbreaking discoveries on how the human body"
+ " senses temperature and touch."
+ )
+])
+print(response["replies"][0].text)
+
+>> {"recipient_name":"David Julius","award_year":2021,"category":"Physiology or Medicine",
+>> "achievement_description":"David Julius was awarded for his transformative findings
+>> regarding the molecular mechanisms underlying the human body's sense of temperature
+>> and touch. Through innovative experiments, he identified specific receptors responsible
+>> for detecting heat and mechanical stimuli, ranging from gentle touch to pain-inducing
+>> pressure.","nationality":"American"}
+```
+
+:::info Model Compatibility and Limitations
+
+- Pydantic models and JSON schemas are supported for latest models starting from `gpt-4o-2024-08-06`.
+- Older models only support basic JSON mode through `{"type": "json_object"}`. For details, see [OpenAI JSON mode documentation](https://platform.openai.com/docs/guides/structured-outputs#json-mode).
+- Streaming limitation: When using streaming with structured outputs, you must provide a JSON schema instead of a Pydantic model for `response_format`.
+- For complete information, check the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+:::
+
+### Streaming
+
+You can stream output as it’s generated. Pass a callback to `streaming_callback`. Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+## Configure any `Generator` or `ChatGenerator` with a streaming callback
+component = SomeGeneratorOrChatGenerator(streaming_callback=print_streaming_chunk)
+
+## If this is a `ChatGenerator`, pass a list of messages:
+## from haystack.dataclasses import ChatMessage
+## component.run([ChatMessage.from_user("Your question here")])
+
+## If this is a (non-chat) `Generator`, pass a prompt:
+## component.run({"prompt": "Your prompt here"})
+```
+
+:::info
+Streaming works only with a single response. If a provider supports multiple candidates, set `n=1`.
+:::
+
+See our [Streaming Support](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+## Usage
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+client = OpenAIChatGenerator()
+response = client.run(
+ [ChatMessage.from_user("What's Natural Language Processing? Be brief.")]
+)
+print(response)
+
+>> {'replies': [ChatMessage(_role=
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/openai.py | + +
+
+## Overview
+
+`OpenAIGenerator` supports OpenAI models starting from gpt-3.5-turbo and later (gpt-4, gpt-4-turbo, and so on).
+
+`OpenAIGenerator` needs an OpenAI key to work. It uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```
+generator = OpenAIGenerator(api_key=Secret.from_token("`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Generators](/reference/generators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/openai.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An OpenRouter API key. Can be set with `OPENROUTER_API_KEY` env variable or passed to `init()` method. |
+| **Mandatory run variables** | `messages`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [ChatMessage](../../concepts/data-classes/chatmessage.mdx) objects |
+| **API reference** | [OpenRouter](/reference/integrations-openrouter) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/openrouter |
+
+
+
+## Overview
+
+The `OpenRouterChatGenerator` enables you to use models from multiple providers (such as `openai/gpt-4o`, `anthropic/claude-3.5-sonnet`, and others) by making chat completion calls to the [OpenRouter API](https://openrouter.ai/docs/quickstart).
+
+This generator also supports OpenRouter-specific features such as:
+
+- Provider routing and model fallback that are configurable with the `generation_kwargs` parameter during initialization or runtime.
+- Custom HTTP headers that can be supplied using the `extra_headers` parameter.
+
+This component uses the same `ChatMessage` format as other Haystack Chat Generators for structured input and output. For more information, see the [ChatMessage documentation](../../concepts/data-classes/chatmessage.mdx).
+
+### Tool Support
+
+`OpenRouterChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = OpenRouterChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Initialization
+
+To use this integration, you must have an active OpenRouter subscription with sufficient credits and an API key. You can provide it with the `OPENROUTER_API_KEY` environment variable or by using a [Secret](../../concepts/secret-management.mdx).
+
+Then, install the `openrouter-haystack` integration:
+
+```shell
+pip install openrouter-haystack
+```
+
+### Streaming
+
+`OpenRouterChatGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM, allowing tokens to be emitted as they are generated. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator
+
+client = OpenRouterChatGenerator()
+response = client.run(
+ [ChatMessage.from_user("What are Agentic Pipelines? Be brief.")]
+)
+print(response["replies"][0].text)
+```
+
+With streaming and model routing:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator
+
+client = OpenRouterChatGenerator(model="openrouter/auto",
+streaming_callback=lambda chunk: print(chunk.content, end="", flush=True))
+
+response = client.run(
+ [ChatMessage.from_user("What are Agentic Pipelines? Be brief.")]
+ )
+
+## check the model used for the response
+print("\n\n Model used: ", response["replies"][0].meta["model"])
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator
+
+llm = OpenRouterChatGenerator(model="anthropic/claude-3-5-sonnet")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(content_parts=[
+ "What does the image show? Max 5 words.",
+ image
+ ])
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator
+
+prompt_builder = ChatPromptBuilder()
+llm = OpenRouterChatGenerator(model="openai/gpt-4o-mini")
+
+pipe = Pipeline()
+pipe.add_component("builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("builder.prompt", "llm.messages")
+
+messages = [
+ ChatMessage.from_system("Give brief answers."),
+ ChatMessage.from_user("Tell me about {{city}}")
+]
+
+response = pipe.run(
+ data={"builder": {"template": messages,
+ "template_variables": {"city": "Berlin"}}}
+)
+print(response)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/sagemakergenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/sagemakergenerator.mdx
new file mode 100644
index 0000000000..8e6988681f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/sagemakergenerator.mdx
@@ -0,0 +1,107 @@
+---
+title: "SagemakerGenerator"
+id: sagemakergenerator
+slug: "/sagemakergenerator"
+description: "This component enables text generation using LLMs deployed on Amazon Sagemaker."
+---
+
+# SagemakerGenerator
+
+This component enables text generation using LLMs deployed on Amazon Sagemaker.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The model to use
`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Amazon Sagemaker](/reference/integrations-amazon-sagemaker) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_sagemaker | + +
+
+`SagemakerGenerator` allows you to make use of models deployed on [AWS SageMaker](https://docs.aws.amazon.com/sagemaker/latest/dg/whatis.html).
+
+## Parameters Overview
+
+`SagemakerGenerator` needs AWS credentials to work. Set the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.
+
+You also need to specify your Sagemaker endpoint at initialization time for the component to work. Pass the endpoint name to the `model` parameter like this:
+
+```python
+generator = SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-instruct-bf16")
+```
+
+Additionally, you can pass any text generation parameters valid for your specific model directly to `SagemakerGenerator` using the `generation_kwargs` parameter, both at initialization and to `run()` method.
+
+If your model also needs custom attributes, pass those as a dictionary at initialization time by setting the `aws_custom_attributes` parameter.
+
+One notable family of models that needs these custom parameters is Llama2, which needs to be initialized with `{"accept_eula": True}` :
+
+```python
+generator = SagemakerGenerator(
+ model="jumpstart-dft-meta-textgenerationneuron-llama-2-7b",
+ aws_custom_attributes={"accept_eula": True}
+)
+```
+
+## Usage
+
+You need to install `amazon-sagemaker-haystack` package to use the `SagemakerGenerator`:
+
+```shell
+pip install amazon-sagemaker-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.amazon_sagemaker import SagemakerGenerator
+
+client = SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-instruct-bf16")
+client.warm_up()
+response = client.run("Briefly explain what NLP is in one sentence.")
+print(response)
+
+>>> {'replies': ["Natural Language Processing (NLP) is a subfield of artificial intelligence and computational linguistics that focuses on the interaction between computers and human languages..."],
+ 'metadata': [{}]}
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack_integrations.components.generators.amazon_sagemaker import SagemakerGenerator
+from haystack import Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders import PromptBuilder
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: What's the official language of {{ country }}?
+"""
+pipe = Pipeline()
+
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("llm", SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-instruct-bf16"))
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "llm")
+
+pipe.run({
+ "prompt_builder": {
+ "country": "France"
+ }
+})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/stackitchatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/stackitchatgenerator.mdx
new file mode 100644
index 0000000000..99180400ff
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/stackitchatgenerator.mdx
@@ -0,0 +1,113 @@
+---
+title: "STACKITChatGenerator"
+id: stackitchatgenerator
+slug: "/stackitchatgenerator"
+description: "This component enables chat completions using the STACKIT API."
+---
+
+# STACKITChatGenerator
+
+This component enables chat completions using the STACKIT API.
+
+`aws_access_key_id`: AWS access key ID. Can be set with `AWS_ACCESS_KEY_ID` env var.
`aws_secret_access_key`: AWS secret access key. Can be set with `AWS_SECRET_ACCESS_KEY` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Amazon Sagemaker](/reference/integrations-amazon-sagemaker) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_sagemaker | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `model`: The model used through the STACKIT API |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects
`meta`: A list of dictionaries with the metadata associated with each reply (such as token count, finish reason, and so on) | +| **API reference** | [STACKIT](/reference/integrations-stackit) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit | + +
+
+## Overview
+
+`STACKITChatGenerator` enables text generation models served by STACKIT through their API.
+
+### Parameters
+
+To use the `STACKITChatGenerator`, ensure you have set a `STACKIT_API_KEY` as an environment variable. Alternatively, provide the API key as another environment variable or a token by setting
+`api_key` and using Haystack’s [secret management](../../concepts/secret-management.mdx).
+
+Set your preferred supported model with the `model` parameter when initializing the component. See the full list of all supported models on the [STACKIT website](https://docs.stackit.cloud/stackit/en/models-licenses-319914532.html).
+
+Optionally, you can change the default `api_base_url`, which is `"https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1"`.
+
+You can pass any text generation parameters valid for the STACKIT Chat Completion API directly to this component with the `generation_kwargs` parameter in the init or run methods.
+
+The component needs a list of `ChatMessage` objects to run. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata. Find out more about it [ChatMessage documentation](../../concepts/data-classes/chatmessage.mdx).
+
+### Streaming
+
+This ChatGenerator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly into the output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Install the `stackit-haystack` package to use the `STACKITChatGenerator`:
+
+```shell
+pip install stackit-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.stackit import STACKITChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = STACKITChatGenerator(model="neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8")
+
+result = generator.run([ChatMessage.from_user("Tell me a joke.")])
+print(result)
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.stackit import STACKITChatGenerator
+
+llm = STACKITChatGenerator(model="meta-llama/Llama-3.2-11B-Vision-Instruct")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(content_parts=[
+ "What does the image show? Max 5 words.",
+ image
+ ])
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+### In a pipeline
+
+You can also use `STACKITChatGenerator` in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.components.generators.stackit import STACKITChatGenerator
+
+prompt_builder = ChatPromptBuilder()
+llm = STACKITChatGenerator(model="neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8")
+
+messages = [ChatMessage.from_user("Question: {{question}} \\n")]
+
+pipeline = Pipeline()
+pipeline.add_component("prompt_builder", prompt_builder)
+pipeline.add_component("llm", llm)
+
+pipeline.connect("prompt_builder.prompt", "llm.messages")
+
+result = pipeline.run({"prompt_builder": {"template_variables": {"question": "Tell me a joke."}, "template": messages}})
+
+print(result)
+```
+
+For an example of streaming in a pipeline, refer to the examples in the STACKIT integration [repository](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit/examples) and on its dedicated [integration page](https://haystack.deepset.ai/integrations/stackit).
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/togetheraichatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/togetheraichatgenerator.mdx
new file mode 100644
index 0000000000..7aec276808
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/togetheraichatgenerator.mdx
@@ -0,0 +1,141 @@
+---
+title: "TogetherAIChatGenerator"
+id: togetheraichatgenerator
+slug: "/togetheraichatgenerator"
+description: "This component enables chat completion using models hosted on Together AI."
+---
+
+# TogetherAIChatGenerator
+
+This component enables chat completion using models hosted on Together AI.
+
+`meta`: A list of dictionaries with the metadata associated with each reply (such as token count, finish reason, and so on) | +| **API reference** | [STACKIT](/reference/integrations-stackit) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/stackit | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Together API key. Can be set with `TOGETHER_API_KEY` env var. |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects |
+| **API reference** | [TogetherAI](/reference/integrations-togetherai) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/togetherai |
+
+
+
+## Overview
+
+`TogetherAIChatGenerator` supports models hosted on [Together AI](https://docs.together.ai/intro), such as `meta-llama/Llama-3.3-70B-Instruct-Turbo`. For the full list of supported models, see [Together AI documentation](https://docs.together.ai/docs/chat-models).
+
+This component needs a list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+You can pass any text generation parameters valid for the Together AI chat completion API directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs` parameter in `run` method. For more details on the parameters supported by the Together AI API, see [Together AI API documentation](https://docs.together.ai/reference/chat-completions-1).
+
+To use this integration, you need to have an active TogetherAI subscription with sufficient credits and an API key. You can provide it with:
+
+- The `TOGETHER_API_KEY` environment variable (recommended)
+- The `api_key` init parameter and Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`
+
+By default, the component uses Together AI's OpenAI-compatible base URL `https://api.together.xyz/v1`, which you can override with `api_base_url` if needed.
+
+### Tool Support
+
+`TogetherAIChatGenerator` supports function calling through the `tools` parameter, which accepts flexible tool configurations:
+
+- **A list of Tool objects**: Pass individual tools as a list
+- **A single Toolset**: Pass an entire Toolset directly
+- **Mixed Tools and Toolsets**: Combine multiple Toolsets with standalone tools in a single list
+
+This allows you to organize related tools into logical groups while also including standalone tools as needed.
+
+```python
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.togetherai import TogetherAIChatGenerator
+
+# Create individual tools
+weather_tool = Tool(name="weather", description="Get weather info", ...)
+news_tool = Tool(name="news", description="Get latest news", ...)
+
+# Group related tools into a toolset
+math_toolset = Toolset([add_tool, subtract_tool, multiply_tool])
+
+# Pass mixed tools and toolsets to the generator
+generator = TogetherAIChatGenerator(
+ tools=[math_toolset, weather_tool, news_tool] # Mix of Toolset and Tool objects
+)
+```
+
+For more details on working with tools, see the [Tool](../../tools/tool.mdx) and [Toolset](../../tools/toolset.mdx) documentation.
+
+### Streaming
+
+`TogetherAIChatGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM, allowing tokens to be emitted as they are generated. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+## Usage
+
+Install the `togetherai-haystack` package to use the `TogetherAIChatGenerator`:
+
+```shell
+pip install togetherai-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.togetherai import TogetherAIChatGenerator
+
+client = TogetherAIChatGenerator()
+response = client.run(
+ [ChatMessage.from_user("What are Agentic Pipelines? Be brief.")]
+)
+print(response["replies"][0].text)
+```
+
+With streaming:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.togetherai import TogetherAIChatGenerator
+
+client = TogetherAIChatGenerator(
+ model="meta-llama/Llama-3.3-70B-Instruct-Turbo",
+ streaming_callback=lambda chunk: print(chunk.content, end="", flush=True),
+)
+
+response = client.run(
+ [ChatMessage.from_user("What are Agentic Pipelines? Be brief.")]
+)
+
+# check the model used for the response
+print("\n\nModel used:", response["replies"][0].meta.get("model"))
+```
+
+### In a Pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.togetherai import TogetherAIChatGenerator
+
+prompt_builder = ChatPromptBuilder()
+llm = TogetherAIChatGenerator(model="meta-llama/Llama-3.3-70B-Instruct-Turbo")
+
+pipe = Pipeline()
+pipe.add_component("builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("builder.prompt", "llm.messages")
+
+messages = [
+ ChatMessage.from_system("Give brief answers."),
+ ChatMessage.from_user("Tell me about {{city}}"),
+]
+
+response = pipe.run(
+ data={"builder": {"template": messages,
+ "template_variables": {"city": "Berlin"}}}
+)
+print(response)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/togetheraigenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/togetheraigenerator.mdx
new file mode 100644
index 0000000000..5abb486694
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/togetheraigenerator.mdx
@@ -0,0 +1,148 @@
+---
+title: "TogetherAIGenerator"
+id: togetheraigenerator
+slug: "/togetheraigenerator"
+description: "This component enables text generation using models hosted on Together AI."
+---
+
+# TogetherAIGenerator
+
+This component enables text generation using models hosted on Together AI.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: A Together API key. Can be set with `TOGETHER_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM |
+| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [TogetherAI](/reference/integrations-togetherai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/togetherai | + +
+
+## Overview
+
+`TogetherAIGenerator` supports models hosted on [Together AI](https://docs.together.ai/intro), such as `meta-llama/Llama-3.3-70B-Instruct-Turbo`. For the full list of supported models, see [Together AI documentation](https://docs.together.ai/docs/chat-models).
+
+This component needs a prompt string to operate. You can pass any text generation parameters valid for the Together AI chat completion API directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs` parameter in `run` method. For more details on the parameters supported by the Together AI API, see [Together AI API documentation](https://docs.together.ai/reference/chat-completions-1).
+
+You can also provide an optional `system_prompt` to set context or instructions for text generation. If not provided, the system prompt is omitted, and the default system prompt of the model is used.
+
+To use this integration, you need to have an active TogetherAI subscription with sufficient credits and an API key. You can provide it with:
+
+- The `TOGETHER_API_KEY` environment variable (recommended)
+- The `api_key` init parameter and Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`
+
+By default, the component uses Together AI's OpenAI-compatible base URL `https://api.together.xyz/v1`, which you can override with `api_base_url` if needed.
+
+### Streaming
+
+`TogetherAIGenerator` supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) responses from the LLM, allowing tokens to be emitted as they are generated. To enable streaming, pass a callable to the `streaming_callback` parameter during initialization.
+
+:::info
+This component is designed for text generation, not for chat. If you want to use Together AI LLMs for chat, use [`TogetherAIChatGenerator`](togetheraichatgenerator.mdx) instead.
+:::
+
+## Usage
+
+Install the `togetherai-haystack` package to use the `TogetherAIGenerator`:
+
+```shell
+pip install togetherai-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.togetherai import TogetherAIGenerator
+
+client = TogetherAIGenerator(model="meta-llama/Llama-3.3-70B-Instruct-Turbo")
+response = client.run("What's Natural Language Processing? Be brief.")
+print(response)
+
+>> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence
+>> that focuses on enabling computers to understand, interpret, and generate human language
+>> in a way that is meaningful and useful.'],
+>> 'meta': [{'model': 'meta-llama/Llama-3.3-70B-Instruct-Turbo', 'index': 0,
+>> 'finish_reason': 'stop', 'usage': {'prompt_tokens': 15, 'completion_tokens': 36,
+>> 'total_tokens': 51}}]}
+```
+
+With streaming:
+
+```python
+from haystack_integrations.components.generators.togetherai import TogetherAIGenerator
+
+client = TogetherAIGenerator(
+ model="meta-llama/Llama-3.3-70B-Instruct-Turbo",
+ streaming_callback=lambda chunk: print(chunk.content, end="", flush=True),
+)
+
+response = client.run("What's Natural Language Processing? Be brief.")
+print(response)
+```
+
+With system prompt:
+
+```python
+from haystack_integrations.components.generators.togetherai import TogetherAIGenerator
+
+client = TogetherAIGenerator(
+ model="meta-llama/Llama-3.3-70B-Instruct-Turbo",
+ system_prompt="You are a helpful assistant that provides concise answers."
+)
+
+response = client.run("What's Natural Language Processing?")
+print(response["replies"][0])
+```
+
+### In a Pipeline
+
+```python
+from haystack import Pipeline, Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.generators.togetherai import TogetherAIGenerator
+
+docstore = InMemoryDocumentStore()
+docstore.write_documents([
+ Document(content="Rome is the capital of Italy"),
+ Document(content="Paris is the capital of France")
+])
+
+query = "What is the capital of France?"
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: {{ query }}?
+"""
+
+pipe = Pipeline()
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("llm", TogetherAIGenerator(model="meta-llama/Llama-3.3-70B-Instruct-Turbo"))
+
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "llm")
+
+result = pipe.run({
+ "prompt_builder": {"query": query},
+ "retriever": {"query": query}
+})
+
+print(result)
+
+>> {'llm': {'replies': ['The capital of France is Paris.'],
+>> 'meta': [{'model': 'meta-llama/Llama-3.3-70B-Instruct-Turbo', ...}]}}
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaicodegenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaicodegenerator.mdx
new file mode 100644
index 0000000000..9f2b3f9c04
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaicodegenerator.mdx
@@ -0,0 +1,99 @@
+---
+title: "VertexAICodeGenerator"
+id: vertexaicodegenerator
+slug: "/vertexaicodegenerator"
+description: "This component enables code generation using Google Vertex AI generative model."
+---
+
+# VertexAICodeGenerator
+
+This component enables code generation using Google Vertex AI generative model.
+
+`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [TogetherAI](/reference/integrations-togetherai) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/togetherai | + +
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `prefix`: A string of code before the current point
`suffix`: An optional string of code after the current point | +| **Output variables** | `replies`: Code generated by the model | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | + +
+
+`VertexAICodeGenerator` supports `code-bison`, `code-bison-32k`, and `code-gecko`.
+
+### Parameters Overview
+
+`VertexAICodeGenerator` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+You need to install `google-vertex-haystack` package first to use the `VertexAIImageCaptioner`:
+
+```shell
+pip install google-vertex-haystack
+```
+
+Basic usage:
+
+````python
+from haystack_integrations.components.generators.google_vertex import VertexAICodeGenerator
+
+generator = VertexAICodeGenerator()
+
+result = generator.run(prefix="def to_json(data):")
+
+for answer in result["replies"]:
+ print(answer)
+
+>>> ```python
+>>> import json
+>>>
+>>> def to_json(data):
+>>> """Converts a Python object to a JSON string.
+>>>
+>>> Args:
+>>> data: The Python object to convert.
+>>>
+>>> Returns:
+>>> A JSON string representing the Python object.
+>>> """
+>>>
+>>> return json.dumps(data)
+>>> ```
+````
+
+You can also set other parameters like the number of output tokens, temperature, stop sequences, and the number of candidates.
+
+Let’s try a different model:
+
+```python
+from haystack_integrations.components.generators.google_vertex import VertexAICodeGenerator
+
+generator = VertexAICodeGenerator(
+ model="code-gecko",
+ temperature=0.8,
+ candidate_count=3
+)
+
+result = generator.run(prefix="def convert_temperature(degrees):")
+
+for answer in result["replies"]:
+ print(answer)
+
+>>>
+>>> return degrees * (9/5) + 32
+
+>>>
+>>> return round(degrees * (9.0 / 5.0) + 32, 1)
+
+>>>
+>>> return 5 * (degrees - 32) /9
+>>>
+>>> def convert_temperature_back(degrees):
+>>> return 9 * (degrees / 5) + 32
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaigeminichatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaigeminichatgenerator.mdx
new file mode 100644
index 0000000000..767ef98ada
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaigeminichatgenerator.mdx
@@ -0,0 +1,170 @@
+---
+title: "VertexAIGeminiChatGenerator"
+id: vertexaigeminichatgenerator
+slug: "/vertexaigeminichatgenerator"
+description: "`VertexAIGeminiChatGenerator` enables chat completion using Google Gemini models."
+---
+
+# VertexAIGeminiChatGenerator
+
+`VertexAIGeminiChatGenerator` enables chat completion using Google Gemini models.
+
+:::warning Deprecation Notice
+
+This integration uses the deprecated google-generativeai SDK, which will lose support after August 2025.
+
+We recommend switching to the new [GoogleGenAIChatGenerator](googlegenaichatgenerator.mdx) integration instead.
+:::
+
+`suffix`: An optional string of code after the current point | +| **Output variables** | `replies`: Code generated by the model | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat |
+| **Output variables** | `replies`: A list of alternative replies of the model to the input chat |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+
+
+
+`VertexAIGeminiGenerator` supports `gemini-1.5-pro` and `gemini-1.5-flash`/ `gemini-2.0-flash` models. Note that [Google recommends upgrading](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions) from `gemini-1.5-pro` to `gemini-2.0-flash`.
+
+For available models, see https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models.
+
+:::info
+To explore the full capabilities of Gemini check out this [article](https://haystack.deepset.ai/blog/gemini-models-with-google-vertex-for-haystack) and the related [🧑🍳 Cookbook](https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/vertexai-gemini-examples.ipynb).
+:::
+
+### Parameters Overview
+
+`VertexAIGeminiChatGenerator` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+You need to install the `google-vertex-haystack` package to use the `VertexAIGeminiChatGenerator`:
+
+```shell
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiChatGenerator
+
+gemini_chat = VertexAIGeminiChatGenerator()
+
+messages = [ChatMessage.from_user("Tell me the name of a movie")]
+res = gemini_chat.run(messages)
+
+print(res["replies"][0].text)
+>>> The Shawshank Redemption
+
+messages += [res["replies"][0], ChatMessage.from_user("Who's the main actor?")]
+res = gemini_chat.run(messages)
+
+print(res["replies"][0].text)
+>>> Tim Robbins
+```
+
+When chatting with Gemini Pro, you can also easily use function calls. First, define the function locally and convert into a [Tool](../../tools/tool.mdx):
+
+```python
+from typing import Annotated
+from haystack.tools import create_tool_from_function
+
+## example function to get the current weather
+def get_current_weather(
+ location: Annotated[str, "The city for which to get the weather, e.g. 'San Francisco'"] = "Munich",
+ unit: Annotated[str, "The unit for the temperature, e.g. 'celsius'"] = "celsius",
+) -> str:
+ return f"The weather in {location} is sunny. The temperature is 20 {unit}."
+
+tool = create_tool_from_function(get_current_weather)
+```
+
+Create a new instance of `VertexAIGeminiChatGenerator` to set the tools and a [ToolInvoker](../tools/toolinvoker.mdx) to invoke the tools.:
+
+```python
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiChatGenerator
+from haystack.components.tools import ToolInvoker
+
+gemini_chat = VertexAIGeminiChatGenerator(model="gemini-2.0-flash-exp", tools=[tool])
+
+tool_invoker = ToolInvoker(tools=[tool])
+```
+
+And then ask our question:
+
+```python
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What is the temperature in celsius in Berlin?")]
+res = gemini_chat.run(messages=messages)
+
+print(res["replies"][0].tool_calls)
+>>> [ToolCall(tool_name='get_current_weather',
+>>> arguments={'unit': 'celsius', 'location': 'Berlin'}, id=None)]
+
+tool_messages = tool_invoker.run(messages=replies)["tool_messages"]
+messages = user_message + replies + tool_messages
+
+messages += res["replies"][0] + [ChatMessage.from_function(content=weather, name="get_current_weather")]
+
+final_replies = gemini_chat.run(messages=messages)["replies"]
+print(final_replies[0].text)
+>>> The temperature in Berlin is 20 degrees Celsius.
+```
+
+### In a pipeline
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiChatGenerator
+
+## no parameter init, we don't use any runtime template variables
+prompt_builder = ChatPromptBuilder()
+gemini_chat = VertexAIGeminiChatGenerator()
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("gemini", gemini)
+pipe.connect("prompt_builder.prompt", "gemini.messages")
+
+location = "Rome"
+messages = [ChatMessage.from_user("Tell me briefly about {{location}} history")]
+res = pipe.run(data={"prompt_builder": {"template_variables":{"location": location}, "template": messages}})
+
+print(res)
+
+>>> - **753 B.C.:** Traditional date of the founding of Rome by Romulus and Remus.
+>>> - **509 B.C.:** Establishment of the Roman Republic, replacing the Etruscan monarchy.
+>>> - **492-264 B.C.:** Series of wars against neighboring tribes, resulting in the expansion of the Roman Republic's territory.
+>>> - **264-146 B.C.:** Three Punic Wars against Carthage, resulting in the destruction of Carthage and the Roman Republic becoming the dominant power in the Mediterranean.
+>>> - **133-73 B.C.:** Series of civil wars and slave revolts, leading to the rise of Julius Caesar.
+>>> - **49 B.C.:** Julius Caesar crosses the Rubicon River, starting the Roman Civil War.
+>>> - **44 B.C.:** Julius Caesar is assassinated, leading to the Second Triumvirate of Octavian, Mark Antony, and Lepidus.
+>>> - **31 B.C.:** Battle of Actium, where Octavian defeats Mark Antony and Cleopatra, becoming the sole ruler of Rome.
+>>> - **27 B.C.:** The Roman Republic is transformed into the Roman Empire, with Octavian becoming the first Roman emperor, known as Augustus.
+>>> - **1st century A.D.:** The Roman Empire reaches its greatest extent, stretching from Britain to Egypt.
+>>> - **3rd century A.D.:** The Roman Empire begins to decline, facing internal instability, invasions by Germanic tribes, and the rise of Christianity.
+>>> - **476 A.D.:** The last Western Roman emperor, Romulus Augustulus, is overthrown by the Germanic leader Odoacer, marking the end of the Roman Empire in the West.
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Function Calling and Multimodal QA with Gemini](https://haystack.deepset.ai/cookbook/vertexai-gemini-examples)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaigeminigenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaigeminigenerator.mdx
new file mode 100644
index 0000000000..80198ef190
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaigeminigenerator.mdx
@@ -0,0 +1,159 @@
+---
+title: "VertexAIGeminiGenerator"
+id: vertexaigeminigenerator
+slug: "/vertexaigeminigenerator"
+description: "`VertexAIGeminiGenerator` enables text generation using Google Gemini models."
+---
+
+# VertexAIGeminiGenerator
+
+`VertexAIGeminiGenerator` enables text generation using Google Gemini models.
+
+:::warning Deprecation Notice
+
+This integration uses the deprecated google-generativeai SDK, which will lose support after August 2025.
+
+We recommend switching to the new [GoogleGenAIChatGenerator](googlegenaichatgenerator.mdx) integration instead.
+:::
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory run variables** | `parts`: A variadic list containing a mix of images, audio, video, and text to prompt Gemini |
+| **Output variables** | `replies`: A list of strings or dictionaries with all the replies generated by the model |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+
+
+
+`VertexAIGeminiGenerator` supports `gemini-1.5-pro` and `gemini-1.5-flash`/ `gemini-2.0-flash` models. Note that [Google recommends upgrading](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions) from `gemini-1.5-pro` to `gemini-2.0-flash`.
+
+For details on available models, see https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models.
+
+:::info
+To explore the full capabilities of Gemini check out this [article](https://haystack.deepset.ai/blog/gemini-models-with-google-vertex-for-haystack) and the related [Colab notebook](https://colab.research.google.com/drive/10SdXvH2ATSzqzA3OOmTM8KzD5ZdH_Q6Z?usp=sharing).
+:::
+
+### Parameters Overview
+
+`VertexAIGeminiGenerator` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+You should install `google-vertex-haystack` package to use the `VertexAIGeminiGenerator`:
+
+```shell
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiGenerator
+
+gemini = VertexAIGeminiGenerator()
+result = gemini.run(parts = ["What is the most interesting thing you know?"])
+for answer in result["replies"]:
+ print(answer)
+
+>>> 1. **The Origin of Life:** How and where did life begin? The answers to this question are still shrouded in mystery, but scientists continuously uncover new insights into the remarkable story of our planet's earliest forms of life.
+>>> 2. **The Unseen Universe:** The vast majority of the universe is comprised of matter and energy that we cannot directly observe. Dark matter and dark energy make up over 95% of the universe, yet we still don't fully understand their properties or how they influence the cosmos.
+>>> 3. **Quantum Entanglement:** This eerie phenomenon in quantum mechanics allows two particles to become so intertwined that they share the same fate, regardless of how far apart they are. This has mind-bending implications for our understanding of reality and could potentially lead to advancements in communication and computing.
+>>> 4. **Time Dilation:** Einstein's theory of relativity revealed that time can pass at different rates for different observers. Astronauts traveling at high speeds, for example, experience time dilation relative to people on Earth. This phenomenon could have significant implications for future space travel.
+>>> 5. **The Fermi Paradox:** Despite the vastness of the universe and the abundance of potential life-supporting planets, we have yet to find any concrete evidence of extraterrestrial life. This contradiction between scientific expectations and observational reality is known as the Fermi Paradox and remains one of the most intriguing mysteries in modern science.
+>>> 6. **Biological Evolution:** The idea that life evolves over time through natural selection is one of the most profound and transformative scientific discoveries. It explains the diversity of life on Earth and provides insights into our own origins and the interconnectedness of all living things.
+>>> 7. **Neuroplasticity:** The brain's ability to adapt and change throughout life, known as neuroplasticity, is a remarkable phenomenon that has important implications for learning, memory, and recovery from brain injuries.
+>>> 8. **The Goldilocks Zone:** The concept of the habitable zone, or the Goldilocks zone, refers to the range of distances from a star within which liquid water can exist on a planet's surface. This zone is critical for the potential existence of life as we know it and has been used to guide the search for exoplanets that could support life.
+>>> 9. **String Theory:** This theoretical framework in physics aims to unify all the fundamental forces of nature into a single coherent theory. It suggests that the universe has extra dimensions beyond the familiar three spatial dimensions and time.
+>>> 10. **Consciousness:** The nature of human consciousness and how it arises from the brain's physical processes remain one of the most profound and elusive mysteries in science. Understanding consciousness is crucial for unraveling the complexities of the human mind and our place in the universe.
+```
+
+Advanced usage, multi-modal prompting:
+
+```python
+import requests
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiGenerator
+
+URLS = [
+ "https://raw.githubusercontent.com/silvanocerza/robots/main/robot1.jpg",
+ "https://raw.githubusercontent.com/silvanocerza/robots/main/robot2.jpg",
+ "https://raw.githubusercontent.com/silvanocerza/robots/main/robot3.jpg",
+ "https://raw.githubusercontent.com/silvanocerza/robots/main/robot4.jpg"
+]
+images = [
+ ByteStream(data=requests.get(url).content, mime_type="image/jpeg")
+ for url in URLS
+]
+
+gemini = VertexAIGeminiGenerator()
+result = gemini.run(parts = ["What can you tell me about this robots?", *images])
+for answer in result["replies"]:
+ print(answer)
+>>> The first image is of C-3PO and R2-D2 from the Star Wars franchise. C-3PO is a protocol droid, while R2-D2 is an astromech droid. They are both loyal companions to the heroes of the Star Wars saga.
+>>> The second image is of Maria from the 1927 film Metropolis. Maria is a robot who is created to be the perfect woman. She is beautiful, intelligent, and obedient. However, she is also soulless and lacks any real emotions.
+>>> The third image is of Gort from the 1951 film The Day the Earth Stood Still. Gort is a robot who is sent to Earth to warn humanity about the dangers of nuclear war. He is a powerful and intelligent robot, but he is also compassionate and understanding.
+>>> The fourth image is of Marvin from the 1977 film The Hitchhiker's Guide to the Galaxy. Marvin is a robot who is depressed and pessimistic. He is constantly complaining about everything, but he is also very intelligent and has a dry sense of humor.
+```
+
+### In a pipeline
+
+In a RAG pipeline:
+
+```python
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.builders import PromptBuilder
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.generators.google_vertex import VertexAIGeminiGenerator
+
+docstore = InMemoryDocumentStore()
+docstore.write_documents([Document(content="Rome is the capital of Italy"), Document(content="Paris is the capital of France")])
+
+query = "What is the capital of France?"
+
+template = """
+Given the following information, answer the question.
+
+Context:
+{% for document in documents %}
+ {{ document.content }}
+{% endfor %}
+
+Question: {{ query }}?
+"""
+pipe = Pipeline()
+
+pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore))
+pipe.add_component("prompt_builder", PromptBuilder(template=template))
+pipe.add_component("gemini", VertexAIGeminiGenerator())
+pipe.connect("retriever", "prompt_builder.documents")
+pipe.connect("prompt_builder", "gemini")
+
+res=pipe.run({
+ "prompt_builder": {
+ "query": query
+ },
+ "retriever": {
+ "query": query
+ }
+})
+
+print(res)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Function Calling and Multimodal QA with Gemini](https://haystack.deepset.ai/cookbook/vertexai-gemini-examples)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimagecaptioner.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimagecaptioner.mdx
new file mode 100644
index 0000000000..90f8a3ed91
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimagecaptioner.mdx
@@ -0,0 +1,82 @@
+---
+title: "VertexAIImageCaptioner"
+id: vertexaiimagecaptioner
+slug: "/vertexaiimagecaptioner"
+description: "`VertexAIImageCaptioner` enables text generation using Google Vertex AI `imagetext` generative model."
+---
+
+# VertexAIImageCaptioner
+
+`VertexAIImageCaptioner` enables text generation using Google Vertex AI `imagetext` generative model.
+
+
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `image`: A [`ByteStream`](../../concepts/data-classes.mdx#bytestream) object storing an image |
+| **Output variables** | `captions`: A list of strings generated by the model |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+
+
+
+### Parameters Overview
+
+`VertexAIImageCaptioner` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+You need to install `google-vertex-haystack` package to use the `VertexAIImageCaptioner`:
+
+```shell
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+import requests
+
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIImageCaptioner
+
+captioner = VertexAIImageCaptioner()
+
+image = ByteStream(data=requests.get("https://raw.githubusercontent.com/silvanocerza/robots/main/robot1.jpg").content)
+result = captioner.run(image=image)
+
+for caption in result["captions"]:
+ print(caption)
+
+>>> two gold robots are standing next to each other in the desert
+```
+
+You can also set the caption language and the number of results:
+
+```python
+import requests
+
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIImageCaptioner
+
+captioner = VertexAIImageCaptioner(
+ number_of_results=3, # Can't be greater than 3
+ language="it",
+)
+
+image = ByteStream(data=requests.get("https://raw.githubusercontent.com/silvanocerza/robots/main/robot1.jpg").content)
+result = captioner.run(image=image)
+
+for caption in result["captions"]:
+ print(caption)
+
+>>> due robot dorati sono in piedi uno accanto all'altro in un deserto
+>>> un c3p0 e un r2d2 stanno in piedi uno accanto all'altro in un deserto
+>>> due robot dorati sono in piedi uno accanto all'altro
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimagegenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimagegenerator.mdx
new file mode 100644
index 0000000000..68d1d64bd6
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimagegenerator.mdx
@@ -0,0 +1,76 @@
+---
+title: "VertexAIImageGenerator"
+id: vertexaiimagegenerator
+slug: "/vertexaiimagegenerator"
+description: "This component enables image generation using Google Vertex AI generative model."
+---
+
+# VertexAIImageGenerator
+
+This component enables image generation using Google Vertex AI generative model.
+
+
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the model |
+| **Output variables** | `images`: A list of [`ByteStream`](../../concepts/data-classes.mdx#bytestream) containing images generated by the model |
+| **API reference** | [Google Vertex](/reference/integrations-google-vertex) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex |
+
+
+
+`VertexAIImageGenerator` supports the `imagegeneration` model.
+
+### Parameters Overview
+
+`VertexAIImageGenerator` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+You need to install `google-vertex-haystack` package to use the `VertexAIImageGenerator`:
+
+```python
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from pathlib import Path
+
+from haystack_integrations.components.generators.google_vertex import VertexAIImageGenerator
+
+generator = VertexAIImageGenerator()
+result = generator.run(prompt="Generate an image of a cute cat")
+result["images"][0].to_file(Path("my_image.png"))
+```
+
+You can also set other parameters like the number of images generated and the guidance scale to change the strength of the prompt.
+
+Let’s also use a negative prompt to omit something from the image:
+
+```python
+from pathlib import Path
+
+from haystack_integrations.components.generators.google_vertex import VertexAIImageGenerator
+
+generator = VertexAIImageGenerator(
+ number_of_images=3,
+ guidance_scale=12,
+)
+
+result = generator.run(
+ prompt="Generate an image of a cute cat",
+ negative_prompt="window, chair",
+)
+
+for i, image in enumerate(result["images"]):
+ images.to_file(Path(f"image_{i}.png"))
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimageqa.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimageqa.mdx
new file mode 100644
index 0000000000..aad45f5317
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimageqa.mdx
@@ -0,0 +1,79 @@
+---
+title: "VertexAIImageQA"
+id: vertexaiimageqa
+slug: "/vertexaiimageqa"
+description: "This component enables text generation (image captioning) using Google Vertex AI generative models."
+---
+
+# VertexAIImageQA
+
+This component enables text generation (image captioning) using Google Vertex AI generative models.
+
+
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `image`: A [`ByteStream`](../../concepts/data-classes.mdx#bytestream) containing an image data
`question`: A string of a question about the image | +| **Output variables** | `replies`: A list of strings containing answers generated by the model | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | + +
+
+`VertexAIImageQA` supports the `imagetext` model.
+
+### Parameters Overview
+
+`VertexAIImageQA` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+You need to install `google-vertex-haystack` package to use the `VertexAIImageQA`:
+
+```python
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+```python
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIImageQA
+
+qa = VertexAIImageQA()
+
+image = ByteStream.from_file_path("dog.jpg")
+
+res = qa.run(image=image, question="What color is this dog")
+
+print(res["replies"][0])
+
+>>> white
+```
+
+You can also set the number of answers generated:
+
+```python
+from haystack.dataclasses.byte_stream import ByteStream
+from haystack_integrations.components.generators.google_vertex import VertexAIImageQA
+
+qa = VertexAIImageQA(
+ number_of_results=3,
+)
+image = ByteStream.from_file_path("dog.jpg")
+
+res = qa.run(image=image, question="Tell me something about this dog")
+
+for answer in res["replies"]:
+ print(answer)
+
+>>> pomeranian
+>>> white
+>>> pomeranian puppy
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaitextgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaitextgenerator.mdx
new file mode 100644
index 0000000000..957ad828fb
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaitextgenerator.mdx
@@ -0,0 +1,87 @@
+---
+title: "VertexAITextGenerator"
+id: vertexaitextgenerator
+slug: "/vertexaitextgenerator"
+description: "This component enables text generation using Google Vertex AI generative models."
+---
+
+# VertexAITextGenerator
+
+This component enables text generation using Google Vertex AI generative models.
+
+`question`: A string of a question about the image | +| **Output variables** | `replies`: A list of strings containing answers generated by the model | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | + +
+
+| | |
+| --- | --- |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the model |
+| **Output variables** | `replies`: A list of strings containing answers generated by the model
`safety_attributes`: A dictionary containing scores for safety attributes
`citations`: A list of dictionaries containing grounding citations | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | + +
+
+`VertexAITextGenerator` supports `text-bison`, `text-unicorn` and `text-bison-32k` models.
+
+### Parameters Overview
+
+`VertexAITextGenerator` uses Google Cloud Application Default Credentials (ADCs) for authentication. For more information on how to set up ADCs, see the [official documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+Keep in mind that it’s essential to use an account that has access to a project authorized to use Google Vertex AI endpoints.
+
+You can find your project ID in the [GCP resource manager](https://console.cloud.google.com/cloud-resource-manager) or locally by running `gcloud projects list` in your terminal. For more info on the gcloud CLI, see its [official documentation](https://cloud.google.com/cli).
+
+## Usage
+
+You need to install `google-vertex-haystack` package to use the `VertexAITextGenerator`:
+
+```python
+pip install google-vertex-haystack
+```
+
+### On its own
+
+Basic usage:
+
+````python
+from haystack_integrations.components.generators.google_vertex import VertexAITextGenerator
+
+generator = VertexAITextGenerator()
+res = generator.run("Tell me a good interview question for a software engineer.")
+
+print(res["replies"][0])
+
+>>> **Question:** You are given a list of integers and a target sum. Find all unique combinations of numbers in the list that add up to the target sum.
+>>>
+>>> **Example:**
+>>>
+>>> ```
+>>> Input: [1, 2, 3, 4, 5], target = 7
+>>> Output: [[1, 2, 4], [3, 4]]
+>>> ```
+>>>
+>>> **Follow-up:** What if the list contains duplicate numbers?
+````
+
+You can also set other parameters like the number of answers generated, temperature to control the randomness, and stop sequences to stop generation. For a full list of possible parameters, see the documentation of [`TextGenerationModel.predict()`](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.language_models.TextGenerationModel#vertexai_language_models_TextGenerationModel_predict).
+
+```python
+from haystack_integrations.components.generators.google_vertex import VertexAITextGenerator
+
+generator = VertexAITextGenerator(
+ candidate_count=3,
+ temperature=0.2,
+ stop_sequences=["example", "Example"],
+)
+res = generator.run("Tell me a good interview question for a software engineer.")
+
+for answer in res["replies"]:
+ print(answer)
+ print("-----")
+
+>>> **Question:** You are given a list of integers, and you need to find the longest increasing subsequence. What is the most efficient algorithm to solve this problem?
+>>> -----
+>>> **Question:** You are given a list of integers and a target sum. Find all unique combinations in the list that sum up to the target sum. The same number can be used multiple times in a combination.
+>>> -----
+>>> **Question:** You are given a list of integers and a target sum. Find all unique combinations of numbers in the list that add up to the target sum.
+>>> -----
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/watsonxchatgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/watsonxchatgenerator.mdx
new file mode 100644
index 0000000000..4116640b4f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/watsonxchatgenerator.mdx
@@ -0,0 +1,114 @@
+---
+title: "WatsonxChatGenerator"
+id: watsonxchatgenerator
+slug: "/watsonxchatgenerator"
+description: "Use this component with IBM watsonx models like `granite-3-2b-instruct` for chat generation."
+---
+
+# WatsonxChatGenerator
+
+Use this component with IBM watsonx models like `granite-3-2b-instruct` for chat generation.
+
+`safety_attributes`: A dictionary containing scores for safety attributes
`citations`: A list of dictionaries containing grounding citations | +| **API reference** | [Google Vertex](/reference/integrations-google-vertex) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/google_vertex | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: The IBM Cloud API key. Can be set with `WATSONX_API_KEY` env var.
`project_id`: The IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | + +
+
+This integration supports IBM watsonx.ai foundation models such as `ibm/granite-13b-chat-v2`, `ibm/llama-2-70b-chat`, `ibm/llama-3-70b-instruct`, and similar. These models provide high-quality chat completion capabilities through IBM's cloud platform. Check out the most recent full list in the [IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-ibm.html?context=wx).
+
+## Overview
+
+`WatsonxChatGenerator` needs IBM Cloud credentials to work. You can set these in:
+
+- The `api_key` and `project_id` init parameters using [Secret API](../../concepts/secret-management.mdx)
+- The `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` environment variables (recommended)
+
+Then, the component needs a prompt to operate, but you can pass any text generation parameters valid for the IBM watsonx.ai API directly to this component using the `generation_kwargs` parameter, both at initialization and to `run()` method. For more details on the parameters supported by the IBM watsonx.ai API, refer to the [IBM watsonx.ai documentation](https://cloud.ibm.com/apidocs/watsonx-ai).
+
+Finally, the component needs a list of `ChatMessage` objects to operate. `ChatMessage` is a data class that contains a message, a role (who generated the message, such as `user`, `assistant`, `system`, `function`), and optional metadata.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+You need to install `watsonx-haystack` package to use the `WatsonxChatGenerator`:
+
+```shell
+pip install watsonx-haystack
+```
+
+#### On its own
+
+```python
+from haystack_integrations.components.generators.watsonx.chat.chat_generator import WatsonxChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+generator = WatsonxChatGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+ model="ibm/granite-13b-instruct-v2"
+)
+
+message = ChatMessage.from_user("What's Natural Language Processing? Be brief.")
+print(generator.run([message]))
+```
+
+With multimodal inputs:
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack_integrations.components.generators.watsonx.chat.chat_generator import WatsonxChatGenerator
+
+# Use a multimodal model
+llm = WatsonxChatGenerator(model="meta-llama/llama-3-2-11b-vision-instruct")
+
+image = ImageContent.from_file_path("apple.jpg")
+user_message = ChatMessage.from_user(content_parts=[
+ "What does the image show? Max 5 words.",
+ image
+ ])
+
+response = llm.run([user_message])["replies"][0].text
+print(response)
+
+# Red apple on straw.
+```
+
+#### In a Pipeline
+
+You can also use `WatsonxChatGenerator` to use IBM watsonx.ai chat models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.watsonx.chat.chat_generator import WatsonxChatGenerator
+from haystack.utils import Secret
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", WatsonxChatGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+ model="ibm/granite-13b-instruct-v2"
+))
+pipe.connect("prompt_builder", "llm")
+
+country = "Germany"
+system_message = ChatMessage.from_system("You are an assistant giving out valuable information to language learners.")
+messages = [system_message, ChatMessage.from_user("What's the official language of {{ country }}?")]
+
+res = pipe.run(data={"prompt_builder": {"template_variables": {"country": country}, "template": messages}})
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/watsonxgenerator.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/watsonxgenerator.mdx
new file mode 100644
index 0000000000..5ace5d3ce9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/watsonxgenerator.mdx
@@ -0,0 +1,100 @@
+---
+title: "WatsonxGenerator"
+id: watsonxgenerator
+slug: "/watsonxgenerator"
+description: "Use this component with IBM watsonx models like `granite-3-2b-instruct` for simple text generation tasks."
+---
+
+# WatsonxGenerator
+
+Use this component with IBM watsonx models like `granite-3-2b-instruct` for simple text generation tasks.
+
+`project_id`: The IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `messages` A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **Output variables** | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [PromptBuilder](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `api_key`: An IBM Cloud API key. Can be set with `WATSONX_API_KEY` env var.
`project_id`: An IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | + +
+
+## Overview
+
+This integration supports IBM watsonx.ai foundation models such as `ibm/granite-13b-chat-v2`, `ibm/llama-2-70b-chat`, `ibm/llama-3-70b-instruct`, and similar. These models provide high-quality text generation capabilities through IBM's cloud platform. Check out the most recent full list in the [IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-ibm.html?context=wx).
+
+### Parameters
+
+`WatsonxGenerator` needs IBM Cloud credentials to work. You can provide these in:
+
+- The `WATSONX_API_KEY` environment variable (recommended)
+- The `WATSONX_PROJECT_ID` environment variable (recommended)
+- The `api_key` and `project_id` init parameters using Haystack [Secret](../../concepts/secret-management.mdx) API: `Secret.from_token("your-api-key-here")`
+
+Set your preferred IBM watsonx.ai model in the `model` parameter when initializing the component. The default model is `ibm/granite-3-2b-instruct`.
+
+`WatsonxGenerator` requires a prompt to generate text, but you can pass any text generation parameters available in the IBM watsonx.ai API directly to this component using the `generation_kwargs` parameter, both at initialization and to `run()` method. For more details on the parameters supported by the IBM watsonx.ai API, see [IBM watsonx.ai documentation](https://cloud.ibm.com/apidocs/watsonx-ai).
+
+The component also supports system prompts that can be set at initialization or passed during runtime to provide context or instructions for the generation.
+
+Finally, the component run method requires a single string prompt to generate text.
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Install the `watsonx-haystack` package to use the `WatsonxGenerator`:
+
+```shell
+pip install watsonx-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.watsonx.generator import WatsonxGenerator
+from haystack.utils import Secret
+
+generator = WatsonxGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID")
+)
+
+print(generator.run("What's Natural Language Processing? Be brief."))
+```
+
+### In a pipeline
+
+You can also use `WatsonxGenerator` with the IBM watsonx.ai models in your pipeline.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import PromptBuilder
+from haystack_integrations.components.generators.watsonx.generator import WatsonxGenerator
+from haystack.utils import Secret
+
+template = """
+You are an assistant giving out valuable information to language learners.
+Answer this question, be brief.
+
+Question: {{ query }}?
+"""
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", PromptBuilder(template))
+pipe.add_component("llm", WatsonxGenerator(
+ api_key=Secret.from_env_var("WATSONX_API_KEY"),
+ project_id=Secret.from_env_var("WATSONX_PROJECT_ID")
+))
+pipe.connect("prompt_builder", "llm")
+
+query = "What language is spoken in Germany?"
+res = pipe.run(data={"prompt_builder": {"query": query}})
+
+print(res)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners.mdx
new file mode 100644
index 0000000000..0bd093453f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners.mdx
@@ -0,0 +1,15 @@
+---
+title: "Joiners"
+id: joiners
+slug: "/joiners"
+---
+
+# Joiners
+
+| Component | Description |
+| --- | --- |
+| [AnswerJoiner](joiners/answerjoiner.mdx) | Joins multiple answers from different Generators into a single list. |
+| [BranchJoiner](joiners/branchjoiner.mdx) | Joins different branches of a pipeline into a single output. |
+| [DocumentJoiner](joiners/documentjoiner.mdx) | Joins lists of documents. |
+| [ListJoiner](joiners/listjoiner.mdx) | Joins multiple lists into a single flat list. |
+| [StringJoiner](joiners/stringjoiner.mdx) | Joins strings from different components into a list of strings. |
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/answerjoiner.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/answerjoiner.mdx
new file mode 100644
index 0000000000..f6d498b6cc
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/answerjoiner.mdx
@@ -0,0 +1,63 @@
+---
+title: "AnswerJoiner"
+id: answerjoiner
+slug: "/answerjoiner"
+description: "Merges multiple answers from different Generators into a single list."
+---
+
+# AnswerJoiner
+
+Merges multiple answers from different Generators into a single list.
+
+`project_id`: An IBM Cloud project ID. Can be set with `WATSONX_PROJECT_ID` env var. | +| **Mandatory run variables** | `prompt`: A string containing the prompt for the LLM | +| **Output variables** | `replies`: A list of strings with all the replies generated by the LLM
`meta`: A list of dictionaries with the metadata associated with each reply, such as token count, finish reason, and so on | +| **API reference** | [Watsonx](/reference/integrations-watsonx) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/watsonx | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In query pipelines, after [Generators](../generators.mdx) and, subsequently, components that return a list of answers such as [`AnswerBuilder`](../builders/answerbuilder.mdx) |
+| **Mandatory run variables** | `answers`: A nested list of answers to be merged, received from the Generator. This input is `variadic`, meaning you can connect a variable number of components to it. |
+| **Output variables** | `answers`: A merged list of answers |
+| **API reference** | [Joiners](/reference/joiners-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/joiners/answer_joiner.py |
+
+
+
+## Overvew
+
+`AnswerJoiner` joins input lists of [`Answer`](../../concepts/data-classes.mdx#answer) objects from multiple connections and returns them as one list.
+
+You can optionally set the `top_k` parameter, which specifies the maximum number of answers to return. If you don’t set this parameter, the component returns all answers it receives.
+
+## Usage
+
+In this simple example pipeline, the `AnswerJoiner` merges answers from two instances of Generators:
+
+```python
+from haystack.components.builders import AnswerBuilder
+from haystack.components.joiners import AnswerJoiner
+
+from haystack.core.pipeline import Pipeline
+
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+query = "What's Natural Language Processing?"
+messages = [ChatMessage.from_system("You are a helpful, respectful and honest assistant. Be super concise."),
+ ChatMessage.from_user(query)]
+
+pipe = Pipeline()
+pipe.add_component("gpt-4o", OpenAIChatGenerator(model="gpt-4o"))
+pipe.add_component("llama", OpenAIChatGenerator(model="gpt-3.5-turbo"))
+pipe.add_component("aba", AnswerBuilder())
+pipe.add_component("abb", AnswerBuilder())
+pipe.add_component("joiner", AnswerJoiner())
+
+pipe.connect("gpt-4o.replies", "aba")
+pipe.connect("llama.replies", "abb")
+pipe.connect("aba.answers", "joiner")
+pipe.connect("abb.answers", "joiner")
+
+results = pipe.run(data={"gpt-4o": {"messages": messages},
+ "llama": {"messages": messages},
+ "aba": {"query": query},
+ "abb": {"query": query}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/branchjoiner.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/branchjoiner.mdx
new file mode 100644
index 0000000000..4da7f0a9e0
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/branchjoiner.mdx
@@ -0,0 +1,203 @@
+---
+title: "BranchJoiner"
+id: branchjoiner
+slug: "/branchjoiner"
+description: "Use this component to join different branches of a pipeline into a single output."
+---
+
+import ClickableImage from "@site/src/components/ClickableImage";
+
+# BranchJoiner
+
+Use this component to join different branches of a pipeline into a single output.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible: Can appear at the beginning of a pipeline or at the start of loops. |
+| **Mandatory init variables** | `type`: The type of data expected from preceding components |
+| **Mandatory run variables** | `**kwargs`: Any input data type defined at the initialization. This input is variadic, meaning you can connect a variable number of components to it. |
+| **Output variables** | `value`: The first value received from the connected components. |
+| **API reference** | [Joiners](/reference/joiners-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/joiners/branch.py |
+
+
+
+## Overview
+
+`BranchJoiner` joins multiple branches in a pipeline, allowing their outputs to be reconciled into a single branch. This is especially useful in pipelines with multiple branches that need to be unified before moving to the single component that comes next.
+
+`BranchJoiner` receives multiple data connections of the same type from other components and passes the first value it receives to its single output. This makes it essential for closing loops in pipelines or reconciling multiple branches from a decision component.
+
+`BranchJoiner` can handle only one input of one data type, declared in the `__init__` function. It ensures that the data type remains consistent across the pipeline branches. If more than one value is received for the input when `run` is invoked, the component will raise an error:
+
+```python
+from haystack.components.joiners import BranchJoiner
+
+bj = BranchJoiner(int)
+bj.run(value=[3, 4, 5])
+
+>>> ValueError: BranchJoiner expects only one input, but 3 were received.
+
+```
+
+## Usage
+
+### On its own
+
+Although only one input value is allowed at every run, due to its variadic nature `BranchJoiner` still expects a list. As an example:
+
+```python
+from haystack.components.joiners import BranchJoiner
+
+## an example where input and output are strings
+bj = BranchJoiner(str)
+bj.run(value=["hello"])
+>>> {"value" : "hello"}
+
+## an example where input and output are integers
+bj = BranchJoiner(int)
+bj.run(value=[3])
+>>> {"value": 3}
+```
+
+### In a pipeline
+
+#### Enabling loops
+
+Below is an example where `BranchJoiner` is used for closing a loop. In this example, `BranchJoiner` receives a looped-back list of `ChatMessage` objects from the `JsonSchemaValidator` and sends it down to the `OpenAIChatGenerator` for re-generation.
+
+```python
+import json
+from typing import List
+
+from haystack import Pipeline
+from haystack.components.converters import OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.joiners import BranchJoiner
+from haystack.components.validators import JsonSchemaValidator
+from haystack.dataclasses import ChatMessage
+
+person_schema = {
+ "type": "object",
+ "properties": {
+ "first_name": {"type": "string", "pattern": "^[A-Z][a-z]+$"},
+ "last_name": {"type": "string", "pattern": "^[A-Z][a-z]+$"},
+ "nationality": {"type": "string", "enum": ["Italian", "Portuguese", "American"]},
+ },
+ "required": ["first_name", "last_name", "nationality"]
+}
+
+## Initialize a pipeline
+pipe = Pipeline()
+
+## Add components to the pipeline
+pipe.add_component('joiner', BranchJoiner(List[ChatMessage]))
+pipe.add_component('fc_llm', OpenAIChatGenerator(model="gpt-4o-mini"))
+pipe.add_component('validator', JsonSchemaValidator(json_schema=person_schema))
+pipe.add_component('adapter', OutputAdapter("{{chat_message}}", List[ChatMessage], unsafe=True))
+
+## Connect components
+pipe.connect("adapter", "joiner")
+pipe.connect("joiner", "fc_llm")
+pipe.connect("fc_llm.replies", "validator.messages")
+pipe.connect("validator.validation_error", "joiner")
+
+result = pipe.run(data={
+ "fc_llm": {"generation_kwargs": {"response_format": {"type": "json_object"}}},
+ "adapter": {"chat_message": [ChatMessage.from_user("Create json object from Peter Parker")]}
+})
+
+print(json.loads(result["validator"]["validated"][0].text))
+
+## Output:
+## {'first_name': 'Peter', 'last_name': 'Parker', 'nationality': 'American', 'name': 'Spider-Man', 'occupation':
+## 'Superhero', 'age': 23, 'location': 'New York City'}
+
+```
+
+
+
+
+
+#### Reconciling branches
+
+In this example, the `TextLanguageRouter` component directs the query to one of three language-specific Retrievers. The next component would be a `PromptBuilder`, but we cannot connect multiple Retrievers to a single `PromptBuilder` directly. Instead, we connect all the Retrievers to the `BranchJoiner` component. The `BranchJoiner` then takes the output from the Retriever that was actually called and passes it as a single list of documents to the `PromptBuilder`. The `BranchJoiner` ensures that the pipeline can handle multiple languages seamlessly by consolidating different outputs from the Retrievers into a unified connection for further processing.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.joiners import BranchJoiner
+from haystack.components.builders import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+from haystack.components.routers import TextLanguageRouter
+
+prompt_template = """
+Answer the question based on the given reviews.
+Reviews:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+Question: {{ query}}
+Answer:
+"""
+
+documents = [
+ Document(
+ content="Super appartement. Juste au dessus de plusieurs bars qui ferment très tard. A savoir à l'avance. (Bouchons d'oreilles fournis !)"
+ ),
+ Document(
+ content="El apartamento estaba genial y muy céntrico, todo a mano. Al lado de la librería Lello y De la Torre de los clérigos. Está situado en una zona de marcha, así que si vais en fin de semana , habrá ruido, aunque a nosotros no nos molestaba para dormir"
+ ),
+ Document(
+ content="The keypad with a code is convenient and the location is convenient. Basically everything else, very noisy, wi-fi didn't work, check-in person didn't explain anything about facilities, shower head was broken, there's no cleaning and everything else one may need is charged."
+ ),
+ Document(
+ content="It is very central and appartement has a nice appearance (even though a lot IKEA stuff), *W A R N I N G** the appartement presents itself as a elegant and as a place to relax, very wrong place to relax - you cannot sleep in this appartement, even the beds are vibrating from the bass of the clubs in the same building - you get ear plugs from the hotel."
+ ),
+ Document(
+ content="Céntrico. Muy cómodo para moverse y ver Oporto. Edificio con terraza propia en la última planta. Todo reformado y nuevo. The staff brings a great breakfast every morning to the apartment. Solo que se puede escuchar algo de ruido de la street a primeras horas de la noche. Es un zona de ocio nocturno. Pero respetan los horarios."
+ ),
+]
+
+en_document_store = InMemoryDocumentStore()
+fr_document_store = InMemoryDocumentStore()
+es_document_store = InMemoryDocumentStore()
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(instance=TextLanguageRouter(["en", "fr", "es"]), name="router")
+rag_pipeline.add_component(instance=InMemoryBM25Retriever(document_store=en_document_store), name="en_retriever")
+rag_pipeline.add_component(instance=InMemoryBM25Retriever(document_store=fr_document_store), name="fr_retriever")
+rag_pipeline.add_component(instance=InMemoryBM25Retriever(document_store=es_document_store), name="es_retriever")
+rag_pipeline.add_component(instance=BranchJoiner(type_=list[Document]), name="joiner")
+rag_pipeline.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+rag_pipeline.add_component(instance=OpenAIGenerator(), name="llm")
+
+rag_pipeline.connect("router.en", "en_retriever.query")
+rag_pipeline.connect("router.fr", "fr_retriever.query")
+rag_pipeline.connect("router.es", "es_retriever.query")
+rag_pipeline.connect("en_retriever", "joiner")
+rag_pipeline.connect("fr_retriever", "joiner")
+rag_pipeline.connect("es_retriever", "joiner")
+rag_pipeline.connect("joiner", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+en_question = "Does this apartment has a noise problem?"
+
+result = rag_pipeline.run({"router": {"text": en_question}, "prompt_builder": {"query": en_question}})
+
+print(result["llm"]["replies"][0])
+
+```
+
+Expand to see the pipeline graph
+
+
+
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/documentjoiner.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/documentjoiner.mdx
new file mode 100644
index 0000000000..89a0c54c2e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/documentjoiner.mdx
@@ -0,0 +1,140 @@
+---
+title: "DocumentJoiner"
+id: documentjoiner
+slug: "/documentjoiner"
+description: "Use this component in hybrid retrieval pipelines or indexing pipelines with multiple file converters to join lists of documents."
+---
+
+# DocumentJoiner
+
+Use this component in hybrid retrieval pipelines or indexing pipelines with multiple file converters to join lists of documents.
+
+Expand to see the pipeline graph
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing and query pipelines, after components that return a list of documents such as multiple [Retrievers](../retrievers.mdx) or multiple [Converters](../converters.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents. This input is `variadic`, meaning you can connect a variable number of components to it. |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Joiners](/reference/joiners-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/joiners/document_joiner.py |
+
+
+
+## Overview
+
+`DocumentJoiner` joins input lists of documents from multiple connections and outputs them as one list. You can choose how you want the lists to be joined by specifying the `join_mode`. There are three options available:
+
+- `concatenate` - Combines document from multiple components, discarding any duplicates. documents get their scores from the last component in the pipeline that assigns scores. This mode doesn’t influence document scores.
+- `merge` - Merges the scores of duplicate documents coming from multiple components. You can also assign a weight to the scores to influence how they’re merged and set the top_k limit to specify how many documents you want `DocumentJoiner` to return.
+- `reciprocal_rank_fusion`- Combines documents into a single list based on their ranking received from multiple components. It then calculates a new score based on the ranks of documents in the input lists. If the same Document appears in more than one list (was returned by multiple components), it gets a higher score.
+- `distribution_based_rank_fusion` – Combines rankings from multiple sources into a single, unified ranking. It analyzes how scores are spread out and normalizes them, ensuring that each component's scoring method is taken into account. This normalization helps to balance the influence of each component, resulting in a more robust and fair combined ranking. If a document appears in multiple lists, its final score is adjusted based on the distribution of scores from all lists.
+
+## Usage
+
+### On its own
+
+Below is an example where we are using the `DocumentJoiner` to merge two lists of documents. We run the `DocumentJoiner` and provide the documents. It returns a list of documents ranked by combined scores. By default, equal weight is given to each Retriever score. You could also use custom weights by setting the weights parameter to a list of floats with one weight per input component.
+
+```python
+from haystack import Document
+from haystack.components.joiners.document_joiner import DocumentJoiner
+
+docs_1 = [Document(content="Paris is the capital of France.", score=0.5), Document(content="Berlin is the capital of Germany.", score=0.4)]
+docs_2 = [Document(content="Paris is the capital of France.", score=0.6), Document(content="Rome is the capital of Italy.", score=0.5)]
+
+joiner = DocumentJoiner(join_mode="merge")
+
+joiner.run(documents=[docs_1, docs_2])
+
+## {'documents': [Document(id=0f5beda04153dbfc462c8b31f8536749e43654709ecf0cfe22c6d009c9912214, content: 'Paris is the capital of France.', score: 0.55), Document(id=424beed8b549a359239ab000f33ca3b1ddb0f30a988bbef2a46597b9c27e42f2, content: 'Rome is the capital of Italy.', score: 0.25), Document(id=312b465e77e25c11512ee76ae699ce2eb201f34c8c51384003bb367e24fb6cf8, content: 'Berlin is the capital of Germany.', score: 0.2)]}
+```
+
+### In a pipeline
+
+#### Hybrid Retrieval
+
+Below is an example of a hybrid retrieval pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`) and embedding search (using `InMemoryEmbeddingRetriever`). It then uses the `DocumentJoiner` with its default join mode to concatenate the retrieved documents into one list. The Document Store must contain documents with embeddings, otherwise the `InMemoryEmbeddingRetriever` will not return any documents.
+
+```python
+from haystack.components.joiners.document_joiner import DocumentJoiner
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever, InMemoryEmbeddingRetriever
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=InMemoryBM25Retriever(document_store=document_store), name="bm25_retriever")
+p.add_component(
+ instance=SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"),
+ name="text_embedder",
+ )
+p.add_component(instance=InMemoryEmbeddingRetriever(document_store=document_store), name="embedding_retriever")
+p.add_component(instance=DocumentJoiner(), name="joiner")
+p.connect("bm25_retriever", "joiner")
+p.connect("embedding_retriever", "joiner")
+p.connect("text_embedder", "embedding_retriever")
+query = "What is the capital of France?"
+p.run(data={"bm25_retriever": {"query": query},
+ "text_embedder": {"text": query}})
+```
+
+#### Indexing
+
+Here's an example of an indexing pipeline that uses `DocumentJoiner` to compile all files into a single list of documents that can be fed through the rest of the indexing pipeline as one.
+
+```python
+from haystack.components.writers import DocumentWriter
+from haystack.components.converters import MarkdownToDocument, PyPDFToDocument, TextFileToDocument
+from haystack.components.preprocessors import DocumentSplitter, DocumentCleaner
+from haystack.components.routers import FileTypeRouter
+from haystack.components.joiners import DocumentJoiner
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from pathlib import Path
+
+document_store = InMemoryDocumentStore()
+file_type_router = FileTypeRouter(mime_types=["text/plain", "application/pdf", "text/markdown"])
+text_file_converter = TextFileToDocument()
+markdown_converter = MarkdownToDocument()
+pdf_converter = PyPDFToDocument()
+document_joiner = DocumentJoiner()
+
+document_cleaner = DocumentCleaner()
+document_splitter = DocumentSplitter(split_by="word", split_length=150, split_overlap=50)
+
+document_embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+document_writer = DocumentWriter(document_store)
+
+preprocessing_pipeline = Pipeline()
+preprocessing_pipeline.add_component(instance=file_type_router, name="file_type_router")
+preprocessing_pipeline.add_component(instance=text_file_converter, name="text_file_converter")
+preprocessing_pipeline.add_component(instance=markdown_converter, name="markdown_converter")
+preprocessing_pipeline.add_component(instance=pdf_converter, name="pypdf_converter")
+preprocessing_pipeline.add_component(instance=document_joiner, name="document_joiner")
+preprocessing_pipeline.add_component(instance=document_cleaner, name="document_cleaner")
+preprocessing_pipeline.add_component(instance=document_splitter, name="document_splitter")
+preprocessing_pipeline.add_component(instance=document_embedder, name="document_embedder")
+preprocessing_pipeline.add_component(instance=document_writer, name="document_writer")
+
+preprocessing_pipeline.connect("file_type_router.text/plain", "text_file_converter.sources")
+preprocessing_pipeline.connect("file_type_router.application/pdf", "pypdf_converter.sources")
+preprocessing_pipeline.connect("file_type_router.text/markdown", "markdown_converter.sources")
+preprocessing_pipeline.connect("text_file_converter", "document_joiner")
+preprocessing_pipeline.connect("pypdf_converter", "document_joiner")
+preprocessing_pipeline.connect("markdown_converter", "document_joiner")
+preprocessing_pipeline.connect("document_joiner", "document_cleaner")
+preprocessing_pipeline.connect("document_cleaner", "document_splitter")
+preprocessing_pipeline.connect("document_splitter", "document_embedder")
+preprocessing_pipeline.connect("document_embedder", "document_writer")
+
+preprocessing_pipeline.run({"file_type_router": {"sources": list(Path(output_dir).glob("**/*"))}})
+```
+
++ +## Additional References + +:notebook: Tutorial: [Preprocessing Different File Types](https://haystack.deepset.ai/tutorials/30_file_type_preprocessing_index_pipeline) diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/listjoiner.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/listjoiner.mdx new file mode 100644 index 0000000000..adfb2be615 --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/listjoiner.mdx @@ -0,0 +1,94 @@ +--- +title: "ListJoiner" +id: listjoiner +slug: "/listjoiner" +description: "A component that joins multiple lists into a single flat list." +--- + +# ListJoiner + +A component that joins multiple lists into a single flat list. + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing and query pipelines, after components that return lists of documents such as multiple [Retrievers](../retrievers.mdx) or multiple [Converters](../converters.mdx) |
+| **Mandatory run variables** | `values`: The dictionary of lists to be joined |
+| **Output variables** | `values`: A dictionary with a `values` key containing the joined list |
+| **API reference** | [Joiners](/reference/joiners-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/joiners/list_joiner.py |
+
+
+
+## Overview
+
+The `ListJoiner` component combines multiple lists into one list. It is useful for combining multiple lists from different pipeline components, merging LLM responses, handling multi-step data processing, and gathering data from different sources into one list.
+
+The items stay in order based on when each input list was processed in a pipeline.
+
+You can optionally specify a `list_type_` parameter to set the expected type of the lists being joined (for example, `List[ChatMessage]`). If not set, `ListJoiner` will accept lists containing mixed data types.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.joiners import ListJoiner
+
+list1 = ["Hello", "world"]
+list2 = ["This", "is", "Haystack"]
+list3 = ["ListJoiner", "Example"]
+
+joiner = ListJoiner()
+
+result = joiner.run(values=[list1, list2, list3])
+
+print(result["values"])
+```
+
+### In a pipeline
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+from haystack.components.joiners import ListJoiner
+from typing import List
+
+user_message = [ChatMessage.from_user("Give a brief answer the following question: {{query}}")]
+
+feedback_prompt = """
+ You are given a question and an answer.
+ Your task is to provide a score and a brief feedback on the answer.
+ Question: {{query}}
+ Answer: {{response}}
+ """
+feedback_message = [ChatMessage.from_system(feedback_prompt)]
+
+prompt_builder = ChatPromptBuilder(template=user_message)
+feedback_prompt_builder = ChatPromptBuilder(template=feedback_message)
+llm = OpenAIChatGenerator(model="gpt-4o-mini")
+feedback_llm = OpenAIChatGenerator(model="gpt-4o-mini")
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.add_component("feedback_prompt_builder", feedback_prompt_builder)
+pipe.add_component("feedback_llm", feedback_llm)
+pipe.add_component("list_joiner", ListJoiner(List[ChatMessage]))
+
+pipe.connect("prompt_builder.prompt", "llm.messages")
+pipe.connect("prompt_builder.prompt", "list_joiner")
+pipe.connect("llm.replies", "list_joiner")
+pipe.connect("llm.replies", "feedback_prompt_builder.response")
+pipe.connect("feedback_prompt_builder.prompt", "feedback_llm.messages")
+pipe.connect("feedback_llm.replies", "list_joiner")
+
+query = "What is nuclear physics?"
+ans = pipe.run(data={"prompt_builder": {"template_variables":{"query": query}},
+ "feedback_prompt_builder": {"template_variables":{"query": query}}})
+
+print(ans["list_joiner"]["values"])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/stringjoiner.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/stringjoiner.mdx
new file mode 100644
index 0000000000..a4322e72f9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/stringjoiner.mdx
@@ -0,0 +1,52 @@
+---
+title: "StringJoiner"
+id: stringjoiner
+slug: "/stringjoiner"
+description: "Component to join strings from different components into a list of strings."
+---
+
+# StringJoiner
+
+Component to join strings from different components into a list of strings.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After at least two other components to join their strings |
+| **Mandatory run variables** | `strings`: Multiple strings from connected components. |
+| **Output variables** | `strings`: A list of merged strings |
+| **API reference** | [Joiners](/reference/joiners-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/joiners/string_joiner.py |
+
+
+
+## Overview
+
+The `StringJoiner` component collects multiple string outputs from various pipeline components and combines them into a single list. This is useful when you need to merge several strings from different parts of a pipeline into a unified output.
+
+## Usage
+
+```python
+from haystack.components.joiners import StringJoiner
+from haystack.components.builders import PromptBuilder
+from haystack.core.pipeline import Pipeline
+
+string_1 = "What's Natural Language Processing?"
+string_2 = "What is life?"
+
+pipeline = Pipeline()
+pipeline.add_component("prompt_builder_1", PromptBuilder("Builder 1: {{query}}"))
+pipeline.add_component("prompt_builder_2", PromptBuilder("Builder 2: {{query}}"))
+pipeline.add_component("string_joiner", StringJoiner())
+
+pipeline.connect("prompt_builder_1.prompt", "string_joiner.strings")
+pipeline.connect("prompt_builder_2.prompt", "string_joiner.strings")
+
+result = pipeline.run(data={
+ "prompt_builder_1": {"query": string_1},
+ "prompt_builder_2": {"query": string_2}
+})
+
+print(result)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors.mdx
new file mode 100644
index 0000000000..96d0582bfb
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors.mdx
@@ -0,0 +1,22 @@
+---
+title: "PreProcessors"
+id: preprocessors
+slug: "/preprocessors"
+description: "Use the PreProcessors to prepare your data normalize white spaces, remove headers and footers, clean empty lines in your Documents, or split them into smaller pieces. PreProcessors are useful in an indexing pipeline to prepare your files for search."
+---
+
+# PreProcessors
+
+Use the PreProcessors to prepare your data normalize white spaces, remove headers and footers, clean empty lines in your Documents, or split them into smaller pieces. PreProcessors are useful in an indexing pipeline to prepare your files for search.
+
+| PreProcessor | Description |
+| --- | --- |
+| [ChineseDocumentSplitter](preprocessors/chinesedocumentsplitter.mdx) | Divides Chinese text documents into smaller chunks using advanced Chinese language processing capabilities, using HanLP for accurate Chinese word segmentation and sentence tokenization. |
+| [CSVDocumentCleaner](preprocessors/csvdocumentcleaner.mdx) | Cleans CSV documents by removing empty rows and columns while preserving specific ignored rows and columns. |
+| [CSVDocumentSplitter](preprocessors/csvdocumentsplitter.mdx) | Divides CSV documents into smaller sub-tables based on empty rows and columns. |
+| [DocumentCleaner](preprocessors/documentcleaner.mdx) | Removes extra whitespaces, empty lines, specified substrings, regexes, page headers, and footers from documents. |
+| [DocumentPreprocessor](preprocessors/documentpreprocessor.mdx) | Divides a list of text documents into a list of shorter text documents and then makes them more readable by cleaning. |
+| [DocumentSplitter](preprocessors/documentsplitter.mdx) | Splits a list of text documents into a list of text documents with shorter texts. |
+| [HierarchicalDocumentSplitter](preprocessors/hierarchicaldocumentsplitter.mdx) | Creates a multi-level document structure based on parent-children relationships between text segments. |
+| [RecursiveSplitter](preprocessors/recursivesplitter.mdx) | Splits text into smaller chunks, it does so by recursively applying a list of separators to the text, applied in the order they are provided. | +| [TextCleaner](preprocessors/textcleaner.mdx) | Removes regexes, punctuation, and numbers, as well as converts text to lowercase. Useful to clean up text data before evaluation. | diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/chinesedocumentsplitter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/chinesedocumentsplitter.mdx new file mode 100644 index 0000000000..aa6ee4b368 --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/chinesedocumentsplitter.mdx @@ -0,0 +1,190 @@ +--- +title: "ChineseDocumentSplitter" +id: chinesedocumentsplitter +slug: "/chinesedocumentsplitter" +description: "`ChineseDocumentSplitter` divides Chinese text documents into smaller chunks using advanced Chinese language processing capabilities. It leverages HanLP for accurate Chinese word segmentation and sentence tokenization, making it ideal for processing Chinese text that requires linguistic awareness." +--- + +# ChineseDocumentSplitter + +`ChineseDocumentSplitter` divides Chinese text documents into smaller chunks using advanced Chinese language processing capabilities. It leverages HanLP for accurate Chinese word segmentation and sentence tokenization, making it ideal for processing Chinese text that requires linguistic awareness. + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) and [DocumentCleaner](documentcleaner.mdx), before [Classifiers](../classifiers.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents with Chinese text content |
+| **Output variables** | `documents`: A list of documents, each containing a chunk of the original Chinese text |
+| **API reference** | [HanLP](/reference/integrations-hanlp) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/hanlp |
+
+
+
+## Overview
+
+`ChineseDocumentSplitter` is a specialized document splitter designed specifically for Chinese text processing. Unlike English text where words are separated by spaces, Chinese text is written continuously without spaces between words.
+
+This component leverages HanLP (Han Language Processing) to provide accurate Chinese word segmentation and sentence tokenization. It supports two granularity levels:
+
+- **Coarse granularity**: Provides broader word segmentation suitable for most general use cases. Uses `COARSE_ELECTRA_SMALL_ZH` model for general-purpose segmentation.
+- **Fine granularity**: Offers more detailed word segmentation for specialized applications. Uses `FINE_ELECTRA_SMALL_ZH` model for detailed segmentation.
+
+The splitter can divide documents by various units:
+
+- `word`: Splits by Chinese words (multi-character tokens)
+- `sentence`: Splits by sentences using HanLP sentence tokenizer
+- `passage`: Splits by double line breaks ("\\n\\n")
+- `page`: Splits by form feed characters ("\\f")
+- `line`: Splits by single line breaks ("\\n")
+- `period`: Splits by periods (".")
+- `function`: Uses a custom splitting function
+
+Each extracted chunk retains metadata from the original document and includes additional fields:
+
+- `source_id`: The ID of the original document
+- `page_number`: The page number the chunk belongs to
+- `split_id`: The sequential ID of the split within the document
+- `split_idx_start`: The starting index of the chunk in the original document
+
+When `respect_sentence_boundary=True` is set, the component uses HanLP's sentence tokenizer (`UD_CTB_EOS_MUL`) to ensure that splits occur only between complete sentences, preserving the semantic integrity of the text.
+
+## Usage
+
+### On its own
+
+You can use `ChineseDocumentSplitter` outside of a pipeline to process Chinese documents directly:
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter
+
+## Initialize the splitter with word-based splitting
+splitter = ChineseDocumentSplitter(
+ split_by="word",
+ split_length=10,
+ split_overlap=3,
+ granularity="coarse"
+)
+
+## Create a Chinese document
+doc = Document(content="这是第一句话，这是第二句话，这是第三句话。这是第四句话，这是第五句话，这是第六句话！")
+
+## Warm up the component (loads the necessary models)
+splitter.warm_up()
+
+## Split the document
+result = splitter.run(documents=[doc])
+print(result["documents"]) # List of split documents
+```
+
+### With sentence boundary respect
+
+When splitting by words, you can ensure that sentence boundaries are respected:
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter
+
+doc = Document(content=
+ "这是第一句话，这是第二句话，这是第三句话。"
+ "这是第四句话，这是第五句话，这是第六句话！"
+ "这是第七句话，这是第八句话，这是第九句话？"
+)
+
+splitter = ChineseDocumentSplitter(
+ split_by="word",
+ split_length=10,
+ split_overlap=3,
+ respect_sentence_boundary=True,
+ granularity="coarse"
+)
+splitter.warm_up()
+result = splitter.run(documents=[doc])
+
+## Each chunk will end with a complete sentence
+for doc in result["documents"]:
+ print(f"Chunk: {doc.content}")
+ print(f"Ends with sentence: {doc.content.endswith(('。', '！', '？'))}")
+```
+
+### With fine granularity
+
+For more detailed word segmentation:
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter
+
+doc = Document(content="人工智能技术正在快速发展，改变着我们的生活方式。")
+
+splitter = ChineseDocumentSplitter(
+ split_by="word",
+ split_length=5,
+ split_overlap=0,
+ granularity="fine" # More detailed segmentation
+)
+splitter.warm_up()
+result = splitter.run(documents=[doc])
+print(result["documents"])
+```
+
+### With custom splitting function
+
+You can also use a custom function for splitting:
+
+```python
+from haystack import Document
+from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter
+
+def custom_split(text: str) -> list[str]:
+ """Custom splitting function that splits by commas"""
+ return text.split("，")
+
+doc = Document(content="第一段，第二段，第三段，第四段")
+
+splitter = ChineseDocumentSplitter(
+ split_by="function",
+ splitting_function=custom_split
+)
+splitter.warm_up()
+result = splitter.run(documents=[doc])
+print(result["documents"])
+```
+
+### In a pipeline
+
+Here's how you can integrate `ChineseDocumentSplitter` into a Haystack indexing pipeline:
+
+```python
+from haystack import Pipeline, Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.txt import TextFileToDocument
+from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.writers import DocumentWriter
+
+## Initialize components
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=TextFileToDocument(), name="text_file_converter")
+p.add_component(instance=DocumentCleaner(), name="cleaner")
+p.add_component(instance=ChineseDocumentSplitter(
+ split_by="word",
+ split_length=100,
+ split_overlap=20,
+ respect_sentence_boundary=True,
+ granularity="coarse"
+), name="chinese_splitter")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+
+## Connect components
+p.connect("text_file_converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "chinese_splitter.documents")
+p.connect("chinese_splitter.documents", "writer.documents")
+
+## Run pipeline with Chinese text files
+p.run({"text_file_converter": {"sources": ["path/to/your/chinese/files.txt"]}})
+```
+
+This pipeline processes Chinese text files by converting them to documents, cleaning the text, splitting them into linguistically-aware chunks using Chinese word segmentation, and storing the results in the Document Store for further retrieval and processing.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/csvdocumentcleaner.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/csvdocumentcleaner.mdx
new file mode 100644
index 0000000000..bcf3f40ce4
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/csvdocumentcleaner.mdx
@@ -0,0 +1,86 @@
+---
+title: "CSVDocumentCleaner"
+id: csvdocumentcleaner
+slug: "/csvdocumentcleaner"
+description: "Use `CSVDocumentCleaner` to clean CSV documents by removing empty rows and columns while preserving specific ignored rows and columns. It processes CSV content stored in documents and helps standardize data for further analysis."
+---
+
+# CSVDocumentCleaner
+
+Use `CSVDocumentCleaner` to clean CSV documents by removing empty rows and columns while preserving specific ignored rows and columns. It processes CSV content stored in documents and helps standardize data for further analysis.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) , before [Embedders](../embedders.mdx) or [Writers](../writers/documentwriter.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents containing CSV content |
+| **Output variables** | `documents`: A list of cleaned CSV documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/csv_document_cleaner.py |
+
+
+
+## Overview
+
+`CSVDocumentCleaner` expects a list of `Document` objects as input, each containing CSV-formatted content as text. It cleans the data by removing fully empty rows and columns while allowing users to specify the number of rows and columns to be preserved before cleaning.
+
+### Parameters
+
+- `ignore_rows`: Number of rows to ignore from the top of the CSV table before processing. If any columns are removed, the same columns will be dropped from the ignored rows.
+- `ignore_columns`: Number of columns to ignore from the left of the CSV table before processing. If any rows are removed, the same rows will be dropped from the ignored columns.
+- `remove_empty_rows`: Whether to remove entirely empty rows.
+- `remove_empty_columns`: Whether to remove entirely empty columns.
+- `keep_id`: Whether to retain the original document ID in the output document.
+
+### Cleaning Process
+
+The `CSVDocumentCleaner` algorithm follows these steps:
+
+1. Reads each document's content as a CSV table using pandas.
+2. Retains the specified number of `ignore_rows` from the top and `ignore_columns` from the left.
+3. Drops any rows and columns that are entirely empty (contain only NaN values).
+4. If columns are dropped, they are also removed from ignored rows.
+5. If rows are dropped, they are also removed from ignored columns.
+6. Reattaches the remaining ignored rows and columns to maintain their original positions.
+7. Returns the cleaned CSV content as a new `Document` object.
+
+## Usage
+
+### On its own
+
+You can use `CSVDocumentCleaner` independently to clean up CSV documents:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import CSVDocumentCleaner
+
+cleaner = CSVDocumentCleaner(ignore_rows=1, ignore_columns=0)
+
+documents = [Document(content="""col1,col2,col3\n,,\na,b,c\n,,""" )]
+cleaned_docs = cleaner.run(documents=documents)
+```
+
+### In a pipeline
+
+```python
+from pathlib import Path
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import XLSXToDocument
+from haystack.components.preprocessors import CSVDocumentCleaner
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=XLSXToDocument(), name="xlsx_file_converter")
+p.add_component(instance=CSVDocumentCleaner(ignore_rows=1, ignore_columns=1), name="csv_cleaner")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+
+p.connect("xlsx_file_converter.documents", "csv_cleaner.documents")
+p.connect("csv_cleaner.documents", "writer.documents")
+
+p.run({"xlsx_file_converter": {"sources": [Path("your_xlsx_file.xlsx")]}})
+```
+
+This ensures that CSV documents are properly cleaned before further processing or storage.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/csvdocumentsplitter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/csvdocumentsplitter.mdx
new file mode 100644
index 0000000000..db0c8b8d82
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/csvdocumentsplitter.mdx
@@ -0,0 +1,117 @@
+---
+title: "CSVDocumentSplitter"
+id: csvdocumentsplitter
+slug: "/csvdocumentsplitter"
+description: "`CSVDocumentSplitter` divides CSV documents into smaller sub-tables based on split arguments. This is useful for handling structured data that contains multiple tables, improving data processing efficiency and retrieval."
+---
+
+# CSVDocumentSplitter
+
+`CSVDocumentSplitter` divides CSV documents into smaller sub-tables based on split arguments. This is useful for handling structured data that contains multiple tables, improving data processing efficiency and retrieval.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) , before [CSVDocumentCleaner](csvdocumentcleaner.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents with CSV-formatted content |
+| **Output variables** | `documents`: A list of documents, each containing a sub-table extracted from the original CSV file |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/csv_document_splitter.py |
+
+
+
+## Overview
+
+`CSVDocumentSplitter` expects a list of documents containing CSV-formatted content and returns a list of new `Document` objects, each representing a sub-table extracted from the original document.
+
+There are two modes of operation for the splitter:
+
+1. `threshold` (Default): Identifies empty rows or columns exceeding a given threshold and splits the document accordingly.
+2. `row-wise`: Splits each row into a separate document, treating each as an independent sub-table.
+
+The splitting process follows these rules:
+
+1. **Row-Based Splitting**: If `row_split_threshold` is set, consecutive empty rows equalling or exceeding this threshold trigger a split.
+2. **Column-Based Splitting**: If `column_split_threshold` is set, consecutive empty columns equalling or exceeding this threshold trigger a split.
+3. **Recursive Splitting**: If both thresholds are provided, `CSVDocumentSplitter` first splits by rows and then by columns. If more empty rows are detected, the splitting process is called again. This ensures that sub-tables are fully separated.
+
+Each extracted sub-table retains metadata from the original document and includes additional fields:
+
+- `source_id`: The ID of the original document
+- `row_idx_start`: The starting row index of the sub-table in the original document
+- `col_idx_start`: The starting column index of the sub-table in the original document
+- `split_id`: The sequential ID of the split within the document
+
+This component is especially useful for document processing pipelines that require structured data to be extracted and stored efficiently.
+
+### Supported Document Stores
+
+`CSVDocumentSplitter` is compatible with the following Document Stores:
+
+- [AstraDocumentStore](../../document-stores/astradocumentstore.mdx)
+- [ChromaDocumentStore](../../document-stores/chromadocumentstore.mdx)
+- [ElasticsearchDocumentStore](../../document-stores/elasticsearch-document-store.mdx)
+- [OpenSearchDocumentStore](../../document-stores/opensearch-document-store.mdx)
+- [PgvectorDocumentStore](../../document-stores/pgvectordocumentstore.mdx)
+- [PineconeDocumentStore](../../document-stores/pinecone-document-store.mdx)
+- [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx)
+- [WeaviateDocumentStore](../../document-stores/weaviatedocumentstore.mdx)
+- [MilvusDocumentStore](https://haystack.deepset.ai/integrations/milvus-document-store)
+- [Neo4jDocumentStore](https://haystack.deepset.ai/integrations/neo4j-document-store)
+
+## Usage
+
+### On its own
+
+You can use `CSVDocumentSplitter` outside of a pipeline to process CSV documents directly:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import CSVDocumentSplitter
+
+splitter = CSVDocumentSplitter(row_split_threshold=1, column_split_threshold=1)
+
+doc = Document(
+ content="""ID,LeftVal,,,RightVal,Extra
+1,Hello,,,World,Joined
+2,StillLeft,,,StillRight,Bridge
+,,,,,
+A,B,,,C,D
+E,F,,,G,H
+"""
+)
+split_result = splitter.run([doc])
+print(split_result["documents"]) # List of split tables as Documents
+```
+
+### In a pipeline
+
+Here's how you can integrate `CSVDocumentSplitter` into a Haystack indexing pipeline:
+
+```python
+from haystack import Pipeline, Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.csv import CSVToDocument
+from haystack.components.preprocessors import CSVDocumentSplitter
+from haystack.components.preprocessors import CSVDocumentCleaner
+from haystack.components.writers import DocumentWriter
+
+## Initialize components
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=CSVToDocument(), name="csv_file_converter")
+p.add_component(instance=CSVDocumentSplitter(), name="splitter")
+p.add_component(instance=CSVDocumentCleaner(), name="cleaner")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+
+## Connect components
+p.connect("csv_file_converter.documents", "splitter.documents")
+p.connect("splitter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "writer.documents")
+
+## Run pipeline
+p.run({"csv_file_converter": {"sources": ["path/to/your/file.csv"]}})
+```
+
+This pipeline extracts CSV content, splits it into structured sub-tables, cleans the CSV documents by removing empty rows and columns, and stores the resulting documents in the Document Store for further retrieval and processing.
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentcleaner.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentcleaner.mdx
new file mode 100644
index 0000000000..c006a901d8
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentcleaner.mdx
@@ -0,0 +1,86 @@
+---
+title: "DocumentCleaner"
+id: documentcleaner
+slug: "/documentcleaner"
+description: "Use `DocumentCleaner` to make text documents more readable. It removes extra whitespaces, empty lines, specified substrings, regexes, page headers, and footers in this particular order. This is useful for preparing the documents for further processing by LLMs."
+---
+
+# DocumentCleaner
+
+Use `DocumentCleaner` to make text documents more readable. It removes extra whitespaces, empty lines, specified substrings, regexes, page headers, and footers in this particular order. This is useful for preparing the documents for further processing by LLMs.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) , after [`DocumentSplitter`](documentsplitter.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/document_cleaner.py |
+
+
+
+## Overview
+
+`DocumentCleaner` expects a list of documents as input and returns a list of documents with cleaned texts. Selectable cleaning steps for each input document are to `remove_empty_lines`, `remove_extra_whitespaces` and to `remove_repeated_substrings`. These three parameters are booleans that can be set when the component is initialized.
+
+- `unicode_normalization` normalizes Unicode characters to a standard form. The parameter can be set to NFC, NFKC, NFD, or NFKD.
+- `ascii_only` removes accents from characters and replaces them with their closest ASCII equivalents.
+- `remove_empty_lines` removes empty lines from the document.
+- `remove_extra_whitespaces` removes extra whitespaces from the document.
+- `remove_repeated_substrings` removes repeated substrings (headers/footers) from pages in the document. Pages in the text need to be separated by form feed character "\\f", which is supported by [`TextFileToDocument`](../converters/textfiletodocument.mdx) and [`AzureOCRDocumentConverter`](../converters/azureocrdocumentconverter.mdx).
+
+In addition, you can specify a list of strings that should be removed from all documents as part of the cleaning with the parameter `remove_substring`. You can also specify a regular expression with the parameter `remove_regex` and any matches will be removed.
+
+The cleaning steps are executed in the following order:
+
+1. unicode_normalization
+2. ascii_only
+3. remove_extra_whitespaces
+4. remove_empty_lines
+5. remove_substrings
+6. remove_regex
+7. remove_repeated_substrings
+
+## Usage
+
+### On its own
+
+You can use it outside of a pipeline to clean up your documents:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentCleaner
+
+doc = Document(content="This is a document to clean\n\n\nsubstring to remove")
+
+cleaner = DocumentCleaner(remove_substrings = ["substring to remove"])
+result = cleaner.run(documents=[doc])
+
+assert result["documents"][0].content == "This is a document to clean "
+```
+
+### In a pipeline
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=TextFileToDocument(), name="text_file_converter")
+p.add_component(instance=DocumentCleaner(), name="cleaner")
+p.add_component(instance=DocumentSplitter(split_by="sentence", split_length=1), name="splitter")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+p.connect("text_file_converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+p.run({"text_file_converter": {"sources": your_files}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentpreprocessor.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentpreprocessor.mdx
new file mode 100644
index 0000000000..4efec6a9d9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentpreprocessor.mdx
@@ -0,0 +1,79 @@
+---
+title: "DocumentPreprocessor"
+id: documentpreprocessor
+slug: "/documentpreprocessor"
+description: "Divides a list of text documents into a list of shorter text documents and then makes them more readable by cleaning."
+---
+
+# DocumentPreprocessor
+
+Divides a list of text documents into a list of shorter text documents and then makes them more readable by cleaning.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of split and cleaned documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/document_preprocessor.py |
+
+
+
+## Overview
+
+`DocumentPreprocessor` first splits and then cleans documents.
+
+It is a SuperComponent that combines a `DocumentSplitter` and a `DocumentCleaner` into a single component.
+
+### Parameters
+
+The `DocumentPreprocessor` exposes all initialization parameters of the underlying `DocumentSplitter` and `DocumentCleaner`, and they are all optional. A detailed description of their parameters is in the respective documentation pages:
+
+- [DocumentSplitter](documentsplitter.mdx)
+- [DocumentCleaner](documentcleaner.mdx)
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentPreprocessor
+
+doc = Document(content="I love pizza!")
+preprocessor = DocumentPreprocessor()
+
+result = preprocessor.run(documents=[doc])
+print(result["documents"])
+```
+
+### In a pipeline
+
+You can use the `DocumentPreprocessor` in your indexing pipeline. The example below requires installing additional dependencies for the `MultiFileConverter`:
+
+```shell
+pip install pypdf markdown-it-py mdit_plain trafilatura python-pptx python-docx jq openpyxl tabulate pandas
+```
+
+```python
+from haystack import Pipeline
+from haystack.components.converters import MultiFileConverter
+from haystack.components.preprocessors import DocumentPreprocessor
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+
+pipeline = Pipeline()
+pipeline.add_component("converter", MultiFileConverter())
+pipeline.add_component("preprocessor", DocumentPreprocessor())
+pipeline.add_component("writer", DocumentWriter(document_store = document_store))
+pipeline.connect("converter", "preprocessor")
+pipeline.connect("preprocessor", "writer")
+
+result = pipeline.run(data={"sources": ["test.txt", "test.pdf"]})
+print(result)
+## {'writer': {'documents_written': 3}}
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentsplitter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentsplitter.mdx
new file mode 100644
index 0000000000..e7d1d72fab
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentsplitter.mdx
@@ -0,0 +1,92 @@
+---
+title: "DocumentSplitter"
+id: documentsplitter
+slug: "/documentsplitter"
+description: "`DocumentSplitter` divides a list of text documents into a list of shorter text documents. This is useful for long texts that otherwise wouldn't fit into the maximum text length of language models and can also speed up question answering."
+---
+
+# DocumentSplitter
+
+`DocumentSplitter` divides a list of text documents into a list of shorter text documents. This is useful for long texts that otherwise wouldn't fit into the maximum text length of language models and can also speed up question answering.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) and [`DocumentCleaner`](documentcleaner.mdx) , before [Classifiers](../classifiers.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/document_splitter.py |
+
+
+
+## Overview
+
+`DocumentSplitter` expects a list of documents as input and returns a list of documents with split texts. It splits each input document by `split_by` after `split_length` units with an overlap of `split_overlap` units. These additional parameters can be set when the component is initialized:
+
+- `split_by` can be `"word"`, `"sentence"`, `"passage"` (paragraph), `"page"`, `"line"` or `"function"`.
+- `split_length` is an integer indicating the chunk size, which is the number of words, sentences, or passages.
+- `split_overlap` is an integer indicating the number of overlapping words, sentences, or passages between chunks.
+- `split_threshold` is an integer indicating the minimum number of words, sentences, or passages that the document fragment should have. If the fragment is below the threshold, it will be attached to the previous one.
+
+A field `"source_id"` is added to each document's `meta` data to keep track of the original document that was split. Another meta field `"page_number"` is added to each document to keep track of the page it belonged to in the original document. Other metadata are copied from the original document.
+
+The DocumentSplitter is compatible with the following DocumentStores:
+
+- [AstraDocumentStore](../../document-stores/astradocumentstore.mdx)
+- [ChromaDocumentStore](../../document-stores/chromadocumentstore.mdx) – limited support, overlapping information is not stored.
+- [ElasticsearchDocumentStore](../../document-stores/elasticsearch-document-store.mdx)
+- [OpenSearchDocumentStore](../../document-stores/opensearch-document-store.mdx)
+- [PgvectorDocumentStore](../../document-stores/pgvectordocumentstore.mdx)
+- [PineconeDocumentStore](../../document-stores/pinecone-document-store.mdx) – limited support, overlapping information is not stored.
+- [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx)
+- [WeaviateDocumentStore](../../document-stores/weaviatedocumentstore.mdx)
+- [MilvusDocumentStore](https://haystack.deepset.ai/integrations/milvus-document-store)
+- [Neo4jDocumentStore](https://haystack.deepset.ai/integrations/neo4j-document-store)
+
+## Usage
+
+### On its own
+
+You can use this component outside of a pipeline to shorten your documents like this:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentSplitter
+
+doc = Document(content="Moonlight shimmered softly, wolves howled nearby, night enveloped everything.")
+
+splitter = DocumentSplitter(split_by="word", split_length=3, split_overlap=0)
+result = splitter.run(documents=[doc])
+```
+
+### In a pipeline
+
+Here's how you can use `DocumentSplitter` in an indexing pipeline:
+
+```python
+from pathlib import Path
+
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.txt import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=TextFileToDocument(), name="text_file_converter")
+p.add_component(instance=DocumentCleaner(), name="cleaner")
+p.add_component(instance=DocumentSplitter(split_by="sentence", split_length=1), name="splitter")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+p.connect("text_file_converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+path = "path/to/your/files"
+files = list(Path(path).glob("*.md"))
+p.run({"text_file_converter": {"sources": files}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/hierarchicaldocumentsplitter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/hierarchicaldocumentsplitter.mdx
new file mode 100644
index 0000000000..4454348852
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/hierarchicaldocumentsplitter.mdx
@@ -0,0 +1,97 @@
+---
+title: "HierarchicalDocumentSplitter"
+id: hierarchicaldocumentsplitter
+slug: "/hierarchicaldocumentsplitter"
+description: "Use this component to create a multi-level document structure based on parent-children relationships between text segments."
+---
+
+# HierarchicalDocumentSplitter
+
+Use this component to create a multi-level document structure based on parent-children relationships between text segments.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In indexing pipelines after [Converters](../converters.mdx) and [`DocumentCleaner`](documentcleaner.mdx) |
+| **Mandatory init variables** | `block_sizes`: Set of block sizes to split the document into. The blocks are split in descending order. |
+| **Mandatory run variables** | `documents`: A list of documents to split into hierarchical blocks |
+| **Output variables** | `documents`: A list of hierarchical documents |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | [https://github.com/deepset-ai/haystack/blob/dae8c7babaf28d2ffab4f2a8dedecd63e2394fb4/haystack/components/preprocessors/hierarchical_document_splitter.py](https://github.com/deepset-ai/haystack/blob/dae8c7babaf28d2ffab4f2a8dedecd63e2394fb4/haystack/components/preprocessors/hierarchical_document_splitter.py#L12) |
+
+
+
+## Overview
+
+The `HierarchicalDocumentSplitter` divides documents into blocks of different sizes, creating a tree-like structure.
+
+A block is one of the chunks of text that the splitter produces. It is similar to cutting a long piece of text into smaller pieces: each piece is a block. Blocks form a tree structure where your full document is the root block, and as you split it into smaller and smaller pieces you get child-blocks and leaf-blocks, down to whatever smallest size specified.
+
+The [`AutoMergingRetriever`](../retrievers/automergingretriever.mdx) component then leverages this hierarchical structure to improve document retrieval.
+
+To initialize the component, you need to specify the `block_size`, which is the “maximum length” of each of the blocks, measured in the specific unit (see `split_by` parameter). Pass a set of sizes (for example, `{20, 5}`), and it will:
+
+- First, split the document into blocks of up to 20 units each (the “parent” blocks).
+- Then, it will split each of those into blocks of up to 5 units each (the “child” blocks).
+
+This descending order of sizes builds the hierarchy.
+
+These additional parameters can be set when the component is initialized:
+
+- `split_by` can be `"word"` (default), `"sentence"`, `"passage"`, `"page"`.
+- `split_overlap` is an integer indicating the number of overlapping words, sentences, or passages between chunks, 0 being the default.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import HierarchicalDocumentSplitter
+
+doc = Document(content="This is a simple test document")
+splitter = HierarchicalDocumentSplitter(block_sizes={3, 2}, split_overlap=0, split_by="word")
+splitter.run([doc])
+
+>> {'documents': [Document(id=3f7..., content: 'This is a simple test document', meta: {'block_size': 0, 'parent_id': None, 'children_ids': ['5ff..', '8dc..'], 'level': 0}),
+>> Document(id=5ff.., content: 'This is a ', meta: {'block_size': 3, 'parent_id': '3f7..', 'children_ids': ['f19..', '52c..'], 'level': 1, 'source_id': '3f7..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+>> Document(id=8dc.., content: 'simple test document', meta: {'block_size': 3, 'parent_id': '3f7..', 'children_ids': ['39d..', 'e23..'], 'level': 1, 'source_id': '3f7..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 10}),
+>> Document(id=f19.., content: 'This is ', meta: {'block_size': 2, 'parent_id': '5ff..', 'children_ids': [], 'level': 2, 'source_id': '5ff..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+>> Document(id=52c.., content: 'a ', meta: {'block_size': 2, 'parent_id': '5ff..', 'children_ids': [], 'level': 2, 'source_id': '5ff..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 8}),
+>> Document(id=39d.., content: 'simple test ', meta: {'block_size': 2, 'parent_id': '8dc..', 'children_ids': [], 'level': 2, 'source_id': '8dc..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+>> Document(id=e23.., content: 'document', meta: {'block_size': 2, 'parent_id': '8dc..', 'children_ids': [], 'level': 2, 'source_id': '8dc..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 12})]}
+```
+
+### In a pipeline
+
+This Haystack pipeline processes `.md` files by converting them to documents, cleaning the text, splitting it into sentence-based chunks, and storing the results in an In-Memory Document Store.
+
+```python
+from pathlib import Path
+
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.txt import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import HierarchicalDocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+
+Pipeline = Pipeline()
+Pipeline.add_component(instance=TextFileToDocument(), name="text_file_converter")
+Pipeline.add_component(instance=DocumentCleaner(), name="cleaner")
+Pipeline.add_component(instance=HierarchicalDocumentSplitter(
+ block_sizes={10, 6, 3}, split_overlap=0, split_by="sentence", name="splitter"
+)
+Pipeline.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+Pipeline.connect("text_file_converter.documents", "cleaner.documents")
+Pipeline.connect("cleaner.documents", "splitter.documents")
+Pipeline.connect("splitter.documents", "writer.documents")
+
+path = "path/to/your/files"
+files = list(Path(path).glob("*.md"))
+Pipeline.run({"text_file_converter": {"sources": files}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/recursivesplitter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/recursivesplitter.mdx
new file mode 100644
index 0000000000..1bed20d60e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/recursivesplitter.mdx
@@ -0,0 +1,98 @@
+---
+title: "RecursiveDocumentSplitter"
+id: recursivesplitter
+slug: "/recursivesplitter"
+description: "This component recursively breaks down text into smaller chunks by applying a given list of separators to the text."
+---
+
+# RecursiveDocumentSplitter
+
+This component recursively breaks down text into smaller chunks by applying a given list of separators to the text.
+
+
+
+| | |
+| --- | --- |
+| Most common position in a pipeline | In indexing pipelines after [Converters](../converters.mdx) and [`DocumentCleaner`](documentcleaner.mdx) , before [Classifiers](../classifiers.mdx) |
+| Mandatory run variables | `documents`: A list of documents |
+| Output variables | `documents`: A list of documents |
+| API reference | [PreProcessors](/reference/preprocessors-api) |
+| Github link | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/recursive_splitter.py |
+
+
+
+## Overview
+
+The `RecursiveDocumentSplitter` expects a list of documents as input and returns a list of documents with split texts. You can set the following parameters when initializing the component:
+
+- `split_length`: The maximum length of each chunk, in words, by default. See the `split_units` parameter to change the the unit.
+- `split_overlap`: The number of characters or words that overlap between consecutive chunks.
+- `split_unit`: The unit of the `split_length` parameter. Can be either `"word"`, `"char"`, or `"token"`.
+- `separators`: An optional list of separator strings to use for splitting the text. If you don’t provide any separators, the default ones are `["\n\n", "sentence", "\n", " "]`. The string separators will be treated as regular expressions. If the separator is `"sentence"`, the text will be split into sentences using a custom sentence tokenizer based on NLTK. See [SentenceSplitter](https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/sentence_tokenizer.py#L116) code for more information.
+- `sentence_splitter_params`: Optional parameters to pass to the [SentenceSplitter](https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/sentence_tokenizer.py#L116).
+
+The separators are applied in the same order as they are defined in the list. The first separator is used on the text; any resulting chunk that is within the specified `chunk_size` is retained. For chunks that exceed the defined `chunk_size`, the next separator in the list is applied. If all separators are used and the chunk still exceeds the `chunk_size`, a hard split occurs based on the `chunk_size`, taking into account whether words or characters are used as counting units. This process is repeated until all chunks are within the limits of the specified `chunk_size`.
+
+## Usage
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import RecursiveDocumentSplitter
+
+chunker = RecursiveDocumentSplitter(split_length=260, split_overlap=0, separators=["\n\n", "\n", ".", " "])
+text = ('''Artificial intelligence (AI) - Introduction
+
+AI, in its broadest sense, is intelligence exhibited by machines, particularly computer systems.
+AI technology is widely used throughout industry, government, and science. Some high-profile applications include advanced web search engines; recommendation systems; interacting via human speech; autonomous vehicles; generative and creative tools; and superhuman play and analysis in strategy games.''')
+chunker.warm_up()
+doc = Document(content=text)
+doc_chunks = chunker.run([doc])
+print(doc_chunks["documents"])
+>[
+>Document(id=..., content: 'Artificial intelligence (AI) - Introduction\n\n', meta: {'original_id': '...', 'split_id': 0, 'split_idx_start': 0, '_split_overlap': []})
+>Document(id=..., content: 'AI, in its broadest sense, is intelligence exhibited by machines, particularly computer systems.\n', meta: {'original_id': '...', 'split_id': 1, 'split_idx_start': 45, '_split_overlap': []})
+>Document(id=..., content: 'AI technology is widely used throughout industry, government, and science.', meta: {'original_id': '...', 'split_id': 2, 'split_idx_start': 142, '_split_overlap': []})
+>Document(id=..., content: ' Some high-profile applications include advanced web search engines; recommendation systems; interac...', meta: {'original_id': '...', 'split_id': 3, 'split_idx_start': 216, '_split_overlap': []})
+>]
+```
+
+### In a pipeline
+
+Here's how you can use `RecursiveSplitter` in an indexing pipeline:
+
+```python
+from pathlib import Path
+
+from haystack import Document
+from haystack import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters.txt import TextFileToDocument
+from haystack.components.preprocessors import DocumentCleaner
+from haystack.components.preprocessors import RecursiveDocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=TextFileToDocument(), name="text_file_converter")
+p.add_component(instance=DocumentCleaner(), name="cleaner")
+p.add_component(instance=RecursiveDocumentSplitter(
+ split_length=400,
+ split_overlap=0,
+ split_unit="char",
+ separators=["\n\n", "\n", "sentence", " "],
+ sentence_splitter_params={
+ "language": "en",
+ "use_split_rules": True,
+ "keep_white_spaces": False
+ }
+ ),
+ name="recursive_splitter")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+p.connect("text_file_converter.documents", "cleaner.documents")
+p.connect("cleaner.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+
+path = "path/to/your/files"
+files = list(Path(path).glob("*.md"))
+p.run({"text_file_converter": {"sources": files}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/textcleaner.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/textcleaner.mdx
new file mode 100644
index 0000000000..8ffcc2ec43
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/textcleaner.mdx
@@ -0,0 +1,97 @@
+---
+title: "TextCleaner"
+id: textcleaner
+slug: "/textcleaner"
+description: "Use `TextCleaner` to make text data more readable. It removes regexes, punctuation, and numbers, as well as converts text to lowercase. This is especially useful to clean up text data before evaluation."
+---
+
+# TextCleaner
+
+Use `TextCleaner` to make text data more readable. It removes regexes, punctuation, and numbers, as well as converts text to lowercase. This is especially useful to clean up text data before evaluation.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Between a [Generator](../generators.mdx) and an [Evaluator](../evaluators.mdx) |
+| **Mandatory run variables** | `texts`: A list of strings to be cleaned |
+| **Output variables** | `texts`: A list of cleaned texts |
+| **API reference** | [PreProcessors](/reference/preprocessors-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/preprocessors/text_cleaner.py |
+
+
+
+## Overview
+
+`TextCleaner` expects a list of strings as input and returns a list of strings with cleaned texts. Selectable cleaning steps are to `convert_to_lowercase`, `remove_punctuation`, and to `remove_numbers`. These three parameters are booleans that need to be set when the component is initialized.
+
+- `convert_to_lowercase` converts all characters in texts to lowercase.
+- `remove_punctuation` removes all punctuation from the text.
+- `remove_numbers` removes all numerical digits from the text.
+
+In addition, you can specify a regular expression with the parameter `remove_regexps`, and any matches will be removed.
+
+## Usage
+
+### On its own
+
+You can use it outside of a pipeline to clean up any texts:
+
+```python
+from haystack.components.preprocessors import TextCleaner
+
+text_to_clean = "1Moonlight shimmered softly, 300 Wolves howled nearby, Night enveloped everything."
+
+cleaner = TextCleaner(convert_to_lowercase=True, remove_punctuation=False, remove_numbers=True)
+result = cleaner.run(texts=[text_to_clean])
+```
+
+### In a pipeline
+
+In this example, we are using `TextCleaner` after an `ExtractiveReader` and an `OutputAdapter` to remove the punctuation in texts. Then, our custom-made `ExactMatchEvaluator` component compares the retrieved answer to the ground truth answer.
+
+```python
+from typing import List
+from haystack import component, Document, Pipeline
+from haystack.components.converters import OutputAdapter
+from haystack.components.preprocessors import TextCleaner
+from haystack.components.readers import ExtractiveReader
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+document_store.write_documents(documents=documents)
+
+@component
+class ExactMatchEvaluator:
+ @component.output_types(score=int)
+ def run(self, expected: str, provided: List[str]):
+ return {"score": int(expected in provided)}
+
+adapter = OutputAdapter(
+ template="{{answers | extract_data}}",
+ output_type=List[str],
+ custom_filters={"extract_data": lambda data: [answer.data for answer in data if answer.data]}
+)
+
+p = Pipeline()
+p.add_component("retriever", InMemoryBM25Retriever(document_store=document_store))
+p.add_component("reader", ExtractiveReader())
+p.add_component("adapter", adapter)
+p.add_component("cleaner", TextCleaner(remove_punctuation=True))
+p.add_component("evaluator", ExactMatchEvaluator())
+
+p.connect("retriever", "reader")
+p.connect("reader", "adapter")
+p.connect("adapter", "cleaner.texts")
+p.connect("cleaner", "evaluator.provided")
+
+question = "What behavior indicates a high level of self-awareness of elephants?"
+ground_truth_answer = "recognizing themselves in mirrors"
+
+result = p.run({"retriever": {"query": question}, "reader": {"query": question}, "evaluator": {"expected": ground_truth_answer}})
+print(result)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers.mdx
new file mode 100644
index 0000000000..61d05c530a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers.mdx
@@ -0,0 +1,25 @@
+---
+title: "Rankers"
+id: rankers
+slug: "/rankers"
+description: "Rankers are a group of components that order documents by given criteria. Their goal is to improve your document retrieval results."
+---
+
+# Rankers
+
+Rankers are a group of components that order documents by given criteria. Their goal is to improve your document retrieval results.
+
+| Ranker | Description |
+| --- | --- |
+| [AmazonBedrockRanker](rankers/amazonbedrockranker.mdx) | Ranks documents based on their similarity to the query using Amazon Bedrock models. |
+| [CohereRanker](rankers/cohereranker.mdx) | Ranks documents based on their similarity to the query using Cohere rerank models. |
+| [FastembedRanker](rankers/fastembedranker.mdx) | Ranks documents based on their similarity to the query using cross-encoder models supported by FastEmbed. |
+| [HuggingFaceTEIRanker](rankers/huggingfaceteiranker.mdx) | Ranks documents based on their similarity to the query using a Text Embeddings Inference (TEI) API endpoint. |
+| [JinaRanker](rankers/jinaranker.mdx) | Ranks documents based on their similarity to the query using Jina AI models. |
+| [LostInTheMiddleRanker](rankers/lostinthemiddleranker.mdx) | Positions the most relevant documents at the beginning and at the end of the resulting list while placing the least relevant documents in the middle, based on a [research paper](https://arxiv.org/abs/2307.03172). |
+| [MetaFieldRanker](rankers/metafieldranker.mdx) | A lightweight Ranker that orders documents based on a specific metadata field value. |
+| [MetaFieldGroupingRanker](rankers/metafieldgroupingranker.mdx) | Reorders the documents by grouping them based on metadata keys. |
+| [NvidiaRanker](rankers/nvidiaranker.mdx) | Ranks documents using large-language models from [NVIDIA NIMs](https://ai.nvidia.com) . |
+| [TransformersSimilarityRanker](rankers/transformerssimilarityranker.mdx) | A legacy version of [SentenceTransformersSimilarityRanker](rankers/sentencetransformerssimilarityranker.mdx). |
+| [SentenceTransformersDiversityRanker](rankers/sentencetransformersdiversityranker.mdx) | A Diversity Ranker based on Sentence Transformers. |
+| [SentenceTransformersSimilarityRanker](rankers/sentencetransformerssimilarityranker.mdx) | A model-based Ranker that orders documents based on their relevance to the query. It uses a cross-encoder model to produce query and document embeddings. It then compares the similarity of the query embedding to the document embeddings to produce a ranking with the most similar documents appearing first. It's a powerful Ranker that takes word order and syntax into account. You can use it to improve the initial ranking done by a weaker Retriever, but it's also more expensive computationally than the Rankers that don't use models. | diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/amazonbedrockranker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/amazonbedrockranker.mdx new file mode 100644 index 0000000000..b65281b8f5 --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/amazonbedrockranker.mdx @@ -0,0 +1,96 @@ +--- +title: "AmazonBedrockRanker" +id: amazonbedrockranker +slug: "/amazonbedrockranker" +description: "Use this component to rank documents based on their similarity to the query using Amazon Bedrock models." +--- + +# AmazonBedrockRanker + +Use this component to rank documents based on their similarity to the query using Amazon Bedrock models. + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `aws_access_key_id`: AWS access key ID. Can be set with AWS_ACCESS_KEY_ID env var.
`aws_secret_access_key`: AWS secret access key. Can be set with AWS_SECRET_ACCESS_KEY env var.
`aws_region_name`: AWS region name. Can be set with AWS_DEFAULT_REGION env var. | +| **Mandatory run variables** | `documents`: A list of document objects
`query`: A query string | +| **Output variables** | `documents`: A list of document objects | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock/ | + +
+
+## Overview
+
+`AmazonBedrockRanker` ranks documents based on semantic relevance to a specified query. It uses Amazon Bedrock Rerank API. This list of all supported models can be found in Amazon’s [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/rerank-supported.html). The default model for this Ranker is `cohere.rerank-v3-5:0`.
+
+You can also specify the `top_k` parameter to set the maximum number of documents to return.
+
+### Installation
+
+To start using Amazon Bedrock with Haystack, install the `amazon-bedrock-haystack` package:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### Authentication
+
+This component uses AWS for authentication. You can use the AWS CLI to authenticate through your IAM. For more information on setting up an IAM identity-based policy, see the [official documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html).
+
+:::info Using AWS CLI
+
+Consider using AWS CLI as a more straightforward tool to manage your AWS services. With AWS CLI, you can quickly configure your [boto3 credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html). This way, you won't need to provide detailed authentication parameters when initializing Amazon Bedrock in Haystack.
+:::
+
+To use this component, initialize it with the model name. The AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) should be set as environment variables, configured as described above, or passed as [Secret](../../concepts/secret-management.mdx) arguments. Make sure the region you set supports Amazon Bedrock.
+
+## Usage
+
+### On its own
+
+This example uses `AmazonBedrockRanker` to rank two simple documents. To run the Ranker, pass a `query` and provide the `documents`.
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.amazon_bedrock import AmazonBedrockRanker
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+
+ranker = AmazonBedrockRanker()
+
+ranker.run(query="City in France", documents=docs, top_k=1)
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `AmazonBedrockRanker` to rank the retrieved documents according to their similarity to the query. The pipeline uses the default settings of the Ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.rankers.amazon_bedrock import AmazonBedrockRanker
+
+docs = [
+ Document(content="Paris is in France"),
+ Document(content="Berlin is in Germany"),
+ Document(content="Lyon is in France"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = AmazonBedrockRanker()
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+res = document_ranker_pipeline.run(data={"retriever": {"query": query, "top_k": 3}, "ranker": {"query": query, "top_k": 2}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/choosing-the-right-ranker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/choosing-the-right-ranker.mdx
new file mode 100644
index 0000000000..71f56ba200
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/choosing-the-right-ranker.mdx
@@ -0,0 +1,60 @@
+---
+title: "Choosing the Right Ranker"
+id: choosing-the-right-ranker
+slug: "/choosing-the-right-ranker"
+description: "This page provides guidance on selecting the right Ranker for your pipeline in Haystack. It explains the distinctions between API-based, on-premise rankers and heuristic approaches, and offers advice based on latency, privacy, and diversity requirements."
+---
+
+# Choosing the Right Ranker
+
+This page provides guidance on selecting the right Ranker for your pipeline in Haystack. It explains the distinctions between API-based, on-premise rankers and heuristic approaches, and offers advice based on latency, privacy, and diversity requirements.
+
+Rankers in Haystack reorder a set of retrieved documents based on their estimated relevance to a user query. Rankers operate after retrieval and aim to refine the result list before it's passed to a downstream component like a [Generator](../generators.mdx) or [Reader](../readers.mdx).
+
+This reordering is based on additional signals beyond simple vector similarity. Depending on the Ranker used, these signals can include semantic similarity (with cross-encoders), structured metadata (such as timestamps or categories), or position-based heuristics (for example, placing relevant content at the start and end).
+
+A typical question answering pipeline using a Ranker includes:
+
+1. Retrieve: Use a [Retriever](../retrievers.mdx) to find a candidate set of documents.
+2. Rank: Reorder those documents using a Ranker component.
+3. Answer: Pass the re-ranked documents to a downstream [Generator](../generators.mdx) or [Reader](../readers.mdx).
+
+This guide helps you choose the right Ranker depending on your use case, whether you're optimizing for performance, cost, accuracy, or diversity in results. It focuses on selecting between different types of Rankers in Haystack, not specific models, but rather the general mechanism and interface that best suits your setup.
+
+## API Based Rankers
+
+These Rankers use external APIs to reorder documents using powerful models hosted remotely. They offer high-quality relevance scoring without local compute, but can be slower due to network latency and costly at scale.
+
+The pricing model varies by provider, some charge per token processed , while others bill by usage time or number of API calls. Refer to the respective provider documentation for precise cost structures.
+
+Most API-based Rankers in Haystack currently rely on cross-encoder models (currently, but might change in the future), which evaluate the query and document together to produce highly accurate relevance scores. Examples include [AmazonBedrockRanker](amazonbedrockranker.mdx), [CohereRanker](cohereranker.mdx) and [JinaRanker](jinaranker.mdx).
+
+In contrast, the [NvidiaRanker](nvidiaranker.mdx) uses large language models (LLMs) for ranking. These models treat relevance as a semantic reasoning task, which can yield better results for complex or multi-step queries, though often at higher computational cost.
+
+## On-Premise Rankers
+
+These Rankers run entirely on your local infrastructure. They are ideal for teams prioritizing data privacy, cost control, or low-latency inference without depending on external APIs. Since the models are executed locally, they avoid network bottlenecks and recurring usage costs, but require sufficient compute resources, typically GPU-backed, especially for cross-encoder models.
+
+All on-premise Rankers in Haystack use cross-encoder architectures. These models jointly process the query and each document to assess relevance with deep contextual awareness. For example:
+
+- [SentenceTransformersSimilarityRanker](sentencetransformerssimilarityranker.mdx) ranks documents based on semantic similarity to the query. In addition to the default PyTorch backend (optimal for GPU), it also offers other memory-efficient options which are suitable for CPU-only cases: ONNX and OpenVINO.
+- [TransformersSimilarityRanker](transformerssimilarityranker.mdx) is its legacy predecessor and should generally be avoided in favor of the newer, more flexible SentenceTransformersSimilarityRanker.
+- [HuggingFaceTEIRanker](huggingfaceteiranker.mdx) is based on the Text Embeddings Inference project: whether you have GPU resources or not, it offers high-performance for serving the models locally. In addition, you can also use this component to perform inference with reranking models hosted on Hugging Face Inference Endpoints.
+- [FastembedRanker](fastembedranker.mdx) supports a variety of cross-encoder models and is optimal for CPU-only environments.
+- [SentenceTransformersDiversityRanker](sentencetransformersdiversityranker.mdx) reorders documents to maximize diversity, helping reduce redundancy and cover a broader range of relevant topics.
+
+These Rankers give you full control over model selection, optimization, and deployment, making them well-suited for production environments with strict SLAs or compliance requirements.
+
+## Rule-Based Rankers
+
+Rule-Based Rankers in Haystack prioritize or reorder documents based on heuristic logic rather than semantic understanding. They operate on document metadata or simple structural patterns, making them computationally efficient and useful for enforcing domain-specific rules or structuring inputs in a retrieval pipeline. While they do not assess semantic relevance directly, they serve as valuable complements to more advanced methods like cross-encoder or LLM-based Rankers.
+
+For example:
+
+- [MetaFieldRanker](metafieldranker.mdx) scores and orders documents based on metadata values such as recency, source reliability, or custom-defined priorities.
+- [MetaFieldGroupingRanker](metafieldgroupingranker.mdx) groups documents by a specified metadata field and returns every document in each group together, ensuring that related documents (for example, from the same file) are processed as a single block, which has been shown to improve LLM performance.
+- [LostInTheMiddleRanker](lostinthemiddleranker.mdx) reorders documents after ranking to mitigate position bias in models with limited context windows, ensuring that highly relevant items are not overlooked.
+
+The **MetaFieldRanker** Ranker is typically used _before_ semantic ranking to filter or restructure documents according to business logic.
+
+In contrast, **LostInTheMiddleRanker and MetaFieldGroupingRanker** are intended for use _after_ ranking, to improve the effectiveness of downstream components like LLMs. These deterministic approaches provide speed, transparency, and fine-grained control, making them well-suited for pipelines requiring explainability or strict operational logic.
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/cohereranker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/cohereranker.mdx
new file mode 100644
index 0000000000..d656315631
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/cohereranker.mdx
@@ -0,0 +1,98 @@
+---
+title: "CohereRanker"
+id: cohereranker
+slug: "/cohereranker"
+description: "Use this component to rank documents based on their similarity to the query using Cohere rerank models."
+---
+
+# CohereRanker
+
+Use this component to rank documents based on their similarity to the query using Cohere rerank models.
+
+`aws_secret_access_key`: AWS secret access key. Can be set with AWS_SECRET_ACCESS_KEY env var.
`aws_region_name`: AWS region name. Can be set with AWS_DEFAULT_REGION env var. | +| **Mandatory run variables** | `documents`: A list of document objects
`query`: A query string | +| **Output variables** | `documents`: A list of document objects | +| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock/ | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `api_key`: The Cohere API key. Can be set with `COHERE_API_KEY` or `CO_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of document objects
`query`: A query string
`top_k`: The maximum number of documents to return | +| **Output variables** | `documents`: A list of document objects | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | + +
+
+## Overview
+
+`CohereRanker` ranks `Documents` based on semantic relevance to a specified query. It uses Cohere rerank models for ranking. This list of all supported models can be found in Cohere’s [documentation](https://docs.cohere.com/docs/rerank-2). The default model for this Ranker is `rerank-english-v2.0`.
+
+You can also specify the `top_k` parameter to set the maximum number of documents to return.
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install cohere-haystack
+```
+
+The component uses a `COHERE_API_KEY` or `CO_API_KEY` environment variable by default. Otherwise, you can pass a Cohere API key at initialization with `api_key` like this:
+
+```python
+ranker = CohereRanker(api_key=Secret.from_token("`query`: A query string
`top_k`: The maximum number of documents to return | +| **Output variables** | `documents`: A list of document objects | +| **API reference** | [Cohere](/reference/integrations-cohere) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents
`query`: A query string | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [FastEmbed](/reference/fastembed-embedders) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed | + +
+
+## Overview
+
+`FastembedRanker` ranks the documents based on how similar they are to the query. It uses [cross-encoder models supported by FastEmbed](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+Based on ONXX Runtime, FastEmbed provides a fast experience on standard CPU machines.
+
+`FastembedRanker` is most useful in query pipelines such as a retrieval-augmented generation (RAG) pipeline or a document search pipeline to ensure the retrieved documents are ordered by relevance. You can use it after a Retriever (such as the [`InMemoryEmbeddingRetriever`](../retrievers/inmemoryembeddingretriever.mdx)) to improve the search results. When using `FastembedRanker` with a Retriever, consider setting the Retriever's `top_k` to a small number. This way, the Ranker will have fewer documents to process, which can help make your pipeline faster.
+
+By default, this component uses the `Xenova/ms-marco-MiniLM-L-6-v2` model, but you can switch to a different model by adjusting the `model` parameter when initializing the Ranker. For details on different initialization settings, check out the [API reference](/reference/fastembed-embedders) page.
+
+### Compatible Models
+
+You can find the compatible models in the [FastEmbed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install fastembed-haystack
+```
+
+### Parameters
+
+You can set the path where the model is stored in a cache directory. You can also set the number of threads a single `onnxruntime` session can use.
+
+```python
+cache_dir= "/your_cacheDirectory"
+ranker = FastembedRanker(
+ model="Xenova/ms-marco-MiniLM-L-6-v2",
+ cache_dir=cache_dir,
+ threads=2
+)
+```
+
+If you want to use the data parallel encoding, you can set the parameters `parallel` and `batch_size`.
+
+- If `parallel` > 1, data-parallel encoding will be used. This is recommended for offline encoding of large datasets.
+- If `parallel` is 0, use all available cores.
+- If None, don't use data-parallel processing; use default `onnxruntime` threading instead.
+
+## Usage
+
+### On its own
+
+This example uses `FastembedRanker` to rank two simple documents. To run the Ranker, pass a `query`, provide the `documents`, and set the number of documents to return in the `top_k` parameter.
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.fastembed import FastembedRanker
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+
+ranker = FastembedRanker()
+ranker.warm_up()
+
+ranker.run(query="City in France", documents=docs, top_k=1)
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search using `InMemoryBM25Retriever`. It then uses the `FastembedRanker` to rank the retrieved documents according to their similarity to the query. The pipeline uses the default settings of the Ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.rankers.fastembed import FastembedRanker
+
+docs = [
+ Document(content="Paris is in France"),
+ Document(content="Berlin is in Germany"),
+ Document(content="Lyon is in France"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = FastembedRanker()
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+res = document_ranker_pipeline.run(data={"retriever": {"query": query, "top_k": 3}, "ranker": {"query": query, "top_k": 2}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/huggingfaceteiranker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/huggingfaceteiranker.mdx
new file mode 100644
index 0000000000..f95d57c116
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/huggingfaceteiranker.mdx
@@ -0,0 +1,99 @@
+---
+title: "HuggingFaceTEIRanker"
+id: huggingfaceteiranker
+slug: "/huggingfaceteiranker"
+description: "Use this component to rank documents based on their similarity to the query using a Text Embeddings Inference (TEI) API endpoint."
+---
+
+# HuggingFaceTEIRanker
+
+Use this component to rank documents based on their similarity to the query using a Text Embeddings Inference (TEI) API endpoint.
+
+`query`: A query string | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [FastEmbed](/reference/fastembed-embedders) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents, such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `url`: Base URL of the TEI reranking service (for example, "https://api.example.com"). |
+| **Mandatory run variables** | `query`: A query string
`documents`: A list of document objects | +| **Output variables** | `documents`: A grouped list of documents | +| **API reference** | [Rankers](/reference/rankers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/hugging_face_tei.py | + +
+
+## Overview
+
+HuggingFaceTEIRanker ranks documents based on semantic relevance to a specified query.
+
+You can use it with one of the Text Embeddings Inference (TEI) API endpoints:
+
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+- [Hugging Face Inference Endpoints](https://huggingface.co/inference-endpoints)
+
+You can also specify the `top_k` parameter to set the maximum number of documents to return.
+
+Depending on your TEI server configuration, you may also require a Hugging Face [token](https://huggingface.co/settings/tokens) to use for authorization. You can set it with `HF_API_TOKEN` or `HF_TOKEN` environment variables, or by using Haystack's [Secret management](../../concepts/secret-management.mdx).
+
+## Usage
+
+### On its own
+
+You can use `HuggingFaceTEIRanker` outside of a pipeline to order documents based on your query.
+
+This example uses the `HuggingFaceTEIRanker` to rank two simple documents. To run the Ranker, pass a query, provide the documents, and set the number of documents to return in the `top_k` parameter.
+
+```python
+from haystack import Document
+from haystack.components.rankers import HuggingFaceTEIRanker
+from haystack.utils import Secret
+
+reranker = HuggingFaceTEIRanker(
+ url="http://localhost:8080",
+ top_k=5,
+ timeout=30,
+ token=Secret.from_token("my_api_token")
+)
+
+docs = [Document(content="The capital of France is Paris"), Document(content="The capital of Germany is Berlin")]
+
+result = reranker.run(query="What is the capital of France?", documents=docs)
+
+ranked_docs = result["documents"]
+print(ranked_docs)
+>> {'documents': [Document(id=..., content: 'the capital of France is Paris', score: 0.9979767),
+>> Document(id=..., content: 'the capital of Germany is Berlin', score: 0.13982213)]}
+```
+
+### In a pipeline
+
+`HuggingFaceTEIRanker` is most efficient in query pipelines when used after a Retriever.
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `HuggingFaceTEIRanker` to rank the retrieved documents according to their similarity to the query. The pipeline uses the default settings of the Ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.rankers import HuggingFaceTEIRanker
+
+docs = [Document(content="Paris is in France"),
+ Document(content="Berlin is in Germany"),
+ Document(content="Lyon is in France")]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store = document_store)
+ranker = HuggingFaceTEIRanker(url="http://localhost:8080")
+ranker.warm_up()
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+document_ranker_pipeline.run(data={"retriever": {"query": query, "top_k": 3},
+ "ranker": {"query": query, "top_k": 2}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/jinaranker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/jinaranker.mdx
new file mode 100644
index 0000000000..658f8aa1da
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/jinaranker.mdx
@@ -0,0 +1,99 @@
+---
+title: "JinaRanker"
+id: jinaranker
+slug: "/jinaranker"
+description: "Use this component to rank documents based on their similarity to the query using Jina AI models."
+---
+
+# JinaRanker
+
+Use this component to rank documents based on their similarity to the query using Jina AI models.
+
+`documents`: A list of document objects | +| **Output variables** | `documents`: A grouped list of documents | +| **API reference** | [Rankers](/reference/rankers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/hugging_face_tei.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents (such as a [Retriever](../retrievers.mdx) ) |
+| **Mandatory init variables** | `api_key`: The Jina API key. Can be set with `JINA_API_KEY` env var. |
+| **Mandatory run variables** | `query`: A query string
`documents`: A list of documents | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Jina](/reference/integrations-jina) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina | + +
+
+## Overview
+
+`JinaRanker` ranks the given documents based on how similar they are to the given query. It uses Jina AI ranking models – check out the full list at Jina AI’s [website](https://jina.ai/reranker/). The default model for this Ranker is `jina-reranker-v1-base-en`.
+
+Additionally, you can use the optional `top_k` and `score_threshold` parameters with `JinaRanker` :
+
+- The Ranker's `top_k` is the number of documents it returns (if it's the last component in the pipeline) or forwards to the next component.
+- If you set the `score_threshold` for the Ranker, it will only return documents with a similarity score (computed by the Jina AI model) above this threshold.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install jina-haystack
+```
+
+### Authorization
+
+The component uses a `JINA_API_KEY` environment variable by default. Otherwise, you can pass a Jina API key at initialization with `api_key` like this:
+
+```python
+ranker = JinaRanker(api_key=Secret.from_token("`documents`: A list of documents | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Jina](/reference/integrations-jina) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents (such as a [Retriever](../retrievers.mdx) ) |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Rankers](/reference/rankers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/lost_in_the_middle.py |
+
+
+
+## Overview
+
+The `LostInTheMiddleRanker` reorders the documents based on the "Lost in the Middle" order, described in the ["Lost in the Middle: How Language Models Use Long Contexts"](https://arxiv.org/abs/2307.03172) research paper. It aims to lay out paragraphs into LLM context so that the relevant paragraphs are at the beginning or end of the input context, while the least relevant information is in the middle of the context. This reordering is helpful when very long contexts are sent to an LLM, as current models pay more attention to the start and end of long input contexts.
+
+In contrast to other rankers, `LostInTheMiddleRanker` assumes that the input documents are already sorted by relevance, and it doesn’t require a query as input. It is typically used as the last component before building a prompt for an LLM to prepare the input context for the LLM.
+
+### Parameters
+
+If you specify the `word_count_threshold` when running the component, the Ranker includes all documents up until the point where adding another document would exceed the given threshold. The last document that exceeds the threshold will be included in the resulting list of Documents, but all following documents will be discarded.
+
+You can also specify the `top_k` parameter to set the maximum number of documents to return.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.rankers import LostInTheMiddleRanker
+
+ranker = LostInTheMiddleRanker()
+docs = [Document(content="Paris"),
+ Document(content="Berlin"),
+ Document(content="Madrid")]
+result = ranker.run(documents=docs)
+
+for doc in result["documents"]:
+ print(doc.content)
+```
+
+### In a pipeline
+
+Note that this example requires an OpenAI key to run.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.rankers import LostInTheMiddleRanker
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+## Define prompt template
+prompt_template = [
+ ChatMessage.from_system("You are a helpful assistant."),
+ ChatMessage.from_user(
+ "Given these documents, answer the question.\nDocuments:\n"
+ "{% for doc in documents %}{{ doc.content }}{% endfor %}\n"
+ "Question: {{query}}\nAnswer:"
+ )
+]
+
+## Define documents
+docs = [
+ Document(content="Paris is in France..."),
+ Document(content="Berlin is in Germany..."),
+ Document(content="Lyon is in France...")
+]
+
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = LostInTheMiddleRanker(word_count_threshold=1024)
+prompt_builder = ChatPromptBuilder(template=prompt_template, required_variables={"query", "documents"})
+generator = OpenAIChatGenerator()
+
+p = Pipeline()
+p.add_component(instance=retriever, name="retriever")
+p.add_component(instance=ranker, name="ranker")
+p.add_component(instance=prompt_builder, name="prompt_builder")
+p.add_component(instance=generator, name="llm")
+
+p.connect("retriever.documents", "ranker.documents")
+p.connect("ranker.documents", "prompt_builder.documents")
+p.connect("prompt_builder.messages", "llm.messages")
+
+p.run({
+ "retriever": {"query": "What cities are in France?", "top_k": 3},
+ "prompt_builder": {"query": "What cities are in France?"}
+})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/metafieldgroupingranker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/metafieldgroupingranker.mdx
new file mode 100644
index 0000000000..4d7b563d3e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/metafieldgroupingranker.mdx
@@ -0,0 +1,121 @@
+---
+title: "MetaFieldGroupingRanker"
+id: metafieldgroupingranker
+slug: "/metafieldgroupingranker"
+description: "Reorder the documents by grouping them based on metadata keys."
+---
+
+# MetaFieldGroupingRanker
+
+Reorder the documents by grouping them based on metadata keys.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents, such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `group_by`: The name of the meta field to group by |
+| **Mandatory run variables** | `documents`: A list of documents to group |
+| **Output variables** | `documents`: A grouped list of documents |
+| **API reference** | [Rankers](/reference/rankers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/meta_field_grouping_ranker.py |
+
+
+
+## Overview
+
+The `MetaFieldGroupingRanker` component groups documents by a primary metadata key `group_by`, and subgroups them with an optional secondary key, `subgroup_by`.
+Within each group or subgroup, the component can also sort documents by a metadata key `sort_docs_by`.
+
+The output is a flat list of documents ordered by `group_by` and `subgroup_by` values. Any documents without a group are placed at the end of the list.
+
+The component helps improve the efficiency and performance of subsequent processing by an LLM.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.rankers import MetaFieldGroupingRanker
+from haystack import Document
+
+docs = [
+ Document(content="JavaScript is popular", meta={"group": "42", "split_id": 7, "subgroup": "subB"}),
+ Document(content="Python is popular", meta={"group": "42", "split_id": 4, "subgroup": "subB"}),
+ Document(content="A chromosome is DNA", meta={"group": "314", "split_id": 2, "subgroup": "subC"}),
+ Document(content="An octopus has three hearts", meta={"group": "11", "split_id": 2, "subgroup": "subD"}),
+ Document(content="Java is popular", meta={"group": "42", "split_id": 3, "subgroup": "subB"}),
+]
+
+ranker = MetaFieldGroupingRanker(group_by="group", subgroup_by="subgroup", sort_docs_by="split_id")
+result = ranker.run(documents=docs)
+print(result["documents"])
+
+```
+
+### In a pipeline
+
+The following pipeline uses the `MetaFieldGroupingRanker` to organize documents by certain meta fields while sorting by page number, then formats these organized documents into a chat message which is passed to the `OpenAIChatGenerator` to create a structured explanation of the content.
+
+```python
+from haystack import Pipeline
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.rankers import MetaFieldGroupingRanker
+from haystack.dataclasses import Document, ChatMessage
+
+docs = [
+ Document(
+ content="Chapter 1: Introduction to Python",
+ meta={"chapter": "1", "section": "intro", "page": 1}
+ ),
+ Document(
+ content="Chapter 2: Basic Data Types",
+ meta={"chapter": "2", "section": "basics", "page": 15}
+ ),
+ Document(
+ content="Chapter 1: Python Installation",
+ meta={"chapter": "1", "section": "setup", "page": 5}
+ ),
+]
+
+ranker = MetaFieldGroupingRanker(
+ group_by="chapter",
+ subgroup_by="section",
+ sort_docs_by="page"
+)
+
+chat_generator = OpenAIChatGenerator(
+ generation_kwargs={
+ "temperature": 0.7,
+ "max_tokens": 500
+ }
+)
+
+## First run the ranker
+ranked_result = ranker.run(documents=docs)
+ranked_docs = ranked_result["documents"]
+
+## Create chat messages with the ranked documents
+messages = [
+ ChatMessage.from_system("You are a helpful programming tutor."),
+ ChatMessage.from_user(
+ f"Here are the course documents in order:\n" +
+ "\n".join([f"- {doc.content}" for doc in ranked_docs]) +
+ "\n\nBased on these documents, explain the structure of this Python course."
+ )
+]
+
+## Create and run pipeline for just the chat generator
+pipeline = Pipeline()
+pipeline.add_component("chat_generator", chat_generator)
+
+result = pipeline.run(
+ data={
+ "chat_generator": {
+ "messages": messages
+ }
+ }
+)
+
+print(result["chat_generator"]["replies"][0])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/metafieldranker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/metafieldranker.mdx
new file mode 100644
index 0000000000..1ea5c66825
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/metafieldranker.mdx
@@ -0,0 +1,82 @@
+---
+title: "MetaFieldRanker"
+id: metafieldranker
+slug: "/metafieldranker"
+description: "`MetaFieldRanker` ranks Documents based on the value of their meta field you specify. It's a lightweight Ranker that can improve your pipeline's results without slowing it down."
+---
+
+# MetaFieldRanker
+
+`MetaFieldRanker` ranks Documents based on the value of their meta field you specify. It's a lightweight Ranker that can improve your pipeline's results without slowing it down.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents, such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `meta_field`: The name of the meta field to rank by |
+| **Mandatory run variables** | `documents`: A list of documents
`top_k`: The maximum number of documents to return. If not provided, returns all documents it received. | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Rankers](/reference/rankers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/meta_field.py | + +
+
+## Overview
+
+`MetaFieldRanker` sorts documents based on the value of a specific meta field in descending or ascending order. This means the returned list of `Document` objects are arranged in a selected order, with string values sorted alphabetically or in reverse (for example, Tokyo, Paris, Berlin).
+
+`MetaFieldRanker` comes with the optional parameters `weight` and `ranking_mode` you can use to combine a document’s score assigned by the Retriever and the value of its meta field for the ranking. The `weight` parameter lets you balance the importance of the Document's content and the meta field in the ranking process. The `ranking_mode` parameter defines how the scores from the Retriever and the Ranker are combined.
+
+This Ranker is useful in query pipelines, like retrieval-augmented generation (RAG) pipelines or document search pipelines. It ensures the documents are ordered by their meta field value. You can also use it after a Retriever (such as the `InMemoryEmbeddingRetriever`) to combine the Retriever’s score with a document’s meta value for improved ranking.
+
+By default, `MetaFieldRanker` sorts documents only based on the meta field. You can adjust this by setting the `weight` to less than 1 when initializing this component. For more details on different initialization settings, check out the API reference for this component.
+
+## Usage
+
+### On its own
+
+You can use this Ranker outside of a pipeline to sort documents.
+
+This example uses the `MetaFieldRanker` to rank two simple documents. When running the Ranker, you pass the `query`, provide the `documents` and set the number of documents to rank using the `top_k` parameter.
+
+```python
+from haystack import Document
+from haystack.components.rankers import MetaFieldRanker
+
+docs = [Document(content="Paris", meta={"rating": 1.3}), Document(content="Berlin", meta={"rating": 0.7})]
+
+ranker = MetaFieldRanker(meta_field="rating")
+
+ranker.run(query="City in France", documents=docs, top_k=1)
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `MetaFieldRanker` to rank the retrieved documents based on the meta field `rating`, using the Ranker's default settings:
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.rankers import MetaFieldRanker
+
+docs = [Document(content="Paris", meta={"rating": 1.3}),
+ Document(content="Berlin", meta={"rating": 0.7}),
+ Document(content="Barcelona", meta={"rating": 2.1})]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store = document_store)
+ranker = MetaFieldRanker(meta_field="rating")
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+document_ranker_pipeline.run(data={"retriever": {"query": query, "top_k": 3},
+ "ranker": {"query": query, "top_k": 2}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/nvidiaranker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/nvidiaranker.mdx
new file mode 100644
index 0000000000..989c919d22
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/nvidiaranker.mdx
@@ -0,0 +1,111 @@
+---
+title: "NvidiaRanker"
+id: nvidiaranker
+slug: "/nvidiaranker"
+description: "Use this component to rank documents based on their similarity to the query using Nvidia-hosted models."
+---
+
+# NvidiaRanker
+
+Use this component to rank documents based on their similarity to the query using Nvidia-hosted models.
+
+`top_k`: The maximum number of documents to return. If not provided, returns all documents it received. | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Rankers](/reference/rankers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/meta_field.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `api_key`: API key for the NVIDIA NIM. Can be set with `NVIDIA_API_KEY` env var. |
+| **Mandatory run variables** | `query`: A query string
`documents`: A list of document objects | +| **Output variables** | `documents`: A list of document objects | +| **API reference** | [Nvidia](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | + +
+
+## Overview
+
+`NvidiaRanker` ranks `Documents` based on semantic relevance to a specified query. It uses ranking models provided by [NVIDIA NIMs](https://ai.nvidia.com). The default model for this Ranker is `nvidia/nv-rerankqa-mistral-4b-v3`.
+
+You can also specify the `top_k` parameter to set the maximum number of documents to return.
+
+See the rest of the customizable parameters you can set for `NvidiaRanker` in our [API reference](/reference/integrations-nvidia).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install nvidia-haystack
+```
+
+The component uses an `NVIDIA_API_KEY` environment variable by default. Otherwise, you can pass an Nvidia API key at initialization with `api_key` like this:
+
+```python
+ranker = NvidiaRanker(api_key=Secret.from_token("`documents`: A list of document objects | +| **Output variables** | `documents`: A list of document objects | +| **API reference** | [Nvidia](/reference/integrations-nvidia) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `documents`: A list of documents
`query`: A query string | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Rankers](/reference/rankers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/sentence_transformers_diversity.py | + +
+
+## Overview
+
+The `SentenceTransformersDiversityRanker` uses a ranking algorithm to order documents to maximize their overall diversity. It ranks a list of documents based on their similarity to the query. The component embeds the query and the documents using a pre-trained Sentence Transformers model.
+
+This Ranker’s default model is `sentence-transformers/all-MiniLM-L6-v2`.
+
+You can optionally set the `top_k` parameter, which specifies the maximum number of documents to return. If you don’t set this parameter, the component returns all documents it receives.
+
+Find the full list of optional initialization parameters in our [API reference](/reference/rankers-api#sentencetransformersdiversityranker).
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.rankers import SentenceTransformersDiversityRanker
+
+ranker = SentenceTransformersDiversityRanker(model="sentence-transformers/all-MiniLM-L6-v2", similarity="cosine")
+ranker.warm_up()
+
+docs = [Document(content="Regular Exercise"), Document(content="Balanced Nutrition"), Document(content="Positive Mindset"),
+ Document(content="Eating Well"), Document(content="Doing physical activities"), Document(content="Thinking positively")]
+
+query = "How can I maintain physical fitness?"
+output = ranker.run(query=query, documents=docs)
+docs = output["documents"]
+
+print(docs)
+```
+
+### In a pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.rankers import SentenceTransformersDiversityRanker
+
+docs = [Document(content="The iconic Eiffel Tower is a symbol of Paris"),
+ Document(content="Visit Luxembourg Gardens for a haven of tranquility in Paris"),
+ Document(content="The Point Alexandre III bridge in Paris is famous for its Beaux-Arts style")]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store = document_store)
+ranker = SentenceTransformersDiversityRanker(meta_field="rating")
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Most famous iconic sight in Paris"
+document_ranker_pipeline.run(data={"retriever": {"query": query, "top_k": 3},
+ "ranker": {"query": query, "top_k": 2}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/sentencetransformerssimilarityranker.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/sentencetransformerssimilarityranker.mdx
new file mode 100644
index 0000000000..e7308e741a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/sentencetransformerssimilarityranker.mdx
@@ -0,0 +1,107 @@
+---
+title: "SentenceTransformersSimilarityRanker"
+id: sentencetransformerssimilarityranker
+slug: "/sentencetransformerssimilarityranker"
+description: "Use this component to rank documents based on their similarity to the query. The SentenceTransformersSimilarityRanker is a powerful, model-based Ranker that uses a cross-encoder model to produce document and query embeddings."
+---
+
+# SentenceTransformersSimilarityRanker
+
+Use this component to rank documents based on their similarity to the query. The SentenceTransformersSimilarityRanker is a powerful, model-based Ranker that uses a cross-encoder model to produce document and query embeddings.
+
+`query`: A query string | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Rankers](/reference/rankers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/sentence_transformers_diversity.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `token` (only for private models): The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `documents`: A list of documents
`query`: A query string | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Rankers](/reference/rankers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/sentence_transformers_similarity.py | + +
+
+## Overview
+
+`SentenceTransformersSimilarityRanker` ranks documents based on how similar they are to the query. It uses a pre-trained cross-encoder model from the Hugging Face Hub to embed both the query and the documents. It then compares the embeddings to determine how similar they are. The result is a list of `Document` objects in ranked order, with the Documents most similar to the query appearing first.
+
+`SentenceTransformersSimilarityRanker` is most useful in query pipelines, such as a retrieval-augmented generation (RAG) pipeline or a document search pipeline, to ensure the retrieved documents are ordered by relevance. You can use it after a Retriever (such as the `InMemoryEmbeddingRetriever`) to improve the search results. When using `SentenceTransformersSimilarityRanker` with a Retriever, consider setting the Retriever's `top_k` to a small number. This way, the Ranker will have fewer documents to process, which can help make your pipeline faster.
+
+By default, this component uses the `cross-encoder/ms-marco-MiniLM-L-6-v2` model, but it's flexible. You can switch to a different model by adjusting the `model` parameter when initializing the Ranker. For details on different initialization settings, check out the API reference for this component.
+
+You can set the `device` parameter to use HF models on your CPU or GPU.
+
+Additionally, you can select the backend to use for the Sentence Transformers mode with the `backend` parameter: `torch` (default), `onnx`, or `openvino`.
+
+### Authorization
+
+The component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with [Secret](../../concepts/secret-management.mdx) `token`:
+
+```python
+ranker = SentenceTransformersSimilarityRanker(token=Secret.from_token("`query`: A query string | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Rankers](/reference/rankers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/sentence_transformers_similarity.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `token` (only for private models): The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `documents`: A list of documents
`query`: A query string | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Rankers](/reference/rankers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/transformers_similarity.py | + +
+
+## Overview
+
+`TransformersSimilarityRanker` ranks documents based on how similar they are to the query. It uses a pre-trained cross-encoder model from the Hugging Face Hub to embed both the query and the documents. It then compares the embeddings to determine how similar they are. The result is a list of `Document `objects in ranked order, with the Documents most similar to the query appearing first.
+
+`TransformersSimilarityRanker` is most useful in query pipelines, such as a retrieval-augmented generation (RAG) pipeline or a document search pipeline, to ensure the retrieved documents are ordered by relevance. You can use it after a Retriever (such as the `InMemoryEmbeddingRetriever`) to improve the search results. When using `TransformersSimilarityRanker` with a Retriever, consider setting the Retriever's `top_k` to a small number. This way, the Ranker will have fewer documents to process, which can help make your pipeline faster.
+
+By default, this component uses the `cross-encoder/ms-marco-MiniLM-L-6-v2` model, but it's flexible. You can switch to a different model by adjusting the `model` parameter when initializing the Ranker. For details on different initialization settings, check out the API reference for this component.
+
+You can also set the `device` parameter to use HF models on your CPU or GPU.
+
+### Authorization
+
+The component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with `token` – see code examples below.
+
+```python
+ranker = TransformersSimilarityRanker(token=Secret.from_token("`query`: A query string | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Rankers](/reference/rankers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/transformers_similarity.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In query pipelines, after a component that returns a list of documents, such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `documents`: A list of documents
`query`: A query string | +| **Output variables** | `answers`: A list of [`ExtractedAnswer`](../../concepts/data-classes.mdx#extractedanswer) objects | +| **API reference** | [Readers](/reference/readers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/readers/extractive.py | + +
+
+## Overview
+
+`ExtractiveReader` locates and extracts answers to a given query from the document text. It's used in extractive QA systems where you want to know exactly where the answer is located within the document. It's usually coupled with a Retriever that precedes it, but you can also use it with other components that fetch documents.
+
+Readers assign a _probability_ to answers. This score ranges from 0 to 1, indicating how well the results the Reader returned match the query. Probability closest to 1 means the model has high confidence in the answer's relevance. The Reader sorts the answers based on their probability scores, with higher probability listed first. You can limit the number of answers the Reader returns in the optional `top_k` parameter.
+
+You can use the probability to set the quality expectations for your system. To do that, use the `confidence_score` parameter of the Reader to set a minimum probability threshold for answers. For example, setting `confidence_threshold` to `0.7` means only answers with a probability higher than 0.7 will be returned.
+
+By default, the Reader includes a scenario where no answer to the query is found in the document text (`no_answer=True`). In this case, it returns an additional `ExtractedAnswer` with no text and the probability that none of the `top_k` answers are correct. For example, if `top_k=4` the system will return four answers and an additional empty one. Each answer has a probability assigned. If the empty answer has a probability of 0.5, it means that's the probability that none of the returned answers is correct. To receive only the actual top_k answers, set the `no_answer` parameter to `False` when initializing the component.
+
+### Models
+
+Here are the models that we recommend for using with `ExtractiveReader`:
+
+| | | |
+| --- | --- | --- |
+| Model URL | Description | Language |
+| [deepset/roberta-base-squad2-distilled](https://huggingface.co/deepset/roberta-base-squad2-distilled) (default) | A distilled model, relatively fast and with good performance. | English |
+| [deepset/roberta-large-squad2](https://huggingface.co/deepset/roberta-large-squad2) | A large model with good performance. Slower than the distilled one. | English |
+| [deepset/tinyroberta-squad2](https://huggingface.co/deepset/tinyroberta-squad2) | A distilled version of roberta-large-squad2 model, very fast. | English |
+| [deepset/xlm-roberta-base-squad2](https://huggingface.co/deepset/xlm-roberta-base-squad2) | A base multilingual model with good speed and performance. | Multilingual |
+
+You can also view other question answering models on [Hugging Face](https://huggingface.co/models?pipeline_tag=question-answering).
+
+## Usage
+
+### On its own
+
+Below is an example that uses the `ExtractiveReader` outside of a pipeline. The Reader gets the query and the documents at runtime. It should return two answers and an additional third answer with no text and the probability that the `top_k` answers are incorrect.
+
+```python
+from haystack import Document
+from haystack.components.readers import ExtractiveReader
+
+docs = [Document(content="Paris is the capital of France."), Document(content="Berlin is the capital of Germany.")]
+
+reader = ExtractiveReader()
+reader.warm_up()
+
+reader.run(query="What is the capital of France?", documents=docs, top_k=2)
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that retrieves a document from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `ExtractiveReader` to extract the answer to our query from the top retrieved documents.
+
+With the ExtractiveReader’s `top_k` set to 2, an additional, third answer with no text and the probability that the other `top_k` answers are incorrect is also returned.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.readers import ExtractiveReader
+
+docs = [Document(content="Paris is the capital of France."),
+ Document(content="Berlin is the capital of Germany."),
+ Document(content="Rome is the capital of Italy."),
+ Document(content="Madrid is the capital of Spain.")]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store = document_store)
+reader = ExtractiveReader()
+reader.warm_up()
+
+extractive_qa_pipeline = Pipeline()
+extractive_qa_pipeline.add_component(instance=retriever, name="retriever")
+extractive_qa_pipeline.add_component(instance=reader, name="reader")
+
+extractive_qa_pipeline.connect("retriever.documents", "reader.documents")
+
+query = "What is the capital of France?"
+extractive_qa_pipeline.run(data={"retriever": {"query": query, "top_k": 3},
+ "reader": {"query": query, "top_k": 2}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers.mdx
new file mode 100644
index 0000000000..1a43243db2
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers.mdx
@@ -0,0 +1,160 @@
+---
+title: "Retrievers"
+id: retrievers
+slug: "/retrievers"
+description: "Retrievers go through all the documents in a Document Store and select the ones that match the user query."
+---
+
+# Retrievers
+
+Retrievers go through all the documents in a Document Store and select the ones that match the user query.
+
+## How Do Retrievers Work?
+
+Retrievers are the basic components of the majority of search systems. They’re used in the retrieval part of the retrieval-augmented generation (RAG) pipelines, they’re at the core of document retrieval pipelines, and they’re paired up with a Reader in extractive question answering pipelines.
+
+When given a query, the Retriever sifts through the documents in the Document Store, assigns a score to each document to indicate how relevant it is to the query, and returns top candidates. It then passes the selected documents on to the next component in the pipeline or returns them as answers to the query.
+
+Nevertheless, it's important to note that most Retrievers based on dense embedding do not compare each document with the query but use approximate techniques to achieve almost the same result with better performance.
+
+## Retriever Types
+
+Depending on how they calculate the similarity between the query and the document, you can divide Retrievers into sparse keyword-based, dense embedding-based, and sparse embedding-based. Several Document Stores can be coupled with different types of Retrievers.
+
+### Sparse Keyword-Based Retrievers
+
+The sparse keyword-based Retrievers look for keywords shared between the documents and the query using the BM25 algorithm or similar ones. This algorithm computes a weighted world overlap between the documents and the query.
+
+Main features:
+
+- Simple but effective, don’t need training, work quite well out of the box
+- Can work on any language
+- Don’t take word order or syntax into account
+- Can’t handle out-of-vocabulary words
+- Are good for use cases where precise wording matters
+- Can’t handle synonyms or words with similar meaning
+
+### Dense Embedding-Based Retrievers
+
+Dense embedding-based Retrievers work with embeddings, which are vector representations of words that capture their semantics. Dense Retrievers need an [Embedder](embedders.mdx) first to turn the documents and the query into vectors. Then, they calculate the vector similarity of the query and each document in the Document Store to fetch the most relevant documents.
+
+Main features:
+
+- They’re powerful but also more expensive computationally than sparse Retrievers
+- They’re trained on labeled datasets
+- They’re language-specific, which means they can only work in the language of the dataset they were trained on. Nevertheless, multilingual embedding models are available.
+- Because they work with embeddings, they take word order and syntax into account
+- Can handle out-of-vocabulary words to a certain extent
+
+### Sparse Embedding-Based Retrievers
+
+This category includes approaches such as [SPLADE](https://www.pinecone.io/learn/splade/). These techniques combine the positive aspects of keyword-based and dense embedding Retrievers using specific embedding models.
+
+In particular, SPLADE uses Language Models like BERT to weigh the relevance of different terms in the query and perform automatic term expansions, reducing the vocabulary mismatch problem (queries and relevant documents often lack term overlap).
+
+Main features:
+
+- Better than dense embedding Retrievers on precise keyword matching
+- Better than BM25 on semantic matching
+- Slower than BM25
+- Still experimental compared to both BM25 and dense embeddings: few models supported by few Document Stores
+
+### Filter Retriever
+
+`FilterRetriever` is a special kind of Retriever that can work with all Document Stores and retrieves all documents that match the provided filters.
+
+For more information, read this Retriever's [documentation page](retrievers/filterretriever.mdx).
+
+### Advanced Retriever Techniques
+
+#### Combining Retrievers
+
+You can use different types of Retrievers in one pipeline to take advantage of the strengths and mitigate the weaknesses of each of them. There are two most common strategies to do this: combining a sparse and dense Retriever (hybrid retrieval) and using two dense Retrievers, each with a different model (multi-embedding retrieval).
+
+##### Hybrid Retrieval
+
+You can use different Retriever types, sparse and dense, in one pipeline to take advantage of their strengths and make your pipeline more robust to different kinds of queries and documents. When both Retrievers fetch their candidate documents, you can combine them to produce the final ranking and get the top documents as a result.
+
+See an example of this approach in our [`DocumentJoiner` docs](joiners/documentjoiner.mdx#in-a-pipeline).
+
+:::tip Metadata Filtering
+
+When talking about hybrid retrieval, some database providers mean _metadata filtering_ on dense embedding retrieval. While this is different from combining different Retrievers, it is usually supported by Haystack Retrievers. For more information, check the [Metadata Filtering page](../concepts/metadata-filtering.mdx).
+:::
+
+:::info Hybrid Retrievers
+
+Some Document Stores offer hybrid retrieval on the database side.
+In general, these solutions can be performant, but they offer fewer customization options (for instance, on how to merge results from different retrieval techniques).
+Some hybrid Retrievers are available in Haystack, such as [`QdrantHybridRetriever`](retrievers/qdranthybridretriever.mdx).
+If your preferred Document Store does not have a hybrid Retriever available or if you want to customize the behavior even further, check out the hybrid retrieval pipelines [tutorial](https://haystack.deepset.ai/tutorials/33_hybrid_retrieval).
+:::
+
+##### Multi-Embedding Retrieval
+
+In this strategy, you use two embedding-based Retrievers, each with a different model, to embed the same documents. You then end up having multiple embeddings of one document. It can also be handy if you need multimodal retrieval.
+
+## Retrievers and Document Stores
+
+Retrievers are tightly coupled with [Document Stores](../concepts/document-store.mdx). Most Document Stores can work both with a sparse or a dense Retriever or both Retriever types combined. See the documentation of a specific Document Store to check which Retrievers it supports.
+
+### Naming Conventions
+
+The Retriever names in Haystack consist of:
+
+- Document Store name +
+- Retrieval method +
+- _Retriever_.
+
+Practical examples:
+
+- `ElasticsearchBM25Retriever`: BM25 is a sparse keyword-based retrieval technique, and this Retriever works with `ElasticsearchDocumentStore`.
+- `ElasticsearchEmbeddingRetriever`: When not mentioned, Embedding stays for Dense Embedding, and this Retriever works with `ElasticsearchDocumentStore`.
+- `QdrantSparseEmbeddingRetriever` (in construction): Sparse Embedding is the technique, and this Retriever works with `QdrantDocumentStore`.
+
+While we try to stick to this convention, there is sometimes a need to be flexible and accommodate features that are specific to a Document Store. For example:
+
+- `ChromaQueryTextRetriever`: This Retriever uses the query API of Chroma and expects text inputs. It works with `ChromaDocumentStore`.
+
+## FilterPolicy
+
+`FilterPolicy` determines how filters are applied during the document retrieval process. It controls the interaction between static filters set during Retriever initialization and dynamic filters provided at runtime. The possible values are:
+
+- **REPLACE** (default): Any runtime filters completely override the initialization filters. This allows specific queries to dynamically change the filtering scope.
+- **MERGE**: Combines runtime filters with initialization filters, narrowing down the search results.
+
+The `FilterPolicy` is set in a selected Retriever's init method, while `filters` can be set in both init and run methods.
+
+## Using a Retriever
+
+For details on how to initialize and use a Retriever in a pipeline, see the documentation for a specific Retriever. The following Retrievers are available in Haystack:
+
+| Component | Description |
+| --- | --- |
+| [AstraEmbeddingRetriever](retrievers/astraretriever.mdx) | An embedding-based Retriever compatible with the AstraDocumentStore. |
+| [AutoMergingRetriever](retrievers/automergingretriever.mdx) | Retrieves complete parent documents instead of fragmented chunks when multiple related pieces match a query. |
+| [AzureAISearchEmbeddingRetriever](retrievers/azureaisearchembeddingretriever.mdx) | An embedding Retriever compatible with the Azure AI Search Document Store. |
+| [AzureAISearchBM25Retriever](retrievers/azureaisearchbm25retriever.mdx) | A keyword-based Retriever that fetches Documents matching a query from the Azure AI Search Document Store. |
+| [AzureAISearchHybridRetriever](retrievers/azureaisearchhybridretriever.mdx) | A Retriever based both on dense and sparse embeddings, compatible with the Azure AI Search Document Store. |
+| [ChromaEmbeddingRetriever](retrievers/chromaembeddingretriever.mdx) | An embedding-based Retriever compatible with the Chroma Document Store. |
+| [ChromaQueryTextRetriever](retrievers/chromaqueryretriever.mdx) | A Retriever compatible with the Chroma Document Store that uses the Chroma query API. |
+| [ElasticsearchEmbeddingRetriever](retrievers/elasticsearchembeddingretriever.mdx) | An embedding-based Retriever compatible with the Elasticsearch Document Store. |
+| [ElasticsearchBM25Retriever](retrievers/elasticsearchbm25retriever.mdx) | A keyword-based Retriever that fetches Documents matching a query from the Elasticsearch Document Store. |
+| [InMemoryBM25Retriever](retrievers/inmemorybm25retriever.mdx) | A keyword-based Retriever compatible with the InMemoryDocumentStore. |
+| [InMemoryEmbeddingRetriever](retrievers/inmemoryembeddingretriever.mdx) | An embedding-based Retriever compatible with the InMemoryDocumentStore. |
+| [FilterRetriever](retrievers/filterretriever.mdx) | A special Retriever to be used with any Document Store to get the Documents that match specific filters. |
+| [MongoDBAtlasEmbeddingRetriever](retrievers/mongodbatlasembeddingretriever.mdx) | An embedding Retriever compatible with the MongoDB Atlas Document Store. |
+| [OpenSearchBM25Retriever](retrievers/opensearchbm25retriever.mdx) | A keyword-based Retriever that fetches Documents matching a query from an OpenSearch Document Store. |
+| [OpenSearchEmbeddingRetriever](retrievers/opensearchembeddingretriever.mdx) | An embedding-based Retriever compatible with the OpenSearch Document Store. |
+| [OpenSearchHybridRetriever](retrievers/opensearchhybridretriever.mdx) | A SuperComponent that implements a Hybrid Retriever in a single component, relying on OpenSearch as the backend Document Store. |
+| [PgvectorEmbeddingRetriever](retrievers/pgvectorembeddingretriever.mdx) | An embedding-based Retriever compatible with the Pgvector Document Store. |
+| [PgvectorKeywordRetriever](retrievers/pgvectorkeywordretriever.mdx) | A keyword-based Retriever that fetches documents matching a query from the Pgvector Document Store. |
+| [PineconeEmbeddingRetriever](retrievers/pineconedenseretriever.mdx) | An embedding-based Retriever compatible with the Pinecone Document Store. |
+| [QdrantEmbeddingRetriever](retrievers/qdrantembeddingretriever.mdx) | An embedding-based Retriever compatible with the Qdrant Document Store. |
+| [QdrantSparseEmbeddingRetriever](retrievers/qdrantsparseembeddingretriever.mdx) | A sparse embedding-based Retriever compatible with the Qdrant Document Store. |
+| [QdrantHybridRetriever](retrievers/qdranthybridretriever.mdx) | A Retriever based both on dense and sparse embeddings, compatible with the Qdrant Document Store. |
+| [SentenceWindowRetriever](retrievers/sentencewindowretrieval.mdx) | Retrieves neighboring sentences around relevant sentences to get the full context. |
+| [SnowflakeTableRetriever](retrievers/snowflaketableretriever.mdx) | Connects to a Snowflake database to execute an SQL query. |
+| [WeaviateBM25Retriever](retrievers/weaviatebm25retriever.mdx) | A keyword-based Retriever that fetches Documents matching a query from the Weaviate Document Store. |
+| [WeaviateEmbeddingRetriever](retrievers/weaviateembeddingretriever.mdx) | An embedding Retriever compatible with the Weaviate Document Store. |
+| [WeaviateHybridRetriever](retrievers/weaviatehybridretriever.mdx) | Combines BM25 keyword search and vector similarity to fetch documents from the Weaviate Document Store. |
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/astraretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/astraretriever.mdx
new file mode 100644
index 0000000000..fb9cdfc4f2
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/astraretriever.mdx
@@ -0,0 +1,99 @@
+---
+title: "AstraEmbeddingRetriever"
+id: astraretriever
+slug: "/astraretriever"
+description: "This is an embedding-based Retriever compatible with the Astra Document Store."
+---
+
+# AstraEmbeddingRetriever
+
+This is an embedding-based Retriever compatible with the Astra Document Store.
+
+`query`: A query string | +| **Output variables** | `answers`: A list of [`ExtractedAnswer`](../../concepts/data-classes.mdx#extractedanswer) objects | +| **API reference** | [Readers](/reference/readers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/readers/extractive.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline
2. The last component in the semantic search pipeline
3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline | +| **Mandatory init variables** | `document_store`: An instance of [AstraDocumentStore](../../document-stores/astradocumentstore.mdx) | +| **Mandatory run variables** | `query_embedding`: A list of floats | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Astra](/reference/integrations-astra) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/astra | + +
+
+## Overview
+
+`AstraEmbeddingRetriever` compares the query and document embeddings and fetches the documents most relevant to the query from the [`AstraDocumentStore`](../../document-stores/astradocumentstore.mdx) based on the outcome.
+
+When using the `AstraEmbeddingRetriever` in your NLP system, make sure it has the query and document embeddings available. You can do so by adding a Document Embedder to your indexing pipeline and a Text Embedder to your query pipeline.
+
+In addition to the `query_embedding`, the `AstraEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of documents to retrieve) and `filters` to narrow down the search space.
+
+### Setup and installation
+
+Once you have an AstraDB account and have created a database, install the `astra-haystack` integration:
+
+```shell
+pip install astra-haystack
+```
+
+From the configuration in AstraDB’s web UI, you need the database ID and a generated token.
+
+You will additionally need a collection name and a namespace. When you create the collection name, you also need to set the embedding dimensions and the similarity metric. The namespace organizes data in a database and is called a keyspace in Apache Cassandra.
+
+Then, optionally, install sentence-transformers as well to run the example below:
+
+```shell
+pip install sentence-transformers
+```
+
+## Usage
+
+We strongly encourage passing authentication data through environment variables: make sure to populate the environment variables `ASTRA_DB_API_ENDPOINT` and `ASTRA_DB_APPLICATION_TOKEN` before running the following example.
+
+### In a pipeline
+
+Use this Retriever in a query pipeline like this:
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack_integrations.components.retrievers.astra import AstraEmbeddingRetriever
+from haystack_integrations.document_stores.astra import AstraDocumentStore
+
+document_store = AstraDocumentStore()
+
+model = "sentence-transformers/all-mpnet-base-v2"
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder(model=model)
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.SKIP)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder(model=model))
+query_pipeline.add_component("retriever", AstraEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result['retriever']['documents'][0])
+```
+
+The example output would be:
+
+```python
+Document(id=cfe93bc1c274908801e6670440bf2bbba54fad792770d57421f85ffa2a4fcc94, content: 'There are over 7,000 languages spoken around the world today.', score: 0.8929937, embedding: vector of size 768)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Using AstraDB as a data store in your Haystack pipelines](https://haystack.deepset.ai/cookbook/astradb_haystack_integration)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/automergingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/automergingretriever.mdx
new file mode 100644
index 0000000000..c90e0a4bf7
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/automergingretriever.mdx
@@ -0,0 +1,146 @@
+---
+title: "AutoMergingRetriever"
+id: automergingretriever
+slug: "/automergingretriever"
+description: "Use AutoMergingRetriever to improve search results by returning complete parent documents instead of fragmented chunks when multiple related pieces match a query."
+---
+
+# AutoMergingRetriever
+
+Use AutoMergingRetriever to improve search results by returning complete parent documents instead of fragmented chunks when multiple related pieces match a query.
+
+2. The last component in the semantic search pipeline
3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline | +| **Mandatory init variables** | `document_store`: An instance of [AstraDocumentStore](../../document-stores/astradocumentstore.mdx) | +| **Mandatory run variables** | `query_embedding`: A list of floats | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Astra](/reference/integrations-astra) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/astra | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Used after the main Retriever component that returns hierarchical documents. |
+| **Mandatory init variables** | `document_store`: Document Store from which to retrieve the parent documents |
+| **Mandatory run variables** | `documents`: A list of leaf documents that were matched by a Retriever |
+| **Output variables** | `documents`: A list resulting documents |
+| **API reference** | [Retrievers](/reference/retrievers-api) |
+| **GitHub link** | [https://github.com/deepset-ai/haystack/blob/dae8c7babaf28d2ffab4f2a8dedecd63e2394fb4/haystack/components/retrievers/auto_merging_retriever.py](https://github.com/deepset-ai/haystack/blob/dae8c7babaf28d2ffab4f2a8dedecd63e2394fb4/haystack/components/retrievers/auto_merging_retriever.py#L116) |
+
+
+
+## Overview
+
+The `AutoMergingRetriever` is a component that works with a hierarchical document structure. It returns the parent documents instead of individual leaf documents when a certain threshold is met.
+
+This can be particularly useful when working with paragraphs split into multiple chunks. When several chunks from the same paragraph match your query, the complete paragraph often provides more context and value than the individual pieces alone.
+
+Here is how this Retriever works:
+
+1. It requires documents to be organized in a tree structure, with leaf nodes stored in a document index - see [`HierarchicalDocumentSplitter`](../preprocessors/hierarchicaldocumentsplitter.mdx) documentation.
+2. When searching, it counts how many leaf documents under the same parent match your query.
+3. If this count exceeds your defined threshold, it returns the parent document instead of the individual leaves.
+
+The `AutoMergingRetriever` can currently be used by the following Document Stores:
+
+- [AstraDocumentStore](../../document-stores/astradocumentstore.mdx)
+- [ElasticsearchDocumentStore](../../document-stores/elasticsearch-document-store.mdx)
+- [OpenSearchDocumentStore](../../document-stores/opensearch-document-store.mdx)
+- [PgvectorDocumentStore](../../document-stores/pgvectordocumentstore.mdx)
+- [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx)
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import HierarchicalDocumentSplitter
+from haystack.components.retrievers.auto_merging_retriever import AutoMergingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+## create a hierarchical document structure with 3 levels, where the parent document has 3 children
+text = "The sun rose early in the morning. It cast a warm glow over the trees. Birds began to sing."
+original_document = Document(content=text)
+builder = HierarchicalDocumentSplitter(block_sizes=[10, 3], split_overlap=0, split_by="word")
+docs = builder.run([original_document])["documents"]
+
+## store level-1 parent documents and initialize the retriever
+doc_store_parents = InMemoryDocumentStore()
+for doc in docs["documents"]:
+ if doc.meta["children_ids"] and doc.meta["level"] == 1:
+ doc_store_parents.write_documents([doc])
+retriever = AutoMergingRetriever(doc_store_parents, threshold=0.5)
+
+## assume we retrieved 2 leaf docs from the same parent, the parent document should be returned,
+## since it has 3 children and the threshold=0.5, and we retrieved 2 children (2/3 > 0.66(6))
+leaf_docs = [doc for doc in docs["documents"] if not doc.meta["children_ids"]]
+docs = retriever.run(leaf_docs[4:6])
+>> {'documents': [Document(id=538..),
+>> content: 'warm glow over the trees. Birds began to sing.',
+>> meta: {'block_size': 10, 'parent_id': '835..', 'children_ids': ['c17...', '3ff...', '352...'], 'level': 1, 'source_id': '835...',
+>> 'page_number': 1, 'split_id': 1, 'split_idx_start': 45})]}
+```
+
+### In a pipeline
+
+This is an example of a RAG Haystack pipeline. It first retrieves leaf-level document chunks using BM25, merges them into higher-level parent documents with `AutoMergingRetriever`, constructs a prompt, and generates an answer using OpenAI's chat model.
+
+```python
+from typing import List, Tuple
+from haystack import Document, Pipeline
+from haystack_experimental.components.splitters import HierarchicalDocumentSplitter
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.retrievers import AutoMergingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.dataclasses import ChatMessage
+
+def indexing(documents: List[Document]) -> Tuple[InMemoryDocumentStore, InMemoryDocumentStore]:
+ splitter = HierarchicalDocumentSplitter(block_sizes={10, 3}, split_overlap=0, split_by="word")
+ docs = splitter.run(documents)
+
+ leaf_documents = [doc for doc in docs["documents"] if doc.meta["__level"] == 1]
+ leaf_doc_store = InMemoryDocumentStore()
+ leaf_doc_store.write_documents(leaf_documents, policy=DuplicatePolicy.OVERWRITE)
+
+ parent_documents = [doc for doc in docs["documents"] if doc.meta["__level"] == 0]
+ parent_doc_store = InMemoryDocumentStore()
+ parent_doc_store.write_documents(parent_documents, policy=DuplicatePolicy.OVERWRITE)
+
+ return leaf_doc_store, parent_doc_store
+
+## Add documents
+docs = [
+ Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")
+]
+
+leaf_docs, parent_docs = indexing(docs)
+
+prompt_template = [
+ ChatMessage.from_system("You are a helpful assistant."),
+ ChatMessage.from_user(
+ "Given these documents, answer the question.\nDocuments:\n"
+ "{% for doc in documents %}{{ doc.content }}{% endfor %}\n"
+ "Question: {{question}}\nAnswer:"
+ )
+]
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(instance=InMemoryBM25Retriever(document_store=leaf_docs), name="bm25_retriever")
+rag_pipeline.add_component(instance=AutoMergingRetriever(parent_docs, threshold=0.6), name="retriever")
+rag_pipeline.add_component(instance=ChatPromptBuilder(template=prompt_template, required_variables={"question", "documents"}), name="prompt_builder")
+rag_pipeline.add_component(instance=OpenAIChatGenerator(), name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+
+rag_pipeline.connect("bm25_retriever.documents", "retriever.documents")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder.messages", "llm.messages")
+rag_pipeline.connect("llm.replies", "answer_builder.replies")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+
+question = "How many languages are there?"
+result = rag_pipeline.run({
+ "bm25_retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ "answer_builder": {"query": question}
+})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchbm25retriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchbm25retriever.mdx
new file mode 100644
index 0000000000..e09387cc70
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchbm25retriever.mdx
@@ -0,0 +1,130 @@
+---
+title: "AzureAISearchBM25Retriever"
+id: azureaisearchbm25retriever
+slug: "/azureaisearchbm25retriever"
+description: "A keyword-based Retriever that fetches Documents matching a query from the Azure AI Search Document Store."
+---
+
+# AzureAISearchBM25Retriever
+
+A keyword-based Retriever that fetches Documents matching a query from the Azure AI Search Document Store.
+
+A keyword-based Retriever that fetches documents matching a query from the Azure AI Search Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. Before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. Before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of [`AzureAISearchDocumentStore`](../../document-stores/azureaisearchdocumentstore.mdx) |
+| **Mandatory run variables** | `query`: A string |
+| **Output variables** | `documents`: A list of documents (matching the query) |
+| **API reference** | [Azure AI Search](/reference/integrations-azure_ai_search) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_ai_search |
+
+
+
+## Overview
+
+The `AzureAISearchBM25Retriever` is a keyword-based Retriever designed to fetch documents that match a query from an `AzureAISearchDocumentStore`. It uses the BM25 algorithm which calculates a weighted word overlap between the query and the documents to determine their similarity. The Retriever accepts textual query but you can also provide a combination of terms with boolean operators. Some examples of valid queries could be `"pool"`, `"pool spa"`, and `"pool spa +airport"`.
+
+In addition to the `query`, the `AzureAISearchBM25Retriever` accepts other optional parameters, including `top_k` (the maximum number of documents to retrieve) and `filters` to narrow down the search space.
+
+If your search index includes a [semantic configuration](https://learn.microsoft.com/en-us/azure/search/semantic-how-to-query-request), you can enable semantic ranking to apply it to the Retriever's results. For more details, refer to the [Azure AI documentation](https://learn.microsoft.com/en-us/azure/search/hybrid-search-how-to-query#semantic-hybrid-search).
+
+If you want a combination of BM25 and vector retrieval, use the `AzureAISearchHybridRetriever`, which uses both vector search and BM25 search to match documents and query.
+
+## Usage
+
+### Installation
+
+This integration requires you to have an active Azure subscription with a deployed [Azure AI Search](https://azure.microsoft.com/en-us/products/ai-services/ai-search) service.
+
+To start using Azure AI search with Haystack, install the package with:
+
+```shell
+pip install azure-ai-search-haystack
+```
+
+### On its own
+
+This Retriever needs `AzureAISearchDocumentStore` and indexed documents to run.
+
+```python
+from haystack import Document
+from haystack_integrations.components.retrievers.azure_ai_search import AzureAISearchBM25Retriever
+from haystack_integrations.document_stores.azure_ai_search import AzureAISearchDocumentStore
+
+document_store = AzureAISearchDocumentStore(index_name="haystack_docs")
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+document_store.write_documents(documents=documents)
+
+retriever = AzureAISearchBM25Retriever(document_store=document_store)
+retriever.run(query="How many languages are spoken around the world today?")
+```
+
+### In a RAG pipeline
+
+The below example shows how to use the `AzureAISearchBM25Retriever` in a RAG pipeline. Set your `OPENAI_API_KEY` as an environment variable and then run the following code:
+
+```python
+
+from haystack_integrations.components.retrievers.azure_ai_search import AzureAISearchBM25Retriever
+from haystack_integrations.document_stores.azure_ai_search import AzureAISearchDocumentStore
+
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+from haystack.document_stores.types import DuplicatePolicy
+
+import os
+api_key = os.environ['OPENAI_API_KEY']
+
+## Create a RAG query pipeline
+prompt_template = """
+ Given these documents, answer the question.\nDocuments:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ \nQuestion: {{question}}
+ \nAnswer:
+ """
+
+document_store = AzureAISearchDocumentStore(index_name="haystack-docs")
+
+## Add Documents
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+
+## policy param is optional, as AzureAISearchDocumentStore has a default policy of DuplicatePolicy.OVERWRITE
+document_store.write_documents(documents=documents, policy=DuplicatePolicy.OVERWRITE)
+
+retriever = AzureAISearchBM25Retriever(document_store=document_store)
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(name="retriever", instance=retriever)
+rag_pipeline.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+rag_pipeline.add_component(instance=OpenAIGenerator(), name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+rag_pipeline.connect("llm.replies", "answer_builder.replies")
+rag_pipeline.connect("llm.meta", "answer_builder.meta")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+
+question = "Tell me something about languages?"
+result = rag_pipeline.run(
+ {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ "answer_builder": {"query": question},
+ }
+ )
+print(result['answer_builder']['answers'][0])
+
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchembeddingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchembeddingretriever.mdx
new file mode 100644
index 0000000000..d93937f4cd
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchembeddingretriever.mdx
@@ -0,0 +1,125 @@
+---
+title: "AzureAISearchEmbeddingRetriever"
+id: azureaisearchembeddingretriever
+slug: "/azureaisearchembeddingretriever"
+description: "An embedding Retriever compatible with the Azure AI Search Document Store."
+---
+
+# AzureAISearchEmbeddingRetriever
+
+An embedding Retriever compatible with the Azure AI Search Document Store.
+
+This Retriever accepts the embeddings of a single query as input and returns a list of matching documents.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the embedding retrieval pipeline 3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of [`AzureAISearchDocumentStore`](../../document-stores/azureaisearchdocumentstore.mdx) |
+| **Mandatory run variables** | `query_embedding`: A list of floats |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Azure AI Search](/reference/integrations-azure_ai_search) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_ai_search |
+
+
+
+## Overview
+
+The `AzureAISearchEmbeddingRetriever` is an embedding-based Retriever compatible with the `AzureAISearchDocumentStore`. It compares the query and document embeddings and fetches the most relevant documents from the `AzureAISearchDocumentStore` based on the outcome.
+
+The query needs to be embedded before being passed to this component. For example, you could use a Text [Embedder](../embedders.mdx) component.
+
+By default, the `AzureAISearchDocumentStore` uses the [HNSW algorithm](https://learn.microsoft.com/en-us/azure/search/vector-search-overview#nearest-neighbors-search) with cosine similarity to handle vector searches. The vector configuration is set during the initialization of the document store and can be customized by providing the `vector_search_configuration` parameter.
+
+In addition to the `query_embedding`, the `AzureAISearchEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of documents to retrieve) and `filters` to narrow down the search space.
+
+:::info Semantic Ranking
+
+The semantic ranking capability of Azure AI Search is not available for vector retrieval. To include semantic ranking in your retrieval process, use the [`AzureAISearchBM25Retriever`](azureaisearchbm25retriever.mdx) or [`AzureAISearchHybridRetriever`](azureaisearchhybridretriever.mdx). For more details, see [Azure AI documentation](https://learn.microsoft.com/en-us/azure/search/semantic-how-to-query-request?tabs=portal-query#set-up-the-query).
+:::
+
+## Usage
+
+### Installation
+
+This integration requires you to have an active Azure subscription with a deployed [Azure AI Search](https://azure.microsoft.com/en-us/products/ai-services/ai-search) service.
+
+To start using Azure AI search with Haystack, install the package with:
+
+```shell
+pip install azure-ai-search-haystack
+```
+
+### On its own
+
+This Retriever needs `AzureAISearchDocumentStore` and indexed documents to run.
+
+```python
+from haystack_integrations.document_stores.azure_ai_search import AzureAISearchDocumentStore
+from haystack_integrations.components.retrievers.azure_ai_search import AzureAISearchEmbeddingRetriever
+
+document_store = AzureAISearchDocumentStore()
+
+retriever = AzureAISearchEmbeddingRetriever(document_store=document_store)
+
+## example run query
+retriever.run(query_embedding=[0.1]*384)
+```
+
+### In a pipeline
+
+Here is how you could use the `AzureAISearchEmbeddingRetriever` in a pipeline. In this example, you would create two pipelines: an indexing one and a querying one.
+
+In the indexing pipeline, the documents are passed to the Document Embedder and then written into the Document Store.
+
+Then, in the querying pipeline, we use a Text Embedder to get the vector representation of the input query that will be then passed to the `AzureAISearchEmbeddingRetriever` to get the results.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder
+from haystack.components.writers import DocumentWriter
+
+from haystack_integrations.components.retrievers.azure_ai_search import AzureAISearchEmbeddingRetriever
+from haystack_integrations.document_stores.azure_ai_search import AzureAISearchDocumentStore
+
+document_store = AzureAISearchDocumentStore(index_name="retrieval-example")
+
+model = "sentence-transformers/all-mpnet-base-v2"
+
+documents = [
+ Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(
+ content="""Elephants have been observed to behave in a way that indicates a
+ high level of self-awareness, such as recognizing themselves in mirrors."""
+ ),
+ Document(
+ content="""In certain parts of the world, like the Maldives, Puerto Rico, and
+ San Diego, you can witness the phenomenon of bioluminescent waves."""
+ ),
+]
+
+document_embedder = SentenceTransformersDocumentEmbedder(model=model)
+document_embedder.warm_up()
+
+## Indexing Pipeline
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(instance=document_embedder, name="doc_embedder")
+indexing_pipeline.add_component(instance=DocumentWriter(document_store=document_store), name="doc_writer")
+indexing_pipeline.connect("doc_embedder", "doc_writer")
+
+indexing_pipeline.run({"doc_embedder": {"documents": documents}})
+
+## Query Pipeline
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder(model=model))
+query_pipeline.add_component("retriever", AzureAISearchEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchhybridretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchhybridretriever.mdx
new file mode 100644
index 0000000000..56acc01804
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchhybridretriever.mdx
@@ -0,0 +1,120 @@
+---
+title: "AzureAISearchHybridRetriever"
+id: azureaisearchhybridretriever
+slug: "/azureaisearchhybridretriever"
+description: "A Retriever based both on dense and sparse embeddings, compatible with the Azure AI Search Document Store."
+---
+
+# AzureAISearchHybridRetriever
+
+A Retriever based both on dense and sparse embeddings, compatible with the Azure AI Search Document Store.
+
+This Retriever combines embedding-based retrieval and BM25 text search search to find matching documents in the search index to get more relevant results.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a TextEmbedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in a hybrid search pipeline 3. After a TextEmbedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of [`AzureAISearchDocumentStore`](../../document-stores/azureaisearchdocumentstore.mdx) |
+| **Mandatory run variables** | `query`: A string
`query_embedding`: A list of floats | +| **Output variables** | `documents`: A list of documents (matching the query) | +| **API reference** | [Azure AI Search](/reference/integrations-azure_ai_search) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_ai_search | + +
+
+## Overview
+
+The `AzureAISearchHybridRetriever` combines vector retrieval and BM25 text search to fetch relevant documents from the `AzureAISearchDocumentStore`. It processes both textual (keyword) queries and query embeddings in a single request, executing all subqueries in parallel. The results are merged and reordered using [Reciprocal Rank Fusion (RRF)](https://learn.microsoft.com/en-us/azure/search/hybrid-search-ranking) to create a unified result set.
+
+Besides the `query` and `query_embedding`, the `AzureAISearchHybridRetriever` accepts optional parameters such as `top_k` (the maximum number of documents to retrieve) and `filters` to refine the search. Additional keyword arguments can also be passed during initialization for further customization.
+
+If your search index includes a [semantic configuration](https://learn.microsoft.com/en-us/azure/search/semantic-how-to-query-request), you can enable semantic ranking to apply it to the Retriever's results. For more details, refer to the [Azure AI documentation](https://learn.microsoft.com/en-us/azure/search/hybrid-search-how-to-query#semantic-hybrid-search).
+
+For purely keyword-based retrieval, you can use `AzureAISearchBM25Retriever`, and for embedding-based retrieval, `AzureAISearchEmbeddingRetriever` is available.
+
+## Usage
+
+### Installation
+
+This integration requires you to have an active Azure subscription with a deployed [Azure AI Search](https://azure.microsoft.com/en-us/products/ai-services/ai-search) service.
+
+To start using Azure AI search with Haystack, install the package with:
+
+```shell
+pip install azure-ai-search-haystack
+```
+
+### On its own
+
+This Retriever needs `AzureAISearchDocumentStore` and indexed documents to run.
+
+```python
+from haystack import Document
+from haystack_integrations.components.retrievers.azure_ai_search import AzureAISearchHybridRetriever
+from haystack_integrations.document_stores.azure_ai_search import AzureAISearchDocumentStore
+
+document_store = AzureAISearchDocumentStore(index_name="haystack_docs")
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+document_store.write_documents(documents=documents)
+
+retriever = AzureAISearchHybridRetriever(document_store=document_store)
+## fake embeddings to keep the example simple
+retriever.run(query="How many languages are spoken around the world today?", query_embedding=[0.1]*384)
+```
+
+### In a RAG pipeline
+
+The following example demonstrates using the `AzureAISearchHybridRetriever` in a pipeline. An indexing pipeline is responsible for indexing and storing documents with embeddings in the `AzureAISearchDocumentStore`, while the query pipeline uses hybrid retrieval to fetch relevant documents based on a given query.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder
+from haystack.components.writers import DocumentWriter
+
+from haystack_integrations.components.retrievers.azure_ai_search import AzureAISearchHybridRetriever
+from haystack_integrations.document_stores.azure_ai_search import AzureAISearchDocumentStore
+
+document_store = AzureAISearchDocumentStore(index_name="hybrid-retrieval-example")
+
+model = "sentence-transformers/all-mpnet-base-v2"
+
+documents = [
+ Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(
+ content="""Elephants have been observed to behave in a way that indicates a
+ high level of self-awareness, such as recognizing themselves in mirrors."""
+ ),
+ Document(
+ content="""In certain parts of the world, like the Maldives, Puerto Rico, and
+ San Diego, you can witness the phenomenon of bioluminescent waves."""
+ ),
+]
+
+document_embedder = SentenceTransformersDocumentEmbedder(model=model)
+document_embedder.warm_up()
+
+## Indexing Pipeline
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(instance=document_embedder, name="doc_embedder")
+indexing_pipeline.add_component(instance=DocumentWriter(document_store=document_store), name="doc_writer")
+indexing_pipeline.connect("doc_embedder", "doc_writer")
+
+indexing_pipeline.run({"doc_embedder": {"documents": documents}})
+
+## Query Pipeline
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder(model=model))
+query_pipeline.add_component("retriever", AzureAISearchHybridRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}, "retriever": {"query": query}})
+
+print(result["retriever"]["documents"][0])
+
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/chromaembeddingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/chromaembeddingretriever.mdx
new file mode 100644
index 0000000000..3ee85570b5
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/chromaembeddingretriever.mdx
@@ -0,0 +1,101 @@
+---
+title: "ChromaEmbeddingRetriever"
+id: chromaembeddingretriever
+slug: "/chromaembeddingretriever"
+description: "This is an embedding Retriever compatible with the Chroma Document Store."
+---
+
+# ChromaEmbeddingRetriever
+
+This is an embedding Retriever compatible with the Chroma Document Store.
+
+`query_embedding`: A list of floats | +| **Output variables** | `documents`: A list of documents (matching the query) | +| **API reference** | [Azure AI Search](/reference/integrations-azure_ai_search) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/azure_ai_search | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a [ChromaDocumentStore](../../document-stores/chromadocumentstore.mdx) |
+| **Mandatory run variables** | `query_embedding`: A list of floats |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Chroma](/reference/integrations-chroma) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chroma |
+
+
+
+## Overview
+
+The `ChromaEmbeddingRetriever` is an embedding-based Retriever compatible with the `ChromaDocumentStore`. It compares the query and document embeddings and fetches the documents most relevant to the query from the `ChromaDocumentStore` based on the outcome.
+
+The query needs to be embedded before being passed to this component. For example, you could use a text [embedder](../embedders.mdx) component.
+
+In addition to the `query_embedding`, the `ChromaEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of documents to retrieve) and `filters` to narrow down the search space.
+
+### Usage
+
+#### On its own
+
+This Retriever needs the `ChromaDocumentStore` and indexed documents to run.
+
+```python
+from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+from haystack_integrations.components.retrievers.chroma import ChromaEmbeddingRetriever
+
+document_store = ChromaDocumentStore()
+
+retriever = ChromaEmbeddingRetriever(document_store=document_store)
+
+## example run query
+retriever.run(query_embedding=[0.1]*384)
+```
+
+#### In a pipeline
+
+Here is how you could use the `ChromaEmbeddingRetriever` in a pipeline. In this example, you would create two pipelines: an indexing one and a querying one.
+
+In the indexing pipeline, the documents are passed to the Document Embedder and then written into the document Store.
+
+Then, in the querying pipeline, we use a text embedder to get the vector representation of the input query that will be then passed to the `ChromaEmbeddingRetriever` to get the results.
+
+```python
+import os
+from pathlib import Path
+
+from haystack import Pipeline
+from haystack.dataclasses import Document
+from haystack.components.writers import DocumentWriter
+## Note: the following requires a "pip install sentence-transformers"
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder
+
+from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+from haystack_integrations.components.retrievers.chroma import ChromaEmbeddingRetriever
+from sentence_transformers import SentenceTransformer
+
+## Chroma is used in-memory so we use the same instances in the two pipelines below
+document_store = ChromaDocumentStore()
+
+documents = [
+ Document(content="This contains variable declarations", meta={"title": "one"}),
+ Document(content="This contains another sort of variable declarations", meta={"title": "two"}),
+ Document(content="This has nothing to do with variable declarations", meta={"title": "three"}),
+ Document(content="A random doc", meta={"title": "four"}),
+]
+
+indexing = Pipeline()
+indexing.add_component("embedder", SentenceTransformersDocumentEmbedder())
+indexing.add_component("writer", DocumentWriter(document_store))
+indexing.connect("embedder.documents", "writer.documents")
+indexing.run({"embedder": {"documents": documents}})
+
+querying = Pipeline()
+querying.add_component("query_embedder", SentenceTransformersTextEmbedder())
+querying.add_component("retriever", ChromaEmbeddingRetriever(document_store))
+querying.connect("query_embedder.embedding", "retriever.query_embedding")
+results = querying.run({"query_embedder": {"text": "Variable declarations"}})
+
+for d in results["retriever"]["documents"]:
+ print(d.meta, d.score)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Use Chroma for RAG and Indexing](https://haystack.deepset.ai/cookbook/chroma-indexing-and-rag-examples)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/chromaqueryretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/chromaqueryretriever.mdx
new file mode 100644
index 0000000000..3655a60e3c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/chromaqueryretriever.mdx
@@ -0,0 +1,92 @@
+---
+title: "ChromaQueryTextRetriever"
+id: chromaqueryretriever
+slug: "/chromaqueryretriever"
+description: "This is a a Retriever compatible with the Chroma Document Store."
+---
+
+# ChromaQueryTextRetriever
+
+This is a a Retriever compatible with the Chroma Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a [ChromaDocumentStore](../../document-stores/chromadocumentstore.mdx) |
+| **Mandatory run variables** | `query`: A single query in plain-text format to be processed by the [Retriever](../retrievers.mdx) |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Chroma](/reference/integrations-chroma) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chroma |
+
+
+
+## Overview
+
+The `ChromaQueryTextRetriever` is an embedding-based Retriever compatible with the `ChromaDocumentStore` that uses the Chroma [query API](https://docs.trychroma.com/reference/Collection#query).
+This component takes a plain-text query string in input and returns the matching documents.
+Chroma will create the embedding for the query using its [embedding function](https://docs.trychroma.com/embeddings#default-all-minilm-l6-v2); in case you do not want to use the default embedding function, this must be specified at `ChromaDocumentStore` initialization.
+
+### Usage
+
+#### On its own
+
+This Retriever needs the `ChromaDocumentStore` and indexed documents to run.
+
+```python
+from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+from haystack_integrations.components.retrievers.chroma import ChromaQueryTextRetriever
+
+document_store = ChromaDocumentStore()
+
+retriever = ChromaQueryTextRetriever(document_store=document_store)
+
+## example run query
+retriever.run(query = "How does Chroma Retriever work?")
+```
+
+#### In a pipeline
+
+Here is how you could use the `ChromaQueryTextRetriever` in a Pipeline. In this example, you would create two pipelines: an indexing one and a querying one.
+
+In the indexing pipeline, the documents are written in the Document Store.
+
+Then, in the querying pipeline, `ChromaQueryTextRetriever` gets the answer from the Document Store based on the provided query.
+
+```python
+import os
+from pathlib import Path
+
+from haystack import Pipeline
+from haystack.dataclasses import Document
+from haystack.components.writers import DocumentWriter
+
+from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+from haystack_integrations.components.retrievers.chroma import ChromaQueryTextRetriever
+
+## Chroma is used in-memory so we use the same instances in the two pipelines below
+document_store = ChromaDocumentStore()
+
+documents = [
+ Document(content="This contains variable declarations", meta={"title": "one"}),
+ Document(content="This contains another sort of variable declarations", meta={"title": "two"}),
+ Document(content="This has nothing to do with variable declarations", meta={"title": "three"}),
+ Document(content="A random doc", meta={"title": "four"}),
+]
+
+indexing = Pipeline()
+indexing.add_component("writer", DocumentWriter(document_store))
+indexing.run({"writer": {"documents": documents}})
+
+querying = Pipeline()
+querying.add_component("retriever", ChromaQueryTextRetriever(document_store))
+results = querying.run({"retriever": {"query": "Variable declarations", "top_k": 3}})
+
+for d in results["retriever"]["documents"]:
+ print(d.meta, d.score)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Use Chroma for RAG and Indexing](https://haystack.deepset.ai/cookbook/chroma-indexing-and-rag-examples)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/elasticsearchbm25retriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/elasticsearchbm25retriever.mdx
new file mode 100644
index 0000000000..8122b89216
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/elasticsearchbm25retriever.mdx
@@ -0,0 +1,150 @@
+---
+title: "ElasticsearchBM25Retriever"
+id: elasticsearchbm25retriever
+slug: "/elasticsearchbm25retriever"
+description: "A keyword-based Retriever that fetches Documents matching a query from the Elasticsearch Document Store."
+---
+
+# ElasticsearchBM25Retriever
+
+A keyword-based Retriever that fetches Documents matching a query from the Elasticsearch Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. Before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. Before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of [ElasticsearchDocumentStore](../../document-stores/elasticsearch-document-store.mdx) |
+| **Mandatory run variables** | `query`: A string |
+| **Output variables** | `documents`: A list of documents (matching the query) |
+| **API reference** | [Elasticsearch](/reference/integrations-elasticsearch) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/elasticsearch |
+
+
+
+## Overview
+
+`ElasticsearchBM25Retriever` is a keyword-based Retriever that fetches Documents matching a query from an `ElasticsearchDocumentStore`. It determines the similarity between Documents and the query based on the BM25 algorithm, which computes a weighted word overlap between the two strings.
+
+Since the `ElasticsearchBM25Retriever` matches strings based on word overlap, it’s often used to find exact matches to names of persons or products, IDs, or well-defined error messages. The BM25 algorithm is very lightweight and simple. Nevertheless, it can be hard to beat with more complex embedding-based approaches on out-of-domain data.
+
+In addition to the `query`, the `ElasticsearchBM25Retriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+When initializing Retriever, you can also adjust how [inexact fuzzy matching](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#fuzziness) is performed, using the `fuzziness` parameter.
+
+If you want a semantic match between a query and documents, you can use `ElasticsearchEmbeddingRetriever`, which uses vectors created by embedding models to retrieve relevant information.
+
+## Installation
+
+[Install](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html) Elasticsearch and then [start](https://www.elastic.co/guide/en/elasticsearch/reference/current/starting-elasticsearch.html) an instance. Haystack supports Elasticsearch 8.
+
+If you have Docker set up, we recommend pulling the Docker image and running it.
+
+```shell
+docker pull docker.elastic.co/elasticsearch/elasticsearch:8.11.1
+docker run -p 9200:9200 -e "discovery.type=single-node" -e "ES_JAVA_OPTS=-Xms1024m -Xmx1024m" -e "xpack.security.enabled=false" elasticsearch:8.11.1
+```
+
+As an alternative, you can go to [Elasticsearch integration GitHub](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/elasticsearch) and start a Docker container running Elasticsearch using the provided `docker-compose.yml`:
+
+```shell
+docker compose up
+```
+
+Once you have a running Elasticsearch instance, install the `elasticsearch-haystack` integration:
+
+```shell
+pip install elasticsearch-haystack
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack_integrations.components.retrievers.elasticsearch import ElasticsearchBM25Retriever
+from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore
+from elasticsearch import Elasticsearch
+
+document_store = ElasticsearchDocumentStore(hosts= "http://localhost:9200/")
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+document_store.write_documents(documents=documents)
+
+retriever = ElasticsearchBM25Retriever(document_store=document_store)
+retriever.run(query="How many languages are spoken around the world today?")
+```
+
+### In a RAG pipeline
+
+Set your `OPENAI_API_KEY` as an environment variable and then run the following code:
+
+```python
+
+from haystack_integrations.components.retrievers.elasticsearch import ElasticsearchBM25Retriever
+from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore
+
+from elasticsearch import Elasticsearch
+
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+from haystack.document_stores.types import DuplicatePolicy
+
+import os
+api_key = os.environ['OPENAI_API_KEY']
+
+## Create a RAG query pipeline
+prompt_template = """
+ Given these documents, answer the question.\nDocuments:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ \nQuestion: {{question}}
+ \nAnswer:
+ """
+
+document_store = ElasticsearchDocumentStore(hosts= "http://localhost:9200/")
+
+## Add Documents
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+
+## DuplicatePolicy.SKIP param is optional, but useful to run the script multiple times without throwing errors
+document_store.write_documents(documents=documents, policy=DuplicatePolicy.SKIP)
+
+retriever = ElasticsearchBM25Retriever(document_store=document_store)
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(name="retriever", instance=retriever)
+rag_pipeline.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+rag_pipeline.add_component(instance=OpenAIGenerator(api_key=api_key), name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+rag_pipeline.connect("llm.replies", "answer_builder.replies")
+rag_pipeline.connect("llm.meta", "answer_builder.meta")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+
+question = "How many languages are spoken around the world today?"
+result = rag_pipeline.run(
+ {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ "answer_builder": {"query": question},
+ }
+ )
+print(result['answer_builder']['answers'][0].data)
+
+```
+
+Here’s an example output you might get:
+
+```python
+"Over 7,000 languages are spoken around the world today"
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/elasticsearchembeddingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/elasticsearchembeddingretriever.mdx
new file mode 100644
index 0000000000..266cb453b0
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/elasticsearchembeddingretriever.mdx
@@ -0,0 +1,104 @@
+---
+title: "ElasticsearchEmbeddingRetriever"
+id: elasticsearchembeddingretriever
+slug: "/elasticsearchembeddingretriever"
+description: "An embedding-based Retriever compatible with the Elasticsearch Document Store."
+---
+
+# ElasticsearchEmbeddingRetriever
+
+An embedding-based Retriever compatible with the Elasticsearch Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of [ElasticsearchDocumentStore](../../document-stores/elasticsearch-document-store.mdx) |
+| **Mandatory run variables** | `query_embedding`: A list of floats |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Elasticsearch](/reference/integrations-elasticsearch) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/elasticsearch |
+
+
+
+## Overview
+
+The `ElasticsearchEmbeddingRetriever` is an embedding-based Retriever compatible with the `ElasticsearchDocumentStore`. It compares the query and Document embeddings and fetches the Documents most relevant to the query from the `ElasticsearchDocumentStore` based on the outcome.
+
+When using the `ElasticsearchEmbeddingRetriever` in your NLP system, ensure it has the query and Document embeddings available. You can do so by adding a Document Embedder to your indexing pipeline and a Text Embedder to your query pipeline.
+
+In addition to the `query_embedding`, the `ElasticsearchEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+
+When initializing Retriever, you can also set `num_candidates`: the number of approximate nearest neighbor candidates on each shard. It's an advanced setting you can read more about in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/knn-search.html#tune-approximate-knn-for-speed-accuracy).
+
+The `embedding_similarity_function` to use for embedding retrieval must be defined when the corresponding `ElasticsearchDocumentStore` is initialized.
+
+## Installation
+
+[Install](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html) Elasticsearch and then [start](https://www.elastic.co/guide/en/elasticsearch/reference/current/starting-elasticsearch.html) an instance. Haystack supports Elasticsearch 8.
+
+If you have Docker set up, we recommend pulling the Docker image and running it.
+
+```shell
+docker pull docker.elastic.co/elasticsearch/elasticsearch:8.11.1
+docker run -p 9200:9200 -e "discovery.type=single-node" -e "ES_JAVA_OPTS=-Xms1024m -Xmx1024m" -e "xpack.security.enabled=false" elasticsearch:8.11.1
+```
+
+As an alternative, you can go to [Elasticsearch integration GitHub](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/elasticsearch) and start a Docker container running Elasticsearch using the provided `docker-compose.yml`:
+
+```shell
+docker compose up
+```
+
+Once you have a running Elasticsearch instance, install the `elasticsearch-haystack` integration:
+
+```shell
+pip install elasticsearch-haystack
+```
+
+## Usage
+
+### In a pipeline
+
+Use this Retriever in a query Pipeline like this:
+
+```python
+from haystack_integrations.components.retrievers.elasticsearch import ElasticsearchEmbeddingRetriever
+from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore
+
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+
+document_store = ElasticsearchDocumentStore(hosts= "http://localhost:9200/")
+
+model = "BAAI/bge-large-en-v1.5"
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder(model=model)
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.SKIP)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder(model=model))
+query_pipeline.add_component("retriever", ElasticsearchEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result['retriever']['documents'][0])
+```
+
+The example output would be:
+
+```python
+Document(id=cfe93bc1c274908801e6670440bf2bbba54fad792770d57421f85ffa2a4fcc94, content: 'There are over 7,000 languages spoken around the world today.', score: 0.87717235, embedding: vector of size 1024)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/filterretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/filterretriever.mdx
new file mode 100644
index 0000000000..9796a5590d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/filterretriever.mdx
@@ -0,0 +1,124 @@
+---
+title: "FilterRetriever"
+id: filterretriever
+slug: "/filterretriever"
+description: "Use this Retriever with any Document Store to get the Documents that match specific filters."
+---
+
+# FilterRetriever
+
+Use this Retriever with any Document Store to get the Documents that match specific filters.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | At the beginning of a Pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a Document Store |
+| **Mandatory run variables** | `filters`: A dictionary of filters in the same syntax supported by the Document Stores |
+| **Output variables** | `documents`: All the documents that match these filters |
+| **API reference** | [Retrievers](/reference/retrievers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/retrievers/filter_retriever.py |
+
+
+
+## Overview
+
+`FilterRetriever` retrieves Documents that match the provided filters.
+
+It’s a special kind of Retriever – it can work with all Document Stores instead of being specialized to work with only one.
+
+However, as every other Retriever, it needs some Document Store at initialization time, and it will perform filtering on the content of that instance only.
+
+Therefore, it can be used as any other Retriever in a Pipeline.
+
+Pay attention when using `FilterRetriever` on a Document Store that contains many Documents, as `FilterRetriever` will return all documents that match the filters. The `run` command with no filters can easily overwhelm other components in the Pipeline (for example, Generators):
+
+```python
+filter_retriever.run({})
+```
+
+Another thing to note is that `FilterRetriever` does not score your Documents or rank them in any way. If you need to rank the Documents by similarity to a query, consider using Ranker components.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.retrievers import FilterRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+docs = [
+ Document(content="Python is a popular programming language", meta={"lang": "en"}),
+ Document(content="python ist eine beliebte Programmiersprache", meta={"lang": "de"}),
+]
+
+doc_store = InMemoryDocumentStore()
+doc_store.write_documents(docs)
+retriever = FilterRetriever(doc_store)
+result = retriever.run(filters={"field": "lang", "operator": "==", "value": "en"})
+
+assert "documents" in result
+assert len(result["documents"]) == 1
+assert result["documents"][0].content == "Python is a popular programming language"
+```
+
+### In a RAG pipeline
+
+Set your `OPENAI_API_KEY` as an environment variable and then run the following code:
+
+```python
+from haystack.components.retrievers.filter_retriever import FilterRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+from haystack import Document, Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+from haystack.document_stores.types import DuplicatePolicy
+
+import os
+api_key = os.environ['OPENAI_API_KEY']
+
+document_store = InMemoryDocumentStore()
+documents = [
+ Document(content="Mark lives in Berlin.", meta={"year": 2018}),
+ Document(content="Mark lives in Paris.", meta={"year": 2021}),
+ Document(content="Mark is Danish.", meta={"year": 2021}),
+ Document(content="Mark lives in New York.", meta={"year": 2023}),
+]
+document_store.write_documents(documents=documents)
+
+## Create a RAG query pipeline
+prompt_template = """
+ Given these documents, answer the question.\nDocuments:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ \nQuestion: {{question}}
+ \nAnswer:
+ """
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(name="retriever", instance=FilterRetriever(document_store=document_store))
+rag_pipeline.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+rag_pipeline.add_component(instance=OpenAIGenerator(api_key=api_key), name="llm")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+result = rag_pipeline.run(
+ {
+ "retriever": {"filters": {"field": "year", "operator": "==", "value": 2021}},
+ "prompt_builder": {"question": "Where does Mark live?"},
+ }
+)
+print(result['answer_builder']['answers'][0])`
+```
+
+Here’s an example output you might get:
+
+```
+According to the provided documents, Mark lives in Paris.
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/inmemorybm25retriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/inmemorybm25retriever.mdx
new file mode 100644
index 0000000000..11243f8f1f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/inmemorybm25retriever.mdx
@@ -0,0 +1,141 @@
+---
+title: "InMemoryBM25Retriever"
+id: inmemorybm25retriever
+slug: "/inmemorybm25retriever"
+description: "A keyword-based Retriever compatible with InMemoryDocumentStore."
+---
+
+# InMemoryBM25Retriever
+
+A keyword-based Retriever compatible with InMemoryDocumentStore.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In query pipelines:
In a RAG pipeline, before a [`PromptBuilder`](../builders/promptbuilder.mdx)
In a semantic search pipeline, as the last component
In an extractive QA pipeline, before an [`ExtractiveReader`](../readers/extractivereader.mdx) | +| **Mandatory init variables** | `document_store`: An instance of [InMemoryDocumentStore](../../document-stores/inmemorydocumentstore.mdx) | +| **Mandatory run variables** | `query`: A query string | +| **Output variables** | `documents`: A list of documents (matching the query) | +| **API reference** | [Retrievers](/reference/retrievers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/retrievers/in_memory/bm25_retriever.py | + +
+
+## Overview
+
+`InMemoryBM25Retriever` is a keyword-based Retriever that fetches Documents matching a query from a temporary in-memory database. It determines the similarity between Documents and the query based on the BM25 algorithm, which computes a weighted word overlap between the two strings.
+
+Since the `InMemoryBM25Retriever` matches strings based on word overlap, it’s often used to find exact matches to names of persons or products, IDs, or well-defined error messages. The BM25 algorithm is very lightweight and simple. Nevertheless, it can be hard to beat with more complex embedding-based approaches on out-of-domain data.
+
+In addition to the `query`, the `InMemoryBM25Retriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+Some relevant parameters that impact the BM25 retrieval must be defined when the corresponding `InMemoryDocumentStore` is initialized: these include the specific BM25 algorithm and its parameters.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+document_store.write_documents(documents=documents)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+retriever.run(query="How many languages are spoken around the world today?")
+```
+
+### In a Pipeline
+
+#### In a RAG Pipeline
+
+Here's an example of the Retriever in a retrieval-augmented generation pipeline:
+
+```python
+import os
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+## Create a RAG query pipeline
+prompt_template = """
+ Given these documents, answer the question.\nDocuments:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ \nQuestion: {{question}}
+ \nAnswer:
+ """
+
+os.environ["OPENAI_API_KEY"] = "sk-XXXXXX"
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(instance=InMemoryBM25Retriever(document_store=InMemoryDocumentStore()), name="retriever")
+rag_pipeline.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+rag_pipeline.add_component(instance=OpenAIGenerator(), name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+rag_pipeline.connect("llm.replies", "answer_builder.replies")
+rag_pipeline.connect("llm.metadata", "answer_builder.metadata")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+
+## Draw the pipeline
+rag_pipeline.draw("./rag_pipeline.png")
+
+## Add Documents
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+rag_pipeline.get_component("retriever").document_store.write_documents(documents)
+
+## Run the pipeline
+question = "How many languages are there?"
+result = rag_pipeline.run(
+ {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ "answer_builder": {"query": question},
+ }
+ )
+print(result['answer_builder']['answers'][0])
+```
+
+#### In a Document Search Pipeline
+
+Here's how you can use this Retriever in a document search pipeline:
+
+```python
+from haystack import Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.pipeline import Pipeline
+
+## Create components and a query pipeline
+document_store = InMemoryDocumentStore()
+retriever = InMemoryBM25Retriever(document_store=document_store)
+
+pipeline = Pipeline()
+pipeline.add_component(instance=retriever, name="retriever")
+
+## Add Documents
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+document_store.write_documents(documents)
+
+## Run the pipeline
+result = pipeline.run(data={"retriever": {"query":"How many languages are there?"}})
+
+print(result['retriever']['documents'][0])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/inmemoryembeddingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/inmemoryembeddingretriever.mdx
new file mode 100644
index 0000000000..2547249e7f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/inmemoryembeddingretriever.mdx
@@ -0,0 +1,69 @@
+---
+title: "InMemoryEmbeddingRetriever"
+id: inmemoryembeddingretriever
+slug: "/inmemoryembeddingretriever"
+description: "Use this Retriever with the InMemoryDocumentStore if you're looking for embedding-based retrieval."
+---
+
+# InMemoryEmbeddingRetriever
+
+Use this Retriever with the InMemoryDocumentStore if you're looking for embedding-based retrieval.
+
+In a RAG pipeline, before a [`PromptBuilder`](../builders/promptbuilder.mdx)
In a semantic search pipeline, as the last component
In an extractive QA pipeline, before an [`ExtractiveReader`](../readers/extractivereader.mdx) | +| **Mandatory init variables** | `document_store`: An instance of [InMemoryDocumentStore](../../document-stores/inmemorydocumentstore.mdx) | +| **Mandatory run variables** | `query`: A query string | +| **Output variables** | `documents`: A list of documents (matching the query) | +| **API reference** | [Retrievers](/reference/retrievers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/retrievers/in_memory/bm25_retriever.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | In query pipelines:
In a RAG pipeline, before a [`PromptBuilder`](../builders/promptbuilder.mdx)
In a semantic search pipeline, as the last component
In an extractive QA pipeline, after a Tex tEmbedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) | +| **Mandatory init variables** | `document_store`: An instance of [InMemoryDocumentStore](../../document-stores/inmemorydocumentstore.mdx) | +| **Mandatory run variables** | `query_embedding`: A list of floating point numbers | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Retrievers](/reference/retrievers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/retrievers/in_memory/embedding_retriever.py | + +
+
+## Overview
+
+The `InMemoryEmbeddingRetriever` is an embedding-based Retriever compatible with the `InMemoryDocumentStore`. It compares the query and Document embeddings and fetches the Documents most relevant to the query from the `InMemoryDocumentStore` based on the outcome.
+
+When using the `InMemoryEmbeddingRetriever` in your NLP system, make sure it has the query and Document embeddings available. You can do so by adding a DocumentEmbedder to your indexing pipeline and a Text Embedder to your query pipeline. For details, see [Embedders](../embedders.mdx).
+
+In addition to the `query_embedding`, the `InMemoryEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+
+The `embedding_similarity_function` to use for embedding retrieval must be defined when the corresponding`InMemoryDocumentStore` is initialized.
+
+## Usage
+
+### In a pipeline
+
+Use this Retriever in a query pipeline like this:
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result['retriever']['documents'][0])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/mongodbatlasembeddingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/mongodbatlasembeddingretriever.mdx
new file mode 100644
index 0000000000..bf31480e6c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/mongodbatlasembeddingretriever.mdx
@@ -0,0 +1,125 @@
+---
+title: "MongoDBAtlasEmbeddingRetriever"
+id: mongodbatlasembeddingretriever
+slug: "/mongodbatlasembeddingretriever"
+description: "This is an embedding Retriever compatible with the MongoDB Atlas Document Store."
+---
+
+# MongoDBAtlasEmbeddingRetriever
+
+This is an embedding Retriever compatible with the MongoDB Atlas Document Store.
+
+In a RAG pipeline, before a [`PromptBuilder`](../builders/promptbuilder.mdx)
In a semantic search pipeline, as the last component
In an extractive QA pipeline, after a Tex tEmbedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) | +| **Mandatory init variables** | `document_store`: An instance of [InMemoryDocumentStore](../../document-stores/inmemorydocumentstore.mdx) | +| **Mandatory run variables** | `query_embedding`: A list of floating point numbers | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Retrievers](/reference/retrievers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/retrievers/in_memory/embedding_retriever.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a [MongoDBAtlasDocumentStore](../../document-stores/mongodbatlasdocumentstore.mdx) |
+| **Mandatory run variables** | `query_embedding`: A list of floats |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [MongoDB Atlas](/reference/integrations-mongodb-atlas) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mongodb_atlas |
+
+
+
+The `MongoDBAtlasEmbeddingRetriever` is an embedding-based Retriever compatible with the [`MongoDBAtlasDocumentStore`](../../document-stores/mongodbatlasdocumentstore.mdx). It compares the query and Document embeddings and fetches the Documents most relevant to the query from the Document Store based on the outcome.
+
+### Parameters
+
+When using the `MongoDBAtlasEmbeddingRetriever` in your NLP system, ensure the query and Document [embeddings](../embedders.mdx) are available. You can do so by adding a Document Embedder to your indexing Pipeline and a Text Embedder to your query Pipeline.
+
+In addition to the `query_embedding`, the `MongoDBAtlasEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+
+## Usage
+
+### Installation
+
+To start using MongoDB Atlas with Haystack, install the package with:
+
+```shell
+pip install mongodb-atlas-haystack
+```
+
+### On its own
+
+The Retriever needs an instance of `MongoDBAtlasDocumentStore` and indexed Documents to run.
+
+```python
+from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore
+from haystack_integrations.components.retrievers.mongodb_atlas import MongoDBAtlasEmbeddingRetriever
+
+document_store = MongoDBAtlasDocumentStore()
+
+retriever = MongoDBAtlasEmbeddingRetriever(document_store=document_store)
+
+## example run query
+retriever.run(query_embedding=[0.1]*384)
+```
+
+### In a Pipeline
+
+```python
+from haystack import Pipeline, Document
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.components.writers import DocumentWriter
+from haystack.components.generators import OpenAIGenerator
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder
+from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore
+from haystack_integrations.components.embedders.mongodb_atlas import MongoDBAtlasEmbeddingRetriever
+
+## Create some example documents
+documents = [
+ Document(content="My name is Jean and I live in Paris."),
+ Document(content="My name is Mark and I live in Berlin."),
+ Document(content="My name is Giorgio and I live in Rome."),
+]
+
+## We support many different databases. Here we load a simple and lightweight in-memory document store.
+document_store = MongoDBAtlasDocumentStore()
+
+## Define some more components
+doc_writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.SKIP)
+doc_embedder = SentenceTransformersDocumentEmbedder(model="intfloat/e5-base-v2")
+query_embedder = SentenceTransformersTextEmbedder(model="intfloat/e5-base-v2")
+
+## Pipeline that ingests document for retrieval
+ingestion_pipe = Pipeline()
+ingestion_pipe.add_component(instance=doc_embedder, name="doc_embedder")
+ingestion_pipe.add_component(instance=doc_writer, name="doc_writer")
+
+ingestion_pipe.connect("doc_embedder.documents", "doc_writer.documents")
+ingestion_pipe.run({"doc_embedder": {"documents": documents}})
+
+## Build a RAG pipeline with a Retriever to get relevant documents to
+## the query and a OpenAIGenerator interacting with LLMs using a custom prompt.
+prompt_template = """
+Given these documents, answer the question.\nDocuments:
+{% for doc in documents %}
+ {{ doc.content }}
+{% endfor %}
+
+\nQuestion: {{question}}
+\nAnswer:
+"""
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(instance=query_embedder, name="query_embedder")
+rag_pipeline.add_component(instance=MongoDBAtlasEmbeddingRetriever(document_store=document_store), name="retriever")
+rag_pipeline.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+rag_pipeline.add_component(instance=OpenAIGenerator(), name="llm")
+rag_pipeline.connect("query_embedder", "retriever.query_embedding")
+rag_pipeline.connect("embedding_retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+## Ask a question on the data you just added.
+question = "Where does Mark live?"
+result = rag_pipeline.run(
+ {
+ "query_embedder": {"text": question},
+ "prompt_builder": {"question": question},
+ }
+)
+
+## For details, like which documents were used to generate the answer, look into the GeneratedAnswer object
+print(result["answer_builder"]["answers"])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/mongodbatlasfulltextretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/mongodbatlasfulltextretriever.mdx
new file mode 100644
index 0000000000..af3f0cf540
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/mongodbatlasfulltextretriever.mdx
@@ -0,0 +1,152 @@
+---
+title: "MongoDBAtlasFullTextRetriever"
+id: mongodbatlasfulltextretriever
+slug: "/mongodbatlasfulltextretriever"
+description: "This is a full-text search Retriever compatible with the MongoDB Atlas Document Store."
+---
+
+# MongoDBAtlasFullTextRetriever
+
+This is a full-text search Retriever compatible with the MongoDB Atlas Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. Before a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. Before an [ExtractiveReader](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a [MongoDBAtlasDocumentStore](../../document-stores/mongodbatlasdocumentstore.mdx) |
+| **Mandatory run variables** | `query`: A query string to search for. If the query contains multiple terms, Atlas Search evaluates each term separately for matches. |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [MongoDB Atlas](/reference/integrations-mongodb-atlas) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mongodb_atlas |
+
+
+
+The `MongoDBAtlasFullTextRetriever` is a full-text search Retriever compatible with the [`MongoDBAtlasDocumentStore`](../../document-stores/mongodbatlasdocumentstore.mdx). The full-text search is dependent on the `full_text_search_index` used in the [`MongoDBAtlasDocumentStore`](../../document-stores/mongodbatlasdocumentstore.mdx).
+
+### Parameters
+
+In addition to the `query`, the `MongoDBAtlasFullTextRetriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+
+When running the component, you can specify more optional parameters such as `fuzzy` or `synonyms`, `match_criteria`, `score`. Check out our [MongoDB Atlas](/reference/integrations-mongodb-atlas) API Reference for more details on all parameters.
+
+## Usage
+
+### Installation
+
+To start using MongoDB Atlas with Haystack, install the package with:
+
+```shell
+pip install mongodb-atlas-haystack
+```
+
+### On its own
+
+The Retriever needs an instance of `MongoDBAtlasDocumentStore` and indexed documents to run.
+
+```python
+from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore
+from haystack_integrations.components.retrievers.mongodb_atlas import MongoDBAtlasFullTextRetriever
+
+store = MongoDBAtlasDocumentStore(database_name="your_existing_db",
+ collection_name="your_existing_collection",
+ vector_search_index="your_existing_index",
+ full_text_search_index="your_existing_index")
+retriever = MongoDBAtlasFullTextRetriever(document_store=store)
+
+results = retriever.run(query="Your search query")
+print(results["documents"])
+```
+
+### In a Pipeline
+
+Here's a Hybrid Retrieval pipeline example that makes use of both available MongoDB Atlas Retrievers:
+
+```python
+from haystack import Pipeline, Document
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.components.writers import DocumentWriter
+from haystack.components.embedders import (
+ SentenceTransformersDocumentEmbedder,
+ SentenceTransformersTextEmbedder,
+)
+from haystack.components.joiners import DocumentJoiner
+
+from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore
+from haystack_integrations.components.retrievers.mongodb_atlas import (
+ MongoDBAtlasEmbeddingRetriever,
+ MongoDBAtlasFullTextRetriever,
+)
+
+documents = [
+ Document(content="My name is Jean and I live in Paris."),
+ Document(content="My name is Mark and I live in Berlin."),
+ Document(content="My name is Giorgio and I live in Rome."),
+ Document(content="Python is a programming language popular for data science."),
+ Document(content="MongoDB Atlas offers full-text search and vector search capabilities."),
+]
+
+document_store = MongoDBAtlasDocumentStore(
+ database_name="haystack_test",
+ collection_name="test_collection",
+ vector_search_index="test_vector_search_index",
+ full_text_search_index="test_full_text_search_index",
+)
+
+## Clean out any old data so this example is repeatable
+print(f"Clearing collection {document_store.collection_name} …")
+document_store.collection.delete_many({})
+
+ingest_pipe = Pipeline()
+
+doc_embedder = SentenceTransformersDocumentEmbedder(model="intfloat/e5-base-v2")
+ingest_pipe.add_component(instance=doc_embedder, name="doc_embedder")
+
+doc_writer = DocumentWriter(
+ document_store=document_store,
+ policy=DuplicatePolicy.SKIP
+)
+ingest_pipe.add_component(instance=doc_writer, name="doc_writer")
+ingest_pipe.connect("doc_embedder.documents", "doc_writer.documents")
+
+print(f"Running ingestion on {len(documents)} in-memory docs …")
+ingest_pipe.run({"doc_embedder": {"documents": documents}})
+
+query_pipe = Pipeline()
+
+text_embedder = SentenceTransformersTextEmbedder(model="intfloat/e5-base-v2")
+query_pipe.add_component(instance=text_embedder, name="text_embedder")
+
+embed_retriever = MongoDBAtlasEmbeddingRetriever(
+ document_store=document_store,
+ top_k=3
+)
+query_pipe.add_component(instance=embed_retriever, name="embedding_retriever")
+query_pipe.connect("text_embedder", "embedding_retriever")
+
+## (c) full-text retriever
+ft_retriever = MongoDBAtlasFullTextRetriever(
+ document_store=document_store,
+ top_k=3
+)
+query_pipe.add_component(instance=ft_retriever, name="full_text_retriever")
+
+joiner = DocumentJoiner(join_mode="reciprocal_rank_fusion", top_k=3)
+query_pipe.add_component(instance=joiner, name="joiner")
+
+query_pipe.connect("embedding_retriever", "joiner")
+query_pipe.connect("full_text_retriever", "joiner")
+
+question = "Where does Mark live?"
+print(f"Running hybrid retrieval for query: '{question}'")
+output = query_pipe.run(
+ {
+ "text_embedder": {"text": question},
+ "full_text_retriever": {"query": question},
+ }
+)
+
+print("\nFinal fused documents:")
+for doc in output["joiner"]["documents"]:
+ print(f"- {doc.content}")
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchbm25retriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchbm25retriever.mdx
new file mode 100644
index 0000000000..068b0f1d81
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchbm25retriever.mdx
@@ -0,0 +1,143 @@
+---
+title: "OpenSearchBM25Retriever"
+id: opensearchbm25retriever
+slug: "/opensearchbm25retriever"
+description: "This is a keyword-based Retriever that fetches Documents matching a query from an OpenSearch Document Store."
+---
+
+# OpenSearchBM25Retriever
+
+This is a keyword-based Retriever that fetches Documents matching a query from an OpenSearch Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. Before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. Before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of an [OpenSearchDocumentStore](../../document-stores/opensearch-document-store.mdx) |
+| **Mandatory run variables** | `query`: A query string |
+| **Output variables** | `documents`: A list of documents matching the query |
+| **API reference** | [OpenSearch](/reference/integrations-opensearch) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opensearch |
+
+
+
+## Overview
+
+`OpenSearchBM25Retriever` is a keyword-based Retriever that fetches Documents matching a query from an `OpenSearchDocumentStore`. It determines the similarity between Documents and the query based on the BM25 algorithm, which computes a weighted word overlap between the two strings.
+
+Since the `OpenSearchBM25Retriever` matches strings based on word overlap, it’s often used to find exact matches to names of persons or products, IDs, or well-defined error messages. The BM25 algorithm is very lightweight and simple. Nevertheless, it can be hard to beat with more complex embedding-based approaches on out-of-domain data.
+
+In addition to the `query`, the `OpenSearchBM25Retriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+You can adjust how [inexact fuzzy matching](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#fuzziness) is performed, using the `fuzziness` parameter.
+It is also possible to specify if all terms in the query must match using the `all_terms_must_match` parameter, which defaults to `False`.
+
+If you want more flexible matching of a query to Documents, you can use the `OpenSearchEmbeddingRetriever`, which uses vectors created by LLMs to retrieve relevant information.
+
+### Setup and installation
+
+[Install](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/index/) and run an OpenSearch instance.
+
+If you have Docker set up, we recommend pulling the Docker image and running it.
+
+```shell
+docker pull opensearchproject/opensearch:2.11.0
+docker run -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" -e "ES_JAVA_OPTS=-Xms1024m -Xmx1024m" opensearchproject/opensearch:2.11.0
+```
+
+As an alternative, you can go to [OpenSearch integration GitHub](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opensearch) and start a Docker container running OpenSearch using the provided `docker-compose.yml`:
+
+```shell
+docker compose up
+```
+
+Once you have a running OpenSearch instance, install the `opensearch-haystack` integration:
+
+```shell
+pip install opensearch-haystack
+```
+
+## Usage
+
+### On its own
+
+This Retriever needs the `OpensearchDocumentStore` and indexed Documents to run. You can’t use it on its own.
+
+### In a RAG pipeline
+
+Set your `OPENAI_API_KEY` as an environment variable and then run the following code:
+
+```python
+from haystack_integrations.components.retrievers.opensearch import OpenSearchBM25Retriever
+from haystack_integrations.document_stores.opensearch import OpenSearchDocumentStore
+
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+from haystack.document_stores.types import DuplicatePolicy
+
+import os
+api_key = os.environ['OPENAI_API_KEY']
+
+## Create a RAG query pipeline
+prompt_template = """
+ Given these documents, answer the question.\nDocuments:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ \nQuestion: {{question}}
+ \nAnswer:
+ """
+
+document_store = OpenSearchDocumentStore(hosts="http://localhost:9200", use_ssl=True,
+verify_certs=False, http_auth=("admin", "admin"))
+
+## Add Documents
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+
+## DuplicatePolicy.SKIP param is optional, but useful to run the script multiple times without throwing errors
+document_store.write_documents(documents=documents, policy=DuplicatePolicy.SKIP)
+
+retriever = OpenSearchBM25Retriever(document_store=document_store)
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(name="retriever", instance=retriever)
+rag_pipeline.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+rag_pipeline.add_component(instance=OpenAIGenerator(api_key=api_key), name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+rag_pipeline.connect("llm.replies", "answer_builder.replies")
+rag_pipeline.connect("llm.metadata", "answer_builder.metadata")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+
+question = "How many languages are spoken around the world today?"
+result = rag_pipeline.run(
+ {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ "answer_builder": {"query": question},
+ }
+ )
+print(result['answer_builder']['answers'][0])
+```
+
+Here’s an example output:
+
+```python
+GeneratedAnswer(
+ data='Over 7,000 languages are spoken around the world today.',
+ query='How many languages are spoken around the world today?',
+ documents=[
+ Document(id=cfe93bc1c274908801e6670440bf2bbba54fad792770d57421f85ffa2a4fcc94, content: 'There are over 7,000 languages spoken around the world today.', score: 7.179112),
+ Document(id=7f225626ad1019b273326fbaf11308edfca6d663308a4a3533ec7787367d59a2, content: 'In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the ph...', score: 1.1426818)],
+ meta={'model': 'gpt-3.5-turbo-0613', 'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 86, 'completion_tokens': 13, 'total_tokens': 99}})
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchembeddingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchembeddingretriever.mdx
new file mode 100644
index 0000000000..2a2d8e3c2a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchembeddingretriever.mdx
@@ -0,0 +1,108 @@
+---
+title: "OpenSearchEmbeddingRetriever"
+id: opensearchembeddingretriever
+slug: "/opensearchembeddingretriever"
+description: "An embedding-based Retriever compatible with the OpenSearch Document Store."
+---
+
+# OpenSearchEmbeddingRetriever
+
+An embedding-based Retriever compatible with the OpenSearch Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of an [OpenSearchDocumentStore](../../document-stores/opensearch-document-store.mdx) |
+| **Mandatory run variables** | `query_embedding`: A list of floats |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [OpenSearch](/reference/integrations-opensearch) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opensearch |
+
+
+
+## Overview
+
+The `OpenSearchEmbeddingRetriever` is an embedding-based Retriever compatible with the `OpenSearchDocumentStore`. It compares the query and Document embeddings and fetches the Documents most relevant to the query from the `OpenSearchDocumentStore` based on the outcome.
+
+When using the `OpenSearchEmbeddingRetriever` in your NLP system, make sure it has the query and Document embeddings available. You can do so by adding a Document Embedder to your indexing pipeline and a Text Embedder to your query pipeline.
+
+In addition to the `query_embedding`, the `OpenSearchEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+
+The `embedding_dim` for storing and retrieving embeddings must be defined when the corresponding `OpenSearchDocumentStore` is initialized.
+
+### Setup and installation
+
+[Install](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/index/) and run an OpenSearch instance.
+
+If you have Docker set up, we recommend pulling the Docker image and running it.
+
+```shell
+docker pull opensearchproject/opensearch:2.11.0
+docker run -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" -e "ES_JAVA_OPTS=-Xms1024m -Xmx1024m" opensearchproject/opensearch:2.11.0
+```
+
+As an alternative, you can go to [OpenSearch integration GitHub](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opensearch) and start a Docker container running OpenSearch using the provided `docker-compose.yml`:
+
+```shell
+docker compose up
+```
+
+Once you have a running OpenSearch instance, install the `opensearch-haystack` integration:
+
+```shell
+pip install opensearch-haystack
+```
+
+## Usage
+
+### In a pipeline
+
+Use this Retriever in a query Pipeline like this:
+
+```python
+from haystack_integrations.components.retrievers.opensearch import OpenSearchEmbeddingRetriever
+from haystack_integrations.document_stores.opensearch import OpenSearchDocumentStore
+
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+
+document_store = OpenSearchDocumentStore(hosts="http://localhost:9200", use_ssl=True,
+verify_certs=False, http_auth=("admin", "admin"))
+
+model = "sentence-transformers/all-mpnet-base-v2"
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder(model=model)
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.SKIP)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder(model=model))
+query_pipeline.add_component("retriever", OpenSearchEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result['retriever']['documents'][0])
+```
+
+The example output would be:
+
+```python
+Document(id=cfe93bc1c274908801e6670440bf2bbba54fad792770d57421f85ffa2a4fcc94, content: 'There are over 7,000 languages spoken around the world today.', score: 0.70026743, embedding: vector of size 768)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [PDF-Based Question Answering with Amazon Bedrock and Haystack](https://haystack.deepset.ai/cookbook/amazon_bedrock_for_documentation_qa)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchhybridretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchhybridretriever.mdx
new file mode 100644
index 0000000000..3d4afc7f97
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchhybridretriever.mdx
@@ -0,0 +1,134 @@
+---
+title: "OpenSearchHybridRetriever"
+id: opensearchhybridretriever
+slug: "/opensearchhybridretriever"
+description: "This is a [SuperComponent](../../concepts/components/supercomponents.mdx) that implements a Hybrid Retriever in a single component, relying on OpenSearch as the backend Document Store."
+---
+
+# OpenSearchHybridRetriever
+
+This is a [SuperComponent](../../concepts/components/supercomponents.mdx) that implements a Hybrid Retriever in a single component, relying on OpenSearch as the backend Document Store.
+
+A Hybrid Retriever uses both traditional keyword-based search (such as BM25) and embedding-based search to retrieve documents, combining the strengths of both approaches. The Retriever then merges and re-ranks the results from both methods.
+
+
+
+| | |
+| --- | --- |
+| Most common position in a pipeline | After an [OpenSearchDocumentStore](../../document-stores/opensearch-document-store.mdx) |
+| Mandatory init variables | `document_store`: An instance of `OpenSearchDocumentStore` to use for retrieval
`embedder`: Any [Embedder](../embedders.mdx) implementing the `TextEmbedder` protocol | +| Mandatory run variables | `query`: A query string | +| Output variables | `documents`: A list of documents matching the query | +| API reference | [OpenSearch](/reference/integrations-opensearch) | +| GitHub | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opensearch | + +
+
+## Overview
+
+The `OpenSearchHybridRetriever` combines two retrieval methods:
+
+1. **BM25 Retrieval**: A keyword-based search that uses the BM25 algorithm to find documents based on term frequency and inverse document frequency. It's based on the [`OpenSearchBM25Retriever`](opensearchbm25retriever.mdx) component and is suitable for traditional keyword-based search.
+2. **Embedding-based Retrieval**: A semantic search that uses vector similarity to find documents that are semantically similar to the query. It's based on the [`OpenSearchEmbeddingRetriever`](opensearchembeddingretriever.mdx) component and is suitable for semantic search.
+
+The component automatically handles:
+
+- Converting the query into an embedding using the provided embedded,
+- Running both retrieval methods in parallel,
+- Merging and re-ranking the results using the specified join mode.
+
+### Setup and Installation
+
+```shell
+pip install opensearch-haystack
+```
+
+### Optional Parameters
+
+This Retriever accepts various optional parameters. You can verify the most up-to-date list of parameters in our [API Reference](/reference/integrations-opensearch#opensearchhybridretriever).
+
+You can pass additional parameters to the underlying components using the `bm25_retriever` and `embedding_retriever` dictionaries.
+The `DocumentJoiner` parameters are all exposed on the `OpenSearchHybridRetriever` class, so you can set them directly.
+
+Here's an example:
+
+```python
+retriever = OpenSearchHybridRetriever(
+ document_store=document_store,
+ embedder=embedder,
+ bm25_retriever={"raise_on_failure": True},
+ embedding_retriever={"raise_on_failure": False}
+)
+```
+
+## Usage
+
+### On its own
+
+This Retriever needs the `OpensearchDocumentStore` populated with documents to run. You can’t use it on its own.
+
+### In a pipeline
+
+Here's a basic example of how to use the `OpenSearchHybridRetriever`:
+
+You can use the following command to run OpenSearch locally using Docker. Make sure you have Docker installed and running on your machine. Note that this example disables the security plugin for simplicity. In a production environment, you should enable security features.
+
+```dockerfile
+docker run -d \\
+ --name opensearch-nosec \\
+ -p 9200:9200 \\
+ -p 9600:9600 \\
+ -e "discovery.type=single-node" \\
+ -e "DISABLE_SECURITY_PLUGIN=true" \\
+ opensearchproject/opensearch:2.12.0
+```
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack_integrations.components.retrievers.opensearch import OpenSearchHybridRetriever
+from haystack_integrations.document_stores.opensearch import OpenSearchDocumentStore
+
+## Initialize the document store
+doc_store = OpenSearchDocumentStore(
+ hosts=["http://localhost:9200"],
+ index="document_store",
+ embedding_dim=384,
+)
+
+## Create some sample documents
+docs = [
+ Document(content="Machine learning is a subset of artificial intelligence."),
+ Document(content="Deep learning is a subset of machine learning."),
+ Document(content="Natural language processing is a field of AI."),
+ Document(content="Reinforcement learning is a type of machine learning."),
+ Document(content="Supervised learning is a type of machine learning."),
+]
+
+## Embed the documents and add them to the document store
+doc_embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+doc_embedder.warm_up()
+docs = doc_embedder.run(docs)
+doc_store.write_documents(docs['documents'])
+
+## Initialize some haystack text embedder, in this case the SentenceTransformersTextEmbedder
+embedder = SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+
+## Initialize the hybrid retriever
+retriever = OpenSearchHybridRetriever(
+ document_store=doc_store,
+ embedder=embedder,
+ top_k_bm25=3,
+ top_k_embedding=3,
+ join_mode="reciprocal_rank_fusion"
+)
+
+## Run the retriever
+results = retriever.run(query="What is reinforcement learning?", filters_bm25=None, filters_embedding=None)
+
+>> results['documents']
+{'documents': [Document(id=..., content: 'Reinforcement learning is a type of machine learning.', score: 1.0),
+ Document(id=..., content: 'Supervised learning is a type of machine learning.', score: 0.9760624679979518),
+ Document(id=..., content: 'Deep learning is a subset of machine learning.', score: 0.4919354838709677),
+ Document(id=..., content: 'Machine learning is a subset of artificial intelligence.', score: 0.4841269841269841)]}
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pgvectorembeddingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pgvectorembeddingretriever.mdx
new file mode 100644
index 0000000000..49ea521927
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pgvectorembeddingretriever.mdx
@@ -0,0 +1,110 @@
+---
+title: "PgvectorEmbeddingRetriever"
+id: pgvectorembeddingretriever
+slug: "/pgvectorembeddingretriever"
+description: "An embedding-based Retriever compatible with the Pgvector Document Store."
+---
+
+# PgvectorEmbeddingRetriever
+
+An embedding-based Retriever compatible with the Pgvector Document Store.
+
+`embedder`: Any [Embedder](../embedders.mdx) implementing the `TextEmbedder` protocol | +| Mandatory run variables | `query`: A query string | +| Output variables | `documents`: A list of documents matching the query | +| API reference | [OpenSearch](/reference/integrations-opensearch) | +| GitHub | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opensearch | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a [PgvectorDocumentStore](../../document-stores/pgvectordocumentstore.mdx) |
+| **Mandatory run variables** | `query_embedding`: A vector representing the query (a list of floats) |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Pgvector](/reference/integrations-pgvector) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/pgvector |
+
+
+
+## Overview
+
+The `PgvectorEmbeddingRetriever` is an embedding-based Retriever compatible with the `PgvectorDocumentStore`. It compares the query and Document embeddings and fetches the Documents most relevant to the query from the `PgvectorDocumentStore` based on the outcome.
+
+When using the `PgvectorEmbeddingRetriever` in your Pipeline, make sure it has the query and Document embeddings available. You can do so by adding a Document Embedder to your indexing Pipeline and a Text Embedder to your query Pipeline.
+
+In addition to the `query_embedding`, the `PgvectorEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+
+Some relevant parameters that impact the embedding retrieval must be defined when the corresponding `PgvectorDocumentStore` is initialized: these include embedding dimension, vector function, and some others related to the search strategy (exact nearest neighbor or HNSW).
+
+## Installation
+
+To quickly set up a PostgreSQL database with pgvector, you can use Docker:
+
+```shell
+docker run -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres ankane/pgvector
+```
+
+For more information on installing pgvector, visit the [pgvector GitHub repository](https://github.com/pgvector/pgvector).
+
+To use pgvector with Haystack, install the `pgvector-haystack` integration:
+
+```shell
+pip install pgvector-haystack
+```
+
+## Usage
+
+### On its own
+
+This Retriever needs the `PgvectorDocumentStore` and indexed Documents to run.
+
+```python
+import os
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack_integrations.components.retrievers.pgvector import PgvectorEmbeddingRetriever
+
+os.environ["PG_CONN_STR"] = "postgresql://postgres:postgres@localhost:5432/postgres"
+
+document_store = PgvectorDocumentStore()
+retriever = PgvectorEmbeddingRetriever(document_store=document_store)
+
+## using a fake vector to keep the example simple
+retriever.run(query_embedding=[0.1]*768)
+```
+
+### In a Pipeline
+
+```python
+import os
+from haystack.document_stores import DuplicatePolicy
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack_integrations.components.retrievers.pgvector import PgvectorEmbeddingRetriever
+
+os.environ["PG_CONN_STR"] = "postgresql://postgres:postgres@localhost:5432/postgres"
+
+document_store = PgvectorDocumentStore(
+ embedding_dimension=768,
+ vector_function="cosine_similarity",
+ recreate_table=True,
+)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", PgvectorEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result['retriever']['documents'][0])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pgvectorkeywordretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pgvectorkeywordretriever.mdx
new file mode 100644
index 0000000000..7702a4d1ca
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pgvectorkeywordretriever.mdx
@@ -0,0 +1,143 @@
+---
+title: "PgvectorKeywordRetriever"
+id: pgvectorkeywordretriever
+slug: "/pgvectorkeywordretriever"
+description: "This is a keyword-based Retriever that fetches documents matching a query from the Pgvector Document Store."
+---
+
+# PgvectorKeywordRetriever
+
+This is a keyword-based Retriever that fetches documents matching a query from the Pgvector Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. Before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. Before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a [PgvectorDocumentStore](../../document-stores/pgvectordocumentstore.mdx) |
+| **Mandatory run variables** | `query`: A string |
+| **Output variables** | `document`: A list of documents (matching the query) |
+| **API reference** | [Pgvector](/reference/integrations-pgvector) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/pgvector |
+
+
+
+## Overview
+
+The `PgvectorKeywordRetriever` is a keyword-based Retriever compatible with the `PgvectorDocumentStore`.
+
+The component uses the `ts_rank_cd` function of PostgreSQL to rank the documents.
+It considers how often the query terms appear in the document, how close together the terms are in the document, and how important is the part of the document where they occur.
+For more details, see [Postgres documentation](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-RANKING).
+
+Keep in mind that, unlike similar components such as `ElasticsearchBM25Retriever`, this Retriever does not apply fuzzy search out of the box, so it’s necessary to carefully formulate the query in order to avoid getting zero results.
+
+In addition to the `query`, the `PgvectorKeywordRetriever` accepts other optional parameters, including `top_k` (the maximum number of documents to retrieve) and `filters` to narrow the search space.
+
+### Installation
+
+To quickly set up a PostgreSQL database with pgvector, you can use Docker:
+
+```shell
+docker run -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres ankane/pgvector
+```
+
+For more information on how to install pgvector, visit the [pgvector GitHub repository](https://github.com/pgvector/pgvector).
+
+Install the `pgvector-haystack` integration:
+
+```shell
+pip install pgvector-haystack
+```
+
+## Usage
+
+### On its own
+
+This Retriever needs the `PgvectorDocumentStore` and indexed documents to run.
+
+Set an environment variable `PG_CONN_STR` with the connection string to your PostgreSQL database.
+
+```python
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack_integrations.components.retrievers.pgvector import PgvectorKeywordRetriever
+
+document_store = PgvectorDocumentStore()
+retriever = PgvectorKeywordRetriever(document_store=document_store)
+
+retriever.run(query="my nice query")
+```
+
+### In a RAG pipeline
+
+The prerequisites necessary for running this code are:
+
+- Set an environment variable `OPENAI_API_KEY` with your OpenAI API key.
+- Set an environment variable `PG_CONN_STR` with the connection string to your PostgreSQL database.
+
+```python
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+from haystack.document_stores.types import DuplicatePolicy
+
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack_integrations.components.retrievers.pgvector import (
+ PgvectorKeywordRetriever,
+)
+
+## Create a RAG query pipeline
+prompt_template = """
+ Given these documents, answer the question.\nDocuments:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ \nQuestion: {{question}}
+ \nAnswer:
+ """
+
+document_store = PgvectorDocumentStore(
+ language="english", # this parameter influences text parsing for keyword retrieval
+ recreate_table=True,
+)
+
+documents = [
+ Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(
+ content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."
+ ),
+ Document(
+ content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves."
+ ),
+]
+
+## DuplicatePolicy.SKIP param is optional, but useful to run the script multiple times without throwing errors
+document_store.write_documents(documents=documents, policy=DuplicatePolicy.SKIP)
+
+retriever = PgvectorKeywordRetriever(document_store=document_store)
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(name="retriever", instance=retriever)
+rag_pipeline.add_component(
+ instance=PromptBuilder(template=prompt_template), name="prompt_builder"
+)
+rag_pipeline.add_component(instance=OpenAIGenerator(), name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+rag_pipeline.connect("llm.replies", "answer_builder.replies")
+rag_pipeline.connect("llm.meta", "answer_builder.meta")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+
+question = "languages spoken around the world today"
+result = rag_pipeline.run(
+ {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ "answer_builder": {"query": question},
+ }
+)
+print(result["answer_builder"])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pineconedenseretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pineconedenseretriever.mdx
new file mode 100644
index 0000000000..812ee2a5c7
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pineconedenseretriever.mdx
@@ -0,0 +1,106 @@
+---
+title: "PineconeEmbeddingRetriever"
+id: pineconedenseretriever
+slug: "/pineconedenseretriever"
+description: "An embedding-based Retriever compatible with the Pinecone Document Store."
+---
+
+# PineconeEmbeddingRetriever
+
+An embedding-based Retriever compatible with the Pinecone Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a [PineconeDocumentStore](../../document-stores/pinecone-document-store.mdx) |
+| **Mandatory run variables** | `query_embedding`: A vector representing the query (a list of floats) |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Pinecone](/reference/integrations-pinecone) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/pinecone |
+
+
+
+## Overview
+
+The `PineconeEmbeddingRetriever` is an embedding-based Retriever compatible with the `PineconeDocumentStore`. It compares the query and Document embeddings and fetches the Documents most relevant to the query from the `PineconeDocumentStore` based on the outcome.
+
+When using the `PineconeEmbeddingRetriever` in your NLP system, make sure it has the query and Document embeddings available. You can do so by adding a Document Embedder to your indexing Pipeline and a Text Embedder to your query Pipeline.
+
+In addition to the `query_embedding`, the `PineconeEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+
+Some relevant parameters that impact the embedding retrieval must be defined when the corresponding `PineconeDocumentStore` is initialized: these include the `dimension` of the embeddings and the distance `metric` to use.
+
+## Usage
+
+### On its own
+
+This Retriever needs the `PineconeDocumentStore` and indexed Documents to run.
+
+```python
+from haystack_integrations.components.retrievers.pinecone import PineconeEmbeddingRetriever
+from haystack_integrations.document_stores.pinecone import PineconeDocumentStore
+
+## Make sure you have the PINECONE_API_KEY environment variable set
+document_store = PineconeDocumentStore(index="my_index_with_documents",
+ namespace="my_namespace",
+ dimension=768)
+
+retriever = PineconeEmbeddingRetriever(document_store=document_store)
+
+## using an imaginary vector to keep the example simple, example run query:
+retriever.run(query_embedding=[0.1]*768)
+```
+
+### In a pipeline
+
+Install the dependencies you’ll need:
+
+```shell
+pip install pinecone-haystack
+pip install sentence-transformers
+```
+
+Use this Retriever in a query Pipeline like this:
+
+```python
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack_integrations.components.retrievers.pinecone import PineconeEmbeddingRetriever
+from haystack_integrations.document_stores.pinecone import PineconeDocumentStore
+
+## Make sure you have the PINECONE_API_KEY environment variable set
+document_store = PineconeDocumentStore(index="my_index",
+ namespace="my_namespace",
+ dimension=768)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", PineconeEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result['retriever']['documents'][0])
+```
+
+The example output would be:
+
+```python
+Document(id=cfe93bc1c274908801e6670440bf2bbba54fad792770d57421f85ffa2a4fcc94, content: 'There are over 7,000 languages spoken around the world today.', score: 0.87717235, embedding: vector of size 768)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdrantembeddingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdrantembeddingretriever.mdx
new file mode 100644
index 0000000000..d47cc71af4
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdrantembeddingretriever.mdx
@@ -0,0 +1,103 @@
+---
+title: "QdrantEmbeddingRetriever"
+id: qdrantembeddingretriever
+slug: "/qdrantembeddingretriever"
+description: "An embedding-based Retriever compatible with the Qdrant Document Store."
+---
+
+# QdrantEmbeddingRetriever
+
+An embedding-based Retriever compatible with the Qdrant Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1\. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG Pipeline
2. The last component in the semantic search pipeline
3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline | +| **Mandatory init variables** | `document_store`: An instance of a [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx) | +| **Mandatory run variables** | `query_embedding`: A vector representing the query (a list of floats) | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Qdrant](/reference/integrations-qdrant) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/qdrant | + +
+
+## Overview
+
+The `QdrantEmbeddingRetriever` is an embedding-based Retriever compatible with the `QdrantDocumentStore`. It compares the query and Document embeddings and fetches the Documents most relevant to the query from the `QdrantDocumentStore` based on the outcome.
+
+When using the `QdrantEmbeddingRetriever` in your NLP system, make sure it has the query and Document embeddings available. You can add a Document Embedder to your indexing Pipeline and a Text Embedder to your query Pipeline.
+
+In addition to the `query_embedding`, the `QdrantEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+
+Some relevant parameters that impact the embedding retrieval must be defined when the corresponding `QdrantDocumentStore` is initialized: these include the embedding dimension (`embedding_dim`), the `similarity` function to use when comparing embeddings and the HNWS configuration (`hnsw_config`).
+
+### Installation
+
+To start using Qdrant with Haystack, first install the package with:
+
+```shell
+pip install qdrant-haystack
+```
+
+### Usage
+
+#### On its own
+
+This Retriever needs the `QdrantDocumentStore` and indexed Documents to run.
+
+```python
+from haystack_integrations.components.retrievers.qdrant import QdrantEmbeddingRetriever
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ return_embedding=True,
+ wait_result_from_api=True,
+)
+retriever = QdrantEmbeddingRetriever(document_store=document_store)
+
+## using a fake vector to keep the example simple
+retriever.run(query_embedding=[0.1]*768)
+```
+
+#### In a Pipeline
+
+```python
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+
+from haystack_integrations.components.retrievers.qdrant import QdrantEmbeddingRetriever
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ return_embedding=True,
+ wait_result_from_api=True,
+)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."),
+ Document(content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", QdrantEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result['retriever']['documents'][0])
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdranthybridretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdranthybridretriever.mdx
new file mode 100644
index 0000000000..26b29153fb
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdranthybridretriever.mdx
@@ -0,0 +1,164 @@
+---
+title: "QdrantHybridRetriever"
+id: qdranthybridretriever
+slug: "/qdranthybridretriever"
+description: "A Retriever based both on dense and sparse embeddings, compatible with the Qdrant Document Store."
+---
+
+# QdrantHybridRetriever
+
+A Retriever based both on dense and sparse embeddings, compatible with the Qdrant Document Store.
+
+2. The last component in the semantic search pipeline
3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline | +| **Mandatory init variables** | `document_store`: An instance of a [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx) | +| **Mandatory run variables** | `query_embedding`: A vector representing the query (a list of floats) | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Qdrant](/reference/integrations-qdrant) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/qdrant | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1\. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline
2. The last component in a hybrid search pipeline
3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline | +| **Mandatory init variables** | `document_store`: An instance of a [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx) | +| **Mandatory run variables** | `query_embedding`: A dense vector representing the query (a list of floats)
`query_sparse_embedding`: A [`SparseEmbedding`](../../concepts/data-classes.mdx#sparseembedding) object containing a vectorial representation of the query | +| **Output variables** | `document`: A list of documents | +| **API reference** | [Qdrant](/reference/integrations-qdrant) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/qdrant | + +
+
+## Overview
+
+The `QdrantHybridRetriever` is a Retriever based both on dense and sparse embeddings, compatible with the [`QdrantDocumentStore`](../../document-stores/qdrant-document-store.mdx).
+
+It compares the query and document’s dense and sparse embeddings and fetches the documents most relevant to the query from the `QdrantDocumentStore`, fusing the scores with Reciprocal Rank Fusion.
+
+:::tip Hybrid Retrieval Pipeline
+
+If you want additional customization for merging or fusing results, consider creating a hybrid retrieval pipeline with [`DocumentJoiner`](../joiners/documentjoiner.mdx).
+
+You can check out our hybrid retrieval pipeline [tutorial](https://haystack.deepset.ai/tutorials/33_hybrid_retrieval) for detailed steps.
+:::
+
+When using the `QdrantHybridRetriever`, make sure it has the query and document with dense and sparse embeddings available. You can do so by:
+
+- Adding a (dense) document Embedder and a sparse document Embedder to your indexing pipeline,
+- Adding a (dense) text Embedder and a sparse text Embedder to your query pipeline.
+
+In addition to `query_embedding` and `query_sparse_embedding`, the `QdrantHybridRetriever` accepts other optional parameters, including `top_k` (the maximum number of documents to retrieve) and `filters` to narrow down the search space.
+
+:::note Sparse Embedding Support
+
+To use Sparse Embedding support, you need to initialize the `QdrantDocumentStore` with `use_sparse_embeddings=True`, which is `False` by default.
+
+If you want to use Document Store or collection previously created with this feature disabled, you must migrate the existing data. You can do this by taking advantage of the `migrate_to_sparse_embeddings_support` utility function.
+:::
+
+### Installation
+
+To start using Qdrant with Haystack, first install the package with:
+
+```shell
+pip install qdrant-haystack
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack_integrations.components.retrievers.qdrant import QdrantHybridRetriever
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack.dataclasses import Document, SparseEmbedding
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ use_sparse_embeddings=True,
+ recreate_index=True,
+ return_embedding=True,
+ wait_result_from_api=True,
+)
+
+doc = Document(content="test",
+ embedding=[0.5]*768,
+ sparse_embedding=SparseEmbedding(indices=[0, 3, 5], values=[0.1, 0.5, 0.12]))
+
+document_store.write_documents([doc])
+
+retriever = QdrantHybridRetriever(document_store=document_store)
+embedding = [0.1]*768
+sparse_embedding = SparseEmbedding(indices=[0, 1, 2, 3], values=[0.1, 0.8, 0.05, 0.33])
+retriever.run(query_embedding=embedding, query_sparse_embedding=sparse_embedding)
+```
+
+### In a pipeline
+
+Currently, you can compute sparse embeddings using Fastembed Sparse Embedders.
+First, install the package with:
+
+```shell
+pip install fastembed-haystack
+```
+
+In the example below, we are using Fastembed Embedders to compute dense embeddings as well.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.writers import DocumentWriter
+from haystack_integrations.components.retrievers.qdrant import QdrantHybridRetriever
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack_integrations.components.embedders.fastembed import (
+ FastembedTextEmbedder,
+ FastembedDocumentEmbedder,
+ FastembedSparseTextEmbedder,
+ FastembedSparseDocumentEmbedder
+)
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ use_sparse_embeddings=True,
+ embedding_dim = 384
+)
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+ Document(content="fastembed is supported by and maintained by Qdrant."),
+]
+
+indexing = Pipeline()
+indexing.add_component("sparse_doc_embedder", FastembedSparseDocumentEmbedder(model="prithvida/Splade_PP_en_v1"))
+indexing.add_component("dense_doc_embedder", FastembedDocumentEmbedder(model="BAAI/bge-small-en-v1.5"))
+indexing.add_component("writer", DocumentWriter(document_store=document_store, policy=DuplicatePolicy.OVERWRITE))
+indexing.connect("sparse_doc_embedder", "dense_doc_embedder")
+indexing.connect("dense_doc_embedder", "writer")
+
+indexing.run({"sparse_doc_embedder": {"documents": documents}})
+
+querying = Pipeline()
+querying.add_component("sparse_text_embedder", FastembedSparseTextEmbedder(model="prithvida/Splade_PP_en_v1"))
+querying.add_component("dense_text_embedder", FastembedTextEmbedder(
+ model="BAAI/bge-small-en-v1.5", prefix="Represent this sentence for searching relevant passages: ")
+ )
+querying.add_component("retriever", QdrantHybridRetriever(document_store=document_store))
+
+querying.connect("sparse_text_embedder.sparse_embedding", "retriever.query_sparse_embedding")
+querying.connect("dense_text_embedder.embedding", "retriever.query_embedding")
+
+question = "Who supports fastembed?"
+
+results = query_mix.run(
+ {"dense_text_embedder": {"text": question},
+ "sparse_text_embedder": {"text": question}}
+)
+
+print(result["retriever"]["documents"][0])
+
+## Document(id=...,
+## content: 'fastembed is supported by and maintained by Qdrant.',
+## score: 1.0)
+```
+
+## Additional References
+
+:notebook: Tutorial: [Creating a Hybrid Retrieval Pipeline](https://haystack.deepset.ai/tutorials/33_hybrid_retrieval)
+
+🧑🍳 Cookbook: [Sparse Embedding Retrieval with Qdrant and FastEmbed](https://haystack.deepset.ai/cookbook/sparse_embedding_retrieval)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdrantsparseembeddingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdrantsparseembeddingretriever.mdx
new file mode 100644
index 0000000000..3b264f4243
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdrantsparseembeddingretriever.mdx
@@ -0,0 +1,137 @@
+---
+title: "QdrantSparseEmbeddingRetriever"
+id: qdrantsparseembeddingretriever
+slug: "/qdrantsparseembeddingretriever"
+description: "A Retriever based on sparse embeddings, compatible with the Qdrant Document Store."
+---
+
+# QdrantSparseEmbeddingRetriever
+
+A Retriever based on sparse embeddings, compatible with the Qdrant Document Store.
+
+2. The last component in a hybrid search pipeline
3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline | +| **Mandatory init variables** | `document_store`: An instance of a [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx) | +| **Mandatory run variables** | `query_embedding`: A dense vector representing the query (a list of floats)
`query_sparse_embedding`: A [`SparseEmbedding`](../../concepts/data-classes.mdx#sparseembedding) object containing a vectorial representation of the query | +| **Output variables** | `document`: A list of documents | +| **API reference** | [Qdrant](/reference/integrations-qdrant) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/qdrant | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1\. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline
2. The last component in the semantic search pipeline
3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline | +| **Mandatory init variables** | `document_store`: An instance of a [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx) | +| **Mandatory run variables** | `query_sparse_embedding`: A [`SparseEmbedding`](../../concepts/data-classes.mdx#sparseembedding) object containing a vectorial representation of the query | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Qdrant](/reference/integrations-qdrant) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/qdrant | + +
+
+## Overview
+
+The `QdrantSparseEmbeddingRetriever` is a Retriever based on sparse embeddings, compatible with the [`QdrantDocumentStore`](../../document-stores/qdrant-document-store.mdx).
+
+It compares the query and document sparse embeddings and, based on the outcome, fetches the documents most relevant to the query from the `QdrantDocumentStore`.
+
+When using the `QdrantSparseEmbeddingRetriever`, make sure it has the query and document sparse embeddings available. You can do so by adding a sparse document Embedder to your indexing pipeline and a sparse text Embedder to your query pipeline.
+
+In addition to the `query_sparse_embedding`, the `QdrantSparseEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of documents to retrieve) and `filters` to narrow down the search space.
+
+:::note Sparse Embedding Support
+
+To use Sparse Embedding support, you need to initialize the `QdrantDocumentStore` with `use_sparse_embeddings=True`, which is `False` by default.
+
+If you want to use Document Store or collection previously created with this feature disabled, you must migrate the existing data. You can do this by taking advantage of the `migrate_to_sparse_embeddings_support` utility function.
+:::
+
+### Installation
+
+To start using Qdrant with Haystack, first install the package with:
+
+```shell
+pip install qdrant-haystack
+```
+
+## Usage
+
+### On its own
+
+This Retriever needs the `QdrantDocumentStore` and indexed documents to run.
+
+```python
+from haystack_integrations.components.retrievers.qdrant import QdrantSparseEmbeddingRetriever
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack.dataclasses import Document, SparseEmbedding
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ use_sparse_embeddings=True,
+ recreate_index=True,
+ return_embedding=True,
+)
+
+doc = Document(content="test", sparse_embedding=SparseEmbedding(indices=[0, 3, 5], values=[0.1, 0.5, 0.12]))
+document_store.write_documents([doc])
+
+retriever = QdrantSparseEmbeddingRetriever(document_store=document_store)
+sparse_embedding = SparseEmbedding(indices=[0, 1, 2, 3], values=[0.1, 0.8, 0.05, 0.33])
+retriever.run(query_sparse_embedding=sparse_embedding)
+```
+
+### In a pipeline
+
+In Haystack, you can compute sparse embeddings using Fastembed Embedders.
+
+First, install the package with:
+
+```shell
+pip install fastembed-haystack
+```
+
+Then, try out this pipeline:
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.writers import DocumentWriter
+from haystack_integrations.components.retrievers.qdrant import QdrantSparseEmbeddingRetriever
+from haystack_integrations.document_stores.qdrant import QdrantDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack_integrations.components.embedders.fastembed import FastembedDocumentEmbedder, FastembedTextEmbedder
+
+document_store = QdrantDocumentStore(
+ ":memory:",
+ recreate_index=True,
+ use_sparse_embeddings=True
+)
+
+documents = [
+ Document(content="My name is Wolfgang and I live in Berlin"),
+ Document(content="I saw a black horse running"),
+ Document(content="Germany has many big cities"),
+ Document(content="fastembed is supported by and maintained by Qdrant."),
+]
+
+sparse_document_embedder = FastembedSparseDocumentEmbedder()
+writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.OVERWRITE)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component("sparse_document_embedder", sparse_document_embedder)
+indexing_pipeline.add_component("writer", writer)
+indexing_pipeline.connect("sparse_document_embedder", "writer")
+
+indexing_pipeline.run({"sparse_document_embedder": {"documents": documents}})
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("sparse_text_embedder", FastembedSparseTextEmbedder())
+query_pipeline.add_component("sparse_retriever", QdrantSparseEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("sparse_text_embedder.sparse_embedding", "sparse_retriever.query_sparse_embedding")
+
+query = "Who supports fastembed?"
+
+result = query_pipeline.run({"sparse_text_embedder": {"text": query}})
+
+print(result["sparse_retriever"]["documents"][0]) # noqa: T201
+
+## Document(id=...,
+## content: 'fastembed is supported by and maintained by Qdrant.',
+## score: 0.758..)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Sparse Embedding Retrieval with Qdrant and FastEmbed](https://haystack.deepset.ai/cookbook/sparse_embedding_retrieval)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/sentencewindowretrieval.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/sentencewindowretrieval.mdx
new file mode 100644
index 0000000000..ab26be5a6f
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/sentencewindowretrieval.mdx
@@ -0,0 +1,81 @@
+---
+title: "SentenceWindowRetriever"
+id: sentencewindowretrieval
+slug: "/sentencewindowretrieval"
+description: "Use this component to retrieve neighboring sentences around relevant sentences to get the full context."
+---
+
+# SentenceWindowRetriever
+
+Use this component to retrieve neighboring sentences around relevant sentences to get the full context.
+
+2. The last component in the semantic search pipeline
3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline | +| **Mandatory init variables** | `document_store`: An instance of a [QdrantDocumentStore](../../document-stores/qdrant-document-store.mdx) | +| **Mandatory run variables** | `query_sparse_embedding`: A [`SparseEmbedding`](../../concepts/data-classes.mdx#sparseembedding) object containing a vectorial representation of the query | +| **Output variables** | `documents`: A list of documents | +| **API reference** | [Qdrant](/reference/integrations-qdrant) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/qdrant | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Used after the main Retriever component, like the `InMemoryEmbeddingRetriever` or any other Retriever. |
+| **Mandatory init variables** | `document_store`: An instance of a Document Store |
+| **Mandatory run variables** | `retrieved_documents`: A list of already retrieved documents for which you want to get a context window |
+| **Output variables** | `context_windows`: A list of strings
`context_documents`: A list of documents ordered by `split_idx_start` | +| **API reference** | [Retrievers](/reference/retrievers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/retrievers/sentence_window_retriever.py | + +
+
+## Overview
+
+The "sentence window" is a retrieval technique that allows for the retrieval of the context around relevant sentences.
+
+During indexing, documents are broken into smaller chunks or sentences and indexed. During retrieval, the sentences most relevant to a given query, based on a certain similarity metric, are retrieved.
+
+Once we have the relevant sentences, we can retrieve neighboring sentences to provide full context. The number of neighboring sentences to retrieve is defined by a fixed number of sentences before and after the relevant sentence.
+
+This component is meant to be used with other Retrievers, such as the `InMemoryEmbeddingRetriever`. These Retrievers find relevant sentences by comparing a query against indexed sentences using a similarity metric. Then, the `SentenceWindowRetriever` component retrieves neighboring sentences around the relevant ones by leveraging metadata stored in the `Document` object.
+
+## Usage
+
+### On its own
+
+```python
+splitter = DocumentSplitter(split_length=10, split_overlap=5, split_by="word")
+text = ("This is a text with some words. There is a second sentence. And there is also a third sentence. "
+ "It also contains a fourth sentence. And a fifth sentence. And a sixth sentence. And a seventh sentence")
+doc = Document(content=text)
+
+docs = splitter.run([doc])
+doc_store = InMemoryDocumentStore()
+doc_store.write_documents(docs["documents"])
+
+retriever = SentenceWindowRetriever(document_store=doc_store, window_size=3)
+```
+
+### In a Pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.retrievers import SentenceWindowRetriever
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+splitter = DocumentSplitter(split_length=10, split_overlap=5, split_by="word")
+text = (
+ "This is a text with some words. There is a second sentence. And there is also a third sentence. "
+ "It also contains a fourth sentence. And a fifth sentence. And a sixth sentence. And a seventh sentence"
+)
+doc = Document(content=text)
+docs = splitter.run([doc])
+doc_store = InMemoryDocumentStore()
+doc_store.write_documents(docs["documents"])
+
+rag = Pipeline()
+rag.add_component("bm25_retriever", InMemoryBM25Retriever(doc_store, top_k=1))
+rag.add_component("sentence_window_retriever", SentenceWindowRetriever(document_store=doc_store, window_size=3))
+rag.connect("bm25_retriever", "sentence_window_retriever")
+
+rag.run({'bm25_retriever': {"query":"third"}})
+```
+
+## Additional References
+
+:notebook: Tutorial: [Retrieving a Context Window Around a Sentence](https://haystack.deepset.ai/tutorials/42_sentence_window_retriever)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/snowflaketableretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/snowflaketableretriever.mdx
new file mode 100644
index 0000000000..714383523d
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/snowflaketableretriever.mdx
@@ -0,0 +1,80 @@
+---
+title: "SnowflakeTableRetriever"
+id: snowflaketableretriever
+slug: "/snowflaketableretriever"
+description: "Connects to a Snowflake database to execute an SQL query."
+---
+
+# SnowflakeTableRetriever
+
+Connects to a Snowflake database to execute an SQL query.
+
+`context_documents`: A list of documents ordered by `split_idx_start` | +| **API reference** | [Retrievers](/reference/retrievers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/retrievers/sentence_window_retriever.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before a [`PromptBuilder`](../builders/promptbuilder.mdx) |
+| **Mandatory init variables** | `user`: User's login
`account`: Snowflake account identifier
`api_key`: Snowflake account password. Can be set with `SNOWFLAKE_API_KEY` env var | +| **Mandatory run variables** | `query`: An SQL query to execute | +| **Output variables** | `dataframe`: The resulting Pandas dataframe version of the table | +| **API reference** | [Snowflake](/reference/integrations-snowflake) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/snowflake | + +
+
+## Overview
+
+The `SnowflakeTableRetriever` connects to a Snowflake database and retrieves data using an SQL query. It then returns a Pandas dataframe and a Markdown version of the table:
+
+To start using the integration, install it with:
+
+```bash
+pip install snowflake-haystack
+```
+
+## Usage
+
+### On its own
+
+```python
+from haystack_integrations.components.retrievers.snowflake import SnowflakeTableRetriever
+
+snowflake = SnowflakeRetriever(
+ user="`account`: Snowflake account identifier
`api_key`: Snowflake account password. Can be set with `SNOWFLAKE_API_KEY` env var | +| **Mandatory run variables** | `query`: An SQL query to execute | +| **Output variables** | `dataframe`: The resulting Pandas dataframe version of the table | +| **API reference** | [Snowflake](/reference/integrations-snowflake) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/snowflake | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. Before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. Before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a [WeaviateDocumentStore](../../document-stores/weaviatedocumentstore.mdx) |
+| **Mandatory run variables** | `query`: A string |
+| **Output variables** | `documents`: A list of documents (matching the query) |
+| **API reference** | [Weaviate](/reference/integrations-weaviate) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/weaviate |
+
+
+
+## Overview
+
+`WeaviateBM25Retriever` is a keyword-based Retriever that fetches Documents matching a query from [`WeaviateDocumentStore`](../../document-stores/weaviatedocumentstore.mdx). It determines the similarity between Documents and the query based on the BM25 algorithm, which computes a weighted word overlap between the
+two strings.
+
+Since the `WeaviateBM25Retriever` matches strings based on word overlap, it’s often used to find exact matches to names of persons or products, IDs, or well-defined error messages. The BM25 algorithm is very lightweight and simple. Beating it with more complex embedding-based approaches on out-of-domain data can be hard.
+
+If you want a semantic match between a query and documents, use the [`WeaviateEmbeddingRetriever`](weaviateembeddingretriever.mdx), which uses vectors created by embedding models to retrieve relevant information.
+
+### Parameters
+
+In addition to the `query`, the `WeaviateBM25Retriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+
+### Usage
+
+### Installation
+
+To start using Weaviate with Haystack, install the package with:
+
+```shell
+pip install weaviate-haystack
+```
+
+#### On its own
+
+This Retriever needs an instance of `WeaviateDocumentStore` and indexed Documents to run.
+
+```python
+from haystack_integrations.document_stores.weaviate.document_store import WeaviateDocumentStore
+from haystack_integrations.components.retrievers.weaviate import WeaviateBM25Retriever
+
+document_store = WeaviateDocumentStore(url="http://localhost:8080")
+
+retriever = WeaviateBM25Retriever(document_store=document_store)
+
+retriever.run(query="How to make a pizza", top_k=3)
+```
+
+#### In a Pipeline
+
+```python
+from haystack_integrations.document_stores.weaviate.document_store import (
+ WeaviateDocumentStore,
+)
+from haystack_integrations.components.retrievers.weaviate import (
+ WeaviateBM25Retriever,
+)
+
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+from haystack.document_stores.types import DuplicatePolicy
+
+## Create a RAG query pipeline
+prompt_template = """
+ Given these documents, answer the question.\nDocuments:
+ {% for doc in documents %}
+ {{ doc.content }}
+ {% endfor %}
+
+ \nQuestion: {{question}}
+ \nAnswer:
+ """
+
+document_store = WeaviateDocumentStore(url="http://localhost:8080")
+
+## Add Documents
+documents = [
+ Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(
+ content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."
+ ),
+ Document(
+ content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves."
+ ),
+]
+
+## DuplicatePolicy.SKIP param is optional, but useful to run the script multiple times without throwing errors
+document_store.write_documents(documents=documents, policy=DuplicatePolicy.SKIP)
+
+rag_pipeline = Pipeline()
+rag_pipeline.add_component(
+ name="retriever", instance=WeaviateBM25Retriever(document_store=document_store)
+)
+rag_pipeline.add_component(
+ instance=PromptBuilder(template=prompt_template), name="prompt_builder"
+)
+rag_pipeline.add_component(instance=OpenAIGenerator(), name="llm")
+rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+rag_pipeline.connect("llm.replies", "answer_builder.replies")
+rag_pipeline.connect("llm.metadata", "answer_builder.metadata")
+rag_pipeline.connect("retriever", "answer_builder.documents")
+
+question = "How many languages are spoken around the world today?"
+result = rag_pipeline.run(
+ {
+ "retriever": {"query": question},
+ "prompt_builder": {"question": question},
+ "answer_builder": {"query": question},
+ }
+)
+print(result["answer_builder"]["answers"][0])
+
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/weaviateembeddingretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/weaviateembeddingretriever.mdx
new file mode 100644
index 0000000000..49b3705ec1
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/weaviateembeddingretriever.mdx
@@ -0,0 +1,116 @@
+---
+title: "WeaviateEmbeddingRetriever"
+id: weaviateembeddingretriever
+slug: "/weaviateembeddingretriever"
+description: "This is an embedding Retriever compatible with the Weaviate Document Store."
+---
+
+# WeaviateEmbeddingRetriever
+
+This is an embedding Retriever compatible with the Weaviate Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in the semantic search pipeline 3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a [WeaviateDocumentStore](../../document-stores/weaviatedocumentstore.mdx) |
+| **Mandatory run variables** | `query_embedding`: A list of floats |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Weaviate](/reference/integrations-weaviate) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/weaviate |
+
+
+
+## Overview
+
+The `WeaviateEmbeddingRetriever` is an embedding-based Retriever compatible with the [`WeaviateDocumentStore`](../../document-stores/weaviatedocumentstore.mdx). It compares the query and Document embeddings and fetches the Documents most relevant to the query from the `WeaviateDocumentStore` based on the outcome.
+
+### Parameters
+
+When using the `WeaviateEmbeddingRetriever` in your NLP system, ensure the query and Document [embeddings](../embedders.mdx) are available. You can do so by adding a Document Embedder to your indexing Pipeline and a Text Embedder to your query Pipeline.
+
+In addition to the `query_embedding`, the `WeaviateEmbeddingRetriever` accepts other optional parameters, including `top_k` (the maximum number of Documents to retrieve) and `filters` to narrow down the search space.
+
+You can also specify `distance`, the maximum allowed distance between embeddings, and `certainty`, the normalized distance between the result items and the search embedding. The behavior of `distance` depends on the Collection’s distance metric used. See the [official Weaviate documentation](https://weaviate.io/developers/weaviate/api/graphql/search-operators#variables) for more information.
+
+The embedding similarity function depends on the vectorizer used in the `WeaviateDocumentStore` collection. Check out the [official Weaviate documentation](https://weaviate.io/developers/weaviate/modules/retriever-vectorizer-modules) to see all the supported vectorizers.
+
+## Usage
+
+### Installation
+
+To start using Weaviate with Haystack, install the package with:
+
+```shell
+pip install weaviate-haystack
+```
+
+### On its own
+
+This Retriever needs an instance of `WeaviateDocumentStore` and indexed Documents to run.
+
+```python
+from haystack_integrations.document_stores.weaviate.document_store import WeaviateDocumentStore
+from haystack_integrations.components.retrievers.weaviate import WeaviateEmbeddingRetriever
+
+document_store = WeaviateDocumentStore(url="http://localhost:8080")
+
+retriever = WeaviateEmbeddingRetriever(document_store=document_store)
+
+## using a fake vector to keep the example simple
+retriever.run(query_embedding=[0.1]*768)
+```
+
+### In a Pipeline
+
+```python
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.embedders import (
+ SentenceTransformersTextEmbedder,
+ SentenceTransformersDocumentEmbedder,
+)
+
+from haystack_integrations.document_stores.weaviate.document_store import (
+ WeaviateDocumentStore,
+)
+from haystack_integrations.components.retrievers.weaviate import (
+ WeaviateEmbeddingRetriever,
+)
+
+document_store = WeaviateDocumentStore(url="http://localhost:8080")
+
+documents = [
+ Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(
+ content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."
+ ),
+ Document(
+ content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves."
+ ),
+]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(
+ documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE
+)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component(
+ "retriever", WeaviateEmbeddingRetriever(document_store=document_store)
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run({"text_embedder": {"text": query}})
+
+print(result["retriever"]["documents"][0])
+
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/weaviatehybridretriever.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/weaviatehybridretriever.mdx
new file mode 100644
index 0000000000..f6d944d0e9
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/weaviatehybridretriever.mdx
@@ -0,0 +1,161 @@
+---
+title: "WeaviateHybridRetriever"
+id: weaviatehybridretriever
+slug: "/weaviatehybridretriever"
+description: "A Retriever that combines BM25 keyword search and vector similarity to fetch documents from the Weaviate Document Store."
+---
+
+# WeaviateHybridRetriever
+
+A Retriever that combines BM25 keyword search and vector similarity to fetch documents from the Weaviate Document Store.
+
+
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | 1. After a Text Embedder and before a [`PromptBuilder`](../builders/promptbuilder.mdx) in a RAG pipeline 2. The last component in a hybrid search pipeline 3. After a Text Embedder and before an [`ExtractiveReader`](../readers/extractivereader.mdx) in an extractive QA pipeline |
+| **Mandatory init variables** | `document_store`: An instance of a [WeaviateDocumentStore](../../document-stores/weaviatedocumentstore.mdx) |
+| **Mandatory run variables** | `query`: A string
`query_embedding`: A list of floats | +| **Output variables** | `documents`: A list of documents (matching the query) | +| **API reference** | [Weaviate](/reference/integrations-weaviate) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/weaviate | + +
+
+## Overview
+
+The `WeaviateHybridRetriever` combines keyword-based (BM25) and vector similarity search to fetch documents from the [`WeaviateDocumentStore`](../../document-stores/weaviatedocumentstore.mdx). Weaviate executes both searches in parallel and fuses the results into a single ranked list. The Retriever requires both a text query and its corresponding embedding.
+
+The `alpha` parameter controls how much each search method contributes to the final results:
+
+- `alpha = 0.0`: only keyword (BM25) scoring is used,
+- `alpha = 1.0`: only vector similarity scoring is used,
+- Values in between blend the two; higher values favor the vector score, lower values favor BM25.
+
+If you don't specify `alpha`, the Weaviate server default is used.
+
+You can also use the `max_vector_distance` parameter to set a threshold for the vector component. Candidates with a distance larger than this threshold are excluded from the vector portion before blending.
+
+See the [official Weaviate documentation](https://weaviate.io/developers/weaviate/search/hybrid#parameters) for more details on hybrid search parameters.
+
+### Parameters
+
+When using the `WeaviateHybridRetriever`, you need to provide both the query text and its embedding. You can do this by adding a Text Embedder to your query pipeline.
+
+In addition to `query` and `query_embedding`, the retriever accepts optional parameters including `top_k` (the maximum number of documents to return), `filters` to narrow down the search space, and `filter_policy` to determine how filters are applied.
+
+## Usage
+
+### Installation
+
+To start using Weaviate with Haystack, install the package with:
+
+```shell
+pip install weaviate-haystack
+```
+
+### On its own
+
+This Retriever needs an instance of `WeaviateDocumentStore` and indexed documents to run.
+
+```python
+from haystack_integrations.document_stores.weaviate.document_store import WeaviateDocumentStore
+from haystack_integrations.components.retrievers.weaviate import WeaviateHybridRetriever
+
+document_store = WeaviateDocumentStore(url="http://localhost:8080")
+
+retriever = WeaviateHybridRetriever(document_store=document_store)
+
+## using a fake vector to keep the example simple
+retriever.run(query="How many languages are there?", query_embedding=[0.1]*768)
+```
+
+### In a pipeline
+
+```python
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.embedders import (
+ SentenceTransformersTextEmbedder,
+ SentenceTransformersDocumentEmbedder,
+)
+
+from haystack_integrations.document_stores.weaviate.document_store import (
+ WeaviateDocumentStore,
+)
+from haystack_integrations.components.retrievers.weaviate import (
+ WeaviateHybridRetriever,
+)
+
+document_store = WeaviateDocumentStore(url="http://localhost:8080")
+
+documents = [
+ Document(content="There are over 7,000 languages spoken around the world today."),
+ Document(
+ content="Elephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors."
+ ),
+ Document(
+ content="In certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves."
+ ),
+]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(
+ documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE
+)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component(
+ "retriever", WeaviateHybridRetriever(document_store=document_store)
+)
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+result = query_pipeline.run(
+ {
+ "text_embedder": {"text": query},
+ "retriever": {"query": query}
+ }
+)
+
+print(result["retriever"]["documents"][0])
+```
+
+### Adjusting the Alpha Parameter
+
+You can set the `alpha` parameter at initialization or override it at query time:
+
+```python
+from haystack_integrations.components.retrievers.weaviate import WeaviateHybridRetriever
+
+## Favor keyword search (good for exact matches)
+retriever_keyword_heavy = WeaviateHybridRetriever(
+ document_store=document_store,
+ alpha=0.25
+)
+
+## Balanced hybrid search
+retriever_balanced = WeaviateHybridRetriever(
+ document_store=document_store,
+ alpha=0.5
+)
+
+## Favor vector search (good for semantic similarity)
+retriever_vector_heavy = WeaviateHybridRetriever(
+ document_store=document_store,
+ alpha=0.75
+)
+
+## Override alpha at query time
+result = retriever_balanced.run(
+ query="artificial intelligence",
+ query_embedding=embedding,
+ alpha=0.8
+)
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers.mdx
new file mode 100644
index 0000000000..3a7459869c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers.mdx
@@ -0,0 +1,22 @@
+---
+title: "Routers"
+id: routers
+slug: "/routers"
+description: "Routers is a group of components that route queries or documents to other components that can handle them best."
+---
+
+# Routers
+
+Routers is a group of components that route queries or documents to other components that can handle them best.
+
+| Component | Description |
+| --- | --- |
+| [ConditionalRouter](routers/conditionalrouter.mdx) | Routes data based on specified conditions. |
+| [DocumentLengthRouter](routers/documentlengthrouter.mdx) | Routes documents to different output connections based on the length of their `content` field. |
+| [DocumentTypeRouter](routers/documenttyperouter.mdx) | Routes documents based on their MIME types to different outputs for further processing. |
+| [FileTypeRouter](routers/filetyperouter.mdx) | Routes file paths or byte streams based on their type further down the pipeline. |
+| [LLMMessagesRouter](routers/llmmessagesrouter.mdx) | Routes Chat Messages to various output connections using a generative Language Model to perform classification. |
+| [MetadataRouter](routers/metadatarouter.mdx) | Routes documents based on their metadata field values. |
+| [TextLanguageRouter](routers/textlanguagerouter.mdx) | Routes queries based on their language. |
+| [TransformersTextRouter](routers/transformerstextrouter.mdx) | Routes text input to various output connections based on a model-defined categorization label. |
+| [TransformersZeroShotTextRouter](routers/transformerszeroshottextrouter.mdx) | Routes text input to various output connections based on user-defined categorization label. |
\ No newline at end of file
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/conditionalrouter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/conditionalrouter.mdx
new file mode 100644
index 0000000000..f78c62f550
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/conditionalrouter.mdx
@@ -0,0 +1,171 @@
+---
+title: "ConditionalRouter"
+id: conditionalrouter
+slug: "/conditionalrouter"
+description: "`ConditionalRouter` routes your data through different paths down the pipeline by evaluating the conditions that you specified."
+---
+
+# ConditionalRouter
+
+`ConditionalRouter` routes your data through different paths down the pipeline by evaluating the conditions that you specified.
+
+`query_embedding`: A list of floats | +| **Output variables** | `documents`: A list of documents (matching the query) | +| **API reference** | [Weaviate](/reference/integrations-weaviate) | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/weaviate | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory init variables** | `routes`: A list of dictionaries defining routs (See the [Overview](#overview) section below) |
+| **Mandatory run variables** | `**kwargs`: Input variables to evaluate in order to choose a specific route. See [Variables](#variables) section for more details. |
+| **Output variables** | A dictionary containing one or more output names and values of the chosen route |
+| **API reference** | [Routers](/reference/routers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/conditional_router.py |
+
+
+
+## Overview
+
+To use `ConditionalRouter` you need to define a list of routes.
+Each route is a dictionary with the following elements:
+
+- `'condition'`: A Jinja2 string expression that determines if the route is selected.
+- `'output'`: A Jinja2 expression or list of expressions defining one or more output values.
+- `'output_type'`: The expected type or list of types corresponding to each output (for example, `str`, `List[int]`).
+ - Note that this doesn't enforce the type conversion of the output. Instead, the output field is rendered using Jinja2, which automatically infers types. If you need to ensure the result is a string (for example, "123" instead of `123`), wrap the Jinja expression in single quotes like this: `output: "'{{message.text}}'"`. This ensures the rendered output is treated as a string by Jinja2.
+- `'output_name'`: The name or list of names under which the output values are published. This is used to connect the router to other components in the pipeline.
+
+### Variables
+
+The `ConditionalRouter` lets you define which variables are optional in your routing conditions.
+
+```python
+from haystack.components.routers import ConditionalRouter
+
+routes = [
+ {
+ "condition": '{{ path == "rag" }}',
+ "output": "{{ question }}",
+ "output_name": "rag_route",
+ "output_type": str
+ },
+ {
+ "condition": "{{ True }}", # fallback route
+ "output": "{{ question }}",
+ "output_name": "default_route",
+ "output_type": str
+ }
+]
+
+## 'path' is optional, 'question' is required
+router = ConditionalRouter(
+ routes=routes,
+ optional_variables=["path"]
+)
+```
+
+The component only waits for the required inputs before running. If you use an optional variable in a condition but don't provide it at runtime, it’s evaluated as `None`, which generally does not raise an error but can affect the condition’s outcome.
+
+### Unsafe behaviour
+
+The `ConditionalRouter` internally renders all the rules' templates using Jinja, by default this is a safe behaviour. Though it limits the output types to strings, bytes, numbers, tuples, lists, dicts, sets, booleans, `None` and `Ellipsis` (`...`), as well as any combination of these structures.
+
+If you want to use more types like `ChatMessage`, `Document` or `Answer` you must enable rendering of unsafe templates by setting the `unsafe` init argument to `True`.
+
+Beware that this is unsafe and can lead to remote code execution if a rule `condition` or `output` templates are customizable by the end user.
+
+## Usage
+
+### On its own
+
+This component is primarily meant to be used in pipelines.
+
+In this example, we configure two routes. The first route sends the `'streams'` value to `'enough_streams'` if the stream count exceeds two. Conversely, the second route directs `'streams'` to `'insufficient_streams'` when there are two or fewer streams.
+
+```python
+from haystack.components.routers import ConditionalRouter
+from typing import List
+
+routes = [
+ {
+ "condition": "{{streams|length > 2}}",
+ "output": "{{streams}}",
+ "output_name": "enough_streams",
+ "output_type": List[int],
+ },
+ {
+ "condition": "{{streams|length <= 2}}",
+ "output": "{{streams}}",
+ "output_name": "insufficient_streams",
+ "output_type": List[int],
+ },
+]
+
+router = ConditionalRouter(routes)
+
+kwargs = {"streams": [1, 2, 3], "query": "Haystack"}
+result = router.run(**kwargs)
+
+print(result)
+## {"enough_streams": [1, 2, 3]}
+```
+
+### In a pipeline
+
+Below is an example of a simple pipeline that routes a query based on its length and returns both the text and its character count.
+
+If the query is too short, the pipeline returns a warning message and the character count, then stops.
+
+If the query is long enough, the pipeline returns the original query and its character count, sends the query to the `PromptBuilder`, and then to the Generator to produce the final answer.
+
+```python
+from haystack import Pipeline
+from haystack.components.routers import ConditionalRouter
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+## Two routes, each returning two outputs: the text and its length
+routes = [
+ {
+ "condition": "{{ query|length > 10 }}",
+ "output": ["{{ query }}", "{{ query|length }}"],
+ "output_name": ["ok_query", "length"],
+ "output_type": [str, int],
+ },
+ {
+ "condition": "{{ query|length <= 10 }}",
+ "output": ["query too short: {{ query }}", "{{ query|length }}"],
+ "output_name": ["too_short_query", "length"],
+ "output_type": [str, int],
+ },
+]
+
+router = ConditionalRouter(routes=routes)
+
+pipe = Pipeline()
+pipe.add_component("router", router)
+pipe.add_component(
+ "prompt_builder",
+ ChatPromptBuilder(
+ template=[ChatMessage.from_user("Answer the following query: {{ query }}")],
+ required_variables={"query"},
+ ),
+)
+pipe.add_component("generator", OpenAIChatGenerator())
+
+pipe.connect("router.ok_query", "prompt_builder.query")
+pipe.connect("prompt_builder.prompt", "generator.messages")
+
+## Short query: length ≤ 10 ⇒ fallback route fires.
+print(pipe.run(data={"router": {"query": "Berlin"}}))
+## {'router': {'too_short_query': 'query too short: Berlin', 'length': 6}}
+
+## Long query: length > 10 ⇒ first route fires.
+print(pipe.run(data={"router": {"query": "What is the capital of Italy?"}}))
+## {'generator': {'replies': ['The capital of Italy is Rome.'], …}}
+```
+
++ +## Additional References + +:notebook: Tutorial: [Building Fallbacks to Websearch with Conditional Routing](https://haystack.deepset.ai/tutorials/36_building_fallbacks_with_conditional_routing) diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/documentlengthrouter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/documentlengthrouter.mdx new file mode 100644 index 0000000000..9e61aeec8e --- /dev/null +++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/documentlengthrouter.mdx @@ -0,0 +1,155 @@ +--- +title: "DocumentLengthRouter" +id: documentlengthrouter +slug: "/documentlengthrouter" +description: "Routes documents to different output connections based on the length of their `content` field." +--- + +# DocumentLengthRouter + +Routes documents to different output connections based on the length of their `content` field. + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `short_documents`: A list of documents where `content` is None or the length of `content` is less than or equal to the threshold.
`long_documents`: A list of documents where the length of `content` is greater than the threshold. | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/document_length_router.py | + +
+
+## Overview
+
+`DocumentLengthRouter` routes documents to different output connections based on the length of their `content` field.
+
+It allows to set a `threshold` init parameter. Documents where `content` is None, or the length of `content` is less than or equal to the threshold are routed to "short_documents". Others are routed to "long_documents".
+
+A common use case for `DocumentLengthRouter` is handling documents obtained from PDFs that contain non-text content, such as scanned pages or images. This component can detect empty or low-content documents and route them to components that perform OCR, generate captions, or compute image embeddings.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.routers import DocumentLengthRouter
+from haystack.dataclasses import Document
+
+docs = [
+ Document(content="Short"),
+ Document(content="Long document "*20),
+]
+
+router = DocumentLengthRouter(threshold=10)
+
+result = router.run(documents=docs)
+print(result)
+
+## {
+## "short_documents": [Document(content="Short", ...)],
+## "long_documents": [Document(content="Long document ...", ...)],
+## }
+```
+
+### In a pipeline
+
+In the following indexing pipeline, the `PyPDFToDocument` Converter extracts text from PDF files. Documents are then split by pages using a `DocumentSplitter`. Next, the `DocumentLengthRouter` routes short documents to `LLMDocumentContentExtractor` to extract text, which is particularly useful for non-textual, image-based pages. Finally, all documents are collected using `DocumentJoiner` and written to the Document Store.
+
+```python
+from haystack import Pipeline
+from haystack.components.converters import PyPDFToDocument
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.joiners import DocumentJoiner
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.routers import DocumentLengthRouter
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+
+indexing_pipe = Pipeline()
+indexing_pipe.add_component(
+ "pdf_converter",
+ PyPDFToDocument(store_full_path=True)
+)
+## setting skip_empty_documents=False is important here because the
+## LLMDocumentContentExtractor can extract text from non-textual documents
+## that otherwise would be skipped
+indexing_pipe.add_component(
+ "pdf_splitter",
+ DocumentSplitter(
+ split_by="page",
+ split_length=1,
+ skip_empty_documents=False
+ )
+)
+indexing_pipe.add_component(
+ "doc_length_router",
+ DocumentLengthRouter(threshold=10)
+)
+indexing_pipe.add_component(
+ "content_extractor",
+ LLMDocumentContentExtractor(
+ chat_generator=OpenAIChatGenerator(model="gpt-4.1-mini")
+ )
+)
+indexing_pipe.add_component(
+ "doc_joiner",
+ DocumentJoiner(sort_by_score=False)
+)
+indexing_pipe.add_component(
+ "document_writer",
+ DocumentWriter(document_store=document_store)
+)
+
+indexing_pipe.connect("pdf_converter.documents", "pdf_splitter.documents")
+indexing_pipe.connect("pdf_splitter.documents", "doc_length_router.documents")
+## The short PDF pages will be enriched/captioned
+indexing_pipe.connect(
+ "doc_length_router.short_documents",
+ "content_extractor.documents"
+)
+indexing_pipe.connect(
+ "doc_length_router.long_documents",
+ "doc_joiner.documents"
+)
+indexing_pipe.connect(
+ "content_extractor.documents",
+ "doc_joiner.documents"
+)
+indexing_pipe.connect("doc_joiner.documents", "document_writer.documents")
+
+## Run the indexing pipeline with sources
+indexing_result = indexing_pipe.run(
+ data={"sources": ["textual_pdf.pdf", "non_textual_pdf.pdf"]}
+)
+
+## Inspect the documents
+indexed_documents = document_store.filter_documents()
+print(f"Indexed {len(indexed_documents)} documents:\n")
+for doc in indexed_documents:
+ print("file_path: ", doc.meta["file_path"])
+ print("page_number: ", doc.meta["page_number"])
+ print("content: ", doc.content)
+ print("-" * 100 + "\n")
+
+## Indexed 3 documents:
+##
+## file_path: textual_pdf.pdf
+## page_number: 1
+## content: A sample PDF file...
+## ----------------------------------------------------------------------------------------------------
+##
+## file_path: textual_pdf.pdf
+## page_number: 2
+## content: Page 2 of Sample PDF...
+## ----------------------------------------------------------------------------------------------------
+##
+## file_path: non_textual_pdf.pdf
+## page_number: 1
+## content: Content extracted from non-textual PDF using a LLM...
+## ----------------------------------------------------------------------------------------------------
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/documenttyperouter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/documenttyperouter.mdx
new file mode 100644
index 0000000000..359f9bcd2e
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/documenttyperouter.mdx
@@ -0,0 +1,167 @@
+---
+title: "DocumentTypeRouter"
+id: documenttyperouter
+slug: "/documenttyperouter"
+description: "Use this Router in pipelines to route documents based on their MIME types to different outputs for further processing."
+---
+
+# DocumentTypeRouter
+
+Use this Router in pipelines to route documents based on their MIME types to different outputs for further processing.
+
+`long_documents`: A list of documents where the length of `content` is greater than the threshold. | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/document_length_router.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | As a preprocessing component to route documents by type before sending them to specific [Converters](../converters.mdx) or [Preprocessors](../preprocessors.mdx) |
+| **Mandatory init variables** | `mime_types`: A list of MIME types or regex patterns for classification |
+| **Mandatory run variables** | `documents`: A list of [Documents](../../concepts/data-classes.mdx#document) to categorize |
+| **Output variables** | `unclassified`: A list of uncategorized [Documents](../../concepts/data-classes.mdx#document)
`mime_types`: For example "text/plain", "application/pdf", "image/jpeg": List of categorized [Documents](../../concepts/data-classes.mdx#document) | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/document_type_router.py | + +
+
+## Overview
+
+`DocumentTypeRouter` routes documents based on their MIME types, supporting both exact matches and regex patterns. It can determine MIME types from document metadata or infer them from file paths using standard Python `mimetypes` module and custom mappings.
+
+When initializing the component, specify the set of MIME types to route to separate outputs. Set the `mime_types` parameter to a list of types, for example: `["text/plain", "audio/x-wav", "image/jpeg"]`. Documents with MIME types that are not listed are routed to an output named "unclassified".
+
+The component requires at least one of the following parameters to determine MIME types:
+
+- `mime_type_meta_field`: Name of the metadata field containing the MIME type
+- `file_path_meta_field`: Name of the metadata field containing the file path (MIME type will be inferred from the file extension)
+
+## Usage
+
+### On its own
+
+Below is an example that uses the `DocumentTypeRouter` to categorize documents by their MIME types:
+
+```python
+from haystack.components.routers import DocumentTypeRouter
+from haystack.dataclasses import Document
+
+docs = [
+ Document(content="Example text", meta={"file_path": "example.txt"}),
+ Document(content="Another document", meta={"mime_type": "application/pdf"}),
+ Document(content="Unknown type")
+]
+
+router = DocumentTypeRouter(
+ mime_type_meta_field="mime_type",
+ file_path_meta_field="file_path",
+ mime_types=["text/plain", "application/pdf"]
+)
+
+result = router.run(documents=docs)
+print(result)
+```
+
+Expected output:
+
+```python
+{
+ "text/plain": [Document(...)],
+ "application/pdf": [Document(...)],
+ "unclassified": [Document(...)]
+}
+```
+
+### Using regex patterns
+
+You can use regex patterns to match multiple MIME types with similar patterns:
+
+```python
+from haystack.components.routers import DocumentTypeRouter
+from haystack.dataclasses import Document
+
+docs = [
+ Document(content="Plain text", meta={"mime_type": "text/plain"}),
+ Document(content="HTML text", meta={"mime_type": "text/html"}),
+ Document(content="Markdown text", meta={"mime_type": "text/markdown"}),
+ Document(content="JPEG image", meta={"mime_type": "image/jpeg"}),
+ Document(content="PNG image", meta={"mime_type": "image/png"}),
+ Document(content="PDF document", meta={"mime_type": "application/pdf"}),
+]
+
+router = DocumentTypeRouter(mime_type_meta_field="mime_type", mime_types=[r"text/.*", r"image/.*"])
+
+result = router.run(documents=docs)
+
+## Result will have:
+## - "text/.*": 3 documents (text/plain, text/html, text/markdown)
+## - "image/.*": 2 documents (image/jpeg, image/png)
+## - "unclassified": 1 document (application/pdf)
+```
+
+### Using custom MIME types
+
+You can add custom MIME type mappings for uncommon file types:
+
+```python
+from haystack.components.routers import DocumentTypeRouter
+from haystack.dataclasses import Document
+
+docs = [
+ Document(content="Word document", meta={"file_path": "document.docx"}),
+ Document(content="Markdown file", meta={"file_path": "readme.md"}),
+ Document(content="Outlook message", meta={"file_path": "email.msg"}),
+]
+
+router = DocumentTypeRouter(
+ file_path_meta_field="file_path",
+ mime_types=[
+ "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+ "text/markdown",
+ "application/vnd.ms-outlook",
+ ],
+ additional_mimetypes={"application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx"},
+)
+
+result = router.run(documents=docs)
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that uses a `DocumentTypeRouter` to categorize documents by type and then process them differently. Text documents get processed by a `DocumentSplitter` before being stored, while PDF documents are stored directly.
+
+```python
+from haystack import Pipeline
+from haystack.components.routers import DocumentTypeRouter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+from haystack.dataclasses import Document
+
+## Create document store
+document_store = InMemoryDocumentStore()
+
+## Create pipeline
+p = Pipeline()
+p.add_component(instance=DocumentTypeRouter(mime_types=["text/plain", "application/pdf"], mime_type_meta_field="mime_type"), name="document_type_router")
+p.add_component(instance=DocumentSplitter(), name="text_splitter")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="text_writer")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="pdf_writer")
+
+## Connect components
+p.connect("document_type_router.text/plain", "text_splitter.documents")
+p.connect("text_splitter.documents", "text_writer.documents")
+p.connect("document_type_router.application/pdf", "pdf_writer.documents")
+
+## Create test documents
+docs = [
+ Document(content="This is a text document that will be split and stored.", meta={"mime_type": "text/plain"}),
+ Document(content="This is a PDF document that will be stored directly.", meta={"mime_type": "application/pdf"}),
+ Document(content="This is an image document that will be unclassified.", meta={"mime_type": "image/jpeg"}),
+]
+
+## Run pipeline
+result = p.run({"document_type_router": {"documents": docs}})
+
+## The pipeline will route documents based on their MIME types:
+## - Text documents (text/plain) → DocumentSplitter → DocumentWriter
+## - PDF documents (application/pdf) → DocumentWriter (direct)
+## - Other documents → unclassified output
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/filetyperouter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/filetyperouter.mdx
new file mode 100644
index 0000000000..c073585a0a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/filetyperouter.mdx
@@ -0,0 +1,67 @@
+---
+title: "FileTypeRouter"
+id: filetyperouter
+slug: "/filetyperouter"
+description: "Use this Router in indexing pipelines to route file paths or byte streams based on their type to different outputs for further processing."
+---
+
+# FileTypeRouter
+
+Use this Router in indexing pipelines to route file paths or byte streams based on their type to different outputs for further processing.
+
+`mime_types`: For example "text/plain", "application/pdf", "image/jpeg": List of categorized [Documents](../../concepts/data-classes.mdx#document) | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/document_type_router.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | As the first component preprocessing data followed by [Converters](../converters.mdx) |
+| **Mandatory init variables** | `mime_types`: A list of MIME types or regex patterns for classification |
+| **Mandatory run variables** | `sources`: A list of file paths or byte streams to categorize |
+| **Output variables** | `unclassified`: A list of uncategorized file paths or [byte streams](../../concepts/data-classes.mdx#bytestream)
`mime_types`: For example "text/plain", "text/html", "application/pdf", "text/markdown", "audio/x-wav", "image/jpeg": List of categorized file paths or byte streams | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/file_type_router.py | + +
+
+## Overview
+
+`FileTypeRouter` routes file paths or byte streams based on their type, for example, plain text, jpeg image, or audio wave. For file paths, it infers MIME types from their extensions, while for byte streams, it determines MIME types based on the provided metadata.
+
+When initializing the component, you specify the set of MIME types to route to separate outputs. To do this, set the `mime_types` parameter to a list of types, for example: `["text/plain", "audio/x-wav", "image/jpeg"]`. Types that are not listed are routed to an output named “unclassified”.
+
+## Usage
+
+### On its own
+
+Below is an example that uses the `FileTypeRouter` to rank two simple documents:
+
+```python
+from haystack import Document
+from haystack.components.routers import FileTypeRouter
+
+router = FileTypeRouter(mime_types=["text/plain"])
+router.run(sources=["text-file-will-be-added.txt", "pdf-will-not-ne-added.pdf"])
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that uses a `FileTypeRouter` to forward only plain text files to a `DocumentSplitter` and then a `DocumentWriter`. Only the content of plain text files gets added to the `InMemoryDocumentStore`, but not the content of files of any other type. As an alternative, you could add a `PyPDFConverter` to the pipeline and use the `FileTypeRouter` to route PDFs to it so that it converts them to documents.
+
+```python
+from haystack import Pipeline
+from haystack.components.routers import FileTypeRouter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.converters import TextFileToDocument
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.writers import DocumentWriter
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=FileTypeRouter(mime_types=["text/plain"]), name="file_type_router")
+p.add_component(instance=TextFileToDocument(), name="text_file_converter")
+p.add_component(instance=DocumentSplitter(), name="splitter")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+p.connect("file_type_router.text/plain", "text_file_converter.sources")
+p.connect("text_file_converter.documents", "splitter.documents")
+p.connect("splitter.documents", "writer.documents")
+p.run({"file_type_router": {"sources":["text-file-will-be-added.txt", "pdf-will-not-be-added.pdf"]}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/llmmessagesrouter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/llmmessagesrouter.mdx
new file mode 100644
index 0000000000..1f763c8970
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/llmmessagesrouter.mdx
@@ -0,0 +1,211 @@
+---
+title: "LLMMessagesRouter"
+id: llmmessagesrouter
+slug: "/llmmessagesrouter"
+description: "Use this component to route Chat Messages to various output connections using a generative Language Model to perform classification."
+---
+
+# LLMMessagesRouter
+
+Use this component to route Chat Messages to various output connections using a generative Language Model to perform classification.
+
+`mime_types`: For example "text/plain", "text/html", "application/pdf", "text/markdown", "audio/x-wav", "image/jpeg": List of categorized file paths or byte streams | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/file_type_router.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory init variables** | `chat_generator`: A Chat Generator instance (the LLM used for classification)
`output_names`: A list of output connection names
`output_patterns`: A list of regular expressions to be matched against the output of the LLM. | +| **Mandatory run variables** | `messages`: A list of Chat Messages | +| **Output variables** | `chat_generator_text`: The text output of the LLM, useful for debugging
`output_names`: Each contains the list of messages that matched the corresponding pattern
`unmatched`: Messages not matching any pattern | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/llm_messages_router.py | + +
+
+## Overview
+
+`LLMMessagesRouter` uses an LLM to classify chat messages and route them to different outputs based on that classification.
+
+This is especially useful for tasks like content moderation. If a message is deemed safe, you might forward it to a Chat Generator to generate a reply. Otherwise, you may halt the interaction or log the message separately.
+
+First, you need to pass a ChatGenerator instance in the `chat_generator` parameter.
+Then, define two lists of the same length:
+
+- `output_names`: The names of the outputs to which you want to route messages,
+- `output_patterns`: Regular expressions that are matched against the LLM output.
+
+Each pattern is evaluated in order, and the first match determines the output. To define appropriate patterns, we recommend reviewing the model card of your chosen LLM and/or experimenting with it.
+
+Optionally, you can provide a `system_prompt` to guide the classification behavior of the LLM. In this case as well, we recommend checking the model card to discover customization options.
+
+To see the full list of parameters, check out our [API reference](/reference/routers-api#llmmessagesrouter).
+
+## Usage
+
+### On its own
+
+Below is an example of using `LLMMessagesRouter` to route Chat Messages to two output connections based on safety classification. Messages that don’t match any pattern are routed to `unmatched`.
+
+We use Llama Guard 4 for content moderation. To use this model with the Hugging Face API, you need to [request access](https://huggingface.co/meta-llama/Llama-Guard-4-12B) and set the `HF_TOKEN` environment variable.
+
+```python
+from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.components.routers.llm_messages_router import LLMMessagesRouter
+from haystack.dataclasses import ChatMessage
+
+chat_generator = HuggingFaceAPIChatGenerator(
+ api_type="serverless_inference_api",
+ api_params={"model": "meta-llama/Llama-Guard-4-12B", "provider": "groq"},
+)
+
+router = LLMMessagesRouter(chat_generator=chat_generator,
+ output_names=["unsafe", "safe"],
+ output_patterns=["unsafe", "safe"])
+
+print(router.run([ChatMessage.from_user("How to rob a bank?")]))
+
+## {
+## 'chat_generator_text': 'unsafe\nS2',
+## 'unsafe': [
+## ChatMessage(
+## _role=`output_names`: A list of output connection names
`output_patterns`: A list of regular expressions to be matched against the output of the LLM. | +| **Mandatory run variables** | `messages`: A list of Chat Messages | +| **Output variables** | `chat_generator_text`: The text output of the LLM, useful for debugging
`output_names`: Each contains the list of messages that matched the corresponding pattern
`unmatched`: Messages not matching any pattern | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/llm_messages_router.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After components that classify documents, such as [`DocumentLanguageClassifier`](../classifiers/documentlanguageclassifier.mdx) |
+| **Mandatory init variables** | `rules`: A dictionary with metadata routing rules (see our API Reference for examples) |
+| **Mandatory run variables** | `documents`: A list of documents or byte streams |
+| **Output variables** | `unmatched`: A list of documents or byte streams not matching any rule
``: A list of documents or byte streams matching custom rules (where `` is the name of the rule). There's one output per one rule you define. Each of these outputs is a list of documents or byte streams. |
+| **API reference** | [Routers](/reference/routers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/metadata_router.py |
+
+
+
+## Overview
+
+`MetadataRouter` routes documents or byte streams to different outputs based on their metadata. You initialize it with `rules` defining the names of the outputs and filters to match documents or byte streams to one of the connections. The filters follow the same syntax as filters in Document Stores. If a document or byte stream matches multiple filters, it is sent to multiple outputs. Objects that do not match any rule go to an output connection named `unmatched`.
+
+In pipelines, this component is most useful after a Classifier (such as the `DocumentLanguageClassifier`) that adds the classification results to the documents' metadata.
+
+This component has no default rules. If you don't define any rules when initializing the component, it routes all documents or byte streams to the `unmatched` output.
+
+## Usage
+
+### On its own
+
+Below is an example that uses the `MetadataRouter` to filter out documents based on their metadata. We initialize the router by setting a rule to pass on all documents with `language` set to `en` in their metadata to an output connection called `en`. Documents that don't match this rule go to an output connection named `unmatched`.
+
+```python
+from haystack import Document
+from haystack.components.routers import MetadataRouter
+
+docs = [Document(content="Paris is the capital of France.", meta={"language": "en"}), Document(content="Berlin ist die Haupststadt von Deutschland.", meta={"language": "de"})]
+router = MetadataRouter(rules={"en": {"field": "meta.language", "operator": "==", "value": "en"}})
+router.run(documents=docs)
+```
+
+### Routing ByteStreams
+
+You can also use `MetadataRouter` to route `ByteStream` objects based on their metadata. This is useful when working with binary data or when you need to route files before they're converted to documents.
+
+```python
+from haystack.dataclasses import ByteStream
+from haystack.components.routers import MetadataRouter
+
+streams = [
+ ByteStream.from_string("Hello world", meta={"language": "en"}),
+ ByteStream.from_string("Bonjour le monde", meta={"language": "fr"})
+]
+
+router = MetadataRouter(
+ rules={"english": {"field": "meta.language", "operator": "==", "value": "en"}},
+ output_type=list[ByteStream]
+)
+
+result = router.run(documents=streams)
+## {'english': [ByteStream(...)], 'unmatched': [ByteStream(...)]}
+```
+
+### In a pipeline
+
+Below is an example of an indexing pipeline that converts text files to documents and uses the `DocumentLanguageClassifier` to detect the language of the text and add it to the documents' metadata. It then uses the `MetadataRouter` to forward only English language documents to the `DocumentWriter`. Documents of other languages will not be added to the `DocumentStore`.
+
+```python
+from haystack import Pipeline
+from haystack.components.file_converters import TextFileToDocument
+from haystack.components.classifiers import DocumentLanguageClassifier
+from haystack.components.routers import MetadataRouter
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=TextFileToDocument(), name="text_file_converter")
+p.add_component(instance=DocumentLanguageClassifier(), name="language_classifier")
+p.add_component(
+ instance=MetadataRouter(rules={"en": {"field": "meta.language", "operator": "==", "value": "en"}}), name="router"
+)
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+p.connect("text_file_converter.documents", "language_classifier.documents")
+p.connect("language_classifier.documents", "router.documents")
+p.connect("router.en", "writer.documents")
+p.run({"text_file_converter": {"sources": ["english-file-will-be-added.txt", "german-file-will-not-be-added.txt"]}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/textlanguagerouter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/textlanguagerouter.mdx
new file mode 100644
index 0000000000..5a152f9255
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/textlanguagerouter.mdx
@@ -0,0 +1,62 @@
+---
+title: "TextLanguageRouter"
+id: textlanguagerouter
+slug: "/textlanguagerouter"
+description: "Use this component in pipelines to route a query based on its language."
+---
+
+# TextLanguageRouter
+
+Use this component in pipelines to route a query based on its language.
+
+`
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | As the first component to route a query to different [Retrievers](../retrievers.mdx) , based on its language |
+| **Mandatory init variables** | `languages`: A list of ISO language codes |
+| **Mandatory run variables** | `text`: A string |
+| **Output variables** | `unmatched`: A string
``: A string (where `` is defined during initialization). For example: `fr`: French language string. |
+| **API reference** | [Routers](/reference/routers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/text_language_router.py |
+
+
+
+## Overview
+
+`TextLanguageRouter` detects the language of an input string and routes it to an output named after the language if it's in the set of languages the component was initialized with. By default, only English is in this set. If the detected language of the input text is not in the component’s `languages` , it's routed to an output named `unmatched`.
+
+In pipelines, it's used as the first component to route a query based on its language and filter out queries in unsupported languages.
+
+The components parameter `languages` must be a list of languages in ISO code, such as en, de, fr, es, it, each corresponding to a different output connection (see [langdetect documentation](https://github.com/Mimino666/langdetect#languages))).
+
+## Usage
+
+### On its own
+
+Below is an example where using the `TextLanguageRouter` to route only French texts to an output connection named `fr`. Other texts, such as the English text below, are routed to an output named `unmatched`.
+
+```python
+from haystack.components.routers import TextLanguageRouter
+
+router = TextLanguageRouter(languages=["fr"])
+router.run(text="What's your query?")
+```
+
+### In a pipeline
+
+Below is an example of a query pipeline that uses a `TextLanguageRouter` to forward only English language queries to the Retriever.
+
+```python
+from haystack import Pipeline
+from haystack.components.routers import TextLanguageRouter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+
+document_store = InMemoryDocumentStore()
+p = Pipeline()
+p.add_component(instance=TextLanguageRouter(), name="text_language_router")
+p.add_component(instance=InMemoryBM25Retriever(document_store=document_store), name="retriever")
+p.connect("text_language_router.en", "retriever.query")
+p.run({"text_language_router": {"text": "What's your query?"}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/transformerstextrouter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/transformerstextrouter.mdx
new file mode 100644
index 0000000000..9a0a28d76c
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/transformerstextrouter.mdx
@@ -0,0 +1,95 @@
+---
+title: "TransformersTextRouter"
+id: transformerstextrouter
+slug: "/transformerstextrouter"
+description: "Use this component to route text input to various output connections based on a model-defined categorization label."
+---
+
+# TransformersTextRouter
+
+Use this component to route text input to various output connections based on a model-defined categorization label.
+
+`
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory init variables** | `model`: The name or path of a Hugging Face model for text classification
`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `text`: The text to be routed to one of the specified outputs based on which label it has been categorized into | +| **Output variables** | `documents`: A dictionary with the label as key and the text as value | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/transformers_text_router.py | + +
+
+## Overview
+
+`TransformersTextRouter` routes text input to various output connections based on its categorization label. This is useful for routing queries to different models in a pipeline depending on their categorization.
+
+First, you need to set a selected model with a `model` parameter when initializing the component. The selected model then provides the set of labels for categorization.
+
+You can additionally provide the `labels` parameter – a list of strings of possible class labels to classify each sequence into. If not provided, the component fetches the labels from the model configuration file hosted on the HuggingFace Hub using `transformers.AutoConfig.from_pretrained`.
+
+To see the full list of parameters, check out our [API reference](/reference/routers-api#transformerstextrouter).
+
+## Usage
+
+### On its own
+
+The `TransformersTextRouter` isn’t very effective on its own, as its main strength lies in working within a pipeline. The component's true potential is unlocked when it is integrated into a pipeline, where it can efficiently route text to the most appropriate components. Please see the following section for a complete example of usage.
+
+### In a pipeline
+
+Below is an example of a simple pipeline that routes English queries to a Text Generator optimized for English text and German queries to a Text Generator optimized for German text.
+
+```python
+from haystack import Pipeline
+from haystack.components.routers import TransformersTextRouter
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.generators.huggingface import HuggingFaceLocalGenerator
+from haystack.dataclasses import ChatMessage
+
+p = Pipeline()
+
+p.add_component(
+ instance=TransformersTextRouter(model="papluca/xlm-roberta-base-language-detection"),
+ name="text_router"
+)
+p.add_component(
+ instance=ChatPromptBuilder(
+ template=[ChatMessage.from_user("Answer the question: {{query}}\nAnswer:")],
+ required_variables={"query"}
+ ),
+ name="english_prompt_builder"
+)
+p.add_component(
+ instance=ChatPromptBuilder(
+ template=[ChatMessage.from_user("Beantworte die Frage: {{query}}\nAntwort:")],
+ required_variables={"query"}
+ ),
+ name="german_prompt_builder"
+)
+p.add_component(
+ instance=HuggingFaceLocalGenerator(model="DiscoResearch/Llama3-DiscoLeo-Instruct-8B-v0.1"),
+ name="german_llm"
+)
+p.add_component(
+ instance=HuggingFaceLocalGenerator(model="microsoft/Phi-3-mini-4k-instruct"),
+ name="english_llm"
+)
+
+p.connect("text_router.en", "english_prompt_builder.query")
+p.connect("text_router.de", "german_prompt_builder.query")
+p.connect("english_prompt_builder.messages", "english_llm.messages")
+p.connect("german_prompt_builder.messages", "german_llm.messages")
+
+## English Example
+print(p.run({"text_router": {"text": "What is the capital of Germany?"}}))
+
+## German Example
+print(p.run({"text_router": {"text": "Was ist die Hauptstadt von Deutschland?"}}))
+```
+
+## Additional References
+
+:notebook: Tutorial: [Query Classification with TransformersTextRouter and TransformersZeroShotTextRouter](https://haystack.deepset.ai/tutorials/41_query_classification_with_transformerstextrouter_and_transformerszeroshottextrouter)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/transformerszeroshottextrouter.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/transformerszeroshottextrouter.mdx
new file mode 100644
index 0000000000..23a0ccad63
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/transformerszeroshottextrouter.mdx
@@ -0,0 +1,116 @@
+---
+title: "TransformersZeroShotTextRouter"
+id: transformerszeroshottextrouter
+slug: "/transformerszeroshottextrouter"
+description: "Use this component to route text input to various output connections based on its user-defined categorization label."
+---
+
+# TransformersZeroShotTextRouter
+
+Use this component to route text input to various output connections based on its user-defined categorization label.
+
+`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `text`: The text to be routed to one of the specified outputs based on which label it has been categorized into | +| **Output variables** | `documents`: A dictionary with the label as key and the text as value | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/transformers_text_router.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Flexible |
+| **Mandatory init variables** | `labels`: A list of labels for classification
`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `text`: The text to be routed to one of the specified outputs based on which label it has been categorized into | +| **Output variables** | `documents`: A dictionary with the label as key and the text as value | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/zero_shot_text_router.py | + +
+
+## Overview
+
+`TransformersZeroShotTextRouter` routes text input to various output connections based on its categorization label. This feature is especially beneficial for directing queries to appropriate components within a pipeline, according to their specific categories. Users can define the labels for this categorization process.
+
+`TransformersZeroShotTextRouter` uses the `MoritzLaurer/deberta-v3-base-zeroshot-v1.1-all-33` zero-shot text classification model by default. You can set another model of your choosing with the `model` parameter.
+
+To use `TransformersZeroShotTextRouter`, you need to provide the mandatory `labels` parameter – a list of strings of possible class labels to classify each sequence into.
+
+To see the full list of parameters, check out our [API reference](/reference/routers-api#transformerszeroshottextrouter).
+
+## Usage
+
+### On its own
+
+The `TransformersZeroShotTextRouter` isn’t very effective on its own, as its main strength lies in working within a pipeline. The component's true potential is unlocked when it is integrated into a pipeline, where it can efficiently route text to the most appropriate components. Please see the following section for a complete example of usage.
+
+### In a pipeline
+
+Below is an example of a simple pipeline that routes input text to an appropriate route in the pipeline.
+
+We first create an `InMemoryDocumentStore` and populate it with documents about Germany and France, embedding these documents using `SentenceTransformersDocumentEmbedder`.
+
+We then create a retrieving pipeline with the `TransformersZeroShotTextRouter` to categorize an incoming text as either "passage" or "query" based on these predefined labels. Depending on the categorization, the text is then processed by appropriate Embedders tailored for passages and queries, respectively. These Embedders generate embeddings that are used by `InMemoryEmbeddingRetriever` to find relevant documents in the Document Store.
+
+Finally, the pipeline is executed with a sample text: "What is the capital of Germany?” which categorizes this input text as “query” and routes it to Query Embedder and subsequently Query Retriever to return the relevant results.
+
+```python
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.core.pipeline import Pipeline
+from haystack.components.routers import TransformersZeroShotTextRouter
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+
+document_store = InMemoryDocumentStore()
+doc_embedder = SentenceTransformersDocumentEmbedder(model="intfloat/e5-base-v2")
+doc_embedder.warm_up()
+docs = [
+ Document(
+ content="Germany, officially the Federal Republic of Germany, is a country in the western region of "
+ "Central Europe. The nation's capital and most populous city is Berlin and its main financial centre "
+ "is Frankfurt; the largest urban area is the Ruhr."
+ ),
+ Document(
+ content="France, officially the French Republic, is a country located primarily in Western Europe. "
+ "France is a unitary semi-presidential republic with its capital in Paris, the country's largest city "
+ "and main cultural and commercial centre; other major urban areas include Marseille, Lyon, Toulouse, "
+ "Lille, Bordeaux, Strasbourg, Nantes and Nice."
+ )
+]
+docs_with_embeddings = doc_embedder.run(docs)
+document_store.write_documents(docs_with_embeddings["documents"])
+
+p = Pipeline()
+p.add_component(instance=TransformersZeroShotTextRouter(labels=["passage", "query"]), name="text_router")
+p.add_component(
+ instance=SentenceTransformersTextEmbedder(model="intfloat/e5-base-v2", prefix="passage: "),
+ name="passage_embedder"
+)
+p.add_component(
+ instance=SentenceTransformersTextEmbedder(model="intfloat/e5-base-v2", prefix="query: "),
+ name="query_embedder"
+)
+p.add_component(
+ instance=InMemoryEmbeddingRetriever(document_store=document_store),
+ name="query_retriever"
+)
+p.add_component(
+ instance=InMemoryEmbeddingRetriever(document_store=document_store),
+ name="passage_retriever"
+)
+
+p.connect("text_router.passage", "passage_embedder.text")
+p.connect("passage_embedder.embedding", "passage_retriever.query_embedding")
+p.connect("text_router.query", "query_embedder.text")
+p.connect("query_embedder.embedding", "query_retriever.query_embedding")
+
+## Query Example
+result = p.run({"text_router": {"text": "What is the capital of Germany?"}})
+print(result)
+
+>>{'query_retriever': {'documents': [Document(id=32d393dd8ee60648ae7e630cfe34b1922e747812ddf9a2c8b3650e66e0ecdb5a,
+content: 'Germany, officially the Federal Republic of Germany, is a country in the western region of Central E...',
+score: 0.8625669285150891), Document(id=c17102d8d818ce5cdfee0288488c518f5c9df238a9739a080142090e8c4cb3ba,
+content: 'France, officially the French Republic, is a country located primarily in Western Europe. France is ...',
+score: 0.7637571978602222)]}}
+
+```
+
+## Additional References
+
+:notebook: Tutorial: [Query Classification with TransformersTextRouter and TransformersZeroShotTextRouter](https://haystack.deepset.ai/tutorials/41_query_classification_with_transformerstextrouter_and_transformerszeroshottextrouter)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/samplers/toppsampler.mdx b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/samplers/toppsampler.mdx
new file mode 100644
index 0000000000..4611b9f05a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/pipeline-components/samplers/toppsampler.mdx
@@ -0,0 +1,124 @@
+---
+title: "TopPSampler"
+id: toppsampler
+slug: "/toppsampler"
+description: "Uses nucleus sampling to filter documents."
+---
+
+# TopPSampler
+
+Uses nucleus sampling to filter documents.
+
+`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. | +| **Mandatory run variables** | `text`: The text to be routed to one of the specified outputs based on which label it has been categorized into | +| **Output variables** | `documents`: A dictionary with the label as key and the text as value | +| **API reference** | [Routers](/reference/routers-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/routers/zero_shot_text_router.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [Ranker](../rankers.mdx) |
+| **Mandatory init variables** | `top_p`: A float between 0 and 1 representing the cumulative probability threshold for document selection |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Samplers](/reference/samplers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/samplers/top_p.py |
+
+
+
+## Overview
+
+Top-P (nucleus) sampling is a method that helps identify and select a subset of documents based on their cumulative probabilities. Instead of choosing a fixed number of documents, this method focuses on a specified percentage of the highest cumulative probabilities within a list of documents. To put it simply, `TopPSampler` provides a way to efficiently select the most relevant documents based on their similarity to a given query.
+
+The practical goal of the `TopPSampler` is to return a list of documents that, in sum, have a score larger than the `top_p` value. So, for example, when `top_p` is set to a high value, more documents will be returned, which can result in more varied outputs. The value is typically set between 0 and 1. By default, the component uses documents' `score` fields to look at the similarity scores.
+
+The component’s `run()` method takes in a set of documents, calculates the similarity scores between the query and the documents, and then filters the documents based on the cumulative probability of these scores.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.samplers import TopPSampler
+
+sampler = TopPSampler(top_p=0.99, score_field="similarity_score")
+docs = [
+ Document(content="Berlin", meta={"similarity_score": -10.6}),
+ Document(content="Belgrade", meta={"similarity_score": -8.9}),
+ Document(content="Sarajevo", meta={"similarity_score": -4.6}),
+]
+output = sampler.run(documents=docs)
+docs = output["documents"]
+print(docs)
+```
+
+### In a pipeline
+
+To best understand how can you use a `TopPSampler` and which components to pair it with, explore the following example.
+
+```python
+# import necessary dependencies
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.fetchers import LinkContentFetcher
+from haystack.components.converters import HTMLToDocument
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.preprocessors import DocumentSplitter
+from haystack.components.rankers import SentenceTransformersSimilarityRanker
+from haystack.components.routers.file_type_router import FileTypeRouter
+from haystack.components.samplers import TopPSampler
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.utils import Secret
+from haystack.dataclasses import ChatMessage
+
+# initialize the components
+web_search = SerperDevWebSearch(
+ api_key=Secret.from_token("
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a Chat Generator |
+| **Mandatory init variables** | `tools`: A list of [`Tools`](../../tools/tool.mdx) that can be invoked |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects from a Chat Generator containing tool calls |
+| **Output variables** | `tool_messages`: A list of `ChatMessage` objects with tool role. Each `ChatMessage` objects wraps the result of a tool invocation. |
+| **API reference** | [Tools](/reference/tools-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/tools/tool_invoker.py |
+
+
+
+## Overview
+
+A `ToolInvoker` is a component that processes `ChatMessage` objects containing tool calls. It invokes the corresponding tools and returns the results as a list of `ChatMessage` objects. Each tool is defined with a name, description, parameters, and a function that performs the task. The `ToolInvoker` manages these tools and handles the invocation process.
+
+You can pass multiple tools to the `ToolInvoker` component, and it will automatically choose the right tool to call based on tool calls produced by a Language Model.
+
+The `ToolInvoker` has two additionally helpful parameters:
+
+- `convert_result_to_json_string`: Use `json.dumps` (when True) or `str` (when False) to convert the result into a string.
+- `raise_on_failure`: If True, it will raise an exception in case of errors. If False, it will return a `ChatMessage` object with `error=True` and a description of the error in `result`. Use this, for example, when you want to keep the Language Model running in a loop and fixing its errors.
+
+:::info ChatMessage and Tool Data Classes
+
+Follow the links to learn more about [ChatMessage](../../concepts/data-classes/chatmessage.mdx) and [Tool](../../tools/tool.mdx) data classes.
+:::
+
+## Usage
+
+### On its own
+
+```python
+from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.components.tools import ToolInvoker
+from haystack.tools import Tool
+
+## Tool definition
+def dummy_weather_function(city: str):
+ return f"The weather in {city} is 20 degrees."
+parameters = {"type": "object",
+ "properties": {"city": {"type": "string"}},
+ "required": ["city"]}
+tool = Tool(name="weather_tool",
+ description="A tool to get the weather",
+ function=dummy_weather_function,
+ parameters=parameters)
+
+## Usually, the ChatMessage with tool_calls is generated by a Language Model
+## Here, we create it manually for demonstration purposes
+tool_call = ToolCall(
+ tool_name="weather_tool",
+ arguments={"city": "Berlin"}
+)
+message = ChatMessage.from_assistant(tool_calls=[tool_call])
+
+## ToolInvoker initialization and run
+invoker = ToolInvoker(tools=[tool])
+result = invoker.run(messages=[message])
+
+print(result)
+```
+
+```
+>> {
+>> 'tool_messages': [
+>> ChatMessage(
+>> _role=
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | After a [Generator](../generators.mdx) |
+| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) instances to be validated – the last message in this list is the one that is validated |
+| **Output variables** | `validated`: A list of messages if the last message is valid
`validation_error`: A list of messages if the last message is invalid | +| **API reference** | [Validators](/reference/validators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/validators/json_schema.py | + +
+
+## Overview
+
+`JsonSchemaValidator` checks the JSON content of a `ChatMessage` against a given [JSON Schema](https://json-schema.org/). If a message's JSON content follows the provided schema, it's moved to the `validated` output. If not, it's moved to the `validation_error`output. When there's an error, the component uses either the provided custom `error_template` or a default template to create the error message. These error `ChatMessages` can be used in Haystack recovery loops.
+
+## Usage
+
+### In a pipeline
+
+In this simple pipeline, the `MessageProducer` sends a list of chat messages to a Generator through `BranchJoiner`. The resulting messages from the Generator are sent to `JsonSchemaValidator`, and the error `ChatMessages` are sent back to `BranchJoiner` for a recovery loop.
+
+```python
+from typing import List
+
+from haystack import Pipeline
+from haystack import component
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.joiners import BranchJoiner
+from haystack.components.validators import JsonSchemaValidator
+from haystack.dataclasses import ChatMessage
+
+@component
+class MessageProducer:
+
+ @component.output_types(messages=List[ChatMessage])
+ def run(self, messages: List[ChatMessage]) -> dict:
+ return {"messages": messages}
+
+p = Pipeline()
+p.add_component("llm", OpenAIChatGenerator(model="gpt-4-1106-preview",
+ generation_kwargs={"response_format": {"type": "json_object"}}))
+p.add_component("schema_validator", JsonSchemaValidator())
+p.add_component("branch_joiner", BranchJoiner(List[ChatMessage]))
+p.add_component("message_producer", MessageProducer())
+
+p.connect("message_producer.messages", "branch_joiner")
+p.connect("branch_joiner", "llm")
+p.connect("llm.replies", "schema_validator.messages")
+p.connect("schema_validator.validation_error", "branch_joiner")
+
+result = p.run(
+ data={"message_producer": {
+ "messages": [ChatMessage.from_user("Generate JSON for person with name 'John' and age 30")]},
+ "schema_validator": {"json_schema": {"type": "object",
+ "properties": {"name": {"type": "string"},
+ "age": {"type": "integer"}}}}})
+print(result)
+
+>> {'schema_validator': {'validated': [ChatMessage(_role=`validation_error`: A list of messages if the last message is invalid | +| **API reference** | [Validators](/reference/validators-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/validators/json_schema.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [`LinkContentFetcher`](../fetchers/linkcontentfetcher.mdx) or [Converters](../converters.mdx) |
+| **Mandatory init variables** | `api_key`: The SearchAPI API key. Can be set with `SEARCHAPI_API_KEY` env var. |
+| **Mandatory run variables** | `query`: A string with your query |
+| **Output variables** | `documents`: A list of documents
`links`: A list of strings of resulting links | +| **API reference** | [Websearch](/reference/websearch-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/websearch/searchapi.py | + +
+
+## Overview
+
+When you give `SearchApiWebSearch` a query, it returns a list of the URLs most relevant to your search. It uses page snippets (pieces of text displayed under the page title in search results) to find the answers, not the whole pages.
+
+To search the content of the web pages, use the [`LinkContentFetcher`](../fetchers/linkcontentfetcher.mdx) component.
+
+`SearchApiWebSearch` requires a [SearchApi](https://www.searchapi.io) key to work. It uses a `SEARCHAPI_API_KEY` environment variable by default. Otherwise, you can pass an `api_key` at initialization – see code examples below.
+
+:::info Alternative search
+
+To use [Serper Dev](https://serper.dev/?gclid=Cj0KCQiAgqGrBhDtARIsAM5s0_kPElllv3M59UPok1Ad-ZNudLaY21zDvbt5qw-b78OcUoqqvplVHRwaAgRgEALw_wcB) as an alternative, see its respective [documentation page](serperdevwebsearch.mdx).
+:::
+
+## Usage
+
+### On its own
+
+This is an example of how `SearchApiWebSearch` looks up answers to our query on the web and converts the results into a list of documents with content snippets of the results, as well as URLs as strings.
+
+```python
+from haystack.components.websearch import SearchApiWebSearch
+
+web_search = SearchApiWebSearch(api_key=Secret.from_token("`links`: A list of strings of resulting links | +| **API reference** | [Websearch](/reference/websearch-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/websearch/searchapi.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | Before [`LinkContentFetcher`](../fetchers/linkcontentfetcher.mdx) or [Converters](../converters.mdx) |
+| **Mandatory init variables** | `api_key`: The SearchAPI API key. Can be set with `SERPERDEV_API_KEY` env var. |
+| **Mandatory run variables** | `query`: A string with your query |
+| **Output variables** | `documents`: A list of documents
`links`: A list of strings of resulting links | +| **API reference** | [Websearch](/reference/websearch-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/websearch/serper_dev.py | + +
+
+## Overview
+
+When you give `SerperDevWebSearch` a query, it returns a list of the URLs most relevant to your search. It uses page snippets (pieces of text displayed under the page title in search results) to find the answers, not the whole pages.
+
+To search the content of the web pages, use the [`LinkContentFetcher`](../fetchers/linkcontentfetcher.mdx) component.
+
+`SerperDevWebSearch` requires a [SerperDev](https://serper.dev/) key to work. It uses a `SERPERDEV_API_KEY` environment variable by default. Otherwise, you can pass an `api_key` at initialization – see code examples below.
+
+:::info Alternative search
+
+To use [Search API](https://www.searchapi.io/) as an alternative, see its respective [documentation page](searchapiwebsearch.mdx).
+:::
+
+## Usage
+
+### On its own
+
+This is an example of how `SerperDevWebSearch` looks up answers to our query on the web and converts the results into a list of documents with content snippets of the results, as well as URLs as strings.
+
+```python
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.utils import Secret
+
+web_search = SerperDevWebSearch(api_key=Secret.from_token("`links`: A list of strings of resulting links | +| **API reference** | [Websearch](/reference/websearch-api) | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/websearch/serper_dev.py | + +
+
+| | |
+| --- | --- |
+| **Most common position in a pipeline** | As the last component in an indexing pipeline |
+| **Mandatory init variables** | `document_store`: A Document Store instance |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents_written`: The number of documents written (integer) |
+| **API reference** | [Document Writers](/reference/document-writers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/writers/document_writer.py |
+
+
+
+## Overview
+
+`DocumentWriter` writes a list of documents into a Document Store of your choice. It’s typically used in an indexing pipeline as the final step after preprocessing documents and creating their embeddings.
+
+To use this component with a specific file type, make sure you use the correct [Converter](../converters.mdx) before it. For example, to use `DocumentWriter` with Markdown files, use the `MarkdownToDocument` component before `DocumentWriter` in your indexing pipeline.
+
+### DuplicatePolicy
+
+The `DuplicatePolicy` is a class that defines the different options for handling documents with the same ID in a `DocumentStore`. It has four possible values:
+
+- **NONE**: The default policy that relies on Document Store settings.
+- **OVERWRITE**: Indicates that if a document with the same ID already exists in the `DocumentStore`, it should be overwritten with the new document.
+- **SKIP**: If a document with the same ID already exists, the new document will be skipped and not added to the `DocumentStore`.
+- **FAIL**: Raises an error if a document with the same ID already exists in the `DocumentStore`. It prevents duplicate documents from being added.
+
+## Usage
+
+### On its own
+
+Below is an example of how to write two documents into an `InMemoryDocumentStore`:
+
+```python
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.writers import DocumentWriter
+
+documents = [
+ Document(content="This is document 1"),
+ Document(content="This is document 2")
+]
+
+document_store = InMemoryDocumentStore()
+document_writer = DocumentWriter(document_store = document_store)
+document_writer.run(documents=documents)
+```
+
+### In a pipeline
+
+Below is an example of an indexing pipeline that first uses the `SentenceTransformersDocumentEmbedder` to create embeddings of documents and then use the `DocumentWriter` to write the documents to an `InMemoryDocumentStore`:
+
+```python
+from haystack.pipeline import Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+from haystack.components.writers import DocumentWriter
+
+documents = [
+ Document(content="This is document 1"),
+ Document(content="This is document 2")
+]
+
+document_store = InMemoryDocumentStore()
+embedder = SentenceTransformersDocumentEmbedder()
+document_writer = DocumentWriter(document_store = document_store, policy=DuplicatePolicy.NONE)
+
+indexing_pipeline = Pipeline()
+indexing_pipeline.add_component(instance=embedder, name="embedder")
+indexing_pipeline.add_component(instance=document_writer, name="writer")
+
+indexing_pipeline.connect("embedder", "writer")
+indexing_pipeline.run({"embedder": {"documents": documents}})
+```
diff --git a/docs-website/versioned_docs/version-2.20-unstable/tools/componenttool.mdx b/docs-website/versioned_docs/version-2.20-unstable/tools/componenttool.mdx
new file mode 100644
index 0000000000..28467cdf4a
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/tools/componenttool.mdx
@@ -0,0 +1,128 @@
+---
+title: "ComponentTool"
+id: componenttool
+slug: "/componenttool"
+description: "This wrapper allows using Haystack components to be used as tools by LLMs."
+---
+
+# ComponentTool
+
+This wrapper allows using Haystack components to be used as tools by LLMs.
+
+
+
+| | |
+| --- | --- |
+| **Mandatory init variables** | `component`: The Haystack component to wrap |
+| **API reference** | [Tools](/reference/tools-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/tools/component_tool.py |
+
+
+
+## Overview
+
+`ComponentTool` is a Tool that wraps Haystack components, allowing them to be used as tools by LLMs. ComponentTool automatically generates LLM-compatible tool schemas from component input sockets, which are derived from the component's `run` method signature and type hints.
+
+It does input type conversion and offers support for components with run methods that have the following input types:
+
+- Basic types (str, int, float, bool, dict)
+- Dataclasses (both simple and nested structures)
+- Lists of basic types (such as List[str])
+- Lists of dataclasses (such as List[Document])
+- Parameters with mixed types (such as List[Document], str...)
+
+### Parameters
+
+- `component` is mandatory and needs to be a Haystack component, either an existing one or a custom component.
+- `name` is optional and defaults to the name of the component written in snake case, for example, "serper_dev_web_search" for SerperDevWebSearch.
+- `description` is optional and defaults to the component’s docstring. It’s the description that explains to the LLM what the tool can be used for.
+
+## Usage
+
+Install the additional dependencies `docstring-parser` and `jsonschema` package to use the `ComponentTool`:
+
+```shell
+pip install docstring-parser jsonschema
+```
+
+### In a pipeline
+
+You can create a `ComponentTool` from an existing `SerperDevWebSearch` component and let an `OpenAIChatGenerator` use it as a tool in a pipeline.
+
+```python
+from haystack import component, Pipeline
+from haystack.tools import ComponentTool
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.utils import Secret
+from haystack.components.tools.tool_invoker import ToolInvoker
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+## Create a SerperDev search component
+search = SerperDevWebSearch(api_key=Secret.from_env_var("SERPERDEV_API_KEY"), top_k=3)
+
+## Create a tool from the component
+tool = ComponentTool(
+ component=search,
+ name="web_search", # Optional: defaults to "serper_dev_web_search"
+ description="Search the web for current information on any topic" # Optional: defaults to component docstring
+)
+
+## Create pipeline with OpenAIChatGenerator and ToolInvoker
+pipeline = Pipeline()
+pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini", tools=[tool]))
+pipeline.add_component("tool_invoker", ToolInvoker(tools=[tool]))
+
+## Connect components
+pipeline.connect("llm.replies", "tool_invoker.messages")
+
+message = ChatMessage.from_user("Use the web search tool to find information about Nikola Tesla")
+
+## Run pipeline
+result = pipeline.run({"llm": {"messages": [message]}})
+
+print(result)
+```
+
+### With the Agent Component
+
+You can use `ComponentTool` with the [Agent](../pipeline-components/agents-1/agent.mdx) component. Internally, the `Agent` component includes a `ToolInvoker` and the ChatGenerator of your choice to execute tool calls and process tool results.
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import ComponentTool
+from haystack.components.agents import Agent
+from haystack.components.websearch import SerperDevWebSearch
+from typing import List
+
+## Create a SerperDev search component
+search = SerperDevWebSearch(api_key=Secret.from_env_var("SERPERDEV_API_KEY"), top_k=3)
+
+## Create a tool from the component
+search_tool = ComponentTool(
+ component=search,
+ name="web_search", # Optional: defaults to "serper_dev_web_search"
+ description="Search the web for current information on any topic" # Optional: defaults to component docstring
+)
+
+## Agent Setup
+agent = Agent(
+ chat_generator=OpenAIChatGenerator(),
+ tools=[search_tool],
+ exit_conditions=["text"]
+)
+
+## Run the Agent
+agent.warm_up()
+response = agent.run(messages=[ChatMessage.from_user("Find information about Nikola Tesla")])
+
+## Output
+print(response["messages"][-1].text)
+```
+
+## Additional References
+
+🧑🍳 Cookbook: [Build a GitHub Issue Resolver Agent](https://haystack.deepset.ai/cookbook/github_issue_resolver_agent)
+
+📓 Tutorial: [Build a Tool-Calling Agent](https://haystack.deepset.ai/tutorials/43_building_a_tool_calling_agent)
diff --git a/docs-website/versioned_docs/version-2.20-unstable/tools/mcptool.mdx b/docs-website/versioned_docs/version-2.20-unstable/tools/mcptool.mdx
new file mode 100644
index 0000000000..c161ae1a89
--- /dev/null
+++ b/docs-website/versioned_docs/version-2.20-unstable/tools/mcptool.mdx
@@ -0,0 +1,169 @@
+---
+title: "MCPTool"
+id: mcptool
+slug: "/mcptool"
+description: "MCPTool enables integration with external tools and services through the Model Context Protocol (MCP)."
+---
+
+# MCPTool
+
+MCPTool enables integration with external tools and services through the Model Context Protocol (MCP).
+
+
+
+| | |
+| --- | --- |
+| **Mandatory init variables** | `name`: The name of the tool