Bump unstable version and create unstable docs (#11149)

Co-authored-by: davidsbatista <[email protected]>

VERSION.txt

@@ -1 +1 @@
-2.28.0-rc0
+2.29.0-rc0

docs-website/docusaurus.config.js

@@ -79,7 +79,7 @@ j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
           beforeDefaultRemarkPlugins: [require('./src/remark/versionedReferenceLinks')],
           versions: {
             current: {
-              label: '2.28-unstable',
+              label: '2.29-unstable',
               path: 'next',
               banner: 'unreleased',
             },
@@ -132,7 +132,7 @@ j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
         exclude: ['**/_templates/**'],
         versions: {
           current: {
-            label: '2.28-unstable',
+            label: '2.29-unstable',
             path: 'next',
             banner: 'unreleased',
           },

docs-website/reference_versioned_docs/version-2.28-unstable/experiments-api/experimental_agents_api.md

@@ -0,0 +1,475 @@
+---
+title: "Agents"
+id: experimental-agents-api
+description: "Tool-using agents with provider-agnostic chat model support."
+slug: "/experimental-agents-api"
+---
+
+<a id="haystack_experimental.components.agents.agent"></a>
+
+## Module haystack\_experimental.components.agents.agent
+
+<a id="haystack_experimental.components.agents.agent.Agent"></a>
+
+### Agent
+
+A Haystack component that implements a tool-using agent with provider-agnostic chat model support.
+
+NOTE: This class extends Haystack's Agent component to add support for human-in-the-loop confirmation strategies.
+
+The component processes messages and executes tools until an exit condition is met.
+The exit condition can be triggered either by a direct text response or by invoking a specific designated tool.
+Multiple exit conditions can be specified.
+
+When you call an Agent without tools, it acts as a ChatGenerator, produces one response, then exits.
+
+### Usage example
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools.tool import Tool
+
+from haystack_experimental.components.agents import Agent
+from haystack_experimental.components.agents.human_in_the_loop import (
+    HumanInTheLoopStrategy,
+    AlwaysAskPolicy,
+    NeverAskPolicy,
+    SimpleConsoleUI,
+)
+
+calculator_tool = Tool(name="calculator", description="A tool for performing mathematical calculations.", ...)
+search_tool = Tool(name="search", description="A tool for searching the web.", ...)
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(),
+    tools=[calculator_tool, search_tool],
+    confirmation_strategies={
+        calculator_tool.name: HumanInTheLoopStrategy(
+            confirmation_policy=NeverAskPolicy(), confirmation_ui=SimpleConsoleUI()
+        ),
+        search_tool.name: HumanInTheLoopStrategy(
+            confirmation_policy=AlwaysAskPolicy(), confirmation_ui=SimpleConsoleUI()
+        ),
+    },
+)
+
+# Run the agent
+result = agent.run(
+    messages=[ChatMessage.from_user("Find information about Haystack")]
+)
+
+assert "messages" in result  # Contains conversation history
+```
+
+<a id="haystack_experimental.components.agents.agent.Agent.__init__"></a>
+
+#### Agent.\_\_init\_\_
+
+```python
+def __init__(*,
+             chat_generator: ChatGenerator,
+             tools: ToolsType | None = None,
+             system_prompt: str | None = None,
+             exit_conditions: list[str] | None = None,
+             state_schema: dict[str, Any] | None = None,
+             max_agent_steps: int = 100,
+             streaming_callback: StreamingCallbackT | None = None,
+             raise_on_tool_invocation_failure: bool = False,
+             confirmation_strategies: dict[str, ConfirmationStrategy]
+             | None = None,
+             tool_invoker_kwargs: dict[str, Any] | None = None,
+             chat_message_store: ChatMessageStore | None = None,
+             memory_store: MemoryStore | None = None) -> None
+```
+
+Initialize the agent component.
+
+**Arguments**:
+
+- `chat_generator`: An instance of the chat generator that your agent should use. It must support tools.
+- `tools`: List of Tool objects or a Toolset that the agent can use.
+- `system_prompt`: System prompt for the agent.
+- `exit_conditions`: List of conditions that will cause the agent to return.
+Can include "text" if the agent should return when it generates a message without tool calls,
+or tool names that will cause the agent to return once the tool was executed. Defaults to ["text"].
+- `state_schema`: The schema for the runtime state used by the tools.
+- `max_agent_steps`: Maximum number of steps the agent will run before stopping. Defaults to 100.
+If the agent exceeds this number of steps, it will stop and return the current state.
+- `streaming_callback`: A callback that will be invoked when a response is streamed from the LLM.
+The same callback can be configured to emit tool results when a tool is called.
+- `raise_on_tool_invocation_failure`: Should the agent raise an exception when a tool invocation fails?
+If set to False, the exception will be turned into a chat message and passed to the LLM.
+- `tool_invoker_kwargs`: Additional keyword arguments to pass to the ToolInvoker.
+- `chat_message_store`: The ChatMessageStore that the agent can use to store
+and retrieve chat messages history.
+- `memory_store`: The memory store that the agent can use to store and retrieve memories.
+
+**Raises**:
+
+- `TypeError`: If the chat_generator does not support tools parameter in its run method.
+- `ValueError`: If the exit_conditions are not valid.
+
+<a id="haystack_experimental.components.agents.agent.Agent.run"></a>
+
+#### Agent.run
+
+```python
+def run(messages: list[ChatMessage],
+        streaming_callback: StreamingCallbackT | None = None,
+        *,
+        generation_kwargs: dict[str, Any] | None = None,
+        break_point: AgentBreakpoint | None = None,
+        snapshot: AgentSnapshot | None = None,
+        system_prompt: str | None = None,
+        tools: ToolsType | list[str] | None = None,
+        confirmation_strategy_context: dict[str, Any] | None = None,
+        chat_message_store_kwargs: dict[str, Any] | None = None,
+        memory_store_kwargs: dict[str, Any] | None = None,
+        **kwargs: Any) -> dict[str, Any]
+```
+
+Process messages and execute tools until an exit condition is met.
+
+**Arguments**:
+
+- `messages`: List of Haystack ChatMessage objects to process.
+- `streaming_callback`: A callback that will be invoked when a response is streamed from the LLM.
+The same callback can be configured to emit tool results when a tool is called.
+- `generation_kwargs`: Additional keyword arguments for LLM. These parameters will
+override the parameters passed during component initialization.
+- `break_point`: An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint
+for "tool_invoker".
+- `snapshot`: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains
+the relevant information to restart the Agent execution from where it left off.
+- `system_prompt`: System prompt for the agent. If provided, it overrides the default system prompt.
+- `tools`: Optional list of Tool objects, a Toolset, or list of tool names to use for this run.
+When passing tool names, tools are selected from the Agent's originally configured tools.
+- `confirmation_strategy_context`: Optional dictionary for passing request-scoped resources
+to confirmation strategies. Useful in web/server environments to provide per-request
+objects (e.g., WebSocket connections, async queues, Redis pub/sub clients) that strategies
+can use for non-blocking user interaction.
+- `chat_message_store_kwargs`: Optional dictionary of keyword arguments to pass to the ChatMessageStore.
+For example, it can include the `chat_history_id` and `last_k` parameters for retrieving chat history.
+- `memory_store_kwargs`: Optional dictionary of keyword arguments to pass to the MemoryStore.
+It can include:
+- `user_id`: The user ID to search and add memories from.
+- `run_id`: The run ID to search and add memories from.
+- `agent_id`: The agent ID to search and add memories from.
+- `search_criteria`: A dictionary of containing kwargs for the `search_memories` method.
+    This can include:
+    - `filters`: A dictionary of filters to search for memories.
+    - `query`: The query to search for memories.
+        Note: If you pass this, the user query passed to the agent will be
+        ignored for memory retrieval.
+    - `top_k`: The number of memories to return.
+    - `include_memory_metadata`: Whether to include the memory metadata in the ChatMessage.
+- `kwargs`: Additional data to pass to the State schema used by the Agent.
+The keys must match the schema defined in the Agent's `state_schema`.
+
+**Raises**:
+
+- `RuntimeError`: If the Agent component wasn't warmed up before calling `run()`.
+- `BreakpointException`: If an agent breakpoint is triggered.
+
+**Returns**:
+
+A dictionary with the following keys:
+- "messages": List of all messages exchanged during the agent's run.
+- "last_message": The last message exchanged during the agent's run.
+- Any additional keys defined in the `state_schema`.
+
+<a id="haystack_experimental.components.agents.agent.Agent.run_async"></a>
+
+#### Agent.run\_async
+
+```python
+async def run_async(messages: list[ChatMessage],
+                    streaming_callback: StreamingCallbackT | None = None,
+                    *,
+                    generation_kwargs: dict[str, Any] | None = None,
+                    break_point: AgentBreakpoint | None = None,
+                    snapshot: AgentSnapshot | None = None,
+                    system_prompt: str | None = None,
+                    tools: ToolsType | list[str] | None = None,
+                    confirmation_strategy_context: dict[str, Any]
+                    | None = None,
+                    chat_message_store_kwargs: dict[str, Any] | None = None,
+                    memory_store_kwargs: dict[str, Any] | None = None,
+                    **kwargs: Any) -> dict[str, Any]
+```
+
+Asynchronously process messages and execute tools until the exit condition is met.
+
+This is the asynchronous version of the `run` method. It follows the same logic but uses
+asynchronous operations where possible, such as calling the `run_async` method of the ChatGenerator
+if available.
+
+**Arguments**:
+
+- `messages`: List of Haystack ChatMessage objects to process.
+- `streaming_callback`: An asynchronous callback that will be invoked when a response is streamed from the
+LLM. The same callback can be configured to emit tool results when a tool is called.
+- `generation_kwargs`: Additional keyword arguments for LLM. These parameters will
+override the parameters passed during component initialization.
+- `break_point`: An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint
+for "tool_invoker".
+- `snapshot`: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains
+the relevant information to restart the Agent execution from where it left off.
+- `system_prompt`: System prompt for the agent. If provided, it overrides the default system prompt.
+- `tools`: Optional list of Tool objects, a Toolset, or list of tool names to use for this run.
+- `confirmation_strategy_context`: Optional dictionary for passing request-scoped resources
+to confirmation strategies. Useful in web/server environments to provide per-request
+objects (e.g., WebSocket connections, async queues, Redis pub/sub clients) that strategies
+can use for non-blocking user interaction.
+- `chat_message_store_kwargs`: Optional dictionary of keyword arguments to pass to the ChatMessageStore.
+For example, it can include the `chat_history_id` and `last_k` parameters for retrieving chat history.
+- `kwargs`: Additional data to pass to the State schema used by the Agent.
+- `memory_store_kwargs`: Optional dictionary of keyword arguments to pass to the MemoryStore.
+It can include:
+- `user_id`: The user ID to search and add memories from.
+- `run_id`: The run ID to search and add memories from.
+- `agent_id`: The agent ID to search and add memories from.
+- `search_criteria`: A dictionary of containing kwargs for the `search_memories` method.
+    This can include:
+    - `filters`: A dictionary of filters to search for memories.
+    - `query`: The query to search for memories.
+        Note: If you pass this, the user query passed to the agent will be
+        ignored for memory retrieval.
+    - `top_k`: The number of memories to return.
+    - `include_memory_metadata`: Whether to include the memory metadata in the ChatMessage.
+- `kwargs`: Additional data to pass to the State schema used by the Agent.
+The keys must match the schema defined in the Agent's `state_schema`.
+
+**Raises**:
+
+- `RuntimeError`: If the Agent component wasn't warmed up before calling `run_async()`.
+- `BreakpointException`: If an agent breakpoint is triggered.
+
+**Returns**:
+
+A dictionary with the following keys:
+- "messages": List of all messages exchanged during the agent's run.
+- "last_message": The last message exchanged during the agent's run.
+- Any additional keys defined in the `state_schema`.
+
+<a id="haystack_experimental.components.agents.agent.Agent.to_dict"></a>
+
+#### Agent.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data
+
+<a id="haystack_experimental.components.agents.agent.Agent.from_dict"></a>
+
+#### Agent.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "Agent"
+```
+
+Deserialize the agent from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from
+
+**Returns**:
+
+Deserialized agent
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.breakpoint"></a>
+
+## Module haystack\_experimental.components.agents.human\_in\_the\_loop.breakpoint
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.breakpoint.get_tool_calls_and_descriptions_from_snapshot"></a>
+
+#### get\_tool\_calls\_and\_descriptions\_from\_snapshot
+
+```python
+def get_tool_calls_and_descriptions_from_snapshot(
+        agent_snapshot: AgentSnapshot,
+        breakpoint_tool_only: bool = True
+) -> tuple[list[dict], dict[str, str]]
+```
+
+Extract tool calls and tool descriptions from an AgentSnapshot.
+
+By default, only the tool call that caused the breakpoint is processed and its arguments are reconstructed.
+This is useful for scenarios where you want to present the relevant tool call and its description
+to a human for confirmation before execution.
+
+**Arguments**:
+
+- `agent_snapshot`: The AgentSnapshot from which to extract tool calls and descriptions.
+- `breakpoint_tool_only`: If True, only the tool call that caused the breakpoint is returned. If False, all tool
+calls are returned.
+
+**Returns**:
+
+A tuple containing a list of tool call dictionaries and a dictionary of tool descriptions
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.errors"></a>
+
+## Module haystack\_experimental.components.agents.human\_in\_the\_loop.errors
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.errors.HITLBreakpointException"></a>
+
+### HITLBreakpointException
+
+Exception raised when a tool execution is paused by a ConfirmationStrategy (e.g. BreakpointConfirmationStrategy).
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.errors.HITLBreakpointException.__init__"></a>
+
+#### HITLBreakpointException.\_\_init\_\_
+
+```python
+def __init__(message: str,
+             tool_name: str,
+             snapshot_file_path: str,
+             tool_call_id: str | None = None) -> None
+```
+
+Initialize the HITLBreakpointException.
+
+**Arguments**:
+
+- `message`: The exception message.
+- `tool_name`: The name of the tool whose execution is paused.
+- `snapshot_file_path`: The file path to the saved pipeline snapshot.
+- `tool_call_id`: Optional unique identifier for the tool call. This can be used to track and correlate
+the decision with a specific tool invocation.
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.strategies"></a>
+
+## Module haystack\_experimental.components.agents.human\_in\_the\_loop.strategies
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy"></a>
+
+### BreakpointConfirmationStrategy
+
+Confirmation strategy that raises a tool breakpoint exception to pause execution and gather user feedback.
+
+This strategy is designed for scenarios where immediate user interaction is not possible.
+When a tool execution requires confirmation, it raises an `HITLBreakpointException`, which is caught by the Agent.
+The Agent then serialize its current state, including the tool call details. This information can then be used to
+notify a user to review and confirm the tool execution.
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy.__init__"></a>
+
+#### BreakpointConfirmationStrategy.\_\_init\_\_
+
+```python
+def __init__(snapshot_file_path: str) -> None
+```
+
+Initialize the BreakpointConfirmationStrategy.
+
+**Arguments**:
+
+- `snapshot_file_path`: The path to the directory that the snapshot should be saved.
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy.run"></a>
+
+#### BreakpointConfirmationStrategy.run
+
+```python
+def run(
+    *,
+    tool_name: str,
+    tool_description: str,
+    tool_params: dict[str, Any],
+    tool_call_id: str | None = None,
+    confirmation_strategy_context: dict[str, Any] | None = None
+) -> ToolExecutionDecision
+```
+
+Run the breakpoint confirmation strategy for a given tool and its parameters.
+
+**Arguments**:
+
+- `tool_name`: The name of the tool to be executed.
+- `tool_description`: The description of the tool.
+- `tool_params`: The parameters to be passed to the tool.
+- `tool_call_id`: Optional unique identifier for the tool call. This can be used to track and correlate the decision with a
+specific tool invocation.
+- `confirmation_strategy_context`: Optional dictionary for passing request-scoped resources. Not used by this strategy but included for
+interface compatibility.
+
+**Raises**:
+
+- `HITLBreakpointException`: Always raises an `HITLBreakpointException` exception to signal that user confirmation is required.
+
+**Returns**:
+
+This method does not return; it always raises an exception.
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy.run_async"></a>
+
+#### BreakpointConfirmationStrategy.run\_async
+
+```python
+async def run_async(
+    *,
+    tool_name: str,
+    tool_description: str,
+    tool_params: dict[str, Any],
+    tool_call_id: str | None = None,
+    confirmation_strategy_context: dict[str, Any] | None = None
+) -> ToolExecutionDecision
+```
+
+Async version of run. Calls the sync run() method.
+
+**Arguments**:
+
+- `tool_name`: The name of the tool to be executed.
+- `tool_description`: The description of the tool.
+- `tool_params`: The parameters to be passed to the tool.
+- `tool_call_id`: Optional unique identifier for the tool call.
+- `confirmation_strategy_context`: Optional dictionary for passing request-scoped resources.
+
+**Raises**:
+
+- `HITLBreakpointException`: Always raises an `HITLBreakpointException` exception to signal that user confirmation is required.
+
+**Returns**:
+
+This method does not return; it always raises an exception.
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy.to_dict"></a>
+
+#### BreakpointConfirmationStrategy.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the BreakpointConfirmationStrategy to a dictionary.
+
+<a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy.from_dict"></a>
+
+#### BreakpointConfirmationStrategy.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "BreakpointConfirmationStrategy"
+```
+
+Deserializes the BreakpointConfirmationStrategy from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized BreakpointConfirmationStrategy.
+

docs-website/reference_versioned_docs/version-2.28-unstable/experiments-api/experimental_chatmessage_store_api.md

@@ -0,0 +1,181 @@
+---
+title: "ChatMessage Store"
+id: experimental-chatmessage-store-api
+description: "Storage for the chat messages."
+slug: "/experimental-chatmessage-store-api"
+---
+
+<a id="haystack_experimental.chat_message_stores.in_memory"></a>
+
+## Module haystack\_experimental.chat\_message\_stores.in\_memory
+
+<a id="haystack_experimental.chat_message_stores.in_memory.InMemoryChatMessageStore"></a>
+
+### InMemoryChatMessageStore
+
+Stores chat messages in-memory.
+
+The `chat_history_id` parameter is used as a unique identifier for each conversation or chat session.
+It acts as a namespace that isolates messages from different sessions. Each `chat_history_id` value corresponds to a
+separate list of `ChatMessage` objects stored in memory.
+
+Typical usage involves providing a unique `chat_history_id` (for example, a session ID or conversation ID)
+whenever you write, read, or delete messages. This ensures that chat messages from different
+conversations do not overlap.
+
+Usage example:
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_experimental.chat_message_stores.in_memory import InMemoryChatMessageStore
+
+message_store = InMemoryChatMessageStore()
+
+messages = [
+    ChatMessage.from_assistant("Hello, how can I help you?"),
+    ChatMessage.from_user("Hi, I have a question about Python. What is a Protocol?"),
+]
+message_store.write_messages(chat_history_id="user_456_session_123", messages=messages)
+retrieved_messages = message_store.retrieve_messages(chat_history_id="user_456_session_123")
+
+print(retrieved_messages)
+```
+
+<a id="haystack_experimental.chat_message_stores.in_memory.InMemoryChatMessageStore.__init__"></a>
+
+#### InMemoryChatMessageStore.\_\_init\_\_
+
+```python
+def __init__(skip_system_messages: bool = True,
+             last_k: int | None = 10) -> None
+```
+
+Create an InMemoryChatMessageStore.
+
+**Arguments**:
+
+- `skip_system_messages`: Whether to skip storing system messages. Defaults to True.
+- `last_k`: The number of last messages to retrieve. Defaults to 10 messages if not specified.
+
+<a id="haystack_experimental.chat_message_stores.in_memory.InMemoryChatMessageStore.to_dict"></a>
+
+#### InMemoryChatMessageStore.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_experimental.chat_message_stores.in_memory.InMemoryChatMessageStore.from_dict"></a>
+
+#### InMemoryChatMessageStore.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "InMemoryChatMessageStore"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="haystack_experimental.chat_message_stores.in_memory.InMemoryChatMessageStore.count_messages"></a>
+
+#### InMemoryChatMessageStore.count\_messages
+
+```python
+def count_messages(chat_history_id: str) -> int
+```
+
+Returns the number of chat messages stored in this store.
+
+**Arguments**:
+
+- `chat_history_id`: The chat history id for which to count messages.
+
+**Returns**:
+
+The number of messages.
+
+<a id="haystack_experimental.chat_message_stores.in_memory.InMemoryChatMessageStore.write_messages"></a>
+
+#### InMemoryChatMessageStore.write\_messages
+
+```python
+def write_messages(chat_history_id: str, messages: list[ChatMessage]) -> int
+```
+
+Writes chat messages to the ChatMessageStore.
+
+**Arguments**:
+
+- `chat_history_id`: The chat history id under which to store the messages.
+- `messages`: A list of ChatMessages to write.
+
+**Raises**:
+
+- `ValueError`: If messages is not a list of ChatMessages.
+
+**Returns**:
+
+The number of messages written.
+
+<a id="haystack_experimental.chat_message_stores.in_memory.InMemoryChatMessageStore.retrieve_messages"></a>
+
+#### InMemoryChatMessageStore.retrieve\_messages
+
+```python
+def retrieve_messages(chat_history_id: str,
+                      last_k: int | None = None) -> list[ChatMessage]
+```
+
+Retrieves all stored chat messages.
+
+**Arguments**:
+
+- `chat_history_id`: The chat history id from which to retrieve messages.
+- `last_k`: The number of last messages to retrieve. If unspecified, the last_k parameter passed
+to the constructor will be used.
+
+**Raises**:
+
+- `ValueError`: If last_k is not None and is less than 0.
+
+**Returns**:
+
+A list of chat messages.
+
+<a id="haystack_experimental.chat_message_stores.in_memory.InMemoryChatMessageStore.delete_messages"></a>
+
+#### InMemoryChatMessageStore.delete\_messages
+
+```python
+def delete_messages(chat_history_id: str) -> None
+```
+
+Deletes all stored chat messages.
+
+**Arguments**:
+
+- `chat_history_id`: The chat history id from which to delete messages.
+
+<a id="haystack_experimental.chat_message_stores.in_memory.InMemoryChatMessageStore.delete_all_messages"></a>
+
+#### InMemoryChatMessageStore.delete\_all\_messages
+
+```python
+def delete_all_messages() -> None
+```
+
+Deletes all stored chat messages from all chat history ids.
+

docs-website/reference_versioned_docs/version-2.28-unstable/experiments-api/experimental_generators_api.md

@@ -0,0 +1,152 @@
+---
+title: "Generators"
+id: experimental-generators-api
+description: "Enables text generation using LLMs."
+slug: "/experimental-generators-api"
+---
+
+<a id="haystack_experimental.components.generators.chat.openai"></a>
+
+## Module haystack\_experimental.components.generators.chat.openai
+
+<a id="haystack_experimental.components.generators.chat.openai.OpenAIChatGenerator"></a>
+
+### OpenAIChatGenerator
+
+An OpenAI chat-based text generator component that supports hallucination risk scoring.
+
+This is based on the paper
+[LLMs are Bayesian, in Expectation, not in Realization](https://arxiv.org/abs/2507.11768).
+
+## Usage Example:
+
+    ```python
+    from haystack.dataclasses import ChatMessage
+
+    from haystack_experimental.utils.hallucination_risk_calculator.dataclasses import HallucinationScoreConfig
+    from haystack_experimental.components.generators.chat.openai import OpenAIChatGenerator
+
+    # Evidence-based Example
+    llm = OpenAIChatGenerator(model="gpt-4o")
+    rag_result = llm.run(
+        messages=[
+            ChatMessage.from_user(
+                text="Task: Answer strictly based on the evidence provided below.
+"
+                "Question: Who won the Nobel Prize in Physics in 2019?
+"
+                "Evidence:
+"
+                "- Nobel Prize press release (2019): James Peebles (1/2); Michel Mayor & Didier Queloz (1/2).
+"
+                "Constraints: If evidence is insufficient or conflicting, refuse."
+            )
+        ],
+        hallucination_score_config=HallucinationScoreConfig(skeleton_policy="evidence_erase"),
+    )
+    print(f"Decision: {rag_result['replies'][0].meta['hallucination_decision']}")
+    print(f"Risk bound: {rag_result['replies'][0].meta['hallucination_risk']:.3f}")
+    print(f"Rationale: {rag_result['replies'][0].meta['hallucination_rationale']}")
+    print(f"Answer:
+{rag_result['replies'][0].text}")
+    print("---")
+    ```
+
+<a id="haystack_experimental.components.generators.chat.openai.OpenAIChatGenerator.run"></a>
+
+#### OpenAIChatGenerator.run
+
+```python
+@component.output_types(replies=list[ChatMessage])
+def run(
+    messages: list[ChatMessage],
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    tools: ToolsType | None = None,
+    tools_strict: bool | None = None,
+    hallucination_score_config: HallucinationScoreConfig | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Invokes chat completion based on the provided messages and generation parameters.
+
+**Arguments**:
+
+- `messages`: A list of ChatMessage instances representing the input messages.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will
+override the parameters passed during component initialization.
+For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create).
+- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+If set, it will override the `tools` parameter provided during initialization.
+- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly
+the schema provided in the `parameters` field of the tool definition, but this may increase latency.
+If set, it will override the `tools_strict` parameter set during component initialization.
+- `hallucination_score_config`: If provided, the generator will evaluate the hallucination risk of its responses using
+the OpenAIPlanner and annotate each response with hallucination metrics.
+This involves generating multiple samples and analyzing their consistency, which may increase
+latency and cost. Use this option when you need to assess the reliability of the generated content
+in scenarios where accuracy is critical.
+For details, see the [research paper](https://arxiv.org/abs/2507.11768)
+
+**Returns**:
+
+A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances. If hallucination
+scoring is enabled, each message will include additional metadata:
+  - `hallucination_decision`: "ANSWER" if the model decided to answer, "REFUSE" if it abstained.
+  - `hallucination_risk`: The EDFL hallucination risk bound.
+  - `hallucination_rationale`: The rationale behind the hallucination decision.
+
+<a id="haystack_experimental.components.generators.chat.openai.OpenAIChatGenerator.run_async"></a>
+
+#### OpenAIChatGenerator.run\_async
+
+```python
+@component.output_types(replies=list[ChatMessage])
+async def run_async(
+    messages: list[ChatMessage],
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    tools: ToolsType | None = None,
+    tools_strict: bool | None = None,
+    hallucination_score_config: HallucinationScoreConfig | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Asynchronously invokes chat completion based on the provided messages and generation parameters.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Arguments**:
+
+- `messages`: A list of ChatMessage instances representing the input messages.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+Must be a coroutine.
+- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will
+override the parameters passed during component initialization.
+For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create).
+- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+If set, it will override the `tools` parameter provided during initialization.
+- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly
+the schema provided in the `parameters` field of the tool definition, but this may increase latency.
+If set, it will override the `tools_strict` parameter set during component initialization.
+- `hallucination_score_config`: If provided, the generator will evaluate the hallucination risk of its responses using
+the OpenAIPlanner and annotate each response with hallucination metrics.
+This involves generating multiple samples and analyzing their consistency, which may increase
+latency and cost. Use this option when you need to assess the reliability of the generated content
+in scenarios where accuracy is critical.
+For details, see the [research paper](https://arxiv.org/abs/2507.11768)
+
+**Returns**:
+
+A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances. If hallucination
+scoring is enabled, each message will include additional metadata:
+  - `hallucination_decision`: "ANSWER" if the model decided to answer, "REFUSE" if it abstained.
+  - `hallucination_risk`: The EDFL hallucination risk bound.
+  - `hallucination_rationale`: The rationale behind the hallucination decision.
+

docs-website/reference_versioned_docs/version-2.28-unstable/experiments-api/experimental_mem0_memory_store_api.md

@@ -0,0 +1,218 @@
+---
+title: "Mem0 Memory Store"
+id: experimental-mem0-memory-store-api
+description: "Storage for the memories using Mem0 as the backend."
+slug: "/experimental-mem0-memory-store-api"
+---
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store"></a>
+
+## Module haystack\_experimental.memory\_stores.mem0.memory\_store
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore"></a>
+
+### Mem0MemoryStore
+
+A memory store implementation using Mem0 as the backend.
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore.__init__"></a>
+
+#### Mem0MemoryStore.\_\_init\_\_
+
+```python
+def __init__(*, api_key: Secret = Secret.from_env_var("MEM0_API_KEY"))
+```
+
+Initialize the Mem0 memory store.
+
+**Arguments**:
+
+- `api_key`: The Mem0 API key. You can also set it using `MEM0_API_KEY` environment variable.
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore.to_dict"></a>
+
+#### Mem0MemoryStore.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the store configuration to a dictionary.
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore.from_dict"></a>
+
+#### Mem0MemoryStore.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "Mem0MemoryStore"
+```
+
+Deserialize the store from a dictionary.
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore.add_memories"></a>
+
+#### Mem0MemoryStore.add\_memories
+
+```python
+def add_memories(*,
+                 messages: list[ChatMessage],
+                 infer: bool = True,
+                 user_id: str | None = None,
+                 run_id: str | None = None,
+                 agent_id: str | None = None,
+                 async_mode: bool = False,
+                 **kwargs: Any) -> list[dict[str, Any]]
+```
+
+Add ChatMessage memories to Mem0.
+
+**Arguments**:
+
+- `messages`: List of ChatMessage objects with memory metadata
+- `infer`: Whether to infer facts from the messages. If False, the whole message will
+be added as a memory.
+- `user_id`: The user ID to to store and retrieve memories from the memory store.
+- `run_id`: The run ID to to store and retrieve memories from the memory store.
+- `agent_id`: The agent ID to to store and retrieve memories from the memory store.
+If you want Mem0 to store chat messages from the assistant, you need to set the agent_id.
+- `async_mode`: Whether to add memories asynchronously.
+If True, the method will return immediately and the memories will be added in the background.
+- `kwargs`: Additional keyword arguments to pass to the Mem0 client.add method.
+Note: ChatMessage.meta in the list of messages will be ignored because Mem0 doesn't allow
+passing metadata for each message in the list. You can pass metadata for the whole memory
+by passing the `metadata` keyword argument to the method.
+
+**Returns**:
+
+List of objects with the memory_id and the memory
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore.search_memories"></a>
+
+#### Mem0MemoryStore.search\_memories
+
+```python
+def search_memories(*,
+                    query: str | None = None,
+                    filters: dict[str, Any] | None = None,
+                    top_k: int = 5,
+                    user_id: str | None = None,
+                    run_id: str | None = None,
+                    agent_id: str | None = None,
+                    include_memory_metadata: bool = False,
+                    **kwargs: Any) -> list[ChatMessage]
+```
+
+Search for memories in Mem0.
+
+If filters are not provided, at least one of user_id, run_id, or agent_id must be set.
+If filters are provided, the search will be scoped to the provided filters and the other ids will be ignored.
+
+**Arguments**:
+
+- `query`: Text query to search for. If not provided, all memories will be returned.
+- `filters`: Haystack filters to apply on search. For more details on Haystack filters, see https://docs.haystack.deepset.ai/docs/metadata-filtering
+- `top_k`: Maximum number of results to return
+- `user_id`: The user ID to to store and retrieve memories from the memory store.
+- `run_id`: The run ID to to store and retrieve memories from the memory store.
+- `agent_id`: The agent ID to to store and retrieve memories from the memory store.
+If you want Mem0 to store chat messages from the assistant, you need to set the agent_id.
+- `include_memory_metadata`: Whether to include the mem0 related metadata for the
+retrieved memory in the ChatMessage.
+If True, the metadata will include the mem0 related metadata i.e. memory_id, score, etc.
+in the `mem0_memory_metadata` key.
+If False, the `ChatMessage.meta` will only contain the user defined metadata.
+- `kwargs`: Additional keyword arguments to pass to the Mem0 client.
+If query is passed, the kwargs will be passed to the Mem0 client.search method.
+If query is not passed, the kwargs will be passed to the Mem0 client.get_all method.
+
+**Returns**:
+
+List of ChatMessage memories matching the criteria
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore.search_memories_as_single_message"></a>
+
+#### Mem0MemoryStore.search\_memories\_as\_single\_message
+
+```python
+def search_memories_as_single_message(*,
+                                      query: str | None = None,
+                                      filters: dict[str, Any] | None = None,
+                                      top_k: int = 5,
+                                      user_id: str | None = None,
+                                      run_id: str | None = None,
+                                      agent_id: str | None = None,
+                                      **kwargs: Any) -> ChatMessage
+```
+
+Search for memories in Mem0 and return a single ChatMessage object.
+
+If filters are not provided, at least one of user_id, run_id, or agent_id must be set.
+If filters are provided, the search will be scoped to the provided filters and the other ids will be ignored.
+
+**Arguments**:
+
+- `query`: Text query to search for. If not provided, all memories will be returned.
+- `filters`: Additional filters to apply on search. For more details on mem0 filters, see https://mem0.ai/docs/search/
+- `top_k`: Maximum number of results to return
+- `user_id`: The user ID to to store and retrieve memories from the memory store.
+- `run_id`: The run ID to to store and retrieve memories from the memory store.
+- `agent_id`: The agent ID to to store and retrieve memories from the memory store.
+If you want Mem0 to store chat messages from the assistant, you need to set the agent_id.
+- `kwargs`: Additional keyword arguments to pass to the Mem0 client.
+If query is passed, the kwargs will be passed to the Mem0 client.search method.
+If query is not passed, the kwargs will be passed to the Mem0 client.get_all method.
+
+**Returns**:
+
+A single ChatMessage object with the memories matching the criteria
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore.delete_all_memories"></a>
+
+#### Mem0MemoryStore.delete\_all\_memories
+
+```python
+def delete_all_memories(*,
+                        user_id: str | None = None,
+                        run_id: str | None = None,
+                        agent_id: str | None = None,
+                        **kwargs: Any) -> None
+```
+
+Delete memory records from Mem0.
+
+At least one of user_id, run_id, or agent_id must be set.
+
+**Arguments**:
+
+- `user_id`: The user ID to delete memories from.
+- `run_id`: The run ID to delete memories from.
+- `agent_id`: The agent ID to delete memories from.
+- `kwargs`: Additional keyword arguments to pass to the Mem0 client.delete_all method.
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore.delete_memory"></a>
+
+#### Mem0MemoryStore.delete\_memory
+
+```python
+def delete_memory(memory_id: str, **kwargs: Any) -> None
+```
+
+Delete memory from Mem0.
+
+**Arguments**:
+
+- `memory_id`: The ID of the memory to delete.
+- `kwargs`: Additional keyword arguments to pass to the Mem0 client.delete method.
+
+<a id="haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore.normalize_filters"></a>
+
+#### Mem0MemoryStore.normalize\_filters
+
+```python
+@staticmethod
+def normalize_filters(filters: dict[str, Any]) -> dict[str, Any]
+```
+
+Convert Haystack filters to Mem0 filters.
+

docs-website/reference_versioned_docs/version-2.28-unstable/experiments-api/experimental_preprocessors_api.md

@@ -0,0 +1,76 @@
+---
+title: "Preprocessors"
+id: experimental-preprocessors-api
+description: "Pipelines wrapped as components."
+slug: "/experimental-preprocessors-api"
+---
+
+<a id="haystack_experimental.components.preprocessors.md_header_level_inferrer"></a>
+
+## Module haystack\_experimental.components.preprocessors.md\_header\_level\_inferrer
+
+<a id="haystack_experimental.components.preprocessors.md_header_level_inferrer.MarkdownHeaderLevelInferrer"></a>
+
+### MarkdownHeaderLevelInferrer
+
+Infers and rewrites header levels in Markdown text to normalize hierarchy.
+
+    First header → Always becomes level 1 (#)
+    Subsequent headers → Level increases if no content between headers, stays same if content exists
+    Maximum level → Capped at 6 (######)
+
+    ### Usage example
+    ```python
+    from haystack import Document
+    from haystack_experimental.components.preprocessors import MarkdownHeaderLevelInferrer
+
+    # Create a document with uniform header levels
+    text = "## Title
+## Subheader
+Section
+## Subheader
+More Content"
+    doc = Document(content=text)
+
+    # Initialize the inferrer and process the document
+    inferrer = MarkdownHeaderLevelInferrer()
+    result = inferrer.run([doc])
+
+    # The headers are now normalized with proper hierarchy
+    print(result["documents"][0].content)
+    > # Title
+## Subheader
+Section
+## Subheader
+More Content
+    ```
+
+<a id="haystack_experimental.components.preprocessors.md_header_level_inferrer.MarkdownHeaderLevelInferrer.__init__"></a>
+
+#### MarkdownHeaderLevelInferrer.\_\_init\_\_
+
+```python
+def __init__()
+```
+
+Initializes the MarkdownHeaderLevelInferrer.
+
+<a id="haystack_experimental.components.preprocessors.md_header_level_inferrer.MarkdownHeaderLevelInferrer.run"></a>
+
+#### MarkdownHeaderLevelInferrer.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document]) -> dict
+```
+
+Infers and rewrites the header levels in the content for documents that use uniform header levels.
+
+**Arguments**:
+
+- `documents`: list of Document objects to process.
+
+**Returns**:
+
+dict: a dictionary with the key 'documents' containing the processed Document objects.
+

docs-website/reference_versioned_docs/version-2.28-unstable/experiments-api/experimental_retrievers_api.md

@@ -0,0 +1,124 @@
+---
+title: "Retrievers"
+id: experimental-retrievers-api
+description: "Sweep through Document Stores and return a set of candidate documents that are relevant to the query."
+slug: "/experimental-retrievers-api"
+---
+
+<a id="haystack_experimental.components.retrievers.chat_message_retriever"></a>
+
+## Module haystack\_experimental.components.retrievers.chat\_message\_retriever
+
+<a id="haystack_experimental.components.retrievers.chat_message_retriever.ChatMessageRetriever"></a>
+
+### ChatMessageRetriever
+
+Retrieves chat messages from the underlying ChatMessageStore.
+
+Usage example:
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_experimental.components.retrievers import ChatMessageRetriever
+from haystack_experimental.chat_message_stores.in_memory import InMemoryChatMessageStore
+
+messages = [
+    ChatMessage.from_assistant("Hello, how can I help you?"),
+    ChatMessage.from_user("Hi, I have a question about Python. What is a Protocol?"),
+]
+
+message_store = InMemoryChatMessageStore()
+message_store.write_messages(chat_history_id="user_456_session_123", messages=messages)
+retriever = ChatMessageRetriever(message_store)
+
+result = retriever.run(chat_history_id="user_456_session_123")
+
+print(result["messages"])
+```
+
+<a id="haystack_experimental.components.retrievers.chat_message_retriever.ChatMessageRetriever.__init__"></a>
+
+#### ChatMessageRetriever.\_\_init\_\_
+
+```python
+def __init__(chat_message_store: ChatMessageStore, last_k: int | None = 10)
+```
+
+Create the ChatMessageRetriever component.
+
+**Arguments**:
+
+- `chat_message_store`: An instance of a ChatMessageStore.
+- `last_k`: The number of last messages to retrieve. Defaults to 10 messages if not specified.
+
+<a id="haystack_experimental.components.retrievers.chat_message_retriever.ChatMessageRetriever.to_dict"></a>
+
+#### ChatMessageRetriever.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_experimental.components.retrievers.chat_message_retriever.ChatMessageRetriever.from_dict"></a>
+
+#### ChatMessageRetriever.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "ChatMessageRetriever"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="haystack_experimental.components.retrievers.chat_message_retriever.ChatMessageRetriever.run"></a>
+
+#### ChatMessageRetriever.run
+
+```python
+@component.output_types(messages=list[ChatMessage])
+def run(
+    chat_history_id: str,
+    *,
+    last_k: int | None = None,
+    current_messages: list[ChatMessage] | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Run the ChatMessageRetriever
+
+**Arguments**:
+
+- `chat_history_id`: A unique identifier for the chat session or conversation whose messages should be retrieved.
+Each `chat_history_id` corresponds to a distinct chat history stored in the underlying ChatMessageStore.
+For example, use a session ID or conversation ID to isolate messages from different chat sessions.
+- `last_k`: The number of last messages to retrieve. This parameter takes precedence over the last_k
+parameter passed to the ChatMessageRetriever constructor. If unspecified, the last_k parameter passed
+to the constructor will be used.
+- `current_messages`: A list of incoming chat messages to combine with the retrieved messages. System messages from this list
+are prepended before the retrieved history, while all other messages (e.g., user messages) are appended
+after. This is useful for including new conversational context alongside stored history so the output
+can be directly used as input to a ChatGenerator or an Agent. If not provided, only the stored messages
+will be returned.
+
+**Raises**:
+
+- `ValueError`: If last_k is not None and is less than 0.
+
+**Returns**:
+
+A dictionary with the following key:
+- `messages` - The retrieved chat messages combined with any provided current messages.
+

docs-website/reference_versioned_docs/version-2.28-unstable/experiments-api/experimental_summarizer_api.md

@@ -0,0 +1,198 @@
+---
+title: "Summarizers"
+id: experimental-summarizers-api
+description: "Components that summarize texts into concise versions."
+slug: "/experimental-summarizers-api"
+---
+
+<a id="haystack_experimental.components.summarizers.llm_summarizer"></a>
+
+## Module haystack\_experimental.components.summarizers.llm\_summarizer
+
+<a id="haystack_experimental.components.summarizers.llm_summarizer.LLMSummarizer"></a>
+
+### LLMSummarizer
+
+Summarizes text using a language model.
+
+It's inspired by code from the OpenAI blog post: https://cookbook.openai.com/examples/summarizing_long_documents
+
+Example
+```python
+from haystack_experimental.components.summarizers.summarizer import Summarizer
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack import Document
+
+text = ("Machine learning is a subset of artificial intelligence that provides systems "
+        "the ability to automatically learn and improve from experience without being "
+        "explicitly programmed. The process of learning begins with observations or data. "
+        "Supervised learning algorithms build a mathematical model of sample data, known as "
+        "training data, in order to make predictions or decisions. Unsupervised learning "
+        "algorithms take a set of data that contains only inputs and find structure in the data. "
+        "Reinforcement learning is an area of machine learning where an agent learns to behave "
+        "in an environment by performing actions and seeing the results. Deep learning uses "
+        "artificial neural networks to model complex patterns in data. Neural networks consist "
+        "of layers of connected nodes, each performing a simple computation.")
+
+doc = Document(content=text)
+chat_generator = OpenAIChatGenerator(model="gpt-4")
+summarizer = Summarizer(chat_generator=chat_generator)
+summarizer.run(documents=[doc])
+```
+
+<a id="haystack_experimental.components.summarizers.llm_summarizer.LLMSummarizer.__init__"></a>
+
+#### LLMSummarizer.\_\_init\_\_
+
+```python
+def __init__(chat_generator: ChatGenerator,
+             system_prompt: str
+             | None = "Rewrite this text in summarized form.",
+             summary_detail: float = 0,
+             minimum_chunk_size: int | None = 500,
+             chunk_delimiter: str = ".",
+             summarize_recursively: bool = False,
+             split_overlap: int = 0)
+```
+
+Initialize the Summarizer component.
+
+:param chat_generator: A ChatGenerator instance to use for summarization.
+        :param system_prompt: The prompt to instruct the LLM to summarise text, if not given defaults to:
+            "Rewrite this text in summarized form."
+        :param summary_detail: The level of detail for the summary (0-1), defaults to 0.
+            This parameter controls the trade-off between conciseness and completeness by adjusting how many
+            chunks the text is divided into. At detail=0, the text is processed as a single chunk (or very few
+            chunks), producing the most concise summary. At detail=1, the text is split into the maximum number
+            of chunks allowed by minimum_chunk_size, enabling more granular analysis and detailed summaries.
+            The formula uses linear interpolation: num_chunks = 1 + detail * (max_chunks - 1), where max_chunks
+            is determined by dividing the document length by minimum_chunk_size.
+        :param minimum_chunk_size: The minimum token count per chunk, defaults to 500
+        :param chunk_delimiter: The character used to determine separator priority.
+            "." uses sentence-based splitting, "
+" uses paragraph-based splitting, defaults to "."
+        :param summarize_recursively: Whether to use previous summaries as context, defaults to False.
+        :param split_overlap: Number of tokens to overlap between consecutive chunks, defaults to 0.
+
+
+<a id="haystack_experimental.components.summarizers.llm_summarizer.LLMSummarizer.warm_up"></a>
+
+#### LLMSummarizer.warm\_up
+
+```python
+def warm_up()
+```
+
+Warm up the chat generator and document splitter components.
+
+<a id="haystack_experimental.components.summarizers.llm_summarizer.LLMSummarizer.to_dict"></a>
+
+#### LLMSummarizer.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_experimental.components.summarizers.llm_summarizer.LLMSummarizer.from_dict"></a>
+
+#### LLMSummarizer.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "LLMSummarizer"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary with serialized data.
+
+**Returns**:
+
+An instance of the component.
+
+<a id="haystack_experimental.components.summarizers.llm_summarizer.LLMSummarizer.num_tokens"></a>
+
+#### LLMSummarizer.num\_tokens
+
+```python
+def num_tokens(text: str) -> int
+```
+
+Estimates the token count for a given text.
+
+Uses the RecursiveDocumentSplitter's tokenization logic for consistency.
+
+**Arguments**:
+
+- `text`: The text to tokenize
+
+**Returns**:
+
+The estimated token count
+
+<a id="haystack_experimental.components.summarizers.llm_summarizer.LLMSummarizer.summarize"></a>
+
+#### LLMSummarizer.summarize
+
+```python
+def summarize(text: str,
+              detail: float,
+              minimum_chunk_size: int,
+              summarize_recursively: bool = False) -> str
+```
+
+Summarizes text by splitting it into optimally-sized chunks and processing each with an LLM.
+
+**Arguments**:
+
+- `text`: Text to summarize
+- `detail`: Detail level (0-1) where 0 is most concise and 1 is most detailed
+- `minimum_chunk_size`: Minimum token count per chunk
+- `summarize_recursively`: Whether to use previous summaries as context
+
+**Raises**:
+
+- `ValueError`: If detail is not between 0 and 1
+
+**Returns**:
+
+The textual content summarized by the LLM.
+
+<a id="haystack_experimental.components.summarizers.llm_summarizer.LLMSummarizer.run"></a>
+
+#### LLMSummarizer.run
+
+```python
+@component.output_types(summary=list[Document])
+def run(*,
+        documents: list[Document],
+        detail: float | None = None,
+        minimum_chunk_size: int | None = None,
+        summarize_recursively: bool | None = None,
+        system_prompt: str | None = None) -> dict[str, list[Document]]
+```
+
+Run the summarizer on a list of documents.
+
+**Arguments**:
+
+- `documents`: List of documents to summarize
+- `detail`: The level of detail for the summary (0-1), defaults to 0 overwriting the component's default.
+- `minimum_chunk_size`: The minimum token count per chunk, defaults to 500 overwriting the
+component's default.
+- `system_prompt`: If given it will overwrite prompt given at init time or the default one.
+- `summarize_recursively`: Whether to use previous summaries as context, defaults to False overwriting the
+component's default.
+
+**Raises**:
+
+- `RuntimeError`: If the component wasn't warmed up.
+

docs-website/reference_versioned_docs/version-2.28-unstable/experiments-api/experimental_writers_api.md

@@ -0,0 +1,105 @@
+---
+title: "Writers"
+id: experimental-writers-api
+description: "Writers for Haystack."
+slug: "/experimental-writers-api"
+---
+
+<a id="haystack_experimental.components.writers.chat_message_writer"></a>
+
+## Module haystack\_experimental.components.writers.chat\_message\_writer
+
+<a id="haystack_experimental.components.writers.chat_message_writer.ChatMessageWriter"></a>
+
+### ChatMessageWriter
+
+Writes chat messages to an underlying ChatMessageStore.
+
+Usage example:
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_experimental.components.writers import ChatMessageWriter
+from haystack_experimental.chat_message_stores.in_memory import InMemoryChatMessageStore
+
+messages = [
+    ChatMessage.from_assistant("Hello, how can I help you?"),
+    ChatMessage.from_user("I have a question about Python."),
+]
+message_store = InMemoryChatMessageStore()
+writer = ChatMessageWriter(message_store)
+writer.run(chat_history_id="user_456_session_123", messages=messages)
+```
+
+<a id="haystack_experimental.components.writers.chat_message_writer.ChatMessageWriter.__init__"></a>
+
+#### ChatMessageWriter.\_\_init\_\_
+
+```python
+def __init__(chat_message_store: ChatMessageStore) -> None
+```
+
+Create a ChatMessageWriter component.
+
+**Arguments**:
+
+- `chat_message_store`: The ChatMessageStore where the chat messages are to be written.
+
+<a id="haystack_experimental.components.writers.chat_message_writer.ChatMessageWriter.to_dict"></a>
+
+#### ChatMessageWriter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_experimental.components.writers.chat_message_writer.ChatMessageWriter.from_dict"></a>
+
+#### ChatMessageWriter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "ChatMessageWriter"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Raises**:
+
+- `DeserializationError`: If the message store is not properly specified in the serialization data or its type cannot be imported.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="haystack_experimental.components.writers.chat_message_writer.ChatMessageWriter.run"></a>
+
+#### ChatMessageWriter.run
+
+```python
+@component.output_types(messages_written=int)
+def run(chat_history_id: str, messages: list[ChatMessage]) -> dict[str, int]
+```
+
+Run the ChatMessageWriter on the given input data.
+
+**Arguments**:
+
+- `chat_history_id`: A unique identifier for the chat session or conversation whose messages should be retrieved.
+Each `chat_history_id` corresponds to a distinct chat history stored in the underlying ChatMessageStore.
+For example, use a session ID or conversation ID to isolate messages from different chat sessions.
+- `messages`: A list of chat messages to write to the store.
+
+**Returns**:
+
+- `messages_written`: Number of messages written to the ChatMessageStore.
+

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/agents_api.md

@@ -0,0 +1,477 @@
+---
+title: "Agents"
+id: agents-api
+description: "Tool-using agents with provider-agnostic chat model support."
+slug: "/agents-api"
+---
+
+
+## agent
+
+### Agent
+
+A tool-using Agent powered by a large language model.
+
+The Agent processes messages and calls tools until it meets an exit condition.
+You can set one or more exit conditions to control when it stops.
+For example, it can stop after generating a response or after calling a tool.
+
+Without tools, the Agent works like a standard LLM that generates text. It produces one response and then stops.
+
+### Usage examples
+
+This is an example agent that:
+
+1. Searches for tipping customs in France.
+1. Uses a calculator to compute tips based on its findings.
+1. Returns the final answer with its context.
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import Tool
+
+# Tool functions - in practice, these would have real implementations
+def search(query: str) -> str:
+    '''Search for information on the web.'''
+    # Placeholder: would call actual search API
+    return "In France, a 15% service charge is typically included, but leaving 5-10% extra is appreciated."
+
+def calculator(operation: str, a: float, b: float) -> float:
+    '''Perform mathematical calculations.'''
+    if operation == "multiply":
+        return a * b
+    elif operation == "percentage":
+        return (a / 100) * b
+    return 0
+
+# Define tools with JSON Schema
+tools = [
+    Tool(
+        name="search",
+        description="Searches for information on the web",
+        parameters={
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "The search query"}
+            },
+            "required": ["query"]
+        },
+        function=search
+    ),
+    Tool(
+        name="calculator",
+        description="Performs mathematical calculations",
+        parameters={
+            "type": "object",
+            "properties": {
+                "operation": {"type": "string", "description": "Operation: multiply, percentage"},
+                "a": {"type": "number", "description": "First number"},
+                "b": {"type": "number", "description": "Second number"}
+            },
+            "required": ["operation", "a", "b"]
+        },
+        function=calculator
+    )
+]
+
+# Create and run the agent
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(),
+    tools=tools
+)
+
+result = agent.run(
+    messages=[ChatMessage.from_user("Calculate the appropriate tip for an €85 meal in France")]
+)
+
+print(result["messages"][-1].text)
+```
+
+#### Using a `user_prompt` template with variables
+
+You can define a reusable `user_prompt` with Jinja2 template variables so the Agent can be invoked
+with different inputs without manually constructing `ChatMessage` objects each time.
+This is especially useful when embedding the Agent in a pipeline or calling it in a loop.
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.tools import tool
+from typing import Annotated
+
+
+@tool
+def translate(
+    text: Annotated[str, "The text to translate"],
+    target_language: Annotated[str, "The language to translate to"],
+) -> str:
+    """Translate text to a target language."""
+    # Placeholder: would call an actual translation API
+    return f"[Translated '{text}' to {target_language}]"
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(),
+    tools=[translate],
+    system_prompt="You are a helpful translation assistant.",
+    user_prompt="""{% message role="user"%}
+Translate the following document to {{ language }}: {{ document }}
+{% endmessage %}""",
+    required_variables=["language", "document"],
+)
+
+# The template variables 'language' and 'document' become inputs to the run method
+result = agent.run(
+    language="French",
+    document="The weather is lovely today and the sun is shining.",
+)
+
+print(result["last_message"].text)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    chat_generator: ChatGenerator,
+    tools: ToolsType | None = None,
+    system_prompt: str | None = None,
+    user_prompt: str | None = None,
+    required_variables: list[str] | Literal["*"] | None = None,
+    exit_conditions: list[str] | None = None,
+    state_schema: dict[str, Any] | None = None,
+    max_agent_steps: int = 100,
+    streaming_callback: StreamingCallbackT | None = None,
+    raise_on_tool_invocation_failure: bool = False,
+    tool_invoker_kwargs: dict[str, Any] | None = None,
+    confirmation_strategies: (
+        dict[str | tuple[str, ...], ConfirmationStrategy] | None
+    ) = None
+) -> None
+```
+
+Initialize the agent component.
+
+**Parameters:**
+
+- **chat_generator** (<code>ChatGenerator</code>) – An instance of the chat generator that your agent should use. It must support tools.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset that the agent can use.
+- **system_prompt** (<code>str | None</code>) – System prompt for the agent. Can be a plain string or a Jinja2 string template.
+  For details on the supported template syntax, refer to the
+  [documentation](https://docs.haystack.deepset.ai/docs/chatpromptbuilder#string-templates).
+- **user_prompt** (<code>str | None</code>) – User prompt for the agent, defined as a Jinja2 string template. If provided, this is
+  appended to the messages provided at runtime.
+  For details on the supported template syntax, refer to the
+  [documentation](https://docs.haystack.deepset.ai/docs/chatpromptbuilder#string-templates).
+- **required_variables** (<code>list\[str\] | Literal['\*'] | None</code>) – List variables that must be provided as input to user_prompt or system_prompt.
+  If a variable listed as required is not provided, an exception is raised.
+  If set to `"*"`, all variables found in the prompts are required. Optional.
+- **exit_conditions** (<code>list\[str\] | None</code>) – List of conditions that will cause the agent to return.
+  Can include "text" if the agent should return when it generates a message without tool calls,
+  or tool names that will cause the agent to return once the tool was executed. Defaults to ["text"].
+- **state_schema** (<code>dict\[str, Any\] | None</code>) – The schema for the runtime state used by the tools.
+- **max_agent_steps** (<code>int</code>) – Maximum number of steps the agent will run before stopping. Defaults to 100.
+  If the agent exceeds this number of steps, it will stop and return the current state.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback that will be invoked when a response is streamed from the LLM.
+  The same callback can be configured to emit tool results when a tool is called.
+- **raise_on_tool_invocation_failure** (<code>bool</code>) – Should the agent raise an exception when a tool invocation fails?
+  If set to False, the exception will be turned into a chat message and passed to the LLM.
+- **tool_invoker_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments to pass to the ToolInvoker.
+- **confirmation_strategies** (<code>dict\[str | tuple\[str, ...\], ConfirmationStrategy\] | None</code>) – A dictionary mapping tool names to ConfirmationStrategy instances.
+
+**Raises:**
+
+- <code>TypeError</code> – If the chat_generator does not support tools parameter in its run method.
+- <code>ValueError</code> – If the exit_conditions are not valid.
+- <code>ValueError</code> – If any `user_prompt` variable overlaps with `state` schema or `run` parameters.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Agent.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Agent
+```
+
+Deserialize the agent from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from
+
+**Returns:**
+
+- <code>Agent</code> – Deserialized agent
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage] | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    *,
+    generation_kwargs: dict[str, Any] | None = None,
+    break_point: AgentBreakpoint | None = None,
+    snapshot: AgentSnapshot | None = None,
+    system_prompt: str | None = None,
+    user_prompt: str | None = None,
+    tools: ToolsType | list[str] | None = None,
+    snapshot_callback: SnapshotCallback | None = None,
+    confirmation_strategy_context: dict[str, Any] | None = None,
+    **kwargs: Any
+) -> dict[str, Any]
+```
+
+Process messages and execute tools until an exit condition is met.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\] | None</code>) – List of Haystack ChatMessage objects to process.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback that will be invoked when a response is streamed from the LLM.
+  The same callback can be configured to emit tool results when a tool is called.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for LLM. These parameters will
+  override the parameters passed during component initialization.
+- **break_point** (<code>AgentBreakpoint | None</code>) – An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint
+  for "tool_invoker".
+- **snapshot** (<code>AgentSnapshot | None</code>) – A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains
+  the relevant information to restart the Agent execution from where it left off.
+- **system_prompt** (<code>str | None</code>) – System prompt for the agent. If provided, it overrides the default system prompt.
+- **user_prompt** (<code>str | None</code>) – User prompt for the agent. If provided, it overrides the default user prompt and is
+  appended to the messages provided at runtime.
+- **tools** (<code>ToolsType | list\[str\] | None</code>) – Optional list of Tool objects, a Toolset, or list of tool names to use for this run.
+  When passing tool names, tools are selected from the Agent's originally configured tools.
+- **snapshot_callback** (<code>SnapshotCallback | None</code>) – Optional callback function that is invoked when a pipeline snapshot is created.
+  The callback receives a `PipelineSnapshot` object and can return an optional string.
+  If provided, the callback is used instead of the default file-saving behavior.
+- **confirmation_strategy_context** (<code>dict\[str, Any\] | None</code>) – Optional dictionary for passing request-scoped resources
+  to confirmation strategies. Useful in web/server environments to provide per-request
+  objects (e.g., WebSocket connections, async queues, Redis pub/sub clients) that strategies
+  can use for non-blocking user interaction.
+- **kwargs** (<code>Any</code>) – Additional data to pass to the State schema used by the Agent.
+  The keys must match the schema defined in the Agent's `state_schema`.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- "messages": List of all messages exchanged during the agent's run.
+- "last_message": The last message exchanged during the agent's run.
+- Any additional keys defined in the `state_schema`.
+
+**Raises:**
+
+- <code>BreakpointException</code> – If an agent breakpoint is triggered.
+
+#### run_async
+
+```python
+run_async(
+    messages: list[ChatMessage] | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    *,
+    generation_kwargs: dict[str, Any] | None = None,
+    break_point: AgentBreakpoint | None = None,
+    snapshot: AgentSnapshot | None = None,
+    system_prompt: str | None = None,
+    user_prompt: str | None = None,
+    tools: ToolsType | list[str] | None = None,
+    snapshot_callback: SnapshotCallback | None = None,
+    confirmation_strategy_context: dict[str, Any] | None = None,
+    **kwargs: Any
+) -> dict[str, Any]
+```
+
+Asynchronously process messages and execute tools until the exit condition is met.
+
+This is the asynchronous version of the `run` method. It follows the same logic but uses
+asynchronous operations where possible, such as calling the `run_async` method of the ChatGenerator
+if available.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\] | None</code>) – List of Haystack ChatMessage objects to process.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – An asynchronous callback that will be invoked when a response is streamed from the
+  LLM. The same callback can be configured to emit tool results when a tool is called.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for LLM. These parameters will
+  override the parameters passed during component initialization.
+- **break_point** (<code>AgentBreakpoint | None</code>) – An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint
+  for "tool_invoker".
+- **snapshot** (<code>AgentSnapshot | None</code>) – A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains
+  the relevant information to restart the Agent execution from where it left off.
+- **system_prompt** (<code>str | None</code>) – System prompt for the agent. If provided, it overrides the default system prompt.
+- **user_prompt** (<code>str | None</code>) – User prompt for the agent. If provided, it overrides the default user prompt and is
+  appended to the messages provided at runtime.
+- **tools** (<code>ToolsType | list\[str\] | None</code>) – Optional list of Tool objects, a Toolset, or list of tool names to use for this run.
+- **snapshot_callback** (<code>SnapshotCallback | None</code>) – Optional callback function that is invoked when a pipeline snapshot is created.
+  The callback receives a `PipelineSnapshot` object and can return an optional string.
+  If provided, the callback is used instead of the default file-saving behavior.
+- **kwargs** (<code>Any</code>) – Additional data to pass to the State schema used by the Agent.
+  The keys must match the schema defined in the Agent's `state_schema`.
+- **confirmation_strategy_context** (<code>dict\[str, Any\] | None</code>) – Optional dictionary for passing request-scoped resources
+  to confirmation strategies. Useful in web/server environments to provide per-request
+  objects (e.g., WebSocket connections, async queues, Redis pub/sub clients) that strategies
+  can use for non-blocking user interaction.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- "messages": List of all messages exchanged during the agent's run.
+- "last_message": The last message exchanged during the agent's run.
+- Any additional keys defined in the `state_schema`.
+
+**Raises:**
+
+- <code>BreakpointException</code> – If an agent breakpoint is triggered.
+
+## state/state
+
+### State
+
+State is a container for storing shared information during the execution of an Agent and its tools.
+
+For instance, State can be used to store documents, context, and intermediate results.
+
+Internally it wraps a `_data` dictionary defined by a `schema`. Each schema entry has:
+
+```json
+  "parameter_name": {
+    "type": SomeType,  # expected type
+    "handler": Optional[Callable[[Any, Any], Any]]  # merge/update function
+  }
+```
+
+Handlers control how values are merged when using the `set()` method:
+
+- For list types: defaults to `merge_lists` (concatenates lists)
+- For other types: defaults to `replace_values` (overwrites existing value)
+
+A `messages` field with type `list[ChatMessage]` is automatically added to the schema.
+
+This makes it possible for the Agent to read from and write to the same context.
+
+### Usage example
+
+```python
+from haystack.components.agents.state import State
+
+my_state = State(
+    schema={"gh_repo_name": {"type": str}, "user_name": {"type": str}},
+    data={"gh_repo_name": "my_repo", "user_name": "my_user_name"}
+)
+```
+
+#### __init__
+
+```python
+__init__(schema: dict[str, Any], data: dict[str, Any] | None = None) -> None
+```
+
+Initialize a State object with a schema and optional data.
+
+**Parameters:**
+
+- **schema** (<code>dict\[str, Any\]</code>) – Dictionary mapping parameter names to their type and handler configs.
+  Type must be a valid Python type, and handler must be a callable function or None.
+  If handler is None, the default handler for the type will be used. The default handlers are:
+  - For list types: `haystack.agents.state.state_utils.merge_lists`
+  - For all other types: `haystack.agents.state.state_utils.replace_values`
+- **data** (<code>dict\[str, Any\] | None</code>) – Optional dictionary of initial data to populate the state
+
+#### get
+
+```python
+get(key: str, default: Any = None) -> Any
+```
+
+Retrieve a value from the state by key.
+
+**Parameters:**
+
+- **key** (<code>str</code>) – Key to look up in the state
+- **default** (<code>Any</code>) – Value to return if key is not found
+
+**Returns:**
+
+- <code>Any</code> – Value associated with key or default if not found
+
+#### set
+
+```python
+set(
+    key: str,
+    value: Any,
+    handler_override: Callable[[Any, Any], Any] | None = None,
+) -> None
+```
+
+Set or merge a value in the state according to schema rules.
+
+Value is merged or overwritten according to these rules:
+
+- if handler_override is given, use that
+- else use the handler defined in the schema for 'key'
+
+**Parameters:**
+
+- **key** (<code>str</code>) – Key to store the value under
+- **value** (<code>Any</code>) – Value to store or merge
+- **handler_override** (<code>Callable\\[[Any, Any\], Any\] | None</code>) – Optional function to override the default merge behavior
+
+#### data
+
+```python
+data: dict[str, Any]
+```
+
+All current data of the state.
+
+#### has
+
+```python
+has(key: str) -> bool
+```
+
+Check if a key exists in the state.
+
+**Parameters:**
+
+- **key** (<code>str</code>) – Key to check for existence
+
+**Returns:**
+
+- <code>bool</code> – True if key exists in state, False otherwise
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the State object to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> State
+```
+
+Convert a dictionary back to a State object.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/audio_api.md

@@ -0,0 +1,243 @@
+---
+title: "Audio"
+id: audio-api
+description: "Transcribes audio files."
+slug: "/audio-api"
+---
+
+
+## whisper_local
+
+### LocalWhisperTranscriber
+
+Transcribes audio files using OpenAI's Whisper model on your local machine.
+
+For the supported audio formats, languages, and other parameters, see the
+[Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper
+[GitHub repository](https://github.com/openai/whisper).
+
+### Usage example
+
+<!-- test-ignore -->
+
+```python
+from haystack.components.audio import LocalWhisperTranscriber
+
+whisper = LocalWhisperTranscriber(model="small")
+transcription = whisper.run(sources=["test/test_files/audio/answer.wav"])
+```
+
+#### __init__
+
+```python
+__init__(
+    model: WhisperLocalModel = "large",
+    device: ComponentDevice | None = None,
+    whisper_params: dict[str, Any] | None = None,
+) -> None
+```
+
+Creates an instance of the LocalWhisperTranscriber component.
+
+**Parameters:**
+
+- **model** (<code>WhisperLocalModel</code>) – The name of the model to use. Set to one of the following models:
+  "tiny", "base", "small", "medium", "large" (default).
+  For details on the models and their modifications, see the
+  [Whisper documentation](https://github.com/openai/whisper?tab=readme-ov-file#available-models-and-languages).
+- **device** (<code>ComponentDevice | None</code>) – The device for loading the model. If `None`, automatically selects the default device.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Loads the model in memory.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LocalWhisperTranscriber
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>LocalWhisperTranscriber</code> – The deserialized component.
+
+#### run
+
+```python
+run(
+    sources: list[str | Path | ByteStream],
+    whisper_params: dict[str, Any] | None = None,
+) -> dict[str, Any]
+```
+
+Transcribes a list of audio files into a list of documents.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – A list of paths or binary streams to transcribe.
+- **whisper_params** (<code>dict\[str, Any\] | None</code>) – For the supported audio formats, languages, and other parameters, see the
+  [Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper
+  [GitHup repo](https://github.com/openai/whisper).
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents where each document is a transcribed audio file. The content of
+  the document is the transcription text, and the document's metadata contains the values returned by
+  the Whisper model, such as the alignment data and the path to the audio file used
+  for the transcription.
+
+#### transcribe
+
+```python
+transcribe(
+    sources: list[str | Path | ByteStream], **kwargs: Any
+) -> list[Document]
+```
+
+Transcribes the audio files into a list of Documents, one for each input file.
+
+For the supported audio formats, languages, and other parameters, see the
+[Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper
+[github repo](https://github.com/openai/whisper).
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – A list of paths or binary streams to transcribe.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents, one for each file.
+
+## whisper_remote
+
+### RemoteWhisperTranscriber
+
+Transcribes audio files using the OpenAI's Whisper API.
+
+The component requires an OpenAI API key, see the
+[OpenAI documentation](https://platform.openai.com/docs/api-reference/authentication) for more details.
+For the supported audio formats, languages, and other parameters, see the
+[Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text).
+
+### Usage example
+
+```python
+from haystack.components.audio import RemoteWhisperTranscriber
+
+whisper = RemoteWhisperTranscriber(model="whisper-1")
+transcription = whisper.run(sources=["test/test_files/audio/answer.wav"])
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
+    model: str = "whisper-1",
+    api_base_url: str | None = None,
+    organization: str | None = None,
+    http_client_kwargs: dict[str, Any] | None = None,
+    **kwargs: Any
+) -> None
+```
+
+Creates an instance of the RemoteWhisperTranscriber component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – OpenAI API key.
+  You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter
+  during initialization.
+- **model** (<code>str</code>) – Name of the model to use. Currently accepts only `whisper-1`.
+- **organization** (<code>str | None</code>) – Your OpenAI organization ID. See OpenAI's documentation on
+  [Setting Up Your Organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization).
+- **api_base_url** (<code>str | None</code>) – An optional URL to use as the API base. For details, see the
+  OpenAI [documentation](https://platform.openai.com/docs/api-reference/audio).
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+- **kwargs** (<code>Any</code>) – Other optional parameters for the model. These are sent directly to the OpenAI
+  endpoint. See OpenAI [documentation](https://platform.openai.com/docs/api-reference/audio) for more details.
+  Some of the supported parameters are:
+- `language`: The language of the input audio.
+  Provide the input language in ISO-639-1 format
+  to improve transcription accuracy and latency.
+- `prompt`: An optional text to guide the model's
+  style or continue a previous audio segment.
+  The prompt should match the audio language.
+- `response_format`: The format of the transcript
+  output. This component only supports `json`.
+- `temperature`: The sampling temperature, between 0
+  and 1. Higher values like 0.8 make the output more
+  random, while lower values like 0.2 make it more
+  focused and deterministic. If set to 0, the model
+  uses log probability to automatically increase the
+  temperature until certain thresholds are hit.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> RemoteWhisperTranscriber
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>RemoteWhisperTranscriber</code> – The deserialized component.
+
+#### run
+
+```python
+run(sources: list[str | Path | ByteStream]) -> dict[str, Any]
+```
+
+Transcribes the list of audio files into a list of documents.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – A list of file paths or `ByteStream` objects containing the audio files to transcribe.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents, one document for each file.
+  The content of each document is the transcribed text.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/builders_api.md

@@ -0,0 +1,537 @@
+---
+title: "Builders"
+id: builders-api
+description: "Extract the output of a Generator to an Answer format, and build prompts."
+slug: "/builders-api"
+---
+
+
+## answer_builder
+
+### AnswerBuilder
+
+Converts a query and Generator replies into a `GeneratedAnswer` object.
+
+AnswerBuilder parses Generator replies using custom regular expressions.
+Check out the usage example below to see how it works.
+Optionally, it can also take documents and metadata from the Generator to add to the `GeneratedAnswer` object.
+AnswerBuilder works with both non-chat and chat Generators.
+
+### Usage example
+
+```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."])
+```
+
+### Usage example with documents and reference pattern
+
+```python
+from haystack import Document
+from haystack.components.builders import AnswerBuilder
+
+replies = ["The capital of France is Paris [2]."]
+
+docs = [
+    Document(content="Berlin is the capital of Germany."),
+    Document(content="Paris is the capital of France."),
+    Document(content="Rome is the capital of Italy."),
+]
+
+builder = AnswerBuilder(reference_pattern="\[(\d+)\]", return_only_referenced_documents=False)
+result = builder.run(query="What is the capital of France?", replies=replies, documents=docs)["answers"][0]
+
+print(f"Answer: {result.data}")
+print("References:")
+for doc in result.documents:
+    if doc.meta["referenced"]:
+        print(f"[{doc.meta['source_index']}] {doc.content}")
+print("Other sources:")
+for doc in result.documents:
+    if not doc.meta["referenced"]:
+        print(f"[{doc.meta['source_index']}] {doc.content}")
+
+# >> Answer: The capital of France is Paris
+# >> References:
+# >> [2] Paris is the capital of France.
+# >> Other sources:
+# >> [1] Berlin is the capital of Germany.
+# >> [3] Rome is the capital of Italy.
+```
+
+#### __init__
+
+```python
+__init__(
+    pattern: str | None = None,
+    reference_pattern: str | None = None,
+    last_message_only: bool = False,
+    *,
+    return_only_referenced_documents: bool = True
+) -> None
+```
+
+Creates an instance of the AnswerBuilder component.
+
+**Parameters:**
+
+- **pattern** (<code>str | None</code>) – The regular expression pattern to extract the answer text from the Generator.
+  If not specified, the entire response is used as the answer.
+  The regular expression can have one capture group at most.
+  If present, the capture group text
+  is used as the answer. If no capture group is present, the whole match is used as the answer.
+  Examples:
+  `[^\n]+$` finds "this is an answer" in a string "this is an argument.\\nthis is an answer".
+  `Answer: (.*)` finds "this is an answer" in a string "this is an argument. Answer: this is an answer".
+- **reference_pattern** (<code>str | None</code>) – The regular expression pattern used for parsing the document references.
+  If not specified, no parsing is done, and all documents are returned.
+  References need to be specified as indices of the input documents and start at [1].
+  Example: `\[(\d+)\]` finds "1" in a string "this is an answer[1]".
+  If this parameter is provided, documents metadata will contain a "referenced" key with a boolean value.
+- **last_message_only** (<code>bool</code>) – If False (default value), all messages are used as the answer.
+  If True, only the last message is used as the answer.
+- **return_only_referenced_documents** (<code>bool</code>) – To be used in conjunction with `reference_pattern`.
+  If True (default value), only the documents that were actually referenced in `replies` are returned.
+  If False, all documents are returned.
+  If `reference_pattern` is not provided, this parameter has no effect, and all documents are returned.
+
+#### run
+
+```python
+run(
+    query: str,
+    replies: list[str] | list[ChatMessage],
+    meta: list[dict[str, Any]] | None = None,
+    documents: list[Document] | None = None,
+    pattern: str | None = None,
+    reference_pattern: str | None = None,
+) -> dict[str, Any]
+```
+
+Turns the output of a Generator into `GeneratedAnswer` objects using regular expressions.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The input query used as the Generator prompt.
+- **replies** (<code>list\[str\] | list\[ChatMessage\]</code>) – The output of the Generator. Can be a list of strings or a list of `ChatMessage` objects.
+- **meta** (<code>list\[dict\[str, Any\]\] | None</code>) – The metadata returned by the Generator. If not specified, the generated answer will contain no metadata.
+- **documents** (<code>list\[Document\] | None</code>) – The documents used as the Generator inputs. If specified, they are added to
+  the `GeneratedAnswer` objects.
+  Each Document.meta includes a "source_index" key, representing its 1-based position in the input list.
+  When `reference_pattern` is provided:
+- "referenced" key is added to the Document.meta, indicating if the document was referenced in the output.
+- `return_only_referenced_documents` init parameter controls if all or only referenced documents are
+  returned.
+- **pattern** (<code>str | None</code>) – The regular expression pattern to extract the answer text from the Generator.
+  If not specified, the entire response is used as the answer.
+  The regular expression can have one capture group at most.
+  If present, the capture group text
+  is used as the answer. If no capture group is present, the whole match is used as the answer.
+  Examples:
+  `[^\n]+$` finds "this is an answer" in a string "this is an argument.\\nthis is an answer".
+  `Answer: (.*)` finds "this is an answer" in a string
+  "this is an argument. Answer: this is an answer".
+- **reference_pattern** (<code>str | None</code>) – The regular expression pattern used for parsing the document references.
+  If not specified, no parsing is done, and all documents are returned.
+  References need to be specified as indices of the input documents and start at [1].
+  Example: `\[(\d+)\]` finds "1" in a string "this is an answer[1]".
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `answers`: The answers received from the output of the Generator.
+
+## chat_prompt_builder
+
+### ChatPromptBuilder
+
+Renders a chat prompt from a template using Jinja2 syntax.
+
+A template can be a list of `ChatMessage` objects, or a special string, as shown in the usage examples.
+
+It constructs prompts using static or dynamic templates, which you can update for each pipeline run.
+
+Template variables in the template are optional unless specified otherwise.
+If an optional variable isn't provided, it defaults to an empty string. Use `variable` and `required_variables`
+to define input types and required variables.
+
+### Usage examples
+
+#### Static ChatMessage prompt template
+
+```python
+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.")
+```
+
+#### Overriding static ChatMessage template at runtime
+
+```python
+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.")
+
+msg = "Translate to {{ target_language }} and summarize. Context: {{ snippet }}; Summary:"
+summary_template = [ChatMessage.from_user(msg)]
+builder.run(target_language="spanish", snippet="I can't speak spanish.", template=summary_template)
+```
+
+#### Dynamic ChatMessage prompt template
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+
+# no parameter init, we don't use any runtime template variables
+prompt_builder = ChatPromptBuilder()
+llm = OpenAIChatGenerator(model="gpt-5-mini")
+
+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)
+# >> {'llm': {'replies': [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _content=[TextContent(text=
+# "Berlin is the capital city of Germany and one of the most vibrant
+# and diverse cities in Europe. Here are some key things to know...Enjoy your time exploring the vibrant and dynamic
+# capital of Germany!")], _name=None, _meta={'model': 'gpt-5-mini',
+# 'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 27, 'completion_tokens': 681, 'total_tokens':
+# 708}})]}}
+
+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)
+# >> {'llm': {'replies': [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _content=[TextContent(text=
+# "Here is the weather forecast for Berlin in the next 5
+# days:\n\nDay 1: Mostly cloudy with a high of 22°C (72°F) and...so it's always a good idea to check for updates
+# closer to your visit.")], _name=None, _meta={'model': 'gpt-5-mini',
+# 'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 37, 'completion_tokens': 201,
+# 'total_tokens': 238}})]}}
+```
+
+#### String prompt template
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses.image_content import ImageContent
+
+template = """
+{% message role="system" %}
+You are a helpful assistant.
+{% endmessage %}
+
+{% 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 %}
+"""
+
+images = [ImageContent.from_file_path("test/test_files/images/apple.jpg"),
+          ImageContent.from_file_path("test/test_files/images/haystack-logo.png")]
+
+builder = ChatPromptBuilder(template=template)
+builder.run(user_name="John", images=images)
+```
+
+#### __init__
+
+```python
+__init__(
+    template: list[ChatMessage] | str | None = None,
+    required_variables: list[str] | Literal["*"] | None = None,
+    variables: list[str] | None = None,
+) -> None
+```
+
+Constructs a ChatPromptBuilder component.
+
+**Parameters:**
+
+- **template** (<code>list\[ChatMessage\] | str | None</code>) – A list of `ChatMessage` objects or a string template. The component looks for Jinja2 template syntax and
+  renders the prompt with the provided variables. Provide the template in either
+  the `init` method`or the`run\` method.
+- **required_variables** (<code>list\[str\] | Literal['\*'] | None</code>) – List variables that must be provided as input to ChatPromptBuilder.
+  If a variable listed as required is not provided, an exception is raised.
+  If set to `"*"`, all variables found in the prompt are required. Optional.
+- **variables** (<code>list\[str\] | None</code>) – List input variables to use in prompt templates instead of the ones inferred from the
+  `template` parameter. For example, to use more variables during prompt engineering than the ones present
+  in the default template, you can provide them here.
+
+#### run
+
+```python
+run(
+    template: list[ChatMessage] | str | None = None,
+    template_variables: dict[str, Any] | None = None,
+    **kwargs: Any
+) -> dict[str, list[ChatMessage]]
+```
+
+Renders the prompt template with the provided variables.
+
+It applies the template variables to render the final prompt. You can provide variables with pipeline kwargs.
+To overwrite the default template, you can set the `template` parameter.
+To overwrite pipeline kwargs, you can set the `template_variables` parameter.
+
+**Parameters:**
+
+- **template** (<code>list\[ChatMessage\] | str | None</code>) – An optional list of `ChatMessage` objects or string template to overwrite ChatPromptBuilder's default
+  template.
+  If `None`, the default template provided at initialization is used.
+- **template_variables** (<code>dict\[str, Any\] | None</code>) – An optional dictionary of template variables to overwrite the pipeline variables.
+- **kwargs** (<code>Any</code>) – Pipeline variables used for rendering the prompt.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `prompt`: The updated list of `ChatMessage` objects after rendering the templates.
+
+**Raises:**
+
+- <code>ValueError</code> – If `chat_messages` is empty or contains elements that are not instances of `ChatMessage`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the component.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Serialized dictionary representation of the component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChatPromptBuilder
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize and create the component.
+
+**Returns:**
+
+- <code>ChatPromptBuilder</code> – The deserialized component.
+
+## prompt_builder
+
+### PromptBuilder
+
+Renders a prompt filling in any variables so that it can send it to a Generator.
+
+The prompt uses Jinja2 template syntax.
+The variables in the default template are used as PromptBuilder's input and are all optional.
+If they're not provided, they're replaced with an empty string in the rendered prompt.
+To try out different prompts, you can replace the prompt template at runtime by
+providing a template for each pipeline run invocation.
+
+### Usage examples
+
+#### On its own
+
+This example uses PromptBuilder to render a prompt template and fill it with `target_language`
+and `snippet`. PromptBuilder returns a prompt with the string "Translate the following context to Spanish.
+Context: I can't speak Spanish.; Translation:".
+
+```python
+from haystack.components.builders import PromptBuilder
+
+template = "Translate the following context to {{ target_language }}. Context: {{ snippet }}; Translation:"
+builder = PromptBuilder(template=template)
+builder.run(target_language="spanish", snippet="I can't speak spanish.")
+```
+
+#### In a Pipeline
+
+This is an example of a RAG pipeline where PromptBuilder renders a custom prompt template and fills it
+with the contents of the retrieved documents and a query. The rendered prompt is then sent to a Generator.
+
+```python
+from haystack import Pipeline, Document
+from haystack.utils import Secret
+from haystack.components.generators import OpenAIGenerator
+from haystack.components.builders.prompt_builder import PromptBuilder
+
+# in a real world use case documents could come from a retriever, web, or any other source
+documents = [Document(content="Joe lives in Berlin"), Document(content="Joe is a software engineer")]
+prompt_template = """
+    Given these documents, answer the question.
+    Documents:
+    {% for doc in documents %}
+        {{ doc.content }}
+    {% endfor %}
+
+    Question: {{query}}
+    Answer:
+    """
+p = Pipeline()
+p.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
+p.add_component(instance=OpenAIGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")), name="llm")
+p.connect("prompt_builder", "llm")
+
+question = "Where does Joe live?"
+result = p.run({"prompt_builder": {"documents": documents, "query": question}})
+print(result)
+```
+
+#### Changing the template at runtime (prompt engineering)
+
+You can change the prompt template of an existing pipeline, like in this example:
+
+```python
+documents = [
+    Document(content="Joe lives in Berlin", meta={"name": "doc1"}),
+    Document(content="Joe is a software engineer", meta={"name": "doc1"}),
+]
+new_template = """
+    You are a helpful assistant.
+    Given these documents, answer the question.
+    Documents:
+    {% for doc in documents %}
+        Document {{ loop.index }}:
+        Document name: {{ doc.meta['name'] }}
+        {{ doc.content }}
+    {% endfor %}
+
+    Question: {{ query }}
+    Answer:
+    """
+p.run({
+    "prompt_builder": {
+        "documents": documents,
+        "query": question,
+        "template": new_template,
+    },
+})
+```
+
+To replace the variables in the default template when testing your prompt,
+pass the new variables in the `variables` parameter.
+
+#### Overwriting variables at runtime
+
+To overwrite the values of variables, use `template_variables` during runtime:
+
+```python
+language_template = """
+You are a helpful assistant.
+Given these documents, answer the question.
+Documents:
+{% for doc in documents %}
+    Document {{ loop.index }}:
+    Document name: {{ doc.meta['name'] }}
+    {{ doc.content }}
+{% endfor %}
+
+Question: {{ query }}
+Please provide your answer in {{ answer_language | default('English') }}
+Answer:
+"""
+p.run({
+    "prompt_builder": {
+        "documents": documents,
+        "query": question,
+        "template": language_template,
+        "template_variables": {"answer_language": "German"},
+    },
+})
+```
+
+Note that `language_template` introduces variable `answer_language` which is not bound to any pipeline variable.
+If not set otherwise, it will use its default value 'English'.
+This example overwrites its value to 'German'.
+Use `template_variables` to overwrite pipeline variables (such as documents) as well.
+
+#### __init__
+
+```python
+__init__(
+    template: str,
+    required_variables: list[str] | Literal["*"] | None = None,
+    variables: list[str] | None = None,
+) -> None
+```
+
+Constructs a PromptBuilder component.
+
+**Parameters:**
+
+- **template** (<code>str</code>) – A prompt template that uses Jinja2 syntax to add variables. For example:
+  `"Summarize this document: {{ documents[0].content }}\nSummary:"`
+  It's used to render the prompt.
+  The variables in the default template are input for PromptBuilder and are all optional,
+  unless explicitly specified.
+  If an optional variable is not provided, it's replaced with an empty string in the rendered prompt.
+- **required_variables** (<code>list\[str\] | Literal['\*'] | None</code>) – List variables that must be provided as input to PromptBuilder.
+  If a variable listed as required is not provided, an exception is raised.
+  If set to `"*"`, all variables found in the prompt are required. Optional.
+- **variables** (<code>list\[str\] | None</code>) – List input variables to use in prompt templates instead of the ones inferred from the
+  `template` parameter. For example, to use more variables during prompt engineering than the ones present
+  in the default template, you can provide them here.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the component.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Serialized dictionary representation of the component.
+
+#### run
+
+```python
+run(
+    template: str | None = None,
+    template_variables: dict[str, Any] | None = None,
+    **kwargs: Any
+) -> dict[str, Any]
+```
+
+Renders the prompt template with the provided variables.
+
+It applies the template variables to render the final prompt. You can provide variables via pipeline kwargs.
+In order to overwrite the default template, you can set the `template` parameter.
+In order to overwrite pipeline kwargs, you can set the `template_variables` parameter.
+
+**Parameters:**
+
+- **template** (<code>str | None</code>) – An optional string template to overwrite PromptBuilder's default template. If None, the default template
+  provided at initialization is used.
+- **template_variables** (<code>dict\[str, Any\] | None</code>) – An optional dictionary of template variables to overwrite the pipeline variables.
+- **kwargs** (<code>Any</code>) – Pipeline variables used for rendering the prompt.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `prompt`: The updated prompt text after rendering the prompt template.
+
+**Raises:**
+
+- <code>ValueError</code> – If any of the required template variables is not provided.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/cachings_api.md

@@ -0,0 +1,96 @@
+---
+title: "Caching"
+id: caching-api
+description: "Checks if any document coming from the given URL is already present in the store."
+slug: "/caching-api"
+---
+
+
+## cache_checker
+
+### CacheChecker
+
+Checks for the presence of documents in a Document Store based on a specified field in each document's metadata.
+
+If matching documents are found, they are returned as "hits". If not found in the cache, the items
+are returned as "misses".
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.caching.cache_checker import CacheChecker
+
+docstore = InMemoryDocumentStore()
+documents = [
+    Document(content="doc1", meta={"url": "https://example.com/1"}),
+    Document(content="doc2", meta={"url": "https://example.com/2"}),
+    Document(content="doc3", meta={"url": "https://example.com/1"}),
+    Document(content="doc4", meta={"url": "https://example.com/2"}),
+]
+docstore.write_documents(documents)
+checker = CacheChecker(docstore, cache_field="url")
+results = checker.run(items=["https://example.com/1", "https://example.com/5"])
+assert results == {"hits": [documents[0], documents[2]], "misses": ["https://example.com/5"]}
+```
+
+#### __init__
+
+```python
+__init__(document_store: DocumentStore, cache_field: str) -> None
+```
+
+Creates a CacheChecker component.
+
+**Parameters:**
+
+- **document_store** (<code>DocumentStore</code>) – Document Store to check for the presence of specific documents.
+- **cache_field** (<code>str</code>) – Name of the document's metadata field
+  to check for cache hits.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CacheChecker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>CacheChecker</code> – Deserialized component.
+
+#### run
+
+```python
+run(items: list[Any]) -> dict[str, Any]
+```
+
+Checks if any document associated with the specified cache field is already present in the store.
+
+**Parameters:**
+
+- **items** (<code>list\[Any\]</code>) – Values to be checked against the cache field.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with two keys:
+- `hits` - Documents that matched with at least one of the items.
+- `misses` - Items that were not present in any documents.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/classifiers_api.md

@@ -0,0 +1,247 @@
+---
+title: "Classifiers"
+id: classifiers-api
+description: "Classify documents based on the provided labels."
+slug: "/classifiers-api"
+---
+
+
+## document_language_classifier
+
+### DocumentLanguageClassifier
+
+Classifies the language of each document and adds it to its metadata.
+
+Provide a list of languages during initialization. If the document's text doesn't match any of the
+specified languages, the metadata value is set to "unmatched".
+To route documents based on their language, use the MetadataRouter component after DocumentLanguageClassifier.
+For routing plain text, use the TextLanguageRouter component instead.
+
+### Usage example
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.classifiers import DocumentLanguageClassifier
+from haystack.components.routers import MetadataRouter
+from haystack.components.writers import DocumentWriter
+
+docs = [Document(id="1", content="This is an English document"),
+        Document(id="2", content="Este es un documento en español")]
+
+document_store = InMemoryDocumentStore()
+
+p = Pipeline()
+p.add_component(instance=DocumentLanguageClassifier(languages=["en"]), name="language_classifier")
+p.add_component(
+instance=MetadataRouter(rules={
+    "en": {
+        "field": "meta.language",
+        "operator": "==",
+        "value": "en"
+    }
+}),
+name="router")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+p.connect("language_classifier.documents", "router.documents")
+p.connect("router.en", "writer.documents")
+
+p.run({"language_classifier": {"documents": docs}})
+
+written_docs = document_store.filter_documents()
+assert len(written_docs) == 1
+assert written_docs[0] == Document(id="1", content="This is an English document", meta={"language": "en"})
+```
+
+#### __init__
+
+```python
+__init__(languages: list[str] | None = None) -> None
+```
+
+Initializes the DocumentLanguageClassifier component.
+
+**Parameters:**
+
+- **languages** (<code>list\[str\] | None</code>) – A list of ISO language codes.
+  See the supported languages in [`langdetect` documentation](https://github.com/Mimino666/langdetect#languages).
+  If not specified, defaults to ["en"].
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Classifies the language of each document and adds it to its metadata.
+
+If the document's text doesn't match any of the languages specified at initialization,
+sets the metadata value to "unmatched".
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents for language classification.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following key:
+- `documents`: A list of documents with an added `language` metadata field.
+
+**Raises:**
+
+- <code>TypeError</code> – if the input is not a list of Documents.
+
+## zero_shot_document_classifier
+
+### TransformersZeroShotDocumentClassifier
+
+Performs zero-shot classification of documents based on given labels and adds the predicted label to their metadata.
+
+The component uses a Hugging Face pipeline for zero-shot classification.
+Provide the model and the set of labels to be used for categorization during initialization.
+Additionally, you can configure the component to allow multiple labels to be true.
+
+Classification is run on the document's content field by default. If you want it to run on another field, set the
+`classification_field` to one of the document's metadata fields.
+
+Available models for the task of zero-shot-classification include:
+\- `valhalla/distilbart-mnli-12-3`
+\- `cross-encoder/nli-distilroberta-base`
+\- `cross-encoder/nli-deberta-v3-xsmall`
+
+### Usage example
+
+The following is a pipeline that classifies documents based on predefined classification labels
+retrieved from a search pipeline:
+
+```python
+from haystack import Document
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.core.pipeline import Pipeline
+from haystack.components.classifiers import TransformersZeroShotDocumentClassifier
+
+documents = [Document(id="0", content="Today was a nice day!"),
+             Document(id="1", content="Yesterday was a bad day!")]
+
+document_store = InMemoryDocumentStore()
+retriever = InMemoryBM25Retriever(document_store=document_store)
+document_classifier = TransformersZeroShotDocumentClassifier(
+    model="cross-encoder/nli-deberta-v3-xsmall",
+    labels=["positive", "negative"],
+)
+
+document_store.write_documents(documents)
+
+pipeline = Pipeline()
+pipeline.add_component(instance=retriever, name="retriever")
+pipeline.add_component(instance=document_classifier, name="document_classifier")
+pipeline.connect("retriever", "document_classifier")
+
+queries = ["How was your day today?", "How was your day yesterday?"]
+expected_predictions = ["positive", "negative"]
+
+for idx, query in enumerate(queries):
+    result = pipeline.run({"retriever": {"query": query, "top_k": 1}})
+    assert result["document_classifier"]["documents"][0].to_dict()["id"] == str(idx)
+    assert (result["document_classifier"]["documents"][0].to_dict()["classification"]["label"]
+            == expected_predictions[idx])
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str,
+    labels: list[str],
+    multi_label: bool = False,
+    classification_field: str | None = None,
+    device: ComponentDevice | None = None,
+    token: Secret | None = Secret.from_env_var(
+        ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+    ),
+    huggingface_pipeline_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Initializes the TransformersZeroShotDocumentClassifier.
+
+See the Hugging Face [website](https://huggingface.co/models?pipeline_tag=zero-shot-classification&sort=downloads&search=nli)
+for the full list of zero-shot classification models (NLI) models.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name or path of a Hugging Face model for zero shot document classification.
+- **labels** (<code>list\[str\]</code>) – The set of possible class labels to classify each document into, for example,
+  ["positive", "negative"]. The labels depend on the selected model.
+- **multi_label** (<code>bool</code>) – Whether or not multiple candidate labels can be true.
+  If `False`, the scores are normalized such that
+  the sum of the label likelihoods for each sequence is 1. If `True`, the labels are considered
+  independent and probabilities are normalized for each candidate by doing a softmax of the entailment
+  score vs. the contradiction score.
+- **classification_field** (<code>str | None</code>) – Name of document's meta field to be used for classification.
+  If not set, `Document.content` is used by default.
+- **device** (<code>ComponentDevice | None</code>) – The device on which the model is loaded. If `None`, the default device is automatically
+  selected. If a device/device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter.
+- **token** (<code>Secret | None</code>) – The Hugging Face token to use as HTTP bearer authorization.
+  Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **huggingface_pipeline_kwargs** (<code>dict\[str, Any\] | None</code>) – Dictionary containing keyword arguments used to initialize the
+  Hugging Face pipeline for text classification.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TransformersZeroShotDocumentClassifier
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>TransformersZeroShotDocumentClassifier</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document], batch_size: int = 1) -> dict[str, Any]
+```
+
+Classifies the documents based on the provided labels and adds them to their metadata.
+
+The classification results are stored in the `classification` dict within
+each document's metadata. If `multi_label` is set to `True`, the scores for each label are available under
+the `details` key within the `classification` dictionary.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to process.
+- **batch_size** (<code>int</code>) – Batch size used for processing the content in each document.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following key:
+- `documents`: A list of documents with an added metadata field called `classification`.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/connectors_api.md

@@ -0,0 +1,275 @@
+---
+title: "Connectors"
+id: connectors-api
+description: "Various connectors to integrate with external services."
+slug: "/connectors-api"
+---
+
+
+## openapi
+
+### OpenAPIConnector
+
+OpenAPIConnector enables direct invocation of REST endpoints defined in an OpenAPI specification.
+
+The OpenAPIConnector serves as a bridge between Haystack pipelines and any REST API that follows
+the OpenAPI(formerly Swagger) specification. It dynamically interprets the API specification and
+provides an interface for executing API operations. It is usually invoked by passing input
+arguments to it from a Haystack pipeline run method or by other components in a pipeline that
+pass input arguments to this component.
+
+Example:
+
+<!-- test-ignore -->
+
+```python
+from haystack.utils import Secret
+from haystack.components.connectors.openapi import OpenAPIConnector
+
+serper_dev_token = Secret.from_env_var("SERPERDEV_API_KEY")
+
+def my_custom_config_factory():
+    # Create and return a custom configuration for the OpenAPIClient
+    pass
+
+connector = OpenAPIConnector(
+    openapi_spec="https://bit.ly/serperdev_openapi",
+    credentials=serper_dev_token,
+    service_kwargs={"config_factory": my_custom_config_factory()}
+)
+response = connector.run(
+    operation_id="search",
+    arguments={"q": "Who was Nikola Tesla?"}
+)
+```
+
+Note:
+
+- The `service_kwargs` argument is optional, it can be used to pass additional options to the OpenAPIClient.
+
+#### __init__
+
+```python
+__init__(
+    openapi_spec: str,
+    credentials: Secret | None = None,
+    service_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the OpenAPIConnector with a specification and optional credentials.
+
+**Parameters:**
+
+- **openapi_spec** (<code>str</code>) – URL, file path, or raw string of the OpenAPI specification
+- **credentials** (<code>Secret | None</code>) – Optional API key or credentials for the service wrapped in a Secret
+- **service_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments passed to OpenAPIClient.from_spec()
+  For example, you can pass a custom config_factory or other configuration options.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAPIConnector
+```
+
+Deserialize this component from a dictionary.
+
+#### run
+
+```python
+run(
+    operation_id: str, arguments: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Invokes a REST endpoint specified in the OpenAPI specification.
+
+**Parameters:**
+
+- **operation_id** (<code>str</code>) – The operationId from the OpenAPI spec to invoke
+- **arguments** (<code>dict\[str, Any\] | None</code>) – Optional parameters for the endpoint (query, path, or body parameters)
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary containing the service response
+
+## openapi_service
+
+### patch_request
+
+```python
+patch_request(
+    self: Operation,
+    base_url: str,
+    *,
+    data: Any | None = None,
+    parameters: dict[str, Any] | None = None,
+    raw_response: bool = False,
+    security: dict[str, str] | None = None,
+    session: Any | None = None,
+    verify: bool | str = True
+) -> Any | None
+```
+
+Sends an HTTP request as described by this path.
+
+**Parameters:**
+
+- **base_url** (<code>str</code>) – The URL to append this operation's path to when making
+  the call.
+- **data** (<code>Any | None</code>) – The request body to send.
+- **parameters** (<code>dict\[str, Any\] | None</code>) – The parameters used to create the path.
+- **raw_response** (<code>bool</code>) – If true, return the raw response instead of validating
+  and extrapolating it.
+- **security** (<code>dict\[str, str\] | None</code>) – The security scheme to use, and the values it needs to
+  process successfully.
+- **session** (<code>Any | None</code>) – A persistent request session.
+- **verify** (<code>bool | str</code>) – If we should do an SSL verification on the request or not.
+  In case str was provided, will use that as the CA.
+
+**Returns:**
+
+- <code>Any | None</code> – The response data, either raw or processed depending on raw_response flag.
+
+### OpenAPIServiceConnector
+
+A component which connects the Haystack framework to OpenAPI services.
+
+The `OpenAPIServiceConnector` component connects the Haystack framework to OpenAPI services, enabling it to call
+operations as defined in the OpenAPI specification of the service.
+
+It integrates with `ChatMessage` dataclass, where the `ToolCall` entries in messages are used to determine the
+method to be called and the parameters to be passed. The method name and parameters are then used to invoke the
+method on the OpenAPI service. The response from the service is returned as a `ChatMessage`.
+
+Before using this component, users usually resolve service endpoint parameters with a help of
+`OpenAPIServiceToFunctions` component.
+
+The example below demonstrates how to use the `OpenAPIServiceConnector` to invoke a method on a https://serper.dev/
+service specified via OpenAPI specification.
+
+Note, however, that `OpenAPIServiceConnector` is usually not meant to be used directly, but rather as part of a
+pipeline that includes the `OpenAPIServiceToFunctions` component and a Chat Generator component using an LLM
+with tool calling capabilities. In the example below we use the tool call payload directly, but in a
+real-world scenario, the tool calls would usually be generated by the Chat Generator component.
+
+You need to define the `serper_token` variable with your Serper.dev API token for the example to work.
+Can be through the `SERPERDEV_API_KEY` environment variable or by directly assigning the token string to the
+variable in the code.
+
+Usage example:
+
+<!-- test-ignore -->
+
+```python
+import json
+import httpx
+
+from haystack.components.connectors import OpenAPIServiceConnector
+from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.utils import Secret
+
+tool_call = ToolCall(
+    tool_name="search",
+    arguments={"q": "Why was Sam Altman ousted from OpenAI?"},
+)
+message = ChatMessage.from_assistant(tool_calls=[tool_call])
+
+serper_token = Secret.from_env_var("SERPERDEV_API_KEY").resolve_value()
+serperdev_openapi_spec = json.loads(httpx.get("https://bit.ly/serper_dev_spec", follow_redirects=True).text)
+service_connector = OpenAPIServiceConnector()
+result = service_connector.run(
+    messages=[message],
+    service_openapi_spec=serperdev_openapi_spec,
+    service_credentials=serper_token,
+)
+print(result)
+
+# {'service_response': ChatMessage(_role=<ChatRole.USER: 'user'>, _content=[TextContent(text=
+# '{"searchParameters": {"q": "Why was Sam Altman ousted from OpenAI?",
+# "type": "search", "engine": "google"}, "answerBox": {"snippet": "Concerns over AI safety and OpenAI's role
+# in protecting were at the center of Altman's brief ouster from the company."...
+```
+
+#### __init__
+
+```python
+__init__(ssl_verify: bool | str | None = None) -> None
+```
+
+Initializes the OpenAPIServiceConnector instance
+
+**Parameters:**
+
+- **ssl_verify** (<code>[bool | str | None</code>) – Decide if to use SSL verification to the requests or not,
+  in case a string is passed, will be used as the CA.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage],
+    service_openapi_spec: dict[str, Any],
+    service_credentials: dict | str | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Processes a list of chat messages to invoke a method on an OpenAPI service.
+
+It parses the last message in the list, expecting it to contain tool calls.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of `ChatMessage` objects containing the messages to be processed. The last message
+  should contain the tool calls.
+- **service_openapi_spec** (<code>dict\[str, Any\]</code>) – The OpenAPI JSON specification object of the service to be invoked. All the refs
+  should already be resolved.
+- **service_credentials** (<code>dict | str | None</code>) – The credentials to be used for authentication with the service.
+  Currently, only the http and apiKey OpenAPI security schemes are supported.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `service_response`: a list of `ChatMessage` objects, each containing the response from the service. The
+  response is in JSON format, and the `content` attribute of the `ChatMessage` contains
+  the JSON string.
+
+**Raises:**
+
+- <code>ValueError</code> – If the last message is not from the assistant or if it does not contain tool calls.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OpenAPIServiceConnector</code> – The deserialized component.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/document_stores_api.md

@@ -0,0 +1,593 @@
+---
+title: "Document Stores"
+id: document-stores-api
+description: "Stores your texts and meta data and provides them to the Retriever at query time."
+slug: "/document-stores-api"
+---
+
+
+## document_store
+
+### BM25DocumentStats
+
+A dataclass for managing document statistics for BM25 retrieval.
+
+**Parameters:**
+
+- **freq_token** (<code>dict\[str, int\]</code>) – A Counter of token frequencies in the document.
+- **doc_len** (<code>int</code>) – Number of tokens in the document.
+
+### InMemoryDocumentStore
+
+Stores data in-memory. It's ephemeral and cannot be saved to disk.
+
+#### __init__
+
+```python
+__init__(
+    bm25_tokenization_regex: str = "(?u)\\b\\w+\\b",
+    bm25_algorithm: Literal["BM25Okapi", "BM25L", "BM25Plus"] = "BM25L",
+    bm25_parameters: dict | None = None,
+    embedding_similarity_function: Literal[
+        "dot_product", "cosine"
+    ] = "dot_product",
+    index: str | None = None,
+    async_executor: ThreadPoolExecutor | None = None,
+    return_embedding: bool = True,
+) -> None
+```
+
+Initializes the DocumentStore.
+
+**Parameters:**
+
+- **bm25_tokenization_regex** (<code>str</code>) – The regular expression used to tokenize the text for BM25 retrieval.
+- **bm25_algorithm** (<code>Literal['BM25Okapi', 'BM25L', 'BM25Plus']</code>) – The BM25 algorithm to use. One of "BM25Okapi", "BM25L", or "BM25Plus".
+- **bm25_parameters** (<code>dict | None</code>) – Parameters for BM25 implementation in a dictionary format.
+  For example: `{'k1':1.5, 'b':0.75, 'epsilon':0.25}`
+  You can learn more about these parameters by visiting https://github.com/dorianbrown/rank_bm25.
+- **embedding_similarity_function** (<code>Literal['dot_product', 'cosine']</code>) – The similarity function used to compare Documents embeddings.
+  One of "dot_product" (default) or "cosine". To choose the most appropriate function, look for information
+  about your embedding model.
+- **index** (<code>str | None</code>) – A specific index to store the documents. If not specified, a random UUID is used.
+  Using the same index allows you to store documents across multiple InMemoryDocumentStore instances.
+- **async_executor** (<code>ThreadPoolExecutor | None</code>) – Optional ThreadPoolExecutor to use for async calls. If not provided, a single-threaded
+  executor will be initialized and used.
+- **return_embedding** (<code>bool</code>) – Whether to return the embedding of the retrieved Documents. Default is True.
+
+#### shutdown
+
+```python
+shutdown() -> None
+```
+
+Explicitly shutdown the executor if we own it.
+
+#### storage
+
+```python
+storage: dict[str, Document]
+```
+
+Utility property that returns the storage used by this instance of InMemoryDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> InMemoryDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>InMemoryDocumentStore</code> – The deserialized component.
+
+#### save_to_disk
+
+```python
+save_to_disk(path: str) -> None
+```
+
+Write the database and its data to disk as a JSON file.
+
+**Parameters:**
+
+- **path** (<code>str</code>) – The path to the JSON file.
+
+#### load_from_disk
+
+```python
+load_from_disk(path: str) -> InMemoryDocumentStore
+```
+
+Load the database and its data from disk as a JSON file.
+
+**Parameters:**
+
+- **path** (<code>str</code>) – The path to the JSON file.
+
+**Returns:**
+
+- <code>InMemoryDocumentStore</code> – The loaded InMemoryDocumentStore.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns the number of documents present in the DocumentStore.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – The filters to apply. For a detailed specification of the filters, refer to the
+  [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Refer to the DocumentStore.write_documents() protocol documentation.
+
+If `policy` is set to `DuplicatePolicy.NONE` defaults to `DuplicatePolicy.FAIL`.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with matching document_ids from the DocumentStore.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – The document_ids to delete.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents in the document store.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see filter_documents.
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update. These will be merged with existing metadata.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+**Raises:**
+
+- <code>ValueError</code> – if filters have invalid syntax.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for deletion.
+  For filter syntax, see filter_documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+**Raises:**
+
+- <code>ValueError</code> – if filters have invalid syntax.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply.
+  For a detailed specification of the filters, refer to the
+  [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the number of unique values for each specified metadata field from documents matching the filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply.
+  For a detailed specification of the filters, refer to the
+  [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+- **metadata_fields** (<code>list\[str\]</code>) – List of field names to count unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary mapping each metadata field name (without "meta." prefix)
+  to the count of its unique values among the filtered documents.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns information about the metadata fields present in the stored documents.
+
+Types are inferred from the stored values (keyword, int, float, boolean).
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – A dictionary mapping each metadata field name to a dict with a "type" key.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for the given metadata field across all documents.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field name. Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with "min" and "max" keys. Returns `{"min": None, "max": None}`
+  if the field is missing or has no values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str, search_term: str | None = None
+) -> tuple[list[str], int]
+```
+
+Returns unique values for a metadata field, optionally filtered by a search term in content.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field name. Can include or omit the "meta." prefix.
+- **search_term** (<code>str | None</code>) – If set, only documents whose content contains this term (case-insensitive)
+  are considered.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple of (list of unique values, total count of unique values).
+
+#### bm25_retrieval
+
+```python
+bm25_retrieval(
+    query: str,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    scale_score: bool = False,
+) -> list[Document]
+```
+
+Retrieves documents that are most relevant to the query using BM25 algorithm.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The query string.
+- **filters** (<code>dict\[str, Any\] | None</code>) – A dictionary with filters to narrow down the search space.
+- **top_k** (<code>int</code>) – The number of top documents to retrieve. Default is 10.
+- **scale_score** (<code>bool</code>) – Whether to scale the scores of the retrieved documents. Default is False.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of the top_k documents most relevant to the query.
+
+#### embedding_retrieval
+
+```python
+embedding_retrieval(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    scale_score: bool = False,
+    return_embedding: bool | None = False,
+) -> list[Document]
+```
+
+Retrieves documents that are most similar to the query embedding using a vector similarity metric.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – A dictionary with filters to narrow down the search space.
+- **top_k** (<code>int</code>) – The number of top documents to retrieve. Default is 10.
+- **scale_score** (<code>bool</code>) – Whether to scale the scores of the retrieved Documents. Default is False.
+- **return_embedding** (<code>bool | None</code>) – Whether to return the embedding of the retrieved Documents.
+  If not provided, the value of the `return_embedding` parameter set at component
+  initialization will be used. Default is False.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of the top_k documents most relevant to the query.
+
+**Raises:**
+
+- <code>ValueError</code> – if filters have invalid syntax.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Returns the number of documents present in the DocumentStore.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – The filters to apply. For a detailed specification of the filters, refer to the
+  [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Refer to the DocumentStore.write_documents() protocol documentation.
+
+If `policy` is set to `DuplicatePolicy.NONE` defaults to `DuplicatePolicy.FAIL`.
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Deletes all documents with matching document_ids from the DocumentStore.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – The document_ids to delete.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see filter_documents.
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update. These will be merged with existing metadata.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply.
+  For a detailed specification of the filters, refer to the
+  [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the number of unique values for each specified metadata field from documents matching the filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply.
+  For a detailed specification of the filters, refer to the
+  [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+- **metadata_fields** (<code>list\[str\]</code>) – List of field names to count unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary mapping each metadata field name (without "meta." prefix)
+  to the count of its unique values among the filtered documents.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Returns information about the metadata fields present in the stored documents.
+
+Types are inferred from the stored values (keyword, int, float, boolean).
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – A dictionary mapping each metadata field name to a dict with a "type" key.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for the given metadata field across all documents.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field name. Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with "min" and "max" keys. Returns `{"min": None, "max": None}`
+  if the field is missing or has no values.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str, search_term: str | None = None
+) -> tuple[list[str], int]
+```
+
+Returns unique values for a metadata field, optionally filtered by a search term in content.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field name. Can include or omit the "meta." prefix.
+- **search_term** (<code>str | None</code>) – If set, only documents whose content contains this term (case-insensitive)
+  are considered.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple of (list of unique values, total count of unique values).
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async() -> None
+```
+
+Deletes all documents in the document store.
+
+#### bm25_retrieval_async
+
+```python
+bm25_retrieval_async(
+    query: str,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    scale_score: bool = False,
+) -> list[Document]
+```
+
+Retrieves documents that are most relevant to the query using BM25 algorithm.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The query string.
+- **filters** (<code>dict\[str, Any\] | None</code>) – A dictionary with filters to narrow down the search space.
+- **top_k** (<code>int</code>) – The number of top documents to retrieve. Default is 10.
+- **scale_score** (<code>bool</code>) – Whether to scale the scores of the retrieved documents. Default is False.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of the top_k documents most relevant to the query.
+
+#### embedding_retrieval_async
+
+```python
+embedding_retrieval_async(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    scale_score: bool = False,
+    return_embedding: bool = False,
+) -> list[Document]
+```
+
+Retrieves documents that are most similar to the query embedding using a vector similarity metric.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – A dictionary with filters to narrow down the search space.
+- **top_k** (<code>int</code>) – The number of top documents to retrieve. Default is 10.
+- **scale_score** (<code>bool</code>) – Whether to scale the scores of the retrieved Documents. Default is False.
+- **return_embedding** (<code>bool</code>) – Whether to return the embedding of the retrieved Documents. Default is False.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of the top_k documents most relevant to the query.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/document_writers_api.md

@@ -0,0 +1,129 @@
+---
+title: "Document Writers"
+id: document-writers-api
+description: "Writes Documents to a DocumentStore."
+slug: "/document-writers-api"
+---
+
+
+## document_writer
+
+### DocumentWriter
+
+Writes documents to a DocumentStore.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.writers import DocumentWriter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+docs = [
+    Document(content="Python is a popular programming language"),
+]
+doc_store = InMemoryDocumentStore()
+writer = DocumentWriter(document_store=doc_store)
+writer.run(docs)
+```
+
+#### __init__
+
+```python
+__init__(
+    document_store: DocumentStore,
+    policy: DuplicatePolicy = DuplicatePolicy.NONE,
+) -> None
+```
+
+Create a DocumentWriter component.
+
+**Parameters:**
+
+- **document_store** (<code>DocumentStore</code>) – The instance of the document store where you want to store your documents.
+- **policy** (<code>DuplicatePolicy</code>) – The policy to apply when a Document with the same ID already exists in the DocumentStore.
+- `DuplicatePolicy.NONE`: Default policy, relies on the DocumentStore settings.
+- `DuplicatePolicy.SKIP`: Skips documents with the same ID and doesn't write them to the DocumentStore.
+- `DuplicatePolicy.OVERWRITE`: Overwrites documents with the same ID.
+- `DuplicatePolicy.FAIL`: Raises an error if a Document with the same ID is already in the DocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DocumentWriter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>DocumentWriter</code> – The deserialized component.
+
+**Raises:**
+
+- <code>DeserializationError</code> – If the document store is not properly specified in the serialization data or its type cannot be imported.
+
+#### run
+
+```python
+run(
+    documents: list[Document], policy: DuplicatePolicy | None = None
+) -> dict[str, int]
+```
+
+Run the DocumentWriter on the given input data.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to write to the document store.
+- **policy** (<code>DuplicatePolicy | None</code>) – The policy to use when encountering duplicate documents.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – Number of documents written to the document store.
+
+**Raises:**
+
+- <code>ValueError</code> – If the specified document store is not found.
+
+#### run_async
+
+```python
+run_async(
+    documents: list[Document], policy: DuplicatePolicy | None = None
+) -> dict[str, int]
+```
+
+Asynchronously run the DocumentWriter on the given input data.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to write to the document store.
+- **policy** (<code>DuplicatePolicy | None</code>) – The policy to use when encountering duplicate documents.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – Number of documents written to the document store.
+
+**Raises:**
+
+- <code>ValueError</code> – If the specified document store is not found.
+- <code>TypeError</code> – If the specified document store does not implement `write_documents_async`.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/evaluation_api.md

@@ -0,0 +1,108 @@
+---
+title: "Evaluation"
+id: evaluation-api
+description: "Represents the results of evaluation."
+slug: "/evaluation-api"
+---
+
+
+## eval_run_result
+
+### EvaluationRunResult
+
+Contains the inputs and the outputs of an evaluation pipeline and provides methods to inspect them.
+
+#### __init__
+
+```python
+__init__(
+    run_name: str,
+    inputs: dict[str, list[Any]],
+    results: dict[str, dict[str, Any]],
+) -> None
+```
+
+Initialize a new evaluation run result.
+
+**Parameters:**
+
+- **run_name** (<code>str</code>) – Name of the evaluation run.
+- **inputs** (<code>dict\[str, list\[Any\]\]</code>) – Dictionary containing the inputs used for the run. Each key is the name of the input and its value is a list
+  of input values. The length of the lists should be the same.
+- **results** (<code>dict\[str, dict\[str, Any\]\]</code>) – Dictionary containing the results of the evaluators used in the evaluation pipeline. Each key is the name
+  of the metric and its value is dictionary with the following keys:
+  - 'score': The aggregated score for the metric.
+  - 'individual_scores': A list of scores for each input sample.
+
+#### aggregated_report
+
+```python
+aggregated_report(
+    output_format: Literal["json", "csv", "df"] = "json",
+    csv_file: str | None = None,
+) -> Union[dict[str, list[Any]], DataFrame, str]
+```
+
+Generates a report with aggregated scores for each metric.
+
+**Parameters:**
+
+- **output_format** (<code>Literal['json', 'csv', 'df']</code>) – The output format for the report, "json", "csv", or "df", default to "json".
+- **csv_file** (<code>str | None</code>) – Filepath to save CSV output if `output_format` is "csv", must be provided.
+
+**Returns:**
+
+- <code>Union\[dict\[str, list\[Any\]\], DataFrame, str\]</code> – JSON or DataFrame with aggregated scores, in case the output is set to a CSV file, a message confirming the
+  successful write or an error message.
+
+#### detailed_report
+
+```python
+detailed_report(
+    output_format: Literal["json", "csv", "df"] = "json",
+    csv_file: str | None = None,
+) -> Union[dict[str, list[Any]], DataFrame, str]
+```
+
+Generates a report with detailed scores for each metric.
+
+**Parameters:**
+
+- **output_format** (<code>Literal['json', 'csv', 'df']</code>) – The output format for the report, "json", "csv", or "df", default to "json".
+- **csv_file** (<code>str | None</code>) – Filepath to save CSV output if `output_format` is "csv", must be provided.
+
+**Returns:**
+
+- <code>Union\[dict\[str, list\[Any\]\], DataFrame, str\]</code> – JSON or DataFrame with the detailed scores, in case the output is set to a CSV file, a message confirming
+  the successful write or an error message.
+
+#### comparative_detailed_report
+
+```python
+comparative_detailed_report(
+    other: EvaluationRunResult,
+    keep_columns: list[str] | None = None,
+    output_format: Literal["json", "csv", "df"] = "json",
+    csv_file: str | None = None,
+) -> Union[str, DataFrame, None]
+```
+
+Generates a report with detailed scores for each metric from two evaluation runs for comparison.
+
+**Parameters:**
+
+- **other** (<code>EvaluationRunResult</code>) – Results of another evaluation run to compare with.
+- **keep_columns** (<code>list\[str\] | None</code>) – List of common column names to keep from the inputs of the evaluation runs to compare.
+- **output_format** (<code>Literal['json', 'csv', 'df']</code>) – The output format for the report, "json", "csv", or "df", default to "json".
+- **csv_file** (<code>str | None</code>) – Filepath to save CSV output if `output_format` is "csv", must be provided.
+
+**Returns:**
+
+- <code>Union\[str, DataFrame, None\]</code> – JSON or DataFrame with a comparison of the detailed scores, in case the output is set to a CSV file,
+  a message confirming the successful write or an error message.
+
+**Raises:**
+
+- <code>TypeError</code> – If `other` is not an EvaluationRunResult instance, or if the detailed reports are not
+  dictionaries.
+- <code>ValueError</code> – If the `other` parameter is missing required attributes.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/extractors_api.md

@@ -0,0 +1,691 @@
+---
+title: "Extractors"
+id: extractors-api
+description: "Components to extract specific elements from textual data."
+slug: "/extractors-api"
+---
+
+
+## image/llm_document_content_extractor
+
+### LLMDocumentContentExtractor
+
+Extracts textual content and optionally metadata from image-based documents using a vision-enabled LLM.
+
+One prompt and one LLM call per document. The component converts each document to an image via
+DocumentToImageContent and sends it to the ChatGenerator. The prompt must not contain Jinja variables.
+
+Response handling:
+
+- If the LLM returns a **plain string** (non-JSON or not a JSON object), it is written to the document's content.
+- If the LLM returns a **JSON object with only the key** `document_content`, that value is written to content.
+- If the LLM returns a **JSON object with multiple keys**, the value of `document_content` (if present) is
+  written to content and all other keys are merged into the document's metadata.
+
+The ChatGenerator can be configured to return JSON (e.g. `response_format={"type": "json_object"}`
+in `generation_kwargs`).
+
+Documents that fail extraction are returned in `failed_documents` with `content_extraction_error` in metadata.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+
+prompt = """
+Extract the content from the provided image.
+Format everything as markdown. Return only the extracted content as a JSON object with the key 'document_content'.
+No markdown, no code fence, only raw JSON.
+
+Extract metadata about the image like source of the image, date of creation, etc. if you can.
+Return this metadata as additional key-value pairs in the same JSON object.
+"""
+
+chat_generator = OpenAIChatGenerator(
+        generation_kwargs={
+                "response_format": {
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": "entity_extraction",
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "document_content": {"type": "string"},
+                                "author": {"type": "string"},
+                                "date": {"type": "string"},
+                                "document_type": {"type": "string"},
+                                "title": {"type": "string"},
+                            },
+                            "additionalProperties": False,
+                        },
+                    },
+                }
+            }
+        )
+
+extractor = LLMDocumentContentExtractor(
+    chat_generator=chat_generator,
+    file_path_meta_field="file_path",
+    raise_on_failure=False
+)
+
+documents = [
+    Document(content="", meta={"file_path": "test/test_files/images/image_metadata.png"}),
+    Document(content="", meta={"file_path": "test/test_files/images/apple.jpg", "page_number": 1})
+]
+result = extractor.run(documents=documents)
+updated_documents = result["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    chat_generator: ChatGenerator,
+    prompt: str = DEFAULT_PROMPT_TEMPLATE,
+    file_path_meta_field: str = "file_path",
+    root_path: str | None = None,
+    detail: Literal["auto", "high", "low"] | None = None,
+    size: tuple[int, int] | None = None,
+    raise_on_failure: bool = False,
+    max_workers: int = 3
+) -> None
+```
+
+Initialize the LLMDocumentContentExtractor component.
+
+**Parameters:**
+
+- **chat_generator** (<code>ChatGenerator</code>) – A ChatGenerator that supports vision input. Optionally configured for JSON
+  (e.g. `response_format={"type": "json_object"}` in `generation_kwargs`).
+- **prompt** (<code>str</code>) – Prompt for extraction. Must not contain Jinja variables.
+- **file_path_meta_field** (<code>str</code>) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (<code>str | None</code>) – The root directory path where document files are located. If provided, file paths in
+  document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **detail** (<code>Literal['auto', 'high', 'low'] | None</code>) – Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low".
+- **size** (<code>tuple\[int, int\] | None</code>) – If provided, resizes the image to fit within (width, height) while keeping aspect ratio.
+- **raise_on_failure** (<code>bool</code>) – If True, exceptions from the LLM are raised. If False, failed documents are returned.
+- **max_workers** (<code>int</code>) – Maximum number of threads for parallel LLM calls.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the ChatGenerator if it has a warm_up method.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LLMDocumentContentExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary with serialized data.
+
+**Returns:**
+
+- <code>LLMDocumentContentExtractor</code> – An instance of the component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Run extraction on image-based documents. One LLM call per document.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of image-based documents to process. Each must have a valid file path in its metadata.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with "documents" (successfully processed) and "failed_documents" (with failure metadata).
+
+## llm_metadata_extractor
+
+### LLMMetadataExtractor
+
+Extracts metadata from documents using a Large Language Model (LLM).
+
+The metadata is extracted by providing a prompt to an LLM that generates the metadata.
+
+This component expects as input a list of documents and a prompt. The prompt should have a variable called
+`document` that will point to a single document in the list of documents. So to access the content of the document,
+you can use `{{ document.content }}` in the prompt.
+
+The component will run the LLM on each document in the list and extract metadata from the document. The metadata
+will be added to the document's metadata field. If the LLM fails to extract metadata from a document, the document
+will be added to the `failed_documents` list. The failed documents will have the keys `metadata_extraction_error` and
+`metadata_extraction_response` in their metadata. These documents can be re-run with another extractor to
+extract metadata by using the `metadata_extraction_response` and `metadata_extraction_error` in the prompt.
+
+```python
+from haystack import Document
+from haystack.components.extractors.llm_metadata_extractor import LLMMetadataExtractor
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+NER_PROMPT = '''
+-Goal-
+Given text and a list of entity types, identify all entities of those types from the text.
+
+-Steps-
+1. Identify all entities. For each identified entity, extract the following information:
+- entity: Name of the entity
+- entity_type: One of the following types: [organization, product, service, industry]
+Format each entity as a JSON like: {"entity": <entity_name>, "entity_type": <entity_type>}
+
+2. Return output in a single list with all the entities identified in steps 1.
+
+-Examples-
+######################
+Example 1:
+entity_types: [organization, person, partnership, financial metric, product, service, industry, investment strategy, market trend]
+text: Another area of strength is our co-brand issuance. Visa is the primary network partner for eight of the top
+10 co-brand partnerships in the US today and we are pleased that Visa has finalized a multi-year extension of
+our successful credit co-branded partnership with Alaska Airlines, a portfolio that benefits from a loyal customer
+base and high cross-border usage.
+We have also had significant co-brand momentum in CEMEA. First, we launched a new co-brand card in partnership
+with Qatar Airways, British Airways and the National Bank of Kuwait. Second, we expanded our strong global
+Marriott relationship to launch Qatar's first hospitality co-branded card with Qatar Islamic Bank. Across the
+United Arab Emirates, we now have exclusive agreements with all the leading airlines marked by a recent
+agreement with Emirates Skywards.
+And we also signed an inaugural Airline co-brand agreement in Morocco with Royal Air Maroc. Now newer digital
+issuers are equally
+------------------------
+output:
+{"entities": [{"entity": "Visa", "entity_type": "company"}, {"entity": "Alaska Airlines", "entity_type": "company"}, {"entity": "Qatar Airways", "entity_type": "company"}, {"entity": "British Airways", "entity_type": "company"}, {"entity": "National Bank of Kuwait", "entity_type": "company"}, {"entity": "Marriott", "entity_type": "company"}, {"entity": "Qatar Islamic Bank", "entity_type": "company"}, {"entity": "Emirates Skywards", "entity_type": "company"}, {"entity": "Royal Air Maroc", "entity_type": "company"}]}
+#############################
+-Real Data-
+######################
+entity_types: [company, organization, person, country, product, service]
+text: {{ document.content }}
+######################
+output:
+'''
+
+docs = [
+    Document(content="deepset was founded in 2018 in Berlin, and is known for its Haystack framework"),
+    Document(content="Hugging Face is a company that was founded in New York, USA and is known for its Transformers library")
+]
+
+chat_generator = OpenAIChatGenerator(
+    generation_kwargs={
+        "max_completion_tokens": 500,
+        "temperature": 0.0,
+        "seed": 0,
+        "response_format": {
+            "type": "json_schema",
+            "json_schema": {
+                "name": "entity_extraction",
+                "schema": {
+                    "type": "object",
+                    "properties": {
+                        "entities": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "entity": {"type": "string"},
+                                    "entity_type": {"type": "string"}
+                                },
+                                "required": ["entity", "entity_type"],
+                                "additionalProperties": False
+                            }
+                        }
+                    },
+                    "required": ["entities"],
+                    "additionalProperties": False
+                }
+            }
+        },
+    },
+    max_retries=1,
+    timeout=60.0,
+)
+
+extractor = LLMMetadataExtractor(
+    prompt=NER_PROMPT,
+    chat_generator=chat_generator,
+    expected_keys=["entities"],
+    raise_on_failure=False,
+)
+
+extractor.run(documents=docs)
+# >> {'documents': [
+#     Document(id=.., content: 'deepset was founded in 2018 in Berlin, and is known for its Haystack framework',
+#     meta: {'entities': [{'entity': 'deepset', 'entity_type': 'company'}, {'entity': 'Berlin', 'entity_type': 'city'},
+#           {'entity': 'Haystack', 'entity_type': 'product'}]}),
+#     Document(id=.., content: 'Hugging Face is a company that was founded in New York, USA and is known for its Transformers library',
+#     meta: {'entities': [
+#             {'entity': 'Hugging Face', 'entity_type': 'company'}, {'entity': 'New York', 'entity_type': 'city'},
+#             {'entity': 'USA', 'entity_type': 'country'}, {'entity': 'Transformers', 'entity_type': 'product'}
+#             ]})
+#        ]
+#     'failed_documents': []
+#    }
+# >>
+```
+
+#### __init__
+
+```python
+__init__(
+    prompt: str,
+    chat_generator: ChatGenerator,
+    expected_keys: list[str] | None = None,
+    page_range: list[str | int] | None = None,
+    raise_on_failure: bool = False,
+    max_workers: int = 3,
+) -> None
+```
+
+Initializes the LLMMetadataExtractor.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – The prompt to be used for the LLM.
+- **chat_generator** (<code>ChatGenerator</code>) – a ChatGenerator instance which represents the LLM. In order for the component to work,
+  the LLM should be configured to return a JSON object. For example, when using the OpenAIChatGenerator, you
+  should pass `{"response_format": {"type": "json_object"}}` in the `generation_kwargs`.
+- **expected_keys** (<code>list\[str\] | None</code>) – The keys expected in the JSON output from the LLM.
+- **page_range** (<code>list\[str | int\] | None</code>) – A range of pages to extract metadata from. For example, page_range=['1', '3'] will extract
+  metadata from the first and third pages of each document. It also accepts printable range strings, e.g.:
+  ['1-3', '5', '8', '10-12'] will extract metadata from pages 1, 2, 3, 5, 8, 10,11, 12.
+  If None, metadata will be extracted from the entire document for each document in the documents list.
+  This parameter is optional and can be overridden in the `run` method.
+- **raise_on_failure** (<code>bool</code>) – Whether to raise an error on failure during the execution of the Generator or
+  validation of the JSON output.
+- **max_workers** (<code>int</code>) – The maximum number of workers to use in the thread pool executor.
+  This parameter is used limit the maximum number of requests that should be allowed to run concurrently
+  when using the `run_async` method.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the LLM provider component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LLMMetadataExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary with serialized data.
+
+**Returns:**
+
+- <code>LLMMetadataExtractor</code> – An instance of the component.
+
+#### run
+
+```python
+run(
+    documents: list[Document], page_range: list[str | int] | None = None
+) -> dict[str, Any]
+```
+
+Extract metadata from documents using a Large Language Model.
+
+If `page_range` is provided, the metadata will be extracted from the specified range of pages. This component
+will split the documents into pages and extract metadata from the specified range of pages. The metadata will be
+extracted from the entire document if `page_range` is not provided.
+
+The original documents will be returned updated with the extracted metadata.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of documents to extract metadata from.
+- **page_range** (<code>list\[str | int\] | None</code>) – A range of pages to extract metadata from. For example, page_range=['1', '3'] will extract
+  metadata from the first and third pages of each document. It also accepts printable range
+  strings, e.g.: ['1-3', '5', '8', '10-12'] will extract metadata from pages 1, 2, 3, 5, 8, 10,
+  11, 12.
+  If None, metadata will be extracted from the entire document for each document in the
+  documents list.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the keys:
+- "documents": A list of documents that were successfully updated with the extracted metadata.
+- "failed_documents": A list of documents that failed to extract metadata. These documents will have
+  "metadata_extraction_error" and "metadata_extraction_response" in their metadata. These documents can be
+  re-run with the extractor to extract metadata.
+
+#### run_async
+
+```python
+run_async(
+    documents: list[Document], page_range: list[str | int] | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously extract metadata from documents using a Large Language Model.
+
+If `page_range` is provided, the metadata will be extracted from the specified range of pages. This component
+will split the documents into pages and extract metadata from the specified range of pages. The metadata will be
+extracted from the entire document if `page_range` is not provided.
+
+The original documents will be returned updated with the extracted metadata.
+
+This is the asynchronous version of the `run` method. It has the same parameters
+and return values but can be used with `await` in an async code.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of documents to extract metadata from.
+- **page_range** (<code>list\[str | int\] | None</code>) – A range of pages to extract metadata from. For example, page_range=['1', '3'] will extract
+  metadata from the first and third pages of each document. It also accepts printable range
+  strings, e.g.: ['1-3', '5', '8', '10-12'] will extract metadata from pages 1, 2, 3, 5, 8, 10,
+  11, 12.
+  If None, metadata will be extracted from the entire document for each document in the
+  documents list.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the keys:
+- "documents": A list of documents that were successfully updated with the extracted metadata.
+- "failed_documents": A list of documents that failed to extract metadata. These documents will have
+  "metadata_extraction_error" and "metadata_extraction_response" in their metadata. These documents can be
+  re-run with the extractor to extract metadata.
+
+## named_entity_extractor
+
+### NamedEntityExtractorBackend
+
+Bases: <code>Enum</code>
+
+NLP backend to use for Named Entity Recognition.
+
+#### from_str
+
+```python
+from_str(string: str) -> NamedEntityExtractorBackend
+```
+
+Convert a string to a NamedEntityExtractorBackend enum.
+
+### NamedEntityAnnotation
+
+Describes a single NER annotation.
+
+**Parameters:**
+
+- **entity** (<code>str</code>) – Entity label.
+- **start** (<code>int</code>) – Start index of the entity in the document.
+- **end** (<code>int</code>) – End index of the entity in the document.
+- **score** (<code>float | None</code>) – Score calculated by the model.
+
+### NamedEntityExtractor
+
+Annotates named entities in a collection of documents.
+
+The component supports two backends: Hugging Face and spaCy. The
+former can be used with any sequence classification model from the
+[Hugging Face model hub](https://huggingface.co/models), while the
+latter can be used with any [spaCy model](https://spacy.io/models)
+that contains an NER component. Annotations are stored as metadata
+in the documents.
+
+Usage example:
+
+<!-- test-ignore -->
+
+```python
+from haystack import Document
+from haystack.components.extractors.named_entity_extractor import NamedEntityExtractor
+
+documents = [
+    Document(content="I'm Merlin, the happy pig!"),
+    Document(content="My name is Clara and I live in Berkeley, California."),
+]
+extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
+results = extractor.run(documents=documents)["documents"]
+annotations = [NamedEntityExtractor.get_stored_annotations(doc) for doc in results]
+print(annotations)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    backend: str | NamedEntityExtractorBackend,
+    model: str,
+    pipeline_kwargs: dict[str, Any] | None = None,
+    device: ComponentDevice | None = None,
+    token: Secret | None = Secret.from_env_var(
+        ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+    )
+) -> None
+```
+
+Create a Named Entity extractor component.
+
+**Parameters:**
+
+- **backend** (<code>str | NamedEntityExtractorBackend</code>) – Backend to use for NER.
+- **model** (<code>str</code>) – Name of the model or a path to the model on
+  the local disk. Dependent on the backend.
+- **pipeline_kwargs** (<code>dict\[str, Any\] | None</code>) – Keyword arguments passed to the pipeline. The
+  pipeline can override these arguments. Dependent on the backend.
+- **device** (<code>ComponentDevice | None</code>) – The device on which the model is loaded. If `None`,
+  the default device is automatically selected. If a
+  device/device map is specified in `pipeline_kwargs`,
+  it overrides this parameter (only applicable to the
+  HuggingFace backend).
+- **token** (<code>Secret | None</code>) – The API token to download private models from Hugging Face.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the component.
+
+**Raises:**
+
+- <code>ComponentError</code> – If the backend fails to initialize successfully.
+
+#### run
+
+```python
+run(documents: list[Document], batch_size: int = 1) -> dict[str, Any]
+```
+
+Annotate named entities in each document and store the annotations in the document's metadata.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to process.
+- **batch_size** (<code>int</code>) – Batch size used for processing the documents.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Processed documents.
+
+**Raises:**
+
+- <code>ComponentError</code> – If the backend fails to process a document.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NamedEntityExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>NamedEntityExtractor</code> – Deserialized component.
+
+#### initialized
+
+```python
+initialized: bool
+```
+
+Returns if the extractor is ready to annotate text.
+
+#### get_stored_annotations
+
+```python
+get_stored_annotations(
+    document: Document,
+) -> list[NamedEntityAnnotation] | None
+```
+
+Returns the document's named entity annotations stored in its metadata, if any.
+
+**Parameters:**
+
+- **document** (<code>Document</code>) – Document whose annotations are to be fetched.
+
+**Returns:**
+
+- <code>list\[NamedEntityAnnotation\] | None</code> – The stored annotations.
+
+## regex_text_extractor
+
+### RegexTextExtractor
+
+Extracts text from chat message or string input using a regex pattern.
+
+RegexTextExtractor parses input text or ChatMessages using a provided regular expression pattern.
+It can be configured to search through all messages or only the last message in a list of ChatMessages.
+
+### Usage example
+
+```python
+from haystack.components.extractors import RegexTextExtractor
+from haystack.dataclasses import ChatMessage
+
+# Using with a string
+parser = RegexTextExtractor(regex_pattern='<issue url="(.+)">')
+result = parser.run(text_or_messages='<issue url="github.com/hahahaha">hahahah</issue>')
+# result: {"captured_text": "github.com/hahahaha"}
+
+# Using with ChatMessages
+messages = [ChatMessage.from_user('<issue url="github.com/hahahaha">hahahah</issue>')]
+result = parser.run(text_or_messages=messages)
+# result: {"captured_text": "github.com/hahahaha"}
+```
+
+#### __init__
+
+```python
+__init__(regex_pattern: str) -> None
+```
+
+Creates an instance of the RegexTextExtractor component.
+
+**Parameters:**
+
+- **regex_pattern** (<code>str</code>) – The regular expression pattern used to extract text.
+  The pattern should include a capture group to extract the desired text.
+  Example: `'<issue url="(.+)">'` captures `'github.com/hahahaha'` from `'<issue url="github.com/hahahaha">'`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> RegexTextExtractor
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>RegexTextExtractor</code> – The deserialized component.
+
+#### run
+
+```python
+run(text_or_messages: str | list[ChatMessage]) -> dict[str, str]
+```
+
+Extracts text from input using the configured regex pattern.
+
+**Parameters:**
+
+- **text_or_messages** (<code>str | list\[ChatMessage\]</code>) – Either a string or a list of ChatMessage objects to search through.
+
+**Returns:**
+
+- <code>dict\[str, str\]</code> – - `{"captured_text": "matched text"}` if a match is found
+- `{"captured_text": ""}` if no match is found
+
+**Raises:**
+
+- <code>TypeError</code> – if receiving a list the last element is not a ChatMessage instance.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/fetchers_api.md

@@ -0,0 +1,121 @@
+---
+title: "Fetchers"
+id: fetchers-api
+description: "Fetches content from a list of URLs and returns a list of extracted content streams."
+slug: "/fetchers-api"
+---
+
+
+## link_content
+
+### LinkContentFetcher
+
+Fetches and extracts content from URLs.
+
+It supports various content types, retries on failures, and automatic user-agent rotation for failed web
+requests. Use it as the data-fetching step in your pipelines.
+
+You may need to convert LinkContentFetcher's output into a list of documents. Use HTMLToDocument
+converter to do this.
+
+### Usage example
+
+```python
+from haystack.components.fetchers.link_content import LinkContentFetcher
+
+fetcher = LinkContentFetcher()
+streams = fetcher.run(urls=["https://www.google.com"])["streams"]
+
+assert len(streams) == 1
+assert streams[0].meta == {'content_type': 'text/html', 'url': 'https://www.google.com'}
+assert streams[0].data
+```
+
+For async usage:
+
+```python
+import asyncio
+from haystack.components.fetchers import LinkContentFetcher
+
+async def fetch_async():
+    fetcher = LinkContentFetcher()
+    result = await fetcher.run_async(urls=["https://www.google.com"])
+    return result["streams"]
+
+streams = asyncio.run(fetch_async())
+```
+
+#### __init__
+
+```python
+__init__(
+    raise_on_failure: bool = True,
+    user_agents: list[str] | None = None,
+    retry_attempts: int = 2,
+    timeout: int = 3,
+    http2: bool = False,
+    client_kwargs: dict | None = None,
+    request_headers: dict[str, str] | None = None,
+) -> None
+```
+
+Initializes the component.
+
+**Parameters:**
+
+- **raise_on_failure** (<code>bool</code>) – If `True`, raises an exception if it fails to fetch a single URL.
+  For multiple URLs, it logs errors and returns the content it successfully fetched.
+- **user_agents** (<code>list\[str\] | None</code>) – [User agents](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)
+  for fetching content. If `None`, a default user agent is used.
+- **retry_attempts** (<code>int</code>) – The number of times to retry to fetch the URL's content.
+- **timeout** (<code>int</code>) – Timeout in seconds for the request.
+- **http2** (<code>bool</code>) – Whether to enable HTTP/2 support for requests. Defaults to False.
+  Requires the 'h2' package to be installed (via `pip install httpx[http2]`).
+- **client_kwargs** (<code>dict | None</code>) – Additional keyword arguments to pass to the httpx client.
+  If `None`, default values are used.
+
+#### run
+
+```python
+run(urls: list[str]) -> dict[str, Any]
+```
+
+Fetches content from a list of URLs and returns a list of extracted content streams.
+
+Each content stream is a `ByteStream` object containing the extracted content as binary data.
+Each ByteStream object in the returned list corresponds to the contents of a single URL.
+The content type of each stream is stored in the metadata of the ByteStream object under
+the key "content_type". The URL of the fetched content is stored under the key "url".
+
+**Parameters:**
+
+- **urls** (<code>list\[str\]</code>) – A list of URLs to fetch content from.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – `ByteStream` objects representing the extracted content.
+
+**Raises:**
+
+- <code>Exception</code> – If the provided list of URLs contains only a single URL, and `raise_on_failure` is set to
+  `True`, an exception will be raised in case of an error during content retrieval.
+  In all other scenarios, any retrieval errors are logged, and a list of successfully retrieved `ByteStream`
+  objects is returned.
+
+#### run_async
+
+```python
+run_async(urls: list[str]) -> dict[str, Any]
+```
+
+Asynchronously fetches content from a list of URLs and returns a list of extracted content streams.
+
+This is the asynchronous version of the `run` method with the same parameters and return values.
+
+**Parameters:**
+
+- **urls** (<code>list\[str\]</code>) – A list of URLs to fetch content from.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – `ByteStream` objects representing the extracted content.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/human_in_the_loop_api.md

@@ -0,0 +1,362 @@
+---
+title: "Human-in-the-Loop"
+id: human-in-the-loop-api
+description: "Abstractions for integrating human feedback and interaction into Agent workflows."
+slug: "/human-in-the-loop-api"
+---
+
+
+## dataclasses
+
+### ConfirmationUIResult
+
+Result of the confirmation UI interaction.
+
+**Parameters:**
+
+- **action** (<code>str</code>) – The action taken by the user such as "confirm", "reject", or "modify".
+  This action type is not enforced to allow for custom actions to be implemented.
+- **feedback** (<code>str | None</code>) – Optional feedback message from the user. For example, if the user rejects the tool execution,
+  they might provide a reason for the rejection.
+- **new_tool_params** (<code>dict\[str, Any\] | None</code>) – Optional set of new parameters for the tool. For example, if the user chooses to modify the tool parameters,
+  they can provide a new set of parameters here.
+
+### ToolExecutionDecision
+
+Decision made regarding tool execution.
+
+**Parameters:**
+
+- **tool_name** (<code>str</code>) – The name of the tool to be executed.
+- **execute** (<code>bool</code>) – A boolean indicating whether to execute the tool with the provided parameters.
+- **tool_call_id** (<code>str | None</code>) – Optional unique identifier for the tool call. This can be used to track and correlate the decision with a
+  specific tool invocation.
+- **feedback** (<code>str | None</code>) – Optional feedback message.
+  For example, if the tool execution is rejected, this can contain the reason. Or if the tool parameters were
+  modified, this can contain the modification details.
+- **final_tool_params** (<code>dict\[str, Any\] | None</code>) – Optional final parameters for the tool if execution is confirmed or modified.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Convert the ToolExecutionDecision to a dictionary representation.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary containing the tool execution decision details.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ToolExecutionDecision
+```
+
+Populate the ToolExecutionDecision from a dictionary representation.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – A dictionary containing the tool execution decision details.
+
+**Returns:**
+
+- <code>ToolExecutionDecision</code> – An instance of ToolExecutionDecision.
+
+## policies
+
+### AlwaysAskPolicy
+
+Bases: <code>ConfirmationPolicy</code>
+
+Always ask for confirmation.
+
+#### should_ask
+
+```python
+should_ask(
+    tool_name: str, tool_description: str, tool_params: dict[str, Any]
+) -> bool
+```
+
+Always ask for confirmation before executing the tool.
+
+**Parameters:**
+
+- **tool_name** (<code>str</code>) – The name of the tool to be executed.
+- **tool_description** (<code>str</code>) – The description of the tool.
+- **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
+
+**Returns:**
+
+- <code>bool</code> – Always returns True, indicating confirmation is needed.
+
+### NeverAskPolicy
+
+Bases: <code>ConfirmationPolicy</code>
+
+Never ask for confirmation.
+
+#### should_ask
+
+```python
+should_ask(
+    tool_name: str, tool_description: str, tool_params: dict[str, Any]
+) -> bool
+```
+
+Never ask for confirmation, always proceed with tool execution.
+
+**Parameters:**
+
+- **tool_name** (<code>str</code>) – The name of the tool to be executed.
+- **tool_description** (<code>str</code>) – The description of the tool.
+- **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
+
+**Returns:**
+
+- <code>bool</code> – Always returns False, indicating no confirmation is needed.
+
+### AskOncePolicy
+
+Bases: <code>ConfirmationPolicy</code>
+
+Ask only once per tool with specific parameters.
+
+#### __init__
+
+```python
+__init__() -> None
+```
+
+Creates an instance of AskOncePolicy.
+
+#### should_ask
+
+```python
+should_ask(
+    tool_name: str, tool_description: str, tool_params: dict[str, Any]
+) -> bool
+```
+
+Ask for confirmation only once per tool with specific parameters.
+
+**Parameters:**
+
+- **tool_name** (<code>str</code>) – The name of the tool to be executed.
+- **tool_description** (<code>str</code>) – The description of the tool.
+- **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
+
+**Returns:**
+
+- <code>bool</code> – True if confirmation is needed, False if already asked with the same parameters.
+
+#### update_after_confirmation
+
+```python
+update_after_confirmation(
+    tool_name: str,
+    tool_description: str,
+    tool_params: dict[str, Any],
+    confirmation_result: ConfirmationUIResult,
+) -> None
+```
+
+Store the tool and parameters if the action was "confirm" to avoid asking again.
+
+This method updates the internal state to remember that the user has already confirmed the execution of the
+tool with the given parameters.
+
+**Parameters:**
+
+- **tool_name** (<code>str</code>) – The name of the tool that was executed.
+- **tool_description** (<code>str</code>) – The description of the tool.
+- **tool_params** (<code>dict\[str, Any\]</code>) – The parameters that were passed to the tool.
+- **confirmation_result** (<code>ConfirmationUIResult</code>) – The result from the confirmation UI.
+
+## strategies
+
+### BlockingConfirmationStrategy
+
+Confirmation strategy that blocks execution to gather user feedback.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    confirmation_policy: ConfirmationPolicy,
+    confirmation_ui: ConfirmationUI,
+    reject_template: str = REJECTION_FEEDBACK_TEMPLATE,
+    modify_template: str = MODIFICATION_FEEDBACK_TEMPLATE,
+    user_feedback_template: str = USER_FEEDBACK_TEMPLATE
+) -> None
+```
+
+Initialize the BlockingConfirmationStrategy with a confirmation policy and UI.
+
+**Parameters:**
+
+- **confirmation_policy** (<code>ConfirmationPolicy</code>) – The confirmation policy to determine when to ask for user confirmation.
+- **confirmation_ui** (<code>ConfirmationUI</code>) – The user interface to interact with the user for confirmation.
+- **reject_template** (<code>str</code>) – Template for rejection feedback messages. It should include a `{tool_name}` placeholder.
+- **modify_template** (<code>str</code>) – Template for modification feedback messages. It should include `{tool_name}` and `{final_tool_params}`
+  placeholders.
+- **user_feedback_template** (<code>str</code>) – Template for user feedback messages. It should include a `{feedback}` placeholder.
+
+#### run
+
+```python
+run(
+    *,
+    tool_name: str,
+    tool_description: str,
+    tool_params: dict[str, Any],
+    tool_call_id: str | None = None,
+    confirmation_strategy_context: dict[str, Any] | None = None
+) -> ToolExecutionDecision
+```
+
+Run the human-in-the-loop strategy for a given tool and its parameters.
+
+**Parameters:**
+
+- **tool_name** (<code>str</code>) – The name of the tool to be executed.
+- **tool_description** (<code>str</code>) – The description of the tool.
+- **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
+- **tool_call_id** (<code>str | None</code>) – Optional unique identifier for the tool call. This can be used to track and correlate the decision with a
+  specific tool invocation.
+- **confirmation_strategy_context** (<code>dict\[str, Any\] | None</code>) – Optional dictionary for passing request-scoped resources. Useful in web/server environments
+  to provide per-request objects (e.g., WebSocket connections, async queues, Redis pub/sub clients)
+  that strategies can use for non-blocking user interaction.
+
+**Returns:**
+
+- <code>ToolExecutionDecision</code> – A ToolExecutionDecision indicating whether to execute the tool with the given parameters, or a
+  feedback message if rejected.
+
+#### run_async
+
+```python
+run_async(
+    *,
+    tool_name: str,
+    tool_description: str,
+    tool_params: dict[str, Any],
+    tool_call_id: str | None = None,
+    confirmation_strategy_context: dict[str, Any] | None = None
+) -> ToolExecutionDecision
+```
+
+Async version of run. Calls the sync run() method by default.
+
+**Parameters:**
+
+- **tool_name** (<code>str</code>) – The name of the tool to be executed.
+- **tool_description** (<code>str</code>) – The description of the tool.
+- **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
+- **tool_call_id** (<code>str | None</code>) – Optional unique identifier for the tool call.
+- **confirmation_strategy_context** (<code>dict\[str, Any\] | None</code>) – Optional dictionary for passing request-scoped resources.
+
+**Returns:**
+
+- <code>ToolExecutionDecision</code> – A ToolExecutionDecision indicating whether to execute the tool with the given parameters.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the BlockingConfirmationStrategy to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> BlockingConfirmationStrategy
+```
+
+Deserializes the BlockingConfirmationStrategy from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>BlockingConfirmationStrategy</code> – Deserialized BlockingConfirmationStrategy.
+
+## user_interfaces
+
+### RichConsoleUI
+
+Bases: <code>ConfirmationUI</code>
+
+Rich console interface for user interaction.
+
+#### __init__
+
+```python
+__init__(console: Console | None = None) -> None
+```
+
+Creates an instance of RichConsoleUI.
+
+#### get_user_confirmation
+
+```python
+get_user_confirmation(
+    tool_name: str, tool_description: str, tool_params: dict[str, Any]
+) -> ConfirmationUIResult
+```
+
+Get user confirmation for tool execution via rich console prompts.
+
+**Parameters:**
+
+- **tool_name** (<code>str</code>) – The name of the tool to be executed.
+- **tool_description** (<code>str</code>) – The description of the tool.
+- **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
+
+**Returns:**
+
+- <code>ConfirmationUIResult</code> – ConfirmationUIResult based on user input.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the RichConsoleConfirmationUI to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+### SimpleConsoleUI
+
+Bases: <code>ConfirmationUI</code>
+
+Simple console interface using standard input/output.
+
+#### get_user_confirmation
+
+```python
+get_user_confirmation(
+    tool_name: str, tool_description: str, tool_params: dict[str, Any]
+) -> ConfirmationUIResult
+```
+
+Get user confirmation for tool execution via simple console prompts.
+
+**Parameters:**
+
+- **tool_name** (<code>str</code>) – The name of the tool to be executed.
+- **tool_description** (<code>str</code>) – The description of the tool.
+- **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/image_converters_api.md

@@ -0,0 +1,353 @@
+---
+title: "Image Converters"
+id: image-converters-api
+description: "Various converters to transform image data from one format to another."
+slug: "/image-converters-api"
+---
+
+
+## document_to_image
+
+### DocumentToImageContent
+
+Converts documents sourced from PDF and image files into ImageContents.
+
+This component processes a list of documents and extracts visual content from supported file formats, converting
+them into ImageContents that can be used for multimodal AI tasks. It handles both direct image files and PDF
+documents by extracting specific pages as images.
+
+Documents are expected to have metadata containing:
+
+- The `file_path_meta_field` key with a valid file path that exists when combined with `root_path`
+- A supported image format (MIME type must be one of the supported image types)
+- For PDF files, a `page_number` key specifying which page to extract
+
+### Usage example
+
+<!-- test-ignore -->
+
+```python
+from haystack import Document
+from haystack.components.converters.image.document_to_image import DocumentToImageContent
+
+converter = DocumentToImageContent(
+    file_path_meta_field="file_path",
+    root_path="/data/files",
+    detail="high",
+    size=(800, 600)
+)
+
+documents = [
+    Document(content="Optional description of image.jpg", meta={"file_path": "image.jpg"}),
+    Document(content="Text content of page 1 of doc.pdf", meta={"file_path": "doc.pdf", "page_number": 1})
+]
+
+result = converter.run(documents)
+image_contents = result["image_contents"]
+# [ImageContent(
+#    base64_image='/9j/4A...', mime_type='image/jpeg', detail='high', meta={'file_path': 'image.jpg'}
+#  ),
+#  ImageContent(
+#    base64_image='/9j/4A...', mime_type='image/jpeg', detail='high',
+#    meta={'page_number': 1, 'file_path': 'doc.pdf'}
+#  )]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    file_path_meta_field: str = "file_path",
+    root_path: str | None = None,
+    detail: Literal["auto", "high", "low"] | None = None,
+    size: tuple[int, int] | None = None
+) -> None
+```
+
+Initialize the DocumentToImageContent component.
+
+**Parameters:**
+
+- **file_path_meta_field** (<code>str</code>) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (<code>str | None</code>) – The root directory path where document files are located. If provided, file paths in
+  document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **detail** (<code>Literal['auto', 'high', 'low'] | None</code>) – Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low".
+  This will be passed to the created ImageContent objects.
+- **size** (<code>tuple\[int, int\] | None</code>) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+  maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+  when working with models that have resolution constraints or when transmitting images to remote services.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[ImageContent | None]]
+```
+
+Convert documents with image or PDF sources into ImageContent objects.
+
+This method processes the input documents, extracting images from supported file formats and converting them
+into ImageContent objects.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to process. Each document should have metadata containing at minimum
+  a 'file_path_meta_field' key. PDF documents additionally require a 'page_number' key to specify which
+  page to convert.
+
+**Returns:**
+
+- <code>dict\[str, list\[ImageContent | None\]\]</code> – Dictionary containing one key:
+- "image_contents": ImageContents created from the processed documents. These contain base64-encoded image
+  data and metadata. The order corresponds to order of input documents.
+
+**Raises:**
+
+- <code>ValueError</code> – If any document is missing the required metadata keys, has an invalid file path, or has an unsupported
+  MIME type. The error message will specify which document and what information is missing or incorrect.
+
+## file_to_document
+
+### ImageFileToDocument
+
+Converts image file references into empty Document objects with associated metadata.
+
+This component is useful in pipelines where image file paths need to be wrapped in `Document` objects to be
+processed by downstream components such as the `SentenceTransformersImageDocumentEmbedder`.
+
+It does **not** extract any content from the image files, instead it creates `Document` objects with `None` as
+their content and attaches metadata such as file path and any user-provided values.
+
+### Usage example
+
+```python
+from haystack.components.converters.image import ImageFileToDocument
+
+converter = ImageFileToDocument()
+
+sources = ["image.jpg", "another_image.png"]
+
+result = converter.run(sources=sources)
+documents = result["documents"]
+
+print(documents)
+
+# [Document(id=..., meta: {'file_path': 'image.jpg'}),
+# Document(id=..., meta: {'file_path': 'another_image.png'})]
+```
+
+#### __init__
+
+```python
+__init__(*, store_full_path: bool = False) -> None
+```
+
+Initialize the ImageFileToDocument component.
+
+**Parameters:**
+
+- **store_full_path** (<code>bool</code>) – If True, the full path of the file is stored in the metadata of the document.
+  If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+    *,
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, list[Document]]
+```
+
+Convert image files into empty Document objects with metadata.
+
+This method accepts image file references (as file paths or ByteStreams) and creates `Document` objects
+without content. These documents are enriched with metadata derived from the input source and optional
+user-provided metadata.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths or ByteStream objects to convert.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the documents.
+  This value can be a list of dictionaries or a single dictionary.
+  If it's a single dictionary, its content is added to the metadata of all produced documents.
+  If it's a list, its length must match the number of sources, as they are zipped together.
+  For ByteStream objects, their `meta` is added to the output documents.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary containing:
+- `documents`: A list of `Document` objects with empty content and associated metadata.
+
+## file_to_image
+
+### ImageFileToImageContent
+
+Converts image files to ImageContent objects.
+
+### Usage example
+
+```python
+from haystack.components.converters.image import ImageFileToImageContent
+
+converter = ImageFileToImageContent()
+
+sources = ["image.jpg", "another_image.png"]
+
+image_contents = converter.run(sources=sources)["image_contents"]
+print(image_contents)
+
+# [ImageContent(base64_image='...',
+#               mime_type='image/jpeg',
+#               detail=None,
+#               meta={'file_path': 'image.jpg'}),
+#  ...]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    detail: Literal["auto", "high", "low"] | None = None,
+    size: tuple[int, int] | None = None
+) -> None
+```
+
+Create the ImageFileToImageContent component.
+
+**Parameters:**
+
+- **detail** (<code>Literal['auto', 'high', 'low'] | None</code>) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+  This will be passed to the created ImageContent objects.
+- **size** (<code>tuple\[int, int\] | None</code>) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+  maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+  when working with models that have resolution constraints or when transmitting images to remote services.
+
+#### run
+
+```python
+run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+    *,
+    detail: Literal["auto", "high", "low"] | None = None,
+    size: tuple[int, int] | None = None
+) -> dict[str, list[ImageContent]]
+```
+
+Converts files to ImageContent objects.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths or ByteStream objects to convert.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the ImageContent objects.
+  This value can be a list of dictionaries or a single dictionary.
+  If it's a single dictionary, its content is added to the metadata of all produced ImageContent objects.
+  If it's a list, its length must match the number of sources as they're zipped together.
+  For ByteStream objects, their `meta` is added to the output ImageContent objects.
+- **detail** (<code>Literal['auto', 'high', 'low'] | None</code>) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+  This will be passed to the created ImageContent objects.
+  If not provided, the detail level will be the one set in the constructor.
+- **size** (<code>tuple\[int, int\] | None</code>) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+  maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+  when working with models that have resolution constraints or when transmitting images to remote services.
+  If not provided, the size value will be the one set in the constructor.
+
+**Returns:**
+
+- <code>dict\[str, list\[ImageContent\]\]</code> – A dictionary with the following keys:
+- `image_contents`: A list of ImageContent objects.
+
+## pdf_to_image
+
+### PDFToImageContent
+
+Converts PDF files to ImageContent objects.
+
+### Usage example
+
+```python
+from haystack.components.converters.image import PDFToImageContent
+
+converter = PDFToImageContent()
+
+sources = ["file.pdf", "another_file.pdf"]
+
+image_contents = converter.run(sources=sources)["image_contents"]
+print(image_contents)
+
+# [ImageContent(base64_image='...',
+#               mime_type='application/pdf',
+#               detail=None,
+#               meta={'file_path': 'file.pdf', 'page_number': 1}),
+#  ...]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    detail: Literal["auto", "high", "low"] | None = None,
+    size: tuple[int, int] | None = None,
+    page_range: list[str | int] | None = None
+) -> None
+```
+
+Create the PDFToImageContent component.
+
+**Parameters:**
+
+- **detail** (<code>Literal['auto', 'high', 'low'] | None</code>) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+  This will be passed to the created ImageContent objects.
+- **size** (<code>tuple\[int, int\] | None</code>) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+  maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+  when working with models that have resolution constraints or when transmitting images to remote services.
+- **page_range** (<code>list\[str | int\] | None</code>) – List of page numbers and/or page ranges to convert to images. Page numbers start at 1.
+  If None, all pages in the PDF will be converted. Pages outside the valid range (1 to number of pages)
+  will be skipped with a warning. For example, page_range=[1, 3] will convert only the first and third
+  pages of the document. It also accepts printable range strings, e.g.: ['1-3', '5', '8', '10-12']
+  will convert pages 1, 2, 3, 5, 8, 10, 11, 12.
+
+#### run
+
+```python
+run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+    *,
+    detail: Literal["auto", "high", "low"] | None = None,
+    size: tuple[int, int] | None = None,
+    page_range: list[str | int] | None = None
+) -> dict[str, list[ImageContent]]
+```
+
+Converts files to ImageContent objects.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths or ByteStream objects to convert.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the ImageContent objects.
+  This value can be a list of dictionaries or a single dictionary.
+  If it's a single dictionary, its content is added to the metadata of all produced ImageContent objects.
+  If it's a list, its length must match the number of sources as they're zipped together.
+  For ByteStream objects, their `meta` is added to the output ImageContent objects.
+- **detail** (<code>Literal['auto', 'high', 'low'] | None</code>) – Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
+  This will be passed to the created ImageContent objects.
+  If not provided, the detail level will be the one set in the constructor.
+- **size** (<code>tuple\[int, int\] | None</code>) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+  maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+  when working with models that have resolution constraints or when transmitting images to remote services.
+  If not provided, the size value will be the one set in the constructor.
+- **page_range** (<code>list\[str | int\] | None</code>) – List of page numbers and/or page ranges to convert to images. Page numbers start at 1.
+  If None, all pages in the PDF will be converted. Pages outside the valid range (1 to number of pages)
+  will be skipped with a warning. For example, page_range=[1, 3] will convert only the first and third
+  pages of the document. It also accepts printable range strings, e.g.: ['1-3', '5', '8', '10-12']
+  will convert pages 1, 2, 3, 5, 8, 10, 11, 12.
+  If not provided, the page_range value will be the one set in the constructor.
+
+**Returns:**
+
+- <code>dict\[str, list\[ImageContent\]\]</code> – A dictionary with the following keys:
+- `image_contents`: A list of ImageContent objects.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/joiners_api.md

@@ -0,0 +1,566 @@
+---
+title: "Joiners"
+id: joiners-api
+description: "Components that join list of different objects"
+slug: "/joiners-api"
+---
+
+
+## answer_joiner
+
+### JoinMode
+
+Bases: <code>Enum</code>
+
+Enum for AnswerJoiner join modes.
+
+#### from_str
+
+```python
+from_str(string: str) -> JoinMode
+```
+
+Convert a string to a JoinMode enum.
+
+### AnswerJoiner
+
+Merges multiple lists of `Answer` objects into a single list.
+
+Use this component to combine answers from different Generators into a single list.
+Currently, the component supports only one join mode: `CONCATENATE`.
+This mode concatenates multiple lists of answers into a single list.
+
+### Usage example
+
+In this example, AnswerJoiner merges answers from two different Generators:
+
+```python
+from haystack.components.builders import AnswerBuilder
+from haystack.components.joiners import AnswerJoiner
+
+from haystack.core.pipeline import Pipeline
+
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+
+query = "What's Natural Language Processing?"
+messages = [ChatMessage.from_system("You are a helpful, respectful and honest assistant. Be super concise."),
+            ChatMessage.from_user(query)]
+
+pipe = Pipeline()
+pipe.add_component("llm_1", OpenAIChatGenerator())
+pipe.add_component("llm_2", OpenAIChatGenerator())
+pipe.add_component("aba", AnswerBuilder())
+pipe.add_component("abb", AnswerBuilder())
+pipe.add_component("joiner", AnswerJoiner())
+
+pipe.connect("llm_1.replies", "aba")
+pipe.connect("llm_2.replies", "abb")
+pipe.connect("aba.answers", "joiner")
+pipe.connect("abb.answers", "joiner")
+
+results = pipe.run(data={"llm_1": {"messages": messages},
+                            "llm_2": {"messages": messages},
+                            "aba": {"query": query},
+                            "abb": {"query": query}})
+```
+
+#### __init__
+
+```python
+__init__(
+    join_mode: str | JoinMode = JoinMode.CONCATENATE,
+    top_k: int | None = None,
+    sort_by_score: bool = False,
+) -> None
+```
+
+Creates an AnswerJoiner component.
+
+**Parameters:**
+
+- **join_mode** (<code>str | JoinMode</code>) – Specifies the join mode to use. Available modes:
+- `concatenate`: Concatenates multiple lists of Answers into a single list.
+- **top_k** (<code>int | None</code>) – The maximum number of Answers to return.
+- **sort_by_score** (<code>bool</code>) – If `True`, sorts the documents by score in descending order.
+  If a document has no score, it is handled as if its score is -infinity.
+
+#### run
+
+```python
+run(
+    answers: Variadic[list[AnswerType]], top_k: int | None = None
+) -> dict[str, Any]
+```
+
+Joins multiple lists of Answers into a single list depending on the `join_mode` parameter.
+
+**Parameters:**
+
+- **answers** (<code>Variadic\[list\[AnswerType\]\]</code>) – Nested list of Answers to be merged.
+- **top_k** (<code>int | None</code>) – The maximum number of Answers to return. Overrides the instance's `top_k` if provided.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `answers`: Merged list of Answers
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AnswerJoiner
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AnswerJoiner</code> – The deserialized component.
+
+## branch
+
+### BranchJoiner
+
+A component that merges multiple input branches of a pipeline into a single output stream.
+
+`BranchJoiner` receives multiple inputs of the same data type and forwards the first received value
+to its output. This is useful for scenarios where multiple branches need to converge before proceeding.
+
+### Common Use Cases:
+
+- **Loop Handling:** `BranchJoiner` helps close loops in pipelines. For example, if a pipeline component validates
+  or modifies incoming data and produces an error-handling branch, `BranchJoiner` can merge both branches and send
+  (or resend in the case of a loop) the data to the component that evaluates errors. See "Usage example" below.
+
+- **Decision-Based Merging:** `BranchJoiner` reconciles branches coming from Router components (such as
+  `ConditionalRouter`, `TextLanguageRouter`). Suppose a `TextLanguageRouter` directs user queries to different
+  Retrievers based on the detected language. Each Retriever processes its assigned query and passes the results
+  to `BranchJoiner`, which consolidates them into a single output before passing them to the next component, such
+  as a `PromptBuilder`.
+
+### Example Usage:
+
+```python
+import json
+
+from haystack import Pipeline
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.joiners import BranchJoiner
+from haystack.components.validators import JsonSchemaValidator
+from haystack.dataclasses import ChatMessage
+
+# Define a schema for validation
+person_schema = {
+    "type": "object",
+    "properties": {
+        "first_name": {"type": "string", "pattern": "^[A-Z][a-z]+$"},
+        "last_name": {"type": "string", "pattern": "^[A-Z][a-z]+$"},
+        "nationality": {"type": "string", "enum": ["Italian", "Portuguese", "American"]},
+    },
+    "required": ["first_name", "last_name", "nationality"]
+}
+
+# Initialize a pipeline
+pipe = Pipeline()
+
+# Add components to the pipeline
+pipe.add_component("joiner", BranchJoiner(list[ChatMessage]))
+pipe.add_component("generator", OpenAIChatGenerator(model="gpt-4.1-mini"))
+pipe.add_component("validator", JsonSchemaValidator(json_schema=person_schema))
+
+# And connect them
+pipe.connect("joiner", "generator")
+pipe.connect("generator.replies", "validator.messages")
+pipe.connect("validator.validation_error", "joiner")
+
+result = pipe.run(
+    data={
+    "generator": {"generation_kwargs": {"response_format": {"type": "json_object"}}},
+    "joiner": {"value": [ChatMessage.from_user("Create json from Peter Parker")]}}
+)
+
+print(json.loads(result["validator"]["validated"][0].text))
+
+
+# >> {'first_name': 'Peter', 'last_name': 'Parker', 'nationality': 'American', 'name': 'Spider-Man', 'occupation':
+# >> 'Superhero', 'age': 23, 'location': 'New York City'}
+```
+
+Note that `BranchJoiner` can manage only one data type at a time. In this case, `BranchJoiner` is created for
+passing `list[ChatMessage]`. This determines the type of data that `BranchJoiner` will receive from the upstream
+connected components and also the type of data that `BranchJoiner` will send through its output.
+
+In the code example, `BranchJoiner` receives a looped back `list[ChatMessage]` from the `JsonSchemaValidator` and
+sends it down to the `OpenAIChatGenerator` for re-generation. We can have multiple loopback connections in the
+pipeline. In this instance, the downstream component is only one (the `OpenAIChatGenerator`), but the pipeline could
+have more than one downstream component.
+
+#### __init__
+
+```python
+__init__(type_: type) -> None
+```
+
+Creates a `BranchJoiner` component.
+
+**Parameters:**
+
+- **type\_** (<code>type</code>) – The expected data type of inputs and outputs.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component into a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> BranchJoiner
+```
+
+Deserializes a `BranchJoiner` instance from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary containing serialized component data.
+
+**Returns:**
+
+- <code>BranchJoiner</code> – A deserialized `BranchJoiner` instance.
+
+#### run
+
+```python
+run(**kwargs: Any) -> dict[str, Any]
+```
+
+Executes the `BranchJoiner`, selecting the first available input value and passing it downstream.
+
+**Parameters:**
+
+- \*\***kwargs** (<code>Any</code>) – The input data. Must be of the type declared by `type_` during initialization.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with a single key `value`, containing the first input received.
+
+## document_joiner
+
+### JoinMode
+
+Bases: <code>Enum</code>
+
+Enum for join mode.
+
+#### from_str
+
+```python
+from_str(string: str) -> JoinMode
+```
+
+Convert a string to a JoinMode enum.
+
+### DocumentJoiner
+
+Joins multiple lists of documents into a single list.
+
+It supports different join modes:
+
+- concatenate: Keeps the highest-scored document in case of duplicates.
+- merge: Calculates a weighted sum of scores for duplicates and merges them.
+- reciprocal_rank_fusion: Merges and assigns scores based on reciprocal rank fusion.
+- distribution_based_rank_fusion: Merges and assigns scores based on scores distribution in each Retriever.
+
+### Usage example:
+
+```python
+from haystack import Pipeline, Document
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack.components.joiners import DocumentJoiner
+from haystack.components.retrievers import InMemoryBM25Retriever
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+document_store = InMemoryDocumentStore()
+docs = [Document(content="Paris"), Document(content="Berlin"), Document(content="London")]
+embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
+docs_embeddings = embedder.run(docs)
+document_store.write_documents(docs_embeddings['documents'])
+
+p = Pipeline()
+p.add_component(instance=InMemoryBM25Retriever(document_store=document_store), name="bm25_retriever")
+p.add_component(
+        instance=SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"),
+        name="text_embedder",
+    )
+p.add_component(instance=InMemoryEmbeddingRetriever(document_store=document_store), name="embedding_retriever")
+p.add_component(instance=DocumentJoiner(), name="joiner")
+p.connect("bm25_retriever", "joiner")
+p.connect("embedding_retriever", "joiner")
+p.connect("text_embedder", "embedding_retriever")
+query = "What is the capital of France?"
+p.run(data={"query": query, "text": query, "top_k": 1})
+```
+
+#### __init__
+
+```python
+__init__(
+    join_mode: str | JoinMode = JoinMode.CONCATENATE,
+    weights: list[float] | None = None,
+    top_k: int | None = None,
+    sort_by_score: bool = True,
+) -> None
+```
+
+Creates a DocumentJoiner component.
+
+**Parameters:**
+
+- **join_mode** (<code>str | JoinMode</code>) – Specifies the join mode to use. Available modes:
+- `concatenate`: Keeps the highest-scored document in case of duplicates.
+- `merge`: Calculates a weighted sum of scores for duplicates and merges them.
+- `reciprocal_rank_fusion`: Merges and assigns scores based on reciprocal rank fusion.
+- `distribution_based_rank_fusion`: Merges and assigns scores based on scores
+  distribution in each Retriever.
+- **weights** (<code>list\[float\] | None</code>) – Assign importance to each list of documents to influence how they're joined.
+  This parameter is ignored for
+  `concatenate` or `distribution_based_rank_fusion` join modes.
+  Weight for each list of documents must match the number of inputs.
+- **top_k** (<code>int | None</code>) – The maximum number of documents to return.
+- **sort_by_score** (<code>bool</code>) – If `True`, sorts the documents by score in descending order.
+  If a document has no score, it is handled as if its score is -infinity.
+
+#### run
+
+```python
+run(
+    documents: Variadic[list[Document]], top_k: int | None = None
+) -> dict[str, Any]
+```
+
+Joins multiple lists of Documents into a single list depending on the `join_mode` parameter.
+
+**Parameters:**
+
+- **documents** (<code>Variadic\[list\[Document\]\]</code>) – List of list of documents to be merged.
+- **top_k** (<code>int | None</code>) – The maximum number of documents to return. Overrides the instance's `top_k` if provided.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: Merged list of Documents
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DocumentJoiner
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>DocumentJoiner</code> – The deserialized component.
+
+## list_joiner
+
+### ListJoiner
+
+A component that joins multiple lists into a single flat list.
+
+The ListJoiner receives multiple lists of the same type and concatenates them into a single flat list.
+The output order respects the pipeline's execution sequence, with earlier inputs being added first.
+
+Usage example:
+
+```python
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack import Pipeline
+from haystack.components.joiners import ListJoiner
+
+
+user_message = [ChatMessage.from_user("Give a brief answer the following question: {{query}}")]
+
+feedback_prompt = """
+    You are given a question and an answer.
+    Your task is to provide a score and a brief feedback on the answer.
+    Question: {{query}}
+    Answer: {{response}}
+    """
+feedback_message = [ChatMessage.from_system(feedback_prompt)]
+
+prompt_builder = ChatPromptBuilder(template=user_message)
+feedback_prompt_builder = ChatPromptBuilder(template=feedback_message)
+llm = OpenAIChatGenerator()
+feedback_llm = OpenAIChatGenerator()
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.add_component("feedback_prompt_builder", feedback_prompt_builder)
+pipe.add_component("feedback_llm", feedback_llm)
+pipe.add_component("list_joiner", ListJoiner(list[ChatMessage]))
+
+pipe.connect("prompt_builder.prompt", "llm.messages")
+pipe.connect("prompt_builder.prompt", "list_joiner")
+pipe.connect("llm.replies", "list_joiner")
+pipe.connect("llm.replies", "feedback_prompt_builder.response")
+pipe.connect("feedback_prompt_builder.prompt", "feedback_llm.messages")
+pipe.connect("feedback_llm.replies", "list_joiner")
+
+query = "What is nuclear physics?"
+ans = pipe.run(data={"prompt_builder": {"template_variables":{"query": query}},
+    "feedback_prompt_builder": {"template_variables":{"query": query}}})
+
+print(ans["list_joiner"]["values"])
+```
+
+#### __init__
+
+```python
+__init__(list_type_: type | None = None) -> None
+```
+
+Creates a ListJoiner component.
+
+**Parameters:**
+
+- **list_type\_** (<code>type | None</code>) – The expected type of the lists this component will join (e.g., list[ChatMessage]).
+  If specified, all input lists must conform to this type. If None, the component defaults to handling
+  lists of any type including mixed types.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ListJoiner
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ListJoiner</code> – Deserialized component.
+
+#### run
+
+```python
+run(values: Variadic[list[Any]]) -> dict[str, list[Any]]
+```
+
+Joins multiple lists into a single flat list.
+
+**Parameters:**
+
+- **values** (<code>Variadic\[list\[Any\]\]</code>) – The list to be joined.
+
+**Returns:**
+
+- <code>dict\[str, list\[Any\]\]</code> – Dictionary with 'values' key containing the joined list.
+
+## string_joiner
+
+### StringJoiner
+
+Component to join strings from different components to a list of strings.
+
+### Usage example
+
+```python
+from haystack.components.joiners import StringJoiner
+from haystack.components.builders import PromptBuilder
+from haystack.core.pipeline import Pipeline
+
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+string_1 = "What's Natural Language Processing?"
+string_2 = "What is life?"
+
+pipeline = Pipeline()
+pipeline.add_component("prompt_builder_1", PromptBuilder("Builder 1: {{query}}"))
+pipeline.add_component("prompt_builder_2", PromptBuilder("Builder 2: {{query}}"))
+pipeline.add_component("string_joiner", StringJoiner())
+
+pipeline.connect("prompt_builder_1.prompt", "string_joiner.strings")
+pipeline.connect("prompt_builder_2.prompt", "string_joiner.strings")
+
+print(pipeline.run(data={"prompt_builder_1": {"query": string_1}, "prompt_builder_2": {"query": string_2}}))
+
+# >> {"string_joiner": {"strings": ["Builder 1: What's Natural Language Processing?", "Builder 2: What is life?"]}}
+```
+
+#### run
+
+```python
+run(strings: Variadic[str]) -> dict[str, list[str]]
+```
+
+Joins strings into a list of strings
+
+**Parameters:**
+
+- **strings** (<code>Variadic\[str\]</code>) – strings from different components
+
+**Returns:**
+
+- <code>dict\[str, list\[str\]\]</code> – A dictionary with the following keys:
+- `strings`: Merged list of strings

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/pipeline_api.md

@@ -0,0 +1,497 @@
+---
+title: "Pipeline"
+id: pipeline-api
+description: "Arranges components and integrations in flow."
+slug: "/pipeline-api"
+---
+
+
+## async_pipeline
+
+### AsyncPipeline
+
+Bases: <code>PipelineBase</code>
+
+Asynchronous version of the Pipeline orchestration engine.
+
+Manages components in a pipeline allowing for concurrent processing when the pipeline's execution graph permits.
+This enables efficient processing of components by minimizing idle time and maximizing resource utilization.
+
+#### run_async_generator
+
+```python
+run_async_generator(
+    data: dict[str, Any],
+    include_outputs_from: set[str] | None = None,
+    concurrency_limit: int = 4,
+) -> AsyncIterator[dict[str, Any]]
+```
+
+Executes the pipeline step by step asynchronously, yielding partial outputs when any component finishes.
+
+Usage:
+
+```python
+from haystack import Document
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack import AsyncPipeline
+import asyncio
+
+# Write documents to InMemoryDocumentStore
+document_store = InMemoryDocumentStore()
+document_store.write_documents([
+    Document(content="My name is Jean and I live in Paris."),
+    Document(content="My name is Mark and I live in Berlin."),
+    Document(content="My name is Giorgio and I live in Rome.")
+])
+
+prompt_template = [
+    ChatMessage.from_user(
+        '''
+        Given these documents, answer the question.
+        Documents:
+        {% for doc in documents %}
+            {{ doc.content }}
+        {% endfor %}
+        Question: {{question}}
+        Answer:
+        ''')
+]
+
+# Create and connect pipeline components
+retriever = InMemoryBM25Retriever(document_store=document_store)
+prompt_builder = ChatPromptBuilder(template=prompt_template)
+llm = OpenAIChatGenerator()
+
+rag_pipeline = AsyncPipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+# Prepare input data
+question = "Who lives in Paris?"
+data = {
+    "retriever": {"query": question},
+    "prompt_builder": {"question": question},
+}
+
+
+# Process results as they become available
+async def process_results():
+    async for partial_output in rag_pipeline.run_async_generator(
+            data=data,
+            include_outputs_from={"retriever", "llm"}
+    ):
+        # Each partial_output contains the results from a completed component
+        if "retriever" in partial_output:
+            print("Retrieved documents:", len(partial_output["retriever"]["documents"]))
+        if "llm" in partial_output:
+            print("Generated answer:", partial_output["llm"]["replies"][0])
+
+
+asyncio.run(process_results())
+```
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Initial input data to the pipeline.
+- **concurrency_limit** (<code>int</code>) – The maximum number of components that are allowed to run concurrently.
+- **include_outputs_from** (<code>set\[str\] | None</code>) – Set of component names whose individual outputs are to be
+  included in the pipeline's output. For components that are
+  invoked multiple times (in a loop), only the last-produced
+  output is included.
+
+**Returns:**
+
+- <code>AsyncIterator\[dict\[str, Any\]\]</code> – An async iterator containing partial (and final) outputs.
+
+**Raises:**
+
+- <code>ValueError</code> – If invalid inputs are provided to the pipeline.
+- <code>PipelineMaxComponentRuns</code> – If a component exceeds the maximum number of allowed executions within the pipeline.
+- <code>PipelineRuntimeError</code> – If the Pipeline contains cycles with unsupported connections that would cause
+  it to get stuck and fail running.
+  Or if a Component fails or returns output in an unsupported type.
+
+#### run_async
+
+```python
+run_async(
+    data: dict[str, Any],
+    include_outputs_from: set[str] | None = None,
+    concurrency_limit: int = 4,
+) -> dict[str, Any]
+```
+
+Provides an asynchronous interface to run the pipeline with provided input data.
+
+This method allows the pipeline to be integrated into an asynchronous workflow, enabling non-blocking
+execution of pipeline components.
+
+Usage:
+
+```python
+import asyncio
+
+from haystack import Document
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.core.pipeline import AsyncPipeline
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+# Write documents to InMemoryDocumentStore
+document_store = InMemoryDocumentStore()
+document_store.write_documents([
+    Document(content="My name is Jean and I live in Paris."),
+    Document(content="My name is Mark and I live in Berlin."),
+    Document(content="My name is Giorgio and I live in Rome.")
+])
+
+prompt_template = [
+    ChatMessage.from_user(
+        '''
+        Given these documents, answer the question.
+        Documents:
+        {% for doc in documents %}
+            {{ doc.content }}
+        {% endfor %}
+        Question: {{question}}
+        Answer:
+        ''')
+]
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+prompt_builder = ChatPromptBuilder(template=prompt_template)
+llm = OpenAIChatGenerator()
+
+rag_pipeline = AsyncPipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+# Ask a question
+question = "Who lives in Paris?"
+
+async def run_inner(data, include_outputs_from):
+    return await rag_pipeline.run_async(data=data, include_outputs_from=include_outputs_from)
+
+data = {
+    "retriever": {"query": question},
+    "prompt_builder": {"question": question},
+}
+
+results = asyncio.run(run_inner(data, include_outputs_from={"retriever", "llm"}))
+
+print(results["llm"]["replies"])
+# [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _content=[TextContent(text='Jean lives in Paris.')],
+# _name=None, _meta={'model': 'gpt-5-mini', 'index': 0, 'finish_reason': 'stop', 'usage':
+# {'completion_tokens': 6, 'prompt_tokens': 69, 'total_tokens': 75,
+# 'completion_tokens_details': CompletionTokensDetails(accepted_prediction_tokens=0,
+# audio_tokens=0, reasoning_tokens=0, rejected_prediction_tokens=0), 'prompt_tokens_details':
+# PromptTokensDetails(audio_tokens=0, cached_tokens=0)}})]
+```
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – A dictionary of inputs for the pipeline's components. Each key is a component name
+  and its value is a dictionary of that component's input parameters:
+
+```
+data = {
+    "comp1": {"input1": 1, "input2": 2},
+}
+```
+
+For convenience, this format is also supported when input names are unique:
+
+```
+data = {
+    "input1": 1, "input2": 2,
+}
+```
+
+- **include_outputs_from** (<code>set\[str\] | None</code>) – Set of component names whose individual outputs are to be
+  included in the pipeline's output. For components that are
+  invoked multiple times (in a loop), only the last-produced
+  output is included.
+- **concurrency_limit** (<code>int</code>) – The maximum number of components that should be allowed to run concurrently.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary where each entry corresponds to a component name
+  and its output. If `include_outputs_from` is `None`, this dictionary
+  will only contain the outputs of leaf components, i.e., components
+  without outgoing connections.
+
+**Raises:**
+
+- <code>ValueError</code> – If invalid inputs are provided to the pipeline.
+- <code>PipelineRuntimeError</code> – If the Pipeline contains cycles with unsupported connections that would cause
+  it to get stuck and fail running.
+  Or if a Component fails or returns output in an unsupported type.
+- <code>PipelineMaxComponentRuns</code> – If a Component reaches the maximum number of times it can be run in this Pipeline.
+
+#### run
+
+```python
+run(
+    data: dict[str, Any],
+    include_outputs_from: set[str] | None = None,
+    concurrency_limit: int = 4,
+) -> dict[str, Any]
+```
+
+Provides a synchronous interface to run the pipeline with given input data.
+
+Internally, the pipeline components are executed asynchronously, but the method itself
+will block until the entire pipeline execution is complete.
+
+In case you need asynchronous methods, consider using `run_async` or `run_async_generator`.
+
+Usage:
+
+```python
+from haystack import Document
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.core.pipeline import AsyncPipeline
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+# Write documents to InMemoryDocumentStore
+document_store = InMemoryDocumentStore()
+document_store.write_documents([
+    Document(content="My name is Jean and I live in Paris."),
+    Document(content="My name is Mark and I live in Berlin."),
+    Document(content="My name is Giorgio and I live in Rome.")
+])
+
+prompt_template = [
+    ChatMessage.from_user(
+        '''
+        Given these documents, answer the question.
+        Documents:
+        {% for doc in documents %}
+            {{ doc.content }}
+        {% endfor %}
+        Question: {{question}}
+        Answer:
+        ''')
+]
+
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+prompt_builder = ChatPromptBuilder(template=prompt_template)
+llm = OpenAIChatGenerator()
+
+rag_pipeline = AsyncPipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+# Ask a question
+question = "Who lives in Paris?"
+
+data = {
+    "retriever": {"query": question},
+    "prompt_builder": {"question": question},
+}
+
+results = rag_pipeline.run(data)
+
+print(results["llm"]["replies"])
+# [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _content=[TextContent(text='Jean lives in Paris.')],
+# _name=None, _meta={'model': 'gpt-5-mini', 'index': 0, 'finish_reason': 'stop', 'usage':
+# {'completion_tokens': 6, 'prompt_tokens': 69, 'total_tokens': 75, 'completion_tokens_details':
+# CompletionTokensDetails(accepted_prediction_tokens=0, audio_tokens=0, reasoning_tokens=0,
+# rejected_prediction_tokens=0), 'prompt_tokens_details': PromptTokensDetails(audio_tokens=0,
+# cached_tokens=0)}})]
+```
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – A dictionary of inputs for the pipeline's components. Each key is a component name
+  and its value is a dictionary of that component's input parameters:
+
+```
+data = {
+    "comp1": {"input1": 1, "input2": 2},
+}
+```
+
+For convenience, this format is also supported when input names are unique:
+
+```
+data = {
+    "input1": 1, "input2": 2,
+}
+```
+
+- **include_outputs_from** (<code>set\[str\] | None</code>) – Set of component names whose individual outputs are to be
+  included in the pipeline's output. For components that are
+  invoked multiple times (in a loop), only the last-produced
+  output is included.
+- **concurrency_limit** (<code>int</code>) – The maximum number of components that should be allowed to run concurrently.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary where each entry corresponds to a component name
+  and its output. If `include_outputs_from` is `None`, this dictionary
+  will only contain the outputs of leaf components, i.e., components
+  without outgoing connections.
+
+**Raises:**
+
+- <code>ValueError</code> – If invalid inputs are provided to the pipeline.
+- <code>PipelineRuntimeError</code> – If the Pipeline contains cycles with unsupported connections that would cause
+  it to get stuck and fail running.
+  Or if a Component fails or returns output in an unsupported type.
+- <code>PipelineMaxComponentRuns</code> – If a Component reaches the maximum number of times it can be run in this Pipeline.
+- <code>RuntimeError</code> – If called from within an async context. Use `run_async` instead.
+
+## pipeline
+
+### Pipeline
+
+Bases: <code>PipelineBase</code>
+
+Synchronous version of the orchestration engine.
+
+Orchestrates component execution according to the execution graph, one after the other.
+
+#### run
+
+```python
+run(
+    data: dict[str, Any],
+    include_outputs_from: set[str] | None = None,
+    *,
+    break_point: Breakpoint | AgentBreakpoint | None = None,
+    pipeline_snapshot: PipelineSnapshot | None = None,
+    snapshot_callback: SnapshotCallback | None = None
+) -> dict[str, Any]
+```
+
+Runs the Pipeline with given input data.
+
+Usage:
+
+```python
+from haystack import Pipeline, Document
+from haystack.components.builders.answer_builder import AnswerBuilder
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.dataclasses import ChatMessage
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.utils import Secret
+
+# Write documents to InMemoryDocumentStore
+document_store = InMemoryDocumentStore()
+document_store.write_documents([
+    Document(content="My name is Jean and I live in Paris."),
+    Document(content="My name is Mark and I live in Berlin."),
+    Document(content="My name is Giorgio and I live in Rome.")
+])
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+
+prompt_template = """
+Given these documents, answer the question.
+Documents:
+{% for doc in documents %}
+    {{ doc.content }}
+{% endfor %}
+Question: {{question}}
+Answer:
+"""
+
+template = [ChatMessage.from_user(prompt_template)]
+prompt_builder = ChatPromptBuilder(
+    template=template,
+    required_variables=["question", "documents"],
+    variables=["question", "documents"]
+)
+
+llm = OpenAIChatGenerator()
+rag_pipeline = Pipeline()
+rag_pipeline.add_component("retriever", retriever)
+rag_pipeline.add_component("prompt_builder", prompt_builder)
+rag_pipeline.add_component("llm", llm)
+rag_pipeline.connect("retriever", "prompt_builder.documents")
+rag_pipeline.connect("prompt_builder", "llm")
+
+question = "Who lives in Paris?"
+results = rag_pipeline.run(
+    {
+        "retriever": {"query": question},
+        "prompt_builder": {"question": question},
+    }
+)
+
+print(results["llm"]["replies"][0].text)
+# Jean lives in Paris
+```
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – A dictionary of inputs for the pipeline's components. Each key is a component name
+  and its value is a dictionary of that component's input parameters:
+
+```
+data = {
+    "comp1": {"input1": 1, "input2": 2},
+}
+```
+
+For convenience, this format is also supported when input names are unique:
+
+```
+data = {
+    "input1": 1, "input2": 2,
+}
+```
+
+- **include_outputs_from** (<code>set\[str\] | None</code>) – Set of component names whose individual outputs are to be
+  included in the pipeline's output. For components that are
+  invoked multiple times (in a loop), only the last-produced
+  output is included.
+- **break_point** (<code>Breakpoint | AgentBreakpoint | None</code>) – A set of breakpoints that can be used to debug the pipeline execution.
+- **pipeline_snapshot** (<code>PipelineSnapshot | None</code>) – A dictionary containing a snapshot of a previously saved pipeline execution.
+- **snapshot_callback** (<code>SnapshotCallback | None</code>) – Optional callback function that is invoked when a pipeline snapshot is created.
+  The callback receives a `PipelineSnapshot` object and can return an optional string
+  (e.g., a file path or identifier).
+  If provided, the callback is used instead of the default file-saving behavior,
+  allowing custom handling of snapshots (e.g., saving to a database, sending to a remote service).
+  If not provided, the default behavior saves snapshots to a JSON file.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary where each entry corresponds to a component name
+  and its output. If `include_outputs_from` is `None`, this dictionary
+  will only contain the outputs of leaf components, i.e., components
+  without outgoing connections.
+
+**Raises:**
+
+- <code>ValueError</code> – If invalid inputs are provided to the pipeline.
+- <code>PipelineRuntimeError</code> – If the Pipeline contains cycles with unsupported connections that would cause
+  it to get stuck and fail running.
+  Or if a Component fails or returns output in an unsupported type.
+- <code>PipelineMaxComponentRuns</code> – If a Component reaches the maximum number of times it can be run in this Pipeline.
+- <code>PipelineBreakpointException</code> – When a pipeline_breakpoint is triggered. Contains the component name, state, and partial results.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/preprocessors_api.md

@@ -0,0 +1,992 @@
+---
+title: "PreProcessors"
+id: preprocessors-api
+description: "Preprocess your Documents and texts. Clean, split, and more."
+slug: "/preprocessors-api"
+---
+
+
+## csv_document_cleaner
+
+### CSVDocumentCleaner
+
+A component for cleaning CSV documents by removing empty rows and columns.
+
+This component processes CSV content stored in Documents, allowing
+for the optional ignoring of a specified number of rows and columns before performing
+the cleaning operation. Additionally, it provides options to keep document IDs and
+control whether empty rows and columns should be removed.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    ignore_rows: int = 0,
+    ignore_columns: int = 0,
+    remove_empty_rows: bool = True,
+    remove_empty_columns: bool = True,
+    keep_id: bool = False
+) -> None
+```
+
+Initializes the CSVDocumentCleaner component.
+
+**Parameters:**
+
+- **ignore_rows** (<code>int</code>) – Number of rows to ignore from the top of the CSV table before processing.
+- **ignore_columns** (<code>int</code>) – Number of columns to ignore from the left of the CSV table before processing.
+- **remove_empty_rows** (<code>bool</code>) – Whether to remove rows that are entirely empty.
+- **remove_empty_columns** (<code>bool</code>) – Whether to remove columns that are entirely empty.
+- **keep_id** (<code>bool</code>) – Whether to retain the original document ID in the output document.
+
+Rows and columns ignored using these parameters are preserved in the final output, meaning
+they are not considered when removing empty rows and columns.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Cleans CSV documents by removing empty rows and columns while preserving specified ignored rows and columns.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of Documents containing CSV-formatted content.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with a list of cleaned Documents under the key "documents".
+
+Processing steps:
+
+1. Reads each document's content as a CSV table.
+1. Retains the specified number of `ignore_rows` from the top and `ignore_columns` from the left.
+1. Drops any rows and columns that are entirely empty (if enabled by `remove_empty_rows` and
+   `remove_empty_columns`).
+1. Reattaches the ignored rows and columns to maintain their original positions.
+1. Returns the cleaned CSV content as a new `Document` object, with an option to retain the original
+   document ID.
+
+## csv_document_splitter
+
+### CSVDocumentSplitter
+
+A component for splitting CSV documents into sub-tables based on split arguments.
+
+The splitter supports two modes of operation:
+
+- identify consecutive empty rows or columns that exceed a given threshold
+  and uses them as delimiters to segment the document into smaller tables.
+- split each row into a separate sub-table, represented as a Document.
+
+#### __init__
+
+```python
+__init__(
+    row_split_threshold: int | None = 2,
+    column_split_threshold: int | None = 2,
+    read_csv_kwargs: dict[str, Any] | None = None,
+    split_mode: SplitMode = "threshold",
+) -> None
+```
+
+Initializes the CSVDocumentSplitter component.
+
+**Parameters:**
+
+- **row_split_threshold** (<code>int | None</code>) – The minimum number of consecutive empty rows required to trigger a split.
+- **column_split_threshold** (<code>int | None</code>) – The minimum number of consecutive empty columns required to trigger a split.
+- **read_csv_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments to pass to `pandas.read_csv`.
+  By default, the component with options:
+- `header=None`
+- `skip_blank_lines=False` to preserve blank lines
+- `dtype=object` to prevent type inference (e.g., converting numbers to floats).
+  See https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html for more information.
+- **split_mode** (<code>SplitMode</code>) – If `threshold`, the component will split the document based on the number of
+  consecutive empty rows or columns that exceed the `row_split_threshold` or `column_split_threshold`.
+  If `row-wise`, the component will split each row into a separate sub-table.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Processes and splits a list of CSV documents into multiple sub-tables.
+
+**Splitting Process:**
+
+1. Applies a row-based split if `row_split_threshold` is provided.
+1. Applies a column-based split if `column_split_threshold` is provided.
+1. If both thresholds are specified, performs a recursive split by rows first, then columns, ensuring
+   further fragmentation of any sub-tables that still contain empty sections.
+1. Sorts the resulting sub-tables based on their original positions within the document.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents containing CSV-formatted content.
+  Each document is assumed to contain one or more tables separated by empty rows or columns.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with a key `"documents"`, mapping to a list of new `Document` objects,
+  each representing an extracted sub-table from the original CSV.
+  The metadata of each document includes:
+  \- A field `source_id` to track the original document.
+  \- A field `row_idx_start` to indicate the starting row index of the sub-table in the original table.
+  \- A field `col_idx_start` to indicate the starting column index of the sub-table in the original table.
+  \- A field `split_id` to indicate the order of the split in the original document.
+  \- All other metadata copied from the original document.
+
+- If a document cannot be processed, it is returned unchanged.
+
+- The `meta` field from the original document is preserved in the split documents.
+
+## document_cleaner
+
+### DocumentCleaner
+
+Cleans the text in the documents.
+
+It removes extra whitespaces,
+empty lines, specified substrings, regexes,
+page headers and footers (in this order).
+
+### Usage example:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentCleaner
+
+doc = Document(content="This   is  a  document  to  clean\n\n\nsubstring to remove")
+
+cleaner = DocumentCleaner(remove_substrings = ["substring to remove"])
+result = cleaner.run(documents=[doc])
+
+assert result["documents"][0].content == "This is a document to clean "
+```
+
+#### __init__
+
+```python
+__init__(
+    remove_empty_lines: bool = True,
+    remove_extra_whitespaces: bool = True,
+    remove_repeated_substrings: bool = False,
+    keep_id: bool = False,
+    remove_substrings: list[str] | None = None,
+    remove_regex: str | None = None,
+    unicode_normalization: Literal["NFC", "NFKC", "NFD", "NFKD"] | None = None,
+    ascii_only: bool = False,
+    strip_whitespaces: bool = False,
+    replace_regexes: dict[str, str] | None = None,
+) -> None
+```
+
+Initialize DocumentCleaner.
+
+**Parameters:**
+
+- **remove_empty_lines** (<code>bool</code>) – If `True`, removes empty lines.
+- **remove_extra_whitespaces** (<code>bool</code>) – If `True`, removes extra whitespaces.
+- **remove_repeated_substrings** (<code>bool</code>) – If `True`, removes repeated substrings (headers and footers) from pages.
+  Pages must be separated by a form feed character "\\f",
+  which is supported by `TextFileToDocument` and `AzureOCRDocumentConverter`.
+- **remove_substrings** (<code>list\[str\] | None</code>) – List of substrings to remove from the text.
+- **remove_regex** (<code>str | None</code>) – Regex to match and replace substrings by "".
+- **keep_id** (<code>bool</code>) – If `True`, keeps the IDs of the original documents.
+- **unicode_normalization** (<code>Literal['NFC', 'NFKC', 'NFD', 'NFKD'] | None</code>) – Unicode normalization form to apply to the text.
+  Note: This will run before any other steps.
+- **ascii_only** (<code>bool</code>) – Whether to convert the text to ASCII only.
+  Will remove accents from characters and replace them with ASCII characters.
+  Other non-ASCII characters will be removed.
+  Note: This will run before any pattern matching or removal.
+- **strip_whitespaces** (<code>bool</code>) – If `True`, removes leading and trailing whitespace from the document content
+  using Python's `str.strip()`. Unlike `remove_extra_whitespaces`, this only affects the beginning
+  and end of the text, preserving internal whitespace (useful for markdown formatting).
+- **replace_regexes** (<code>dict\[str, str\] | None</code>) – A dictionary mapping regex patterns to their replacement strings.
+  For example, `{r'\n\n+': '\n'}` replaces multiple consecutive newlines with a single newline.
+  This is applied after `remove_regex` and allows custom replacements instead of just removal.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Cleans up the documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of Documents to clean.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following key:
+- `documents`: List of cleaned Documents.
+
+**Raises:**
+
+- <code>TypeError</code> – if documents is not a list of Documents.
+
+## document_preprocessor
+
+### DocumentPreprocessor
+
+A SuperComponent that first splits and then cleans documents.
+
+This component consists of a DocumentSplitter followed by a DocumentCleaner in a single pipeline.
+It takes a list of documents as input and returns a processed list of documents.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentPreprocessor
+
+doc = Document(content="I love pizza!")
+preprocessor = DocumentPreprocessor()
+result = preprocessor.run(documents=[doc])
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    split_by: Literal[
+        "function", "page", "passage", "period", "word", "line", "sentence"
+    ] = "word",
+    split_length: int = 250,
+    split_overlap: int = 0,
+    split_threshold: int = 0,
+    splitting_function: Callable[[str], list[str]] | None = None,
+    respect_sentence_boundary: bool = False,
+    language: Language = "en",
+    use_split_rules: bool = True,
+    extend_abbreviations: bool = True,
+    remove_empty_lines: bool = True,
+    remove_extra_whitespaces: bool = True,
+    remove_repeated_substrings: bool = False,
+    keep_id: bool = False,
+    remove_substrings: list[str] | None = None,
+    remove_regex: str | None = None,
+    unicode_normalization: Literal["NFC", "NFKC", "NFD", "NFKD"] | None = None,
+    ascii_only: bool = False
+) -> None
+```
+
+Initialize a DocumentPreProcessor that first splits and then cleans documents.
+
+**Splitter Parameters**:
+
+**Parameters:**
+
+- **split_by** (<code>Literal['function', 'page', 'passage', 'period', 'word', 'line', 'sentence']</code>) – The unit of splitting: "function", "page", "passage", "period", "word", "line", or "sentence".
+- **split_length** (<code>int</code>) – The maximum number of units (words, lines, pages, and so on) in each split.
+- **split_overlap** (<code>int</code>) – The number of overlapping units between consecutive splits.
+- **split_threshold** (<code>int</code>) – The minimum number of units per split. If a split is smaller than this, it's merged
+  with the previous split.
+- **splitting_function** (<code>Callable\\[[str\], list\[str\]\] | None</code>) – A custom function for splitting if `split_by="function"`.
+- **respect_sentence_boundary** (<code>bool</code>) – If `True`, splits by words but tries not to break inside a sentence.
+- **language** (<code>Language</code>) – Language used by the sentence tokenizer if `split_by="sentence"` or
+  `respect_sentence_boundary=True`.
+- **use_split_rules** (<code>bool</code>) – Whether to apply additional splitting heuristics for the sentence splitter.
+- **extend_abbreviations** (<code>bool</code>) – Whether to extend the sentence splitter with curated abbreviations for certain
+  languages.
+
+**Cleaner Parameters**:
+
+- **remove_empty_lines** (<code>bool</code>) – If `True`, removes empty lines.
+- **remove_extra_whitespaces** (<code>bool</code>) – If `True`, removes extra whitespaces.
+- **remove_repeated_substrings** (<code>bool</code>) – If `True`, removes repeated substrings like headers/footers across pages.
+- **keep_id** (<code>bool</code>) – If `True`, keeps the original document IDs.
+- **remove_substrings** (<code>list\[str\] | None</code>) – A list of strings to remove from the document content.
+- **remove_regex** (<code>str | None</code>) – A regex pattern whose matches will be removed from the document content.
+- **unicode_normalization** (<code>Literal['NFC', 'NFKC', 'NFD', 'NFKD'] | None</code>) – Unicode normalization form to apply to the text, for example `"NFC"`.
+- **ascii_only** (<code>bool</code>) – If `True`, converts text to ASCII only.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize SuperComponent to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DocumentPreprocessor
+```
+
+Deserializes the SuperComponent from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>DocumentPreprocessor</code> – Deserialized SuperComponent.
+
+## document_splitter
+
+### DocumentSplitter
+
+Splits long documents into smaller chunks.
+
+This is a common preprocessing step during indexing. It helps Embedders create meaningful semantic representations
+and prevents exceeding language model context limits.
+
+The DocumentSplitter is compatible with the following DocumentStores:
+
+- [Astra](https://docs.haystack.deepset.ai/docs/astradocumentstore)
+- [Chroma](https://docs.haystack.deepset.ai/docs/chromadocumentstore) limited support, overlapping information is
+  not stored
+- [Elasticsearch](https://docs.haystack.deepset.ai/docs/elasticsearch-document-store)
+- [OpenSearch](https://docs.haystack.deepset.ai/docs/opensearch-document-store)
+- [Pgvector](https://docs.haystack.deepset.ai/docs/pgvectordocumentstore)
+- [Pinecone](https://docs.haystack.deepset.ai/docs/pinecone-document-store) limited support, overlapping
+  information is not stored
+- [Qdrant](https://docs.haystack.deepset.ai/docs/qdrant-document-store)
+- [Weaviate](https://docs.haystack.deepset.ai/docs/weaviatedocumentstore)
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import DocumentSplitter
+
+doc = Document(content="Moonlight shimmered softly, wolves howled nearby, night enveloped everything.")
+
+splitter = DocumentSplitter(split_by="word", split_length=3, split_overlap=0)
+result = splitter.run(documents=[doc])
+```
+
+#### __init__
+
+```python
+__init__(
+    split_by: Literal[
+        "function", "page", "passage", "period", "word", "line", "sentence"
+    ] = "word",
+    split_length: int = 200,
+    split_overlap: int = 0,
+    split_threshold: int = 0,
+    splitting_function: Callable[[str], list[str]] | None = None,
+    respect_sentence_boundary: bool = False,
+    language: Language = "en",
+    use_split_rules: bool = True,
+    extend_abbreviations: bool = True,
+    *,
+    skip_empty_documents: bool = True
+) -> None
+```
+
+Initialize DocumentSplitter.
+
+**Parameters:**
+
+- **split_by** (<code>Literal['function', 'page', 'passage', 'period', 'word', 'line', 'sentence']</code>) – The unit for splitting your documents. Choose from:
+- `word` for splitting by spaces (" ")
+- `period` for splitting by periods (".")
+- `page` for splitting by form feed ("\\f")
+- `passage` for splitting by double line breaks ("\\n\\n")
+- `line` for splitting each line ("\\n")
+- `sentence` for splitting by NLTK sentence tokenizer
+- **split_length** (<code>int</code>) – The maximum number of units in each split.
+- **split_overlap** (<code>int</code>) – The number of overlapping units for each split.
+- **split_threshold** (<code>int</code>) – The minimum number of units per split. If a split has fewer units
+  than the threshold, it's attached to the previous split.
+- **splitting_function** (<code>Callable\\[[str\], list\[str\]\] | None</code>) – Necessary when `split_by` is set to "function".
+  This is a function which must accept a single `str` as input and return a `list` of `str` as output,
+  representing the chunks after splitting.
+- **respect_sentence_boundary** (<code>bool</code>) – Choose whether to respect sentence boundaries when splitting by "word".
+  If True, uses NLTK to detect sentence boundaries, ensuring splits occur only between sentences.
+- **language** (<code>Language</code>) – Choose the language for the NLTK tokenizer. The default is English ("en").
+- **use_split_rules** (<code>bool</code>) – Choose whether to use additional split rules when splitting by `sentence`.
+- **extend_abbreviations** (<code>bool</code>) – Choose whether to extend NLTK's PunktTokenizer abbreviations with a list
+  of curated abbreviations, if available. This is currently supported for English ("en") and German ("de").
+- **skip_empty_documents** (<code>bool</code>) – Choose whether to skip documents with empty content. Default is True.
+  Set to False when downstream components in the Pipeline (like LLMDocumentContentExtractor) can extract text
+  from non-textual documents.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the DocumentSplitter by loading the sentence tokenizer.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Split documents into smaller parts.
+
+Splits documents by the unit expressed in `split_by`, with a length of `split_length`
+and an overlap of `split_overlap`.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – The documents to split.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following key:
+- `documents`: List of documents with the split texts. Each document includes:
+  - A metadata field `source_id` to track the original document.
+  - A metadata field `page_number` to track the original page number.
+  - All other metadata copied from the original document.
+
+**Raises:**
+
+- <code>TypeError</code> – if the input is not a list of Documents.
+- <code>ValueError</code> – if the content of a document is None.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+## embedding_based_document_splitter
+
+### EmbeddingBasedDocumentSplitter
+
+Splits documents based on embedding similarity using cosine distances between sequential sentence groups.
+
+This component first splits text into sentences, optionally groups them, calculates embeddings for each group,
+and then uses cosine distance between sequential embeddings to determine split points. Any distance above
+the specified percentile is treated as a break point. The component also tracks page numbers based on form feed
+characters (``) in the original document.
+
+This component is inspired by [5 Levels of Text Splitting](https://github.com/FullStackRetrieval-com/RetrievalTutorials/blob/main/tutorials/LevelsOfTextSplitting/5_Levels_Of_Text_Splitting.ipynb) by Greg Kamradt.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersDocumentEmbedder
+from haystack.components.preprocessors import EmbeddingBasedDocumentSplitter
+
+# Create a document with content that has a clear topic shift
+doc = Document(
+    content="This is a first sentence. This is a second sentence. This is a third sentence. "
+    "Completely different topic. The same completely different topic."
+)
+
+# Initialize the embedder to calculate semantic similarities
+embedder = SentenceTransformersDocumentEmbedder()
+
+# Configure the splitter with parameters that control splitting behavior
+splitter = EmbeddingBasedDocumentSplitter(
+    document_embedder=embedder,
+    sentences_per_group=2,      # Group 2 sentences before calculating embeddings
+    percentile=0.95,            # Split when cosine distance exceeds 95th percentile
+    min_length=50,              # Merge splits shorter than 50 characters
+    max_length=1000             # Further split chunks longer than 1000 characters
+)
+result = splitter.run(documents=[doc])
+
+# The result contains a list of Document objects, each representing a semantic chunk
+# Each split document includes metadata: source_id, split_id, and page_number
+print(f"Original document split into {len(result['documents'])} chunks")
+for i, split_doc in enumerate(result['documents']):
+    print(f"Chunk {i}: {split_doc.content[:50]}...")
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_embedder: DocumentEmbedder,
+    sentences_per_group: int = 3,
+    percentile: float = 0.95,
+    min_length: int = 50,
+    max_length: int = 1000,
+    language: Language = "en",
+    use_split_rules: bool = True,
+    extend_abbreviations: bool = True
+) -> None
+```
+
+Initialize EmbeddingBasedDocumentSplitter.
+
+**Parameters:**
+
+- **document_embedder** (<code>DocumentEmbedder</code>) – The DocumentEmbedder to use for calculating embeddings.
+- **sentences_per_group** (<code>int</code>) – Number of sentences to group together before embedding.
+- **percentile** (<code>float</code>) – Percentile threshold for cosine distance. Distances above this percentile
+  are treated as break points.
+- **min_length** (<code>int</code>) – Minimum length of splits in characters. Splits below this length will be merged.
+- **max_length** (<code>int</code>) – Maximum length of splits in characters. Splits above this length will be recursively split.
+- **language** (<code>Language</code>) – Language for sentence tokenization.
+- **use_split_rules** (<code>bool</code>) – Whether to use additional split rules for sentence tokenization. Applies additional
+  split rules from SentenceSplitter to the sentence spans.
+- **extend_abbreviations** (<code>bool</code>) – If True, the abbreviations used by NLTK's PunktTokenizer are extended by a list
+  of curated abbreviations. Currently supported languages are: en, de.
+  If False, the default abbreviations are used.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the component by initializing the sentence splitter.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Split documents based on embedding similarity.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – The documents to split.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following key:
+- `documents`: List of documents with the split texts. Each document includes:
+  - A metadata field `source_id` to track the original document.
+  - A metadata field `split_id` to track the split number.
+  - A metadata field `page_number` to track the original page number.
+  - All other metadata copied from the original document.
+
+**Raises:**
+
+- <code>RuntimeError</code> – If the component wasn't warmed up.
+- <code>TypeError</code> – If the input is not a list of Documents.
+- <code>ValueError</code> – If the document content is None or empty.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Asynchronously split documents based on embedding similarity.
+
+This is the asynchronous version of the `run` method with the same parameters and return values.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – The documents to split.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following key:
+- `documents`: List of documents with the split texts. Each document includes:
+  - A metadata field `source_id` to track the original document.
+  - A metadata field `split_id` to track the split number.
+  - A metadata field `page_number` to track the original page number.
+  - All other metadata copied from the original document.
+
+**Raises:**
+
+- <code>RuntimeError</code> – If the component wasn't warmed up.
+- <code>TypeError</code> – If the input is not a list of Documents.
+- <code>ValueError</code> – If the document content is None or empty.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Serialized dictionary representation of the component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> EmbeddingBasedDocumentSplitter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize and create the component.
+
+**Returns:**
+
+- <code>EmbeddingBasedDocumentSplitter</code> – The deserialized component.
+
+## hierarchical_document_splitter
+
+### HierarchicalDocumentSplitter
+
+Splits a documents into different block sizes building a hierarchical tree structure of blocks of different sizes.
+
+The root node of the tree is the original document, the leaf nodes are the smallest blocks. The blocks in between
+are connected such that the smaller blocks are children of the parent-larger blocks.
+
+## Usage example
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import HierarchicalDocumentSplitter
+
+doc = Document(content="This is a simple test document")
+splitter = HierarchicalDocumentSplitter(block_sizes={3, 2}, split_overlap=0, split_by="word")
+splitter.run([doc])
+# >> {'documents': [Document(id=3f7..., content: 'This is a simple test document', meta: {'block_size': 0, 'parent_id': None, 'children_ids': ['5ff..', '8dc..'], 'level': 0}),
+# >> Document(id=5ff.., content: 'This is a ', meta: {'block_size': 3, 'parent_id': '3f7..', 'children_ids': ['f19..', '52c..'], 'level': 1, 'source_id': '3f7..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+# >> Document(id=8dc.., content: 'simple test document', meta: {'block_size': 3, 'parent_id': '3f7..', 'children_ids': ['39d..', 'e23..'], 'level': 1, 'source_id': '3f7..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 10}),
+# >> Document(id=f19.., content: 'This is ', meta: {'block_size': 2, 'parent_id': '5ff..', 'children_ids': [], 'level': 2, 'source_id': '5ff..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+# >> Document(id=52c.., content: 'a ', meta: {'block_size': 2, 'parent_id': '5ff..', 'children_ids': [], 'level': 2, 'source_id': '5ff..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 8}),
+# >> Document(id=39d.., content: 'simple test ', meta: {'block_size': 2, 'parent_id': '8dc..', 'children_ids': [], 'level': 2, 'source_id': '8dc..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}),
+# >> Document(id=e23.., content: 'document', meta: {'block_size': 2, 'parent_id': '8dc..', 'children_ids': [], 'level': 2, 'source_id': '8dc..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 12})]}
+```
+
+#### __init__
+
+```python
+__init__(
+    block_sizes: set[int],
+    split_overlap: int = 0,
+    split_by: Literal["word", "sentence", "page", "passage"] = "word",
+) -> None
+```
+
+Initialize HierarchicalDocumentSplitter.
+
+**Parameters:**
+
+- **block_sizes** (<code>set\[int\]</code>) – Set of block sizes to split the document into. The blocks are split in descending order.
+- **split_overlap** (<code>int</code>) – The number of overlapping units for each split.
+- **split_by** (<code>Literal['word', 'sentence', 'page', 'passage']</code>) – The unit for splitting your documents.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Builds a hierarchical document structure for each document in a list of documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of Documents to split into hierarchical blocks.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – List of HierarchicalDocument
+
+#### build_hierarchy_from_doc
+
+```python
+build_hierarchy_from_doc(document: Document) -> list[Document]
+```
+
+Build a hierarchical tree document structure from a single document.
+
+Given a document, this function splits the document into hierarchical blocks of different sizes represented
+as HierarchicalDocument objects.
+
+**Parameters:**
+
+- **document** (<code>Document</code>) – Document to split into hierarchical blocks.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – List of HierarchicalDocument
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the component.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Serialized dictionary representation of the component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HierarchicalDocumentSplitter
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize and create the component.
+
+**Returns:**
+
+- <code>HierarchicalDocumentSplitter</code> – The deserialized component.
+
+## markdown_header_splitter
+
+### MarkdownHeaderSplitter
+
+Split documents at ATX-style Markdown headers (#), with optional secondary splitting.
+
+This component processes text documents by:
+
+- Splitting them into chunks at Markdown headers (e.g., '#', '##', etc.), preserving header hierarchy as metadata.
+- Optionally applying a secondary split (by word, passage, period, or line) to each chunk
+  (using haystack's DocumentSplitter).
+- Preserving and propagating metadata such as parent headers, page numbers, and split IDs.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    page_break_character: str = "\x0c",
+    keep_headers: bool = True,
+    header_split_levels: list[int] | None = None,
+    secondary_split: Literal["word", "passage", "period", "line"] | None = None,
+    split_length: int = 200,
+    split_overlap: int = 0,
+    split_threshold: int = 0,
+    skip_empty_documents: bool = True
+) -> None
+```
+
+Initialize the MarkdownHeaderSplitter.
+
+**Parameters:**
+
+- **page_break_character** (<code>str</code>) – Character used to identify page breaks. Defaults to form feed ("").
+- **keep_headers** (<code>bool</code>) – If True, headers are kept in the content. If False, headers are moved to metadata.
+  Defaults to True.
+- **header_split_levels** (<code>list\[int\] | None</code>) – List of header levels (1–6) to split on. For example, `[1, 2]` splits only
+  on `#` and `##` headers, merging content under deeper headers into the preceding chunk. Defaults to
+  all levels `[1, 2, 3, 4, 5, 6]`.
+- **secondary_split** (<code>Literal['word', 'passage', 'period', 'line'] | None</code>) – Optional secondary split condition after header splitting.
+  Options are None, "word", "passage", "period", "line". Defaults to None.
+- **split_length** (<code>int</code>) – The maximum number of units in each split when using secondary splitting. Defaults to 200.
+- **split_overlap** (<code>int</code>) – The number of overlapping units for each split when using secondary splitting.
+  Defaults to 0.
+- **split_threshold** (<code>int</code>) – The minimum number of units per split when using secondary splitting. Defaults to 0.
+- **skip_empty_documents** (<code>bool</code>) – Choose whether to skip documents with empty content. Default is True.
+  Set to False when downstream components in the Pipeline (like LLMDocumentContentExtractor) can extract text
+  from non-textual documents.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the MarkdownHeaderSplitter.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Run the markdown header splitter with optional secondary splitting.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of documents to split
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following key:
+- `documents`: List of documents with the split texts. Each document includes:
+  - A metadata field `source_id` to track the original document.
+  - A metadata field `page_number` to track the original page number.
+  - A metadata field `split_id` to identify the split chunk index within its parent document.
+  - All other metadata copied from the original document.
+
+**Raises:**
+
+- <code>ValueError</code> – If a document has `None` content.
+- <code>TypeError</code> – If a document's content is not a string.
+
+## recursive_splitter
+
+### RecursiveDocumentSplitter
+
+Recursively chunk text into smaller chunks.
+
+This component is used to split text into smaller chunks, it does so by recursively applying a list of separators
+to the text.
+
+The separators are applied in the order they are provided, typically this is a list of separators that are
+applied in a specific order, being the last separator the most specific one.
+
+Each separator is applied to the text, it then checks each of the resulting chunks, it keeps the chunks that
+are within the split_length, for the ones that are larger than the split_length, it applies the next separator in the
+list to the remaining text.
+
+This is done until all chunks are smaller than the split_length parameter.
+
+Example:
+
+```python
+from haystack import Document
+from haystack.components.preprocessors import RecursiveDocumentSplitter
+
+chunker = RecursiveDocumentSplitter(split_length=260, split_overlap=0, separators=["\n\n", "\n", ".", " "])
+text = ('''Artificial intelligence (AI) - Introduction
+
+AI, in its broadest sense, is intelligence exhibited by machines, particularly computer systems.
+AI technology is widely used throughout industry, government, and science. Some high-profile applications include advanced web search engines; recommendation systems; interacting via human speech; autonomous vehicles; generative and creative tools; and superhuman play and analysis in strategy games.''')
+doc = Document(content=text)
+doc_chunks = chunker.run([doc])
+print(doc_chunks["documents"])
+# [
+# Document(id=..., content: 'Artificial intelligence (AI) - Introduction\n\n', meta: {'original_id': '...', 'split_id': 0, 'split_idx_start': 0, '_split_overlap': []})
+# Document(id=..., content: 'AI, in its broadest sense, is intelligence exhibited by machines, particularly computer systems.\n', meta: {'original_id': '...', 'split_id': 1, 'split_idx_start': 45, '_split_overlap': []})
+# Document(id=..., content: 'AI technology is widely used throughout industry, government, and science.', meta: {'original_id': '...', 'split_id': 2, 'split_idx_start': 142, '_split_overlap': []})
+# Document(id=..., content: ' Some high-profile applications include advanced web search engines; recommendation systems; interac...', meta: {'original_id': '...', 'split_id': 3, 'split_idx_start': 216, '_split_overlap': []})
+# ]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    split_length: int = 200,
+    split_overlap: int = 0,
+    split_unit: Literal["word", "char", "token"] = "word",
+    separators: list[str] | None = None,
+    sentence_splitter_params: dict[str, Any] | None = None
+) -> None
+```
+
+Initializes a RecursiveDocumentSplitter.
+
+**Parameters:**
+
+- **split_length** (<code>int</code>) – The maximum length of each chunk by default in words, but can be in characters or tokens.
+  See the `split_units` parameter.
+- **split_overlap** (<code>int</code>) – The number of characters to overlap between consecutive chunks.
+- **split_unit** (<code>Literal['word', 'char', 'token']</code>) – The unit of the split_length parameter. It can be either "word", "char", or "token".
+  If "token" is selected, the text will be split into tokens using the tiktoken tokenizer (o200k_base).
+- **separators** (<code>list\[str\] | None</code>) – An optional list of separator strings to use for splitting the text. The string
+  separators will be treated as regular expressions unless the separator is "sentence", in that case the
+  text will be split into sentences using a custom sentence tokenizer based on NLTK.
+  See: haystack.components.preprocessors.sentence_tokenizer.SentenceSplitter.
+  If no separators are provided, the default separators ["\\n\\n", "sentence", "\\n", " "] are used.
+- **sentence_splitter_params** (<code>dict\[str, Any\] | None</code>) – Optional parameters to pass to the sentence tokenizer.
+  See: haystack.components.preprocessors.sentence_tokenizer.SentenceSplitter for more information.
+
+**Raises:**
+
+- <code>ValueError</code> – If the overlap is greater than or equal to the chunk size or if the overlap is negative, or
+  if any separator is not a string.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the sentence tokenizer and tiktoken tokenizer if needed.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Split a list of documents into documents with smaller chunks of text.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of Documents to split.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary containing a key "documents" with a List of Documents with smaller chunks of text corresponding
+  to the input documents.
+
+## text_cleaner
+
+### TextCleaner
+
+Cleans text strings.
+
+It can remove substrings matching a list of regular expressions, convert text to lowercase,
+remove punctuation, and remove numbers.
+Use it to clean up text data before evaluation.
+
+### Usage example
+
+```python
+from haystack.components.preprocessors import TextCleaner
+
+text_to_clean = "1Moonlight shimmered softly, 300 Wolves howled nearby, Night enveloped everything."
+
+cleaner = TextCleaner(convert_to_lowercase=True, remove_punctuation=False, remove_numbers=True)
+result = cleaner.run(texts=[text_to_clean])
+```
+
+#### __init__
+
+```python
+__init__(
+    remove_regexps: list[str] | None = None,
+    convert_to_lowercase: bool = False,
+    remove_punctuation: bool = False,
+    remove_numbers: bool = False,
+) -> None
+```
+
+Initializes the TextCleaner component.
+
+**Parameters:**
+
+- **remove_regexps** (<code>list\[str\] | None</code>) – A list of regex patterns to remove matching substrings from the text.
+- **convert_to_lowercase** (<code>bool</code>) – If `True`, converts all characters to lowercase.
+- **remove_punctuation** (<code>bool</code>) – If `True`, removes punctuation from the text.
+- **remove_numbers** (<code>bool</code>) – If `True`, removes numerical digits from the text.
+
+#### run
+
+```python
+run(texts: list[str]) -> dict[str, Any]
+```
+
+Cleans up the given list of strings.
+
+**Parameters:**
+
+- **texts** (<code>list\[str\]</code>) – List of strings to clean.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following key:
+- `texts`: the cleaned list of strings.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/query_api.md

@@ -0,0 +1,129 @@
+---
+title: "Query"
+id: query-api
+description: "Components for query processing and expansion."
+slug: "/query-api"
+---
+
+
+## query_expander
+
+### QueryExpander
+
+A component that returns a list of semantically similar queries to improve retrieval recall in RAG systems.
+
+The component uses a chat generator to expand queries. The chat generator is expected to return a JSON response
+with the following structure:
+
+```json
+{"queries": ["expanded query 1", "expanded query 2", "expanded query 3"]}
+```
+
+### Usage example
+
+```python
+from haystack.components.generators.chat.openai import OpenAIChatGenerator
+from haystack.components.query import QueryExpander
+
+expander = QueryExpander(
+    chat_generator=OpenAIChatGenerator(model="gpt-4.1-mini"),
+    n_expansions=3
+)
+
+result = expander.run(query="green energy sources")
+print(result["queries"])
+# Output: ['alternative query 1', 'alternative query 2', 'alternative query 3', 'green energy sources']
+# Note: Up to 3 additional queries + 1 original query (if include_original_query=True)
+
+# To control total number of queries:
+expander = QueryExpander(n_expansions=2, include_original_query=True)  # Up to 3 total
+# or
+expander = QueryExpander(n_expansions=3, include_original_query=False)  # Exactly 3 total
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    chat_generator: ChatGenerator | None = None,
+    prompt_template: str | None = None,
+    n_expansions: int = 4,
+    include_original_query: bool = True
+) -> None
+```
+
+Initialize the QueryExpander component.
+
+**Parameters:**
+
+- **chat_generator** (<code>ChatGenerator | None</code>) – The chat generator component to use for query expansion.
+  If None, a default OpenAIChatGenerator with gpt-4.1-mini model is used.
+- **prompt_template** (<code>str | None</code>) – Custom [PromptBuilder](https://docs.haystack.deepset.ai/docs/promptbuilder)
+  template for query expansion. The template should instruct the LLM to return a JSON response with the
+  structure: `{"queries": ["query1", "query2", "query3"]}`. The template should include 'query' and
+  'n_expansions' variables.
+- **n_expansions** (<code>int</code>) – Number of alternative queries to generate (default: 4).
+- **include_original_query** (<code>bool</code>) – Whether to include the original query in the output.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> QueryExpander
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary with serialized data.
+
+**Returns:**
+
+- <code>QueryExpander</code> – Deserialized component.
+
+#### run
+
+```python
+run(query: str, n_expansions: int | None = None) -> dict[str, list[str]]
+```
+
+Expand the input query into multiple semantically similar queries.
+
+The language of the original query is preserved in the expanded queries.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The original query to expand.
+- **n_expansions** (<code>int | None</code>) – Number of additional queries to generate (not including the original).
+  If None, uses the value from initialization. Can be 0 to generate no additional queries.
+
+**Returns:**
+
+- <code>dict\[str, list\[str\]\]</code> – Dictionary with "queries" key containing the list of expanded queries.
+  If include_original_query=True, the original query will be included in addition
+  to the n_expansions alternative queries.
+
+**Raises:**
+
+- <code>ValueError</code> – If n_expansions is not positive (less than or equal to 0).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the LLM provider component.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/readers_api.md

@@ -0,0 +1,193 @@
+---
+title: "Readers"
+id: readers-api
+description: "Takes a query and a set of Documents as input and returns ExtractedAnswers by selecting a text span within the Documents."
+slug: "/readers-api"
+---
+
+
+## extractive
+
+### ExtractiveReader
+
+Locates and extracts answers to a given query from Documents.
+
+The ExtractiveReader component performs extractive question answering.
+It assigns a score to every possible answer span independently of other answer spans.
+This fixes a common issue of other implementations which make comparisons across documents harder by normalizing
+each document's answers independently.
+
+Example usage:
+
+```python
+from haystack import Document
+from haystack.components.readers import ExtractiveReader
+
+docs = [
+    Document(content="Python is a popular programming language"),
+    Document(content="python ist eine beliebte Programmiersprache"),
+]
+
+reader = ExtractiveReader()
+
+question = "What is a popular programming language?"
+result = reader.run(query=question, documents=docs)
+assert "Python" in result["answers"][0].data
+```
+
+#### __init__
+
+```python
+__init__(
+    model: Path | str = "deepset/roberta-base-squad2-distilled",
+    device: ComponentDevice | None = None,
+    token: Secret | None = Secret.from_env_var(
+        ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+    ),
+    top_k: int = 20,
+    score_threshold: float | None = None,
+    max_seq_length: int = 384,
+    stride: int = 128,
+    max_batch_size: int | None = None,
+    answers_per_seq: int | None = None,
+    no_answer: bool = True,
+    calibration_factor: float = 0.1,
+    overlap_threshold: float | None = 0.01,
+    model_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Creates an instance of ExtractiveReader.
+
+**Parameters:**
+
+- **model** (<code>Path | str</code>) – A Hugging Face transformers question answering model.
+  Can either be a path to a folder containing the model files or an identifier for the Hugging Face hub.
+- **device** (<code>ComponentDevice | None</code>) – The device on which the model is loaded. If `None`, the default device is automatically selected.
+- **token** (<code>Secret | None</code>) – The API token used to download private models from Hugging Face.
+- **top_k** (<code>int</code>) – Number of answers to return per query. It is required even if score_threshold is set.
+  An additional answer with no text is returned if no_answer is set to True (default).
+- **score_threshold** (<code>float | None</code>) – Returns only answers with the probability score above this threshold.
+- **max_seq_length** (<code>int</code>) – Maximum number of tokens. If a sequence exceeds it, the sequence is split.
+- **stride** (<code>int</code>) – Number of tokens that overlap when sequence is split because it exceeds max_seq_length.
+- **max_batch_size** (<code>int | None</code>) – Maximum number of samples that are fed through the model at the same time.
+- **answers_per_seq** (<code>int | None</code>) – Number of answer candidates to consider per sequence.
+  This is relevant when a Document was split into multiple sequences because of max_seq_length.
+- **no_answer** (<code>bool</code>) – Whether to return an additional `no answer` with an empty text and a score representing the
+  probability that the other top_k answers are incorrect.
+- **calibration_factor** (<code>float</code>) – Factor used for calibrating probabilities.
+- **overlap_threshold** (<code>float | None</code>) – If set this will remove duplicate answers if they have an overlap larger than the
+  supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove
+  one of these answers since the second answer has a 100% (1.0) overlap with the first answer.
+  However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so
+  both of these answers could be kept if this variable is set to 0.24 or lower.
+  If None is provided then all answers are kept.
+- **model_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments passed to `AutoModelForQuestionAnswering.from_pretrained`
+  when loading the model specified in `model`. For details on what kwargs you can pass,
+  see the model's documentation.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ExtractiveReader
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ExtractiveReader</code> – Deserialized component.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### deduplicate_by_overlap
+
+```python
+deduplicate_by_overlap(
+    answers: list[ExtractedAnswer], overlap_threshold: float | None
+) -> list[ExtractedAnswer]
+```
+
+De-duplicates overlapping Extractive Answers.
+
+De-duplicates overlapping Extractive Answers from the same document based on how much the spans of the
+answers overlap.
+
+**Parameters:**
+
+- **answers** (<code>list\[ExtractedAnswer\]</code>) – List of answers to be deduplicated.
+- **overlap_threshold** (<code>float | None</code>) – If set this will remove duplicate answers if they have an overlap larger than the
+  supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove
+  one of these answers since the second answer has a 100% (1.0) overlap with the first answer.
+  However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so
+  both of these answers could be kept if this variable is set to 0.24 or lower.
+  If None is provided then all answers are kept.
+
+**Returns:**
+
+- <code>list\[ExtractedAnswer\]</code> – List of deduplicated answers.
+
+#### run
+
+```python
+run(
+    query: str,
+    documents: list[Document],
+    top_k: int | None = None,
+    score_threshold: float | None = None,
+    max_seq_length: int | None = None,
+    stride: int | None = None,
+    max_batch_size: int | None = None,
+    answers_per_seq: int | None = None,
+    no_answer: bool | None = None,
+    overlap_threshold: float | None = None,
+) -> dict[str, Any]
+```
+
+Locates and extracts answers from the given Documents using the given query.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Query string.
+- **documents** (<code>list\[Document\]</code>) – List of Documents in which you want to search for an answer to the query.
+- **top_k** (<code>int | None</code>) – The maximum number of answers to return.
+  An additional answer is returned if no_answer is set to True (default).
+- **score_threshold** (<code>float | None</code>) – Returns only answers with the score above this threshold.
+- **max_seq_length** (<code>int | None</code>) – Maximum number of tokens. If a sequence exceeds it, the sequence is split.
+- **stride** (<code>int | None</code>) – Number of tokens that overlap when sequence is split because it exceeds max_seq_length.
+- **max_batch_size** (<code>int | None</code>) – Maximum number of samples that are fed through the model at the same time.
+- **answers_per_seq** (<code>int | None</code>) – Number of answer candidates to consider per sequence.
+  This is relevant when a Document was split into multiple sequences because of max_seq_length.
+- **no_answer** (<code>bool | None</code>) – Whether to return no answer scores.
+- **overlap_threshold** (<code>float | None</code>) – If set this will remove duplicate answers if they have an overlap larger than the
+  supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove
+  one of these answers since the second answer has a 100% (1.0) overlap with the first answer.
+  However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so
+  both of these answers could be kept if this variable is set to 0.24 or lower.
+  If None is provided then all answers are kept.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – List of answers sorted by (desc.) answer score.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/samplers_api.md

@@ -0,0 +1,81 @@
+---
+title: "Samplers"
+id: samplers-api
+description: "Filters documents based on their similarity scores using top-p sampling."
+slug: "/samplers-api"
+---
+
+
+## top_p
+
+### TopPSampler
+
+Implements top-p (nucleus) sampling for document filtering based on cumulative probability scores.
+
+This component provides functionality to filter a list of documents by selecting those whose scores fall
+within the top 'p' percent of the cumulative distribution. It is useful for focusing on high-probability
+documents while filtering out less relevant ones based on their assigned scores.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.samplers import TopPSampler
+
+sampler = TopPSampler(top_p=0.95, score_field="similarity_score")
+docs = [
+    Document(content="Berlin", meta={"similarity_score": -10.6}),
+    Document(content="Belgrade", meta={"similarity_score": -8.9}),
+    Document(content="Sarajevo", meta={"similarity_score": -4.6}),
+]
+output = sampler.run(documents=docs)
+docs = output["documents"]
+assert len(docs) == 1
+assert docs[0].content == "Sarajevo"
+```
+
+#### __init__
+
+```python
+__init__(
+    top_p: float = 1.0,
+    score_field: str | None = None,
+    min_top_k: int | None = None,
+) -> None
+```
+
+Creates an instance of TopPSampler.
+
+**Parameters:**
+
+- **top_p** (<code>float</code>) – Float between 0 and 1 representing the cumulative probability threshold for document selection.
+  A value of 1.0 indicates no filtering (all documents are retained).
+- **score_field** (<code>str | None</code>) – Name of the field in each document's metadata that contains the score. If None, the default
+  document score field is used.
+- **min_top_k** (<code>int | None</code>) – If specified, the minimum number of documents to return. If the top_p selects
+  fewer documents, additional ones with the next highest scores are added to the selection.
+
+#### run
+
+```python
+run(documents: list[Document], top_p: float | None = None) -> dict[str, Any]
+```
+
+Filters documents using top-p sampling based on their scores.
+
+If the specified top_p results in no documents being selected (especially in cases of a low top_p value), the
+method returns the document with the highest score.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of Document objects to be filtered.
+- **top_p** (<code>float | None</code>) – If specified, a float to override the cumulative probability threshold set during initialization.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following key:
+- `documents`: List of Document objects that have been selected based on the top-p sampling.
+
+**Raises:**
+
+- <code>ValueError</code> – If the top_p value is not within the range [0, 1].

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/tool_components_api.md

@@ -0,0 +1,314 @@
+---
+title: "Tool Components"
+id: tool-components-api
+description: "Components related to Tool Calling."
+slug: "/tool-components-api"
+---
+
+
+## tool_invoker
+
+### ToolInvokerError
+
+Bases: <code>Exception</code>
+
+Base exception class for ToolInvoker errors.
+
+### ToolNotFoundException
+
+Bases: <code>ToolInvokerError</code>
+
+Exception raised when a tool is not found in the list of available tools.
+
+### StringConversionError
+
+Bases: <code>ToolInvokerError</code>
+
+Exception raised when the conversion of a tool result to a string fails.
+
+### ResultConversionError
+
+Bases: <code>ToolInvokerError</code>
+
+Exception raised when the conversion of a tool output to a result fails.
+
+### ToolOutputMergeError
+
+Bases: <code>ToolInvokerError</code>
+
+Exception raised when merging tool outputs into state fails.
+
+#### from_exception
+
+```python
+from_exception(tool_name: str, error: Exception) -> ToolOutputMergeError
+```
+
+Create a ToolOutputMergeError from an exception.
+
+### ToolInvoker
+
+Invokes tools based on prepared tool calls and returns the results as a list of ChatMessage objects.
+
+Also handles reading/writing from a shared `State`.
+At initialization, the ToolInvoker component is provided with a list of available tools.
+At runtime, the component processes a list of ChatMessage object containing tool calls
+and invokes the corresponding tools.
+The results of the tool invocations are returned as a list of ChatMessage objects with tool role.
+
+Usage example:
+
+```python
+from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.tools import Tool
+from haystack.components.tools import ToolInvoker
+
+# Tool definition
+def dummy_weather_function(city: str):
+    return f"The weather in {city} is 20 degrees."
+
+parameters = {"type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"]}
+
+tool = Tool(name="weather_tool",
+            description="A tool to get the weather",
+            function=dummy_weather_function,
+            parameters=parameters)
+
+# Usually, the ChatMessage with tool_calls is generated by a Language Model
+# Here, we create it manually for demonstration purposes
+tool_call = ToolCall(
+    tool_name="weather_tool",
+    arguments={"city": "Berlin"}
+)
+message = ChatMessage.from_assistant(tool_calls=[tool_call])
+
+# ToolInvoker initialization and run
+invoker = ToolInvoker(tools=[tool])
+result = invoker.run(messages=[message])
+
+print(result)
+```
+
+```
+# >> {
+# >>     'tool_messages': [
+# >>         ChatMessage(
+# >>             _role=<ChatRole.TOOL: 'tool'>,
+# >>             _content=[
+# >>                 ToolCallResult(
+# >>                     result='"The weather in Berlin is 20 degrees."',
+# >>                     origin=ToolCall(
+# >>                         tool_name='weather_tool',
+# >>                         arguments={'city': 'Berlin'},
+# >>                         id=None
+# >>                     )
+# >>                 )
+# >>             ],
+# >>             _meta={}
+# >>         )
+# >>     ]
+# >> }
+```
+
+Usage example with a Toolset:
+
+````python
+from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.tools import Tool, Toolset
+from haystack.components.tools import ToolInvoker
+
+# Tool definition
+def dummy_weather_function(city: str):
+    return f"The weather in {city} is 20 degrees."
+
+parameters = {"type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"]}
+
+tool = Tool(name="weather_tool",
+            description="A tool to get the weather",
+            function=dummy_weather_function,
+            parameters=parameters)
+
+# Create a Toolset
+toolset = Toolset([tool])
+
+# 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 with Toolset
+invoker = ToolInvoker(tools=toolset)
+result = invoker.run(messages=[message])
+
+print(result)
+
+#### __init__
+
+```python
+__init__(
+    tools: ToolsType,
+    raise_on_failure: bool = True,
+    convert_result_to_json_string: bool = False,
+    streaming_callback: StreamingCallbackT | None = None,
+    *,
+    enable_streaming_callback_passthrough: bool = False,
+    max_workers: int = 4
+) -> None
+````
+
+Initialize the ToolInvoker component.
+
+**Parameters:**
+
+- **tools** (<code>ToolsType</code>) – A list of Tool and/or Toolset objects, or a Toolset instance that can resolve tools.
+- **raise_on_failure** (<code>bool</code>) – If True, the component will raise an exception in case of errors
+  (tool not found, tool invocation errors, tool result conversion errors).
+  If False, the component will return a ChatMessage object with `error=True`
+  and a description of the error in `result`.
+- **convert_result_to_json_string** (<code>bool</code>) – If True, the tool invocation result will be converted to a string using `json.dumps`.
+  If False, the tool invocation result will be converted to a string using `str`.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that will be called to emit tool results.
+  Note that the result is only emitted once it becomes available — it is not
+  streamed incrementally in real time.
+- **enable_streaming_callback_passthrough** (<code>bool</code>) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
+  This allows tools to stream their results back to the client.
+  Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
+  If False, the `streaming_callback` will not be passed to the tool invocation.
+- **max_workers** (<code>int</code>) – The maximum number of workers to use in the thread pool executor.
+  This also decides the maximum number of concurrent tool invocations.
+
+**Raises:**
+
+- <code>ValueError</code> – If no tools are provided or if duplicate tool names are found.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the tool invoker.
+
+This will warm up the tools registered in the tool invoker.
+This method is idempotent and will only warm up the tools once.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage],
+    state: State | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    *,
+    enable_streaming_callback_passthrough: bool | None = None,
+    tools: ToolsType | None = None
+) -> dict[str, Any]
+```
+
+Processes ChatMessage objects containing tool calls and invokes the corresponding tools, if available.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage objects.
+- **state** (<code>State | None</code>) – The runtime state that should be used by the tools.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that will be called to emit tool results.
+  Note that the result is only emitted once it becomes available — it is not
+  streamed incrementally in real time.
+- **enable_streaming_callback_passthrough** (<code>bool | None</code>) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
+  This allows tools to stream their results back to the client.
+  Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
+  If False, the `streaming_callback` will not be passed to the tool invocation.
+  If None, the value from the constructor will be used.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role.
+  Each ChatMessage objects wraps the result of a tool invocation.
+
+**Raises:**
+
+- <code>ToolNotFoundException</code> – If the tool is not found in the list of available tools and `raise_on_failure` is True.
+- <code>ToolInvocationError</code> – If the tool invocation fails and `raise_on_failure` is True.
+- <code>StringConversionError</code> – If the conversion of the tool result to a string fails and `raise_on_failure` is True.
+- <code>ToolOutputMergeError</code> – If merging tool outputs into state fails and `raise_on_failure` is True.
+
+#### run_async
+
+```python
+run_async(
+    messages: list[ChatMessage],
+    state: State | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    *,
+    enable_streaming_callback_passthrough: bool | None = None,
+    tools: ToolsType | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously processes ChatMessage objects containing tool calls.
+
+Multiple tool calls are performed concurrently.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage objects.
+- **state** (<code>State | None</code>) – The runtime state that should be used by the tools.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – An asynchronous callback function that will be called to emit tool results.
+  Note that the result is only emitted once it becomes available — it is not
+  streamed incrementally in real time.
+- **enable_streaming_callback_passthrough** (<code>bool | None</code>) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
+  This allows tools to stream their results back to the client.
+  Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
+  If False, the `streaming_callback` will not be passed to the tool invocation.
+  If None, the value from the constructor will be used.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role.
+  Each ChatMessage objects wraps the result of a tool invocation.
+
+**Raises:**
+
+- <code>ToolNotFoundException</code> – If the tool is not found in the list of available tools and `raise_on_failure` is True.
+- <code>ToolInvocationError</code> – If the tool invocation fails and `raise_on_failure` is True.
+- <code>StringConversionError</code> – If the conversion of the tool result to a string fails and `raise_on_failure` is True.
+- <code>ToolOutputMergeError</code> – If merging tool outputs into state fails and `raise_on_failure` is True.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ToolInvoker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ToolInvoker</code> – The deserialized component.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/validators_api.md

@@ -0,0 +1,135 @@
+---
+title: "Validators"
+id: validators-api
+description: "Validators validate LLM outputs"
+slug: "/validators-api"
+---
+
+
+## json_schema
+
+### is_valid_json
+
+```python
+is_valid_json(s: str) -> bool
+```
+
+Check if the provided string is a valid JSON.
+
+**Parameters:**
+
+- **s** (<code>str</code>) – The string to be checked.
+
+**Returns:**
+
+- <code>bool</code> – `True` if the string is a valid JSON; otherwise, `False`.
+
+### JsonSchemaValidator
+
+Validates JSON content of `ChatMessage` against a specified [JSON Schema](https://json-schema.org/).
+
+If JSON content of a message conforms to the provided schema, the message is passed along the "validated" output.
+If the JSON content does not conform to the schema, the message is passed along the "validation_error" output.
+In the latter case, the error message is constructed using the provided `error_template` or a default template.
+These error ChatMessages can be used by LLMs in Haystack 2.x recovery loops.
+
+Usage example:
+
+```python
+from haystack import Pipeline
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.joiners import BranchJoiner
+from haystack.components.validators import JsonSchemaValidator
+from haystack import component
+from haystack.dataclasses import ChatMessage
+
+
+@component
+class MessageProducer:
+
+    @component.output_types(messages=list[ChatMessage])
+    def run(self, messages: list[ChatMessage]) -> dict:
+        return {"messages": messages}
+
+
+p = Pipeline()
+p.add_component("llm", OpenAIChatGenerator(generation_kwargs={"response_format": {"type": "json_object"}}))
+p.add_component("schema_validator", JsonSchemaValidator())
+p.add_component("joiner_for_llm", BranchJoiner(list[ChatMessage]))
+p.add_component("message_producer", MessageProducer())
+
+p.connect("message_producer.messages", "joiner_for_llm")
+p.connect("joiner_for_llm", "llm")
+p.connect("llm.replies", "schema_validator.messages")
+p.connect("schema_validator.validation_error", "joiner_for_llm")
+
+result = p.run(data={
+    "message_producer": {
+        "messages":[ChatMessage.from_user("Generate JSON for person with name 'John' and age 30")]},
+        "schema_validator": {
+            "json_schema": {
+                "type": "object",
+                "properties": {"name": {"type": "string"},
+                "age": {"type": "integer"}
+            }
+        }
+    }
+})
+print(result)
+# >> {'schema_validator': {'validated': [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>,
+# _content=[TextContent(text="\n{\n  "name": "John",\n  "age": 30\n}")],
+# _name=None, _meta={'index': 0, 'finish_reason': 'stop', 'usage': {'completion_tokens': 17, 'prompt_tokens': 20,
+# 'total_tokens': 37}})]}}
+```
+
+#### __init__
+
+```python
+__init__(
+    json_schema: dict[str, Any] | None = None, error_template: str | None = None
+) -> None
+```
+
+Initialize the JsonSchemaValidator component.
+
+**Parameters:**
+
+- **json_schema** (<code>dict\[str, Any\] | None</code>) – A dictionary representing the [JSON schema](https://json-schema.org/) against which
+  the messages' content is validated.
+- **error_template** (<code>str | None</code>) – A custom template string for formatting the error message in case of validation failure.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage],
+    json_schema: dict[str, Any] | None = None,
+    error_template: str | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Validates the last of the provided messages against the specified json schema.
+
+If it does, the message is passed along the "validated" output. If it does not, the message is passed along
+the "validation_error" output.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances to be validated. The last message in this list is the one
+  that is validated.
+- **json_schema** (<code>dict\[str, Any\] | None</code>) – A dictionary representing the [JSON schema](https://json-schema.org/)
+  against which the messages' content is validated. If not provided, the schema from the component init
+  is used.
+- **error_template** (<code>str | None</code>) – A custom template string for formatting the error message in case of validation. If not
+  provided, the `error_template` from the component init is used.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- "validated": A list of messages if the last message is valid.
+- "validation_error": A list of messages if the last message is invalid.
+
+**Raises:**
+
+- <code>ValueError</code> – If no JSON schema is provided or if the message content is not a dictionary or a list of
+  dictionaries.

docs-website/reference_versioned_docs/version-2.28-unstable/haystack-api/websearch_api.md

@@ -0,0 +1,266 @@
+---
+title: "Websearch"
+id: websearch-api
+description: "Web search engine for Haystack."
+slug: "/websearch-api"
+---
+
+
+## searchapi
+
+### SearchApiWebSearch
+
+Uses [SearchApi](https://www.searchapi.io/) to search the web for relevant documents.
+
+Usage example:
+
+<!-- test-ignore -->
+
+```python
+from haystack.components.websearch import SearchApiWebSearch
+from haystack.utils import Secret
+
+websearch = SearchApiWebSearch(top_k=10, api_key=Secret.from_env_var("SERPERDEV_API_KEY"))
+results = websearch.run(query="Who is the boyfriend of Olivia Wilde?")
+
+assert results["documents"]
+assert results["links"]
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("SEARCHAPI_API_KEY"),
+    top_k: int | None = 10,
+    allowed_domains: list[str] | None = None,
+    search_params: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the SearchApiWebSearch component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – API key for the SearchApi API
+- **top_k** (<code>int | None</code>) – Number of documents to return.
+- **allowed_domains** (<code>list\[str\] | None</code>) – List of domains to limit the search to.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – Additional parameters passed to the SearchApi API.
+  For example, you can set 'num' to 100 to increase the number of search results.
+  See the [SearchApi website](https://www.searchapi.io/) for more details.
+
+The default search engine is Google, however, users can change it by setting the `engine`
+parameter in the `search_params`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SearchApiWebSearch
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SearchApiWebSearch</code> – The deserialized component.
+
+#### run
+
+```python
+run(query: str) -> dict[str, list[Document] | list[str]]
+```
+
+Uses [SearchApi](https://www.searchapi.io/) to search the web.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Search query.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | list\[str\]\]</code> – A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+
+**Raises:**
+
+- <code>TimeoutError</code> – If the request to the SearchApi API times out.
+- <code>SearchApiError</code> – If an error occurs while querying the SearchApi API.
+
+#### run_async
+
+```python
+run_async(query: str) -> dict[str, list[Document] | list[str]]
+```
+
+Asynchronously uses [SearchApi](https://www.searchapi.io/) to search the web.
+
+This is the asynchronous version of the `run` method with the same parameters and return values.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Search query.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | list\[str\]\]</code> – A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+
+**Raises:**
+
+- <code>TimeoutError</code> – If the request to the SearchApi API times out.
+- <code>SearchApiError</code> – If an error occurs while querying the SearchApi API.
+
+## serper_dev
+
+### SerperDevWebSearch
+
+Uses [Serper](https://serper.dev/) to search the web for relevant documents.
+
+See the [Serper Dev website](https://serper.dev/) for more details.
+
+Usage example:
+
+<!-- test-ignore -->
+
+```python
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.utils import Secret
+
+serper_dev_api = Secret.from_env_var("SERPERDEV_API_KEY")
+
+websearch = SerperDevWebSearch(top_k=10, api_key=serper_dev_api)
+results = websearch.run(query="Who is the boyfriend of Olivia Wilde?")
+
+assert results["documents"]
+assert results["links"]
+
+# Example with domain filtering - exclude subdomains
+websearch_filtered = SerperDevWebSearch(
+    top_k=10,
+    allowed_domains=["example.com"],
+    exclude_subdomains=True,  # Only results from example.com, not blog.example.com
+    api_key=serper_dev_api
+)
+results_filtered = websearch_filtered.run(query="search query")
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("SERPERDEV_API_KEY"),
+    top_k: int | None = 10,
+    allowed_domains: list[str] | None = None,
+    search_params: dict[str, Any] | None = None,
+    *,
+    exclude_subdomains: bool = False
+) -> None
+```
+
+Initialize the SerperDevWebSearch component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – API key for the Serper API.
+- **top_k** (<code>int | None</code>) – Number of documents to return.
+- **allowed_domains** (<code>list\[str\] | None</code>) – List of domains to limit the search to.
+- **exclude_subdomains** (<code>bool</code>) – Whether to exclude subdomains when filtering by allowed_domains.
+  If True, only results from the exact domains in allowed_domains will be returned.
+  If False, results from subdomains will also be included. Defaults to False.
+- **search_params** (<code>dict\[str, Any\] | None</code>) – Additional parameters passed to the Serper API.
+  For example, you can set 'num' to 20 to increase the number of search results.
+  See the [Serper website](https://serper.dev/) for more details.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SerperDevWebSearch
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SerperDevWebSearch</code> – The deserialized component.
+
+#### run
+
+```python
+run(query: str) -> dict[str, list[Document] | list[str]]
+```
+
+Use [Serper](https://serper.dev/) to search the web.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Search query.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | list\[str\]\]</code> – A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+
+**Raises:**
+
+- <code>SerperDevError</code> – If an error occurs while querying the SerperDev API.
+- <code>TimeoutError</code> – If the request to the SerperDev API times out.
+
+#### run_async
+
+```python
+run_async(query: str) -> dict[str, list[Document] | list[str]]
+```
+
+Asynchronously uses [Serper](https://serper.dev/) to search the web.
+
+This is the asynchronous version of the `run` method with the same parameters and return values.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Search query.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | list\[str\]\]</code> – A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+
+**Raises:**
+
+- <code>SerperDevError</code> – If an error occurs while querying the SerperDev API.
+- <code>TimeoutError</code> – If the request to the SerperDev API times out.

docs-website/reference_versioned_docs/version-2.28-unstable/index.mdx

@@ -0,0 +1,21 @@
+---
+id: api-index
+title: API Documentation
+sidebar_position: 1
+---
+
+# API Reference
+
+Complete technical reference for Haystack classes, functions, and modules.
+
+## Haystack API
+
+Core framework API for the `haystack-ai` package. This includes all base components, pipelines, document stores, data classes, and utilities that make up the Haystack framework.
+
+## Integrations API
+
+API reference for official Haystack integrations distributed as separate packages (for example, `<integration-name>-haystack`). Each integration provides components that connect Haystack to external services, models, or platforms. For more information, see the [integrations documentation](/docs/integrations).
+
+## Experiments API
+
+API reference for experimental features. These APIs are under active development and may change in future releases. For more information, see the [experimental features documentation](/docs/experimental-package).

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/aimlapi.md

@@ -0,0 +1,119 @@
+---
+title: "AIMLAPI"
+id: integrations-aimlapi
+description: "AIMLAPI integration for Haystack"
+slug: "/integrations-aimlapi"
+---
+
+<a id="haystack_integrations.components.generators.aimlapi.chat.chat_generator"></a>
+
+## Module haystack\_integrations.components.generators.aimlapi.chat.chat\_generator
+
+<a id="haystack_integrations.components.generators.aimlapi.chat.chat_generator.AIMLAPIChatGenerator"></a>
+
+### AIMLAPIChatGenerator
+
+Enables text generation using AIMLAPI generative models.
+For supported models, see AIMLAPI documentation.
+
+Users can pass any text generation parameters valid for the AIMLAPI chat completion API
+directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+Key Features and Compatibility:
+- **Primary Compatibility**: Designed to work seamlessly with the AIMLAPI chat completion endpoint.
+- **Streaming Support**: Supports streaming responses from the AIMLAPI chat completion endpoint.
+- **Customizability**: Supports all parameters supported by the AIMLAPI chat completion endpoint.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage)
+
+For more details on the parameters supported by the AIMLAPI API, refer to the
+AIMLAPI documentation.
+
+Usage example:
+```python
+from haystack_integrations.components.generators.aimlapi import AIMLAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = AIMLAPIChatGenerator(model="openai/gpt-5-chat-latest")
+response = client.run(messages)
+print(response)
+
+>>{'replies': [ChatMessage(_content='Natural Language Processing (NLP) is a branch of artificial intelligence
+>>that focuses on enabling computers to understand, interpret, and generate human language in a way that is
+>>meaningful and useful.', _role=<ChatRole.ASSISTANT: 'assistant'>, _name=None,
+>>_meta={'model': 'openai/gpt-5-chat-latest', 'index': 0, 'finish_reason': 'stop',
+>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]}
+```
+
+<a id="haystack_integrations.components.generators.aimlapi.chat.chat_generator.AIMLAPIChatGenerator.__init__"></a>
+
+#### AIMLAPIChatGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+             api_key: Secret = Secret.from_env_var("AIMLAPI_API_KEY"),
+             model: str = "openai/gpt-5-chat-latest",
+             streaming_callback: StreamingCallbackT | None = None,
+             api_base_url: str | None = "https://api.aimlapi.com/v1",
+             generation_kwargs: dict[str, Any] | None = None,
+             tools: ToolsType | None = None,
+             timeout: float | None = None,
+             extra_headers: dict[str, Any] | None = None,
+             max_retries: int | None = None,
+             http_client_kwargs: dict[str, Any] | None = None)
+```
+
+Creates an instance of AIMLAPIChatGenerator. Unless specified otherwise,
+
+the default model is `openai/gpt-5-chat-latest`.
+
+**Arguments**:
+
+- `api_key`: The AIMLAPI API key.
+- `model`: The name of the AIMLAPI chat completion model to use.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+The callback function accepts StreamingChunk as an argument.
+- `api_base_url`: The AIMLAPI API Base url.
+For more details, see AIMLAPI documentation.
+- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to
+the AIMLAPI endpoint. See AIMLAPI API docs for more details.
+Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+    Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+    considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+    comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+    events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `tools`: A list of tools or a Toolset for which the model can prepare calls. This parameter can accept either a
+list of `Tool` objects or a `Toolset` instance.
+- `timeout`: The timeout for the AIMLAPI API call.
+- `extra_headers`: Additional HTTP headers to include in requests to the AIMLAPI API.
+- `max_retries`: Maximum number of retries to contact AIMLAPI after an internal error.
+If not set, it defaults to either the `AIMLAPI_MAX_RETRIES` environment variable, or set to 5.
+- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`).
+
+<a id="haystack_integrations.components.generators.aimlapi.chat.chat_generator.AIMLAPIChatGenerator.to_dict"></a>
+
+#### AIMLAPIChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns**:
+
+The serialized component as a dictionary.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/amazon_sagemaker.md

@@ -0,0 +1,150 @@
+---
+title: "Amazon Sagemaker"
+id: integrations-amazon-sagemaker
+description: "Amazon Sagemaker integration for Haystack"
+slug: "/integrations-amazon-sagemaker"
+---
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker"></a>
+
+## Module haystack\_integrations.components.generators.amazon\_sagemaker.sagemaker
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker.SagemakerGenerator"></a>
+
+### SagemakerGenerator
+
+Enables text generation using Amazon Sagemaker.
+
+SagemakerGenerator supports Large Language Models (LLMs) hosted and deployed on a SageMaker Inference Endpoint.
+For guidance on how to deploy a model to SageMaker, refer to the
+[SageMaker JumpStart foundation models documentation](https://docs.aws.amazon.com/sagemaker/latest/dg/jumpstart-foundation-models-use.html).
+
+Usage example:
+```python
+# Make sure your AWS credentials are set up correctly. You can use environment variables or a shared credentials
+# file. Then you can use the generator as follows:
+from haystack_integrations.components.generators.amazon_sagemaker import SagemakerGenerator
+
+generator = SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-bf16")
+response = generator.run("What's Natural Language Processing? Be brief.")
+print(response)
+>>> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on
+>>> the interaction between computers and human language. It involves enabling computers to understand, interpret,
+>>> and respond to natural human language in a way that is both meaningful and useful.'], 'meta': [{}]}
+```
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker.SagemakerGenerator.__init__"></a>
+
+#### SagemakerGenerator.\_\_init\_\_
+
+```python
+def __init__(
+        model: str,
+        aws_access_key_id: Secret | None = Secret.from_env_var(
+            ["AWS_ACCESS_KEY_ID"], strict=False),
+        aws_secret_access_key: Secret
+    | None = Secret.from_env_var(  # noqa: B008
+        ["AWS_SECRET_ACCESS_KEY"], strict=False),
+        aws_session_token: Secret | None = Secret.from_env_var(
+            ["AWS_SESSION_TOKEN"], strict=False),
+        aws_region_name: Secret | None = Secret.from_env_var(
+            ["AWS_DEFAULT_REGION"], strict=False),
+        aws_profile_name: Secret | None = Secret.from_env_var(["AWS_PROFILE"],
+                                                              strict=False),
+        aws_custom_attributes: dict[str, Any] | None = None,
+        generation_kwargs: dict[str, Any] | None = None)
+```
+
+Instantiates the session with SageMaker.
+
+**Arguments**:
+
+- `aws_access_key_id`: The `Secret` for AWS access key ID.
+- `aws_secret_access_key`: The `Secret` for AWS secret access key.
+- `aws_session_token`: The `Secret` for AWS session token.
+- `aws_region_name`: The `Secret` for AWS region name. If not provided, the default region will be used.
+- `aws_profile_name`: The `Secret` for AWS profile name. If not provided, the default profile will be used.
+- `model`: The name for SageMaker Model Endpoint.
+- `aws_custom_attributes`: Custom attributes to be passed to SageMaker, for example `{"accept_eula": True}`
+in case of Llama-2 models.
+- `generation_kwargs`: Additional keyword arguments for text generation. For a list of supported parameters
+see your model's documentation page, for example here for HuggingFace models:
+https://huggingface.co/blog/sagemaker-huggingface-llm#4-run-inference-and-chat-with-our-model
+
+Specifically, Llama-2 models support the following inference payload parameters:
+
+- `max_new_tokens`: Model generates text until the output length (excluding the input context length)
+    reaches `max_new_tokens`. If specified, it must be a positive integer.
+- `temperature`: Controls the randomness in the output. Higher temperature results in output sequence with
+    low-probability words and lower temperature results in output sequence with high-probability words.
+    If `temperature=0`, it results in greedy decoding. If specified, it must be a positive float.
+- `top_p`: In each step of text generation, sample from the smallest possible set of words with cumulative
+    probability `top_p`. If specified, it must be a float between 0 and 1.
+- `return_full_text`: If `True`, input text will be part of the output generated text. If specified, it must
+    be boolean. The default value for it is `False`.
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker.SagemakerGenerator.to_dict"></a>
+
+#### SagemakerGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker.SagemakerGenerator.from_dict"></a>
+
+#### SagemakerGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "SagemakerGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.generators.amazon_sagemaker.sagemaker.SagemakerGenerator.run"></a>
+
+#### SagemakerGenerator.run
+
+```python
+@component.output_types(replies=list[str], meta=list[dict[str, Any]])
+def run(
+    prompt: str,
+    generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Invoke the text generation inference based on the provided prompt and generation parameters.
+
+**Arguments**:
+
+- `prompt`: The string prompt to use for text generation.
+- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will
+potentially override the parameters passed in the `__init__` method.
+
+**Raises**:
+
+- `ValueError`: If the model response type is not a list of dictionaries or a single dictionary.
+- `SagemakerNotReadyError`: If the SageMaker model is not ready to accept requests.
+- `SagemakerInferenceError`: If the SageMaker Inference returns an error.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list of strings containing the generated responses
+- `meta`: A list of dictionaries containing the metadata for each response.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/anthropic.md

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

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/arcadedb.md

@@ -0,0 +1,391 @@
+---
+title: "ArcadeDB"
+id: integrations-arcadedb
+description: "ArcadeDB integration for Haystack"
+slug: "/integrations-arcadedb"
+---
+
+
+## haystack_integrations.components.retrievers.arcadedb.embedding_retriever
+
+### ArcadeDBEmbeddingRetriever
+
+Retrieve documents from ArcadeDB using vector similarity (LSM_VECTOR / HNSW index).
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.components.embedders import SentenceTransformersTextEmbedder
+from haystack_integrations.components.retrievers.arcadedb import ArcadeDBEmbeddingRetriever
+from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore
+
+store = ArcadeDBDocumentStore(database="mydb")
+retriever = ArcadeDBEmbeddingRetriever(document_store=store, top_k=5)
+
+# Add documents to DocumentStore
+documents = [
+    Document(text="My name is Carla and I live in Berlin"),
+    Document(text="My name is Paul and I live in New York"),
+    Document(text="My name is Silvano and I live in Matera"),
+    Document(text="My name is Usagi Tsukino and I live in Tokyo"),
+]
+document_store.write_documents(documents)
+
+embedder = SentenceTransformersTextEmbedder()
+query_embeddings = embedder.run("Who lives in Berlin?")["embedding"]
+
+result = retriever.run(query=query_embeddings)
+for doc in result["documents"]:
+    print(doc.content)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: ArcadeDBDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create an ArcadeDBEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>ArcadeDBDocumentStore</code>) – An instance of `ArcadeDBDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Default filters applied to every retrieval call.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+- **filter_policy** (<code>FilterPolicy</code>) – How runtime filters interact with default filters.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by vector similarity.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – The embedding vector to search with.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional filters to narrow results.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of `Document`s most similar to the given `query_embedding`
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ArcadeDBEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ArcadeDBEmbeddingRetriever</code> – Deserialized component.
+
+## haystack_integrations.document_stores.arcadedb.document_store
+
+ArcadeDB DocumentStore for Haystack 2.x — document storage + vector search via HTTP/JSON API.
+
+### ArcadeDBDocumentStore
+
+An ArcadeDB-backed DocumentStore for Haystack 2.x.
+
+Uses ArcadeDB's HTTP/JSON API for all operations — no special drivers required.
+Supports HNSW vector search (LSM_VECTOR) and SQL metadata filtering.
+
+Usage example:
+
+```python
+from haystack.dataclasses.document import Document
+from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore
+
+document_store = ArcadeDBDocumentStore(
+    url="http://localhost:2480",
+    database="haystack",
+    embedding_dimension=768,
+)
+document_store.write_documents([
+    Document(content="This is first", embedding=[0.0]*5),
+    Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5])
+])
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    url: str = "http://localhost:2480",
+    database: str = "haystack",
+    username: Secret = Secret.from_env_var("ARCADEDB_USERNAME", strict=False),
+    password: Secret = Secret.from_env_var("ARCADEDB_PASSWORD", strict=False),
+    type_name: str = "Document",
+    embedding_dimension: int = 768,
+    similarity_function: str = "cosine",
+    recreate_type: bool = False,
+    create_database: bool = True
+) -> None
+```
+
+Create an ArcadeDBDocumentStore instance.
+
+**Parameters:**
+
+- **url** (<code>str</code>) – ArcadeDB HTTP endpoint.
+- **database** (<code>str</code>) – Database name.
+- **username** (<code>Secret</code>) – HTTP Basic Auth username (default: `ARCADEDB_USERNAME` env var).
+- **password** (<code>Secret</code>) – HTTP Basic Auth password (default: `ARCADEDB_PASSWORD` env var).
+- **type_name** (<code>str</code>) – Vertex type name for documents.
+- **embedding_dimension** (<code>int</code>) – Vector dimension for the HNSW index.
+- **similarity_function** (<code>str</code>) – Distance metric — `"cosine"`, `"euclidean"`, or `"dot"`.
+- **recreate_type** (<code>bool</code>) – If `True`, drop and recreate the type on initialization.
+- **create_database** (<code>bool</code>) – If `True`, create the database if it doesn't exist.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the DocumentStore to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ArcadeDBDocumentStore
+```
+
+Deserializes the DocumentStore from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ArcadeDBDocumentStore</code> – The deserialized DocumentStore.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – Number of documents in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Return documents matching the given filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Haystack filter dictionary.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – List of matching documents.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to the store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of Haystack Documents to write.
+- **policy** (<code>DuplicatePolicy</code>) – How to handle duplicate document IDs.
+
+**Returns:**
+
+- <code>int</code> – Number of documents written.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents by their IDs.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – List of document IDs to delete.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents in the document store.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for deletion.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Counts the number of documents matching the provided filter
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to the documents
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filter
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Counts unique values for each metadata field in documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+- **metadata_fields** (<code>list\[str\]</code>) – Metadata fields for which to count unique values.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary where keys are metadata field names and values are the
+  counts of unique values for that field.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the metadata fields and their corresponding types based on sampled documents.
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – A dictionary mapping field names to dictionaries with a `type` key.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+For a given metadata field, finds its min and max values.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to inspect.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with `min` and `max` keys and their corresponding values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a field matching a search term or all possible values
+if no search term is given.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to inspect.
+- **search_term** (<code>str | None</code>) – Optional case-insensitive substring search term.
+- **from\_** (<code>int</code>) – The starting index for pagination.
+- **size** (<code>int</code>) – The number of values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing the paginated values and the total count.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/astra.md

@@ -0,0 +1,520 @@
+---
+title: "Astra"
+id: integrations-astra
+description: "Astra integration for Haystack"
+slug: "/integrations-astra"
+---
+
+
+## haystack_integrations.components.retrievers.astra.retriever
+
+### AstraEmbeddingRetriever
+
+A component for retrieving documents from an AstraDocumentStore.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.astra import AstraDocumentStore
+from haystack_integrations.components.retrievers.astra import AstraEmbeddingRetriever
+
+document_store = AstraDocumentStore(
+    api_endpoint=api_endpoint,
+    token=token,
+    collection_name=collection_name,
+    duplicates_policy=DuplicatePolicy.SKIP,
+    embedding_dim=384,
+)
+
+retriever = AstraEmbeddingRetriever(document_store=document_store)
+```
+
+#### __init__
+
+```python
+__init__(
+    document_store: AstraDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Initialize the AstraEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>AstraDocumentStore</code>) – An instance of AstraDocumentStore.
+- **filters** (<code>dict\[str, Any\] | None</code>) – a dictionary with filters to narrow down the search space.
+- **top_k** (<code>int</code>) – the maximum number of documents to retrieve.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the AstraDocumentStore.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – floats representing the query embedding
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – the maximum number of documents to retrieve.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – a dictionary with the following keys:
+- `documents`: A list of documents retrieved from the AstraDocumentStore.
+
+#### run_async
+
+```python
+run_async(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the AstraDocumentStore asynchronously.
+
+Runs the sync search in a thread pool to avoid blocking the event loop.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – floats representing the query embedding
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – the maximum number of documents to retrieve.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – a dictionary with the following keys:
+- `documents`: A list of documents retrieved from the AstraDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AstraEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AstraEmbeddingRetriever</code> – Deserialized component.
+
+## haystack_integrations.document_stores.astra.document_store
+
+### AstraDocumentStore
+
+An AstraDocumentStore document store for Haystack.
+
+Example Usage:
+
+```python
+from haystack_integrations.document_stores.astra import AstraDocumentStore
+
+document_store = AstraDocumentStore(
+    api_endpoint=api_endpoint,
+    token=token,
+    collection_name=collection_name,
+    duplicates_policy=DuplicatePolicy.SKIP,
+    embedding_dim=384,
+)
+```
+
+#### __init__
+
+```python
+__init__(
+    api_endpoint: Secret = Secret.from_env_var("ASTRA_DB_API_ENDPOINT"),
+    token: Secret = Secret.from_env_var("ASTRA_DB_APPLICATION_TOKEN"),
+    collection_name: str = "documents",
+    embedding_dimension: int = 768,
+    duplicates_policy: DuplicatePolicy = DuplicatePolicy.NONE,
+    similarity: str = "cosine",
+    namespace: str | None = None,
+) -> None
+```
+
+The connection to Astra DB is established and managed through the JSON API.
+
+The required credentials (api endpoint and application token) can be generated
+through the UI by clicking and the connect tab, and then selecting JSON API and
+Generate Configuration.
+
+**Parameters:**
+
+- **api_endpoint** (<code>Secret</code>) – the Astra DB API endpoint.
+- **token** (<code>Secret</code>) – the Astra DB application token.
+- **collection_name** (<code>str</code>) – the current collection in the keyspace in the current Astra DB.
+- **embedding_dimension** (<code>int</code>) – dimension of embedding vector.
+- **duplicates_policy** (<code>DuplicatePolicy</code>) – handle duplicate documents based on DuplicatePolicy parameter options.
+  Parameter options : (`SKIP`, `OVERWRITE`, `FAIL`, `NONE`)
+- `DuplicatePolicy.NONE`: Default policy, If a Document with the same ID already exists,
+  it is skipped and not written.
+- `DuplicatePolicy.SKIP`: if a Document with the same ID already exists, it is skipped and not written.
+- `DuplicatePolicy.OVERWRITE`: if a Document with the same ID already exists, it is overwritten.
+- `DuplicatePolicy.FAIL`: if a Document with the same ID already exists, an error is raised.
+- **similarity** (<code>str</code>) – the similarity function used to compare document vectors.
+
+**Raises:**
+
+- <code>ValueError</code> – if the API endpoint or token is not set.
+
+#### index
+
+```python
+index: AstraClient
+```
+
+Return the AstraClient index, initializing it if necessary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AstraDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AstraDocumentStore</code> – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Indexes documents for later queries.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – a list of Haystack Document objects.
+- **policy** (<code>DuplicatePolicy</code>) – handle duplicate documents based on DuplicatePolicy parameter options.
+  Parameter options : (`SKIP`, `OVERWRITE`, `FAIL`, `NONE`)
+- `DuplicatePolicy.NONE`: Default policy, If a Document with the same ID already exists,
+  it is skipped and not written.
+- `DuplicatePolicy.SKIP`: If a Document with the same ID already exists,
+  it is skipped and not written.
+- `DuplicatePolicy.OVERWRITE`: If a Document with the same ID already exists, it is overwritten.
+- `DuplicatePolicy.FAIL`: If a Document with the same ID already exists, an error is raised.
+
+**Returns:**
+
+- <code>int</code> – number of documents written.
+
+**Raises:**
+
+- <code>ValueError</code> – if the documents are not of type Document or dict.
+- <code>DuplicateDocumentError</code> – if a document with the same ID already exists and policy is set to FAIL.
+- <code>Exception</code> – if the document ID is not a string or if `id` and `_id` are both present in the document.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Counts the number of documents in the document store.
+
+**Returns:**
+
+- <code>int</code> – the number of documents in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns at most 1000 documents that match the filter.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – filters to apply.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – matching documents.
+
+**Raises:**
+
+- <code>AstraDocumentStoreFilterError</code> – if the filter is invalid or not supported by this class.
+
+#### get_documents_by_id
+
+```python
+get_documents_by_id(ids: list[str]) -> list[Document]
+```
+
+Gets documents by their IDs.
+
+**Parameters:**
+
+- **ids** (<code>list\[str\]</code>) – the IDs of the documents to retrieve.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – the matching documents.
+
+#### get_document_by_id
+
+```python
+get_document_by_id(document_id: str) -> Document
+```
+
+Gets a document by its ID.
+
+**Parameters:**
+
+- **document_id** (<code>str</code>) – the ID to filter by
+
+**Returns:**
+
+- <code>Document</code> – the found document
+
+**Raises:**
+
+- <code>MissingDocumentError</code> – if the document is not found
+
+#### search
+
+```python
+search(
+    query_embedding: list[float],
+    top_k: int,
+    filters: dict[str, Any] | None = None,
+) -> list[Document]
+```
+
+Perform a search for a list of queries.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – a list of query embeddings.
+- **top_k** (<code>int</code>) – the number of results to return.
+- **filters** (<code>dict\[str, Any\] | None</code>) – filters to apply during search.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – matching documents.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents from the document store.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – IDs of the documents to delete.
+
+**Raises:**
+
+- <code>MissingDocumentError</code> – if no document was deleted but document IDs were provided.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents from the document store.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to find documents to delete.
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+**Raises:**
+
+- <code>AstraDocumentStoreFilterError</code> – if the filter is invalid or not supported.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates documents that match the provided filters with the given metadata.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to find documents to update.
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+**Raises:**
+
+- <code>AstraDocumentStoreFilterError</code> – if the filter is invalid or not supported.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Applies a filter and counts the documents that matched it.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filter.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Applies a filter selecting documents and counts the unique values for each meta field of the matched documents.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+- **metadata_fields** (<code>list\[str\]</code>) – The metadata fields to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary where the keys are the metadata field names and the values are the count of unique
+  values.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the metadata fields and the corresponding types.
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – A dictionary mapping field names to dictionaries with a `type` key.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+For a given metadata field, find its max and min value.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to inspect.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with `min` and `max`.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a field matching a search term or all possible values if no search term is given.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to inspect.
+- **search_term** (<code>str | None</code>) – Optional case-insensitive substring search term.
+- **from\_** (<code>int</code>) – The starting index for pagination.
+- **size** (<code>int</code>) – The number of values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing the paginated values and the total count.
+
+## haystack_integrations.document_stores.astra.errors
+
+### AstraDocumentStoreError
+
+Bases: <code>DocumentStoreError</code>
+
+Parent class for all AstraDocumentStore errors.
+
+### AstraDocumentStoreFilterError
+
+Bases: <code>FilterError</code>
+
+Raised when an invalid filter is passed to AstraDocumentStore.
+
+### AstraDocumentStoreConfigError
+
+Bases: <code>AstraDocumentStoreError</code>
+
+Raised when an invalid configuration is passed to AstraDocumentStore.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/azure_ai_search.md

@@ -0,0 +1,463 @@
+---
+title: "Azure AI Search"
+id: integrations-azure_ai_search
+description: "Azure AI Search integration for Haystack"
+slug: "/integrations-azure_ai_search"
+---
+
+
+## haystack_integrations.components.retrievers.azure_ai_search.embedding_retriever
+
+### AzureAISearchEmbeddingRetriever
+
+Retrieves documents from the AzureAISearchDocumentStore using a vector similarity metric.
+
+Must be connected to the AzureAISearchDocumentStore to run.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: AzureAISearchDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+    **kwargs: Any
+) -> None
+```
+
+Create the AzureAISearchEmbeddingRetriever component.
+
+**Parameters:**
+
+- **document_store** (<code>AzureAISearchDocumentStore</code>) – An instance of AzureAISearchDocumentStore to use with the Retriever.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied when fetching documents from the Document Store.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+- **kwargs** (<code>Any</code>) – Additional keyword arguments to pass to the Azure AI's search endpoint.
+  Some of the supported parameters:
+  - `query_type`: A string indicating the type of query to perform. Possible values are
+    'simple','full' and 'semantic'.
+  - `semantic_configuration_name`: The name of semantic configuration to be used when
+    processing semantic queries.
+    For more information on parameters, see the
+    [official Azure AI Search documentation](https://learn.microsoft.com/en-us/azure/search/).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureAISearchEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AzureAISearchEmbeddingRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the AzureAISearchDocumentStore.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – A list of floats representing the query embedding.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See `__init__` method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – The maximum number of documents to retrieve.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – Dictionary with the following keys:
+- `documents`: A list of documents retrieved from the AzureAISearchDocumentStore.
+
+## haystack_integrations.document_stores.azure_ai_search.document_store
+
+### AzureAISearchDocumentStore
+
+Document store using [Azure AI Search](https://azure.microsoft.com/products/ai-services/ai-search/) as the backend.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var(
+        "AZURE_AI_SEARCH_API_KEY", strict=False
+    ),
+    azure_endpoint: Secret = Secret.from_env_var(
+        "AZURE_AI_SEARCH_ENDPOINT", strict=True
+    ),
+    index_name: str = "default",
+    embedding_dimension: int = 768,
+    metadata_fields: dict[str, SearchField | type] | None = None,
+    vector_search_configuration: VectorSearch | None = None,
+    include_search_metadata: bool = False,
+    azure_token_credential: TokenCredential | None = None,
+    **index_creation_kwargs: Any
+) -> None
+```
+
+Creates a new instance of AzureAISearchDocumentStore.
+
+**Parameters:**
+
+- **azure_endpoint** (<code>Secret</code>) – The URL endpoint of an Azure AI Search service.
+- **api_key** (<code>Secret</code>) – The API key to use for authentication.
+- **index_name** (<code>str</code>) – Name of index in Azure AI Search, if it doesn't exist it will be created.
+- **embedding_dimension** (<code>int</code>) – Dimension of the embeddings.
+- **metadata_fields** (<code>dict\[str, SearchField | type\] | None</code>) – A dictionary mapping metadata field names to their corresponding field definitions.
+  Each field can be defined either as:
+- A SearchField object to specify detailed field configuration like type, searchability, and filterability
+- A Python type (`str`, `bool`, `int`, `float`, or `datetime`) to create a simple filterable field
+
+These fields are automatically added when creating the search index.
+Example:
+
+```python
+metadata_fields={
+    "Title": SearchField(
+        name="Title",
+        type="Edm.String",
+        searchable=True,
+        filterable=True
+    ),
+    "Pages": int
+}
+```
+
+- **vector_search_configuration** (<code>VectorSearch | None</code>) – Configuration option related to vector search.
+  Default configuration uses the HNSW algorithm with cosine similarity to handle vector searches.
+- **include_search_metadata** (<code>bool</code>) – Whether to include Azure AI Search metadata fields
+  in the returned documents. When set to True, the `meta` field of the returned
+  documents will contain the @search.score, @search.reranker_score, @search.highlights,
+  @search.captions, and other fields returned by Azure AI Search.
+- **azure_token_credential** (<code>TokenCredential | None</code>) – An Azure `TokenCredential` instance used to authenticate requests.
+  When provided, this takes priority over `api_key`.
+- **index_creation_kwargs** (<code>Any</code>) – Optional keyword parameters to be passed to `SearchIndex` class
+  during index creation. Some of the supported parameters:
+  \- `semantic_search`: Defines semantic configuration of the search index. This parameter is needed
+  to enable semantic search capabilities in index.
+  \- `similarity`: The type of similarity algorithm to be used when scoring and ranking the documents
+  matching a search query. The similarity algorithm can only be defined at index creation time and
+  cannot be modified on existing indexes.
+
+For more information on parameters, see the [official Azure AI Search documentation](https://learn.microsoft.com/en-us/azure/search/).
+
+#### client
+
+```python
+client: SearchClient
+```
+
+Return the Azure SearchClient, creating the index if it does not exist.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureAISearchDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AzureAISearchDocumentStore</code> – Deserialized component.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the search index.
+
+**Returns:**
+
+- <code>int</code> – list of retrieved documents.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the count of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Counts unique values for each specified metadata field in documents matching the filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents.
+- **metadata_fields** (<code>list\[str\]</code>) – List of field names to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – Dictionary mapping field names to counts of unique values.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the information about metadata fields in the index.
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – Dictionary mapping field names to type information.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get the minimum and maximum values for.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the keys "min" and "max".
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a metadata field with optional search and pagination.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get unique values for.
+- **search_term** (<code>str | None</code>) – Optional search term to filter unique values.
+- **from\_** (<code>int</code>) – Starting offset for pagination.
+- **size** (<code>int</code>) – Number of values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – Tuple of (list of unique values, total count of matching values).
+
+#### query_sql
+
+```python
+query_sql(query: str) -> Any
+```
+
+Executes an SQL query if supported by the document store backend.
+
+Azure AI Search does not support SQL queries.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes the provided documents to search index.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – documents to write to the index.
+- **policy** (<code>DuplicatePolicy</code>) – Policy to determine how duplicates are handled.
+
+**Returns:**
+
+- <code>int</code> – the number of documents added to index.
+
+**Raises:**
+
+- <code>ValueError</code> – If the documents are not of type Document.
+- <code>TypeError</code> – If the document ids are not strings.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with a matching document_ids from the search index.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – ids of the documents to be deleted.
+
+#### delete_all_documents
+
+```python
+delete_all_documents(recreate_index: bool = False) -> None
+```
+
+Deletes all documents in the document store.
+
+**Parameters:**
+
+- **recreate_index** (<code>bool</code>) – If True, the index will be deleted and recreated with the original schema.
+  If False, all documents will be deleted while preserving the index.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+Azure AI Search does not support server-side delete by query, so this method
+first searches for matching documents, then deletes them in a batch operation.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for deletion.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the fields of all documents that match the provided filters.
+
+Azure AI Search does not support server-side update by query, so this method
+first searches for matching documents, then updates them using merge operations.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (<code>dict\[str, Any\]</code>) – The fields to update. These fields must exist in the index schema.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+#### get_documents_by_id
+
+```python
+get_documents_by_id(document_ids: list[str]) -> list[Document]
+```
+
+Retrieves documents by their IDs.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – IDs of the documents to retrieve.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – List of documents with the given IDs.
+
+#### search_documents
+
+```python
+search_documents(search_text: str = '*', top_k: int = 10) -> list[Document]
+```
+
+Returns all documents that match the provided search_text.
+
+If search_text is None, returns all documents.
+
+**Parameters:**
+
+- **search_text** (<code>str</code>) – the text to search for in the Document list.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given search_text.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the provided filters.
+
+Filters should be given as a dictionary supporting filtering by metadata. For details on
+filters, see the [metadata filtering documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – the filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+## haystack_integrations.document_stores.azure_ai_search.filters

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/azure_doc_intelligence.md

@@ -0,0 +1,155 @@
+---
+title: "Azure Document Intelligence"
+id: integrations-azure_doc_intelligence
+description: "Azure Document Intelligence integration for Haystack"
+slug: "/integrations-azure_doc_intelligence"
+---
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter"></a>
+
+## Module haystack\_integrations.components.converters.azure\_doc\_intelligence.converter
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter"></a>
+
+### AzureDocumentIntelligenceConverter
+
+Converts files to Documents using Azure's Document Intelligence service.
+
+This component uses the azure-ai-documentintelligence package (v1.0.0+) and outputs
+GitHub Flavored Markdown for better integration with LLM/RAG applications.
+
+Supported file formats: PDF, JPEG, PNG, BMP, TIFF, DOCX, XLSX, PPTX, HTML.
+
+Key features:
+- Markdown output with preserved structure (headings, tables, lists)
+- Inline table integration (tables rendered as markdown tables)
+- Improved layout analysis and reading order
+- Support for section headings
+
+To use this component, you need an active Azure account
+and a Document Intelligence or Cognitive Services resource. For setup instructions, see
+[Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/quickstarts/get-started-sdks-rest-api).
+
+### Usage example
+
+```python
+import os
+from haystack_integrations.components.converters.azure_doc_intelligence import (
+    AzureDocumentIntelligenceConverter,
+)
+from haystack.utils import Secret
+
+converter = AzureDocumentIntelligenceConverter(
+    endpoint=os.environ["AZURE_DI_ENDPOINT"],
+    api_key=Secret.from_env_var("AZURE_DI_API_KEY"),
+)
+
+results = converter.run(sources=["invoice.pdf", "contract.docx"])
+documents = results["documents"]
+
+# Documents contain markdown with inline tables
+print(documents[0].content)
+```
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter.__init__"></a>
+
+#### AzureDocumentIntelligenceConverter.\_\_init\_\_
+
+```python
+def __init__(endpoint: str,
+             *,
+             api_key: Secret = Secret.from_env_var("AZURE_DI_API_KEY"),
+             model_id: str = "prebuilt-document",
+             store_full_path: bool = False)
+```
+
+Creates an AzureDocumentIntelligenceConverter component.
+
+**Arguments**:
+
+- `endpoint`: The endpoint URL of your Azure Document Intelligence resource.
+Example: "https://YOUR_RESOURCE.cognitiveservices.azure.com/"
+- `api_key`: API key for Azure authentication. Can use Secret.from_env_var()
+to load from AZURE_DI_API_KEY environment variable.
+- `model_id`: Azure model to use for analysis. Options:
+- "prebuilt-document": General document analysis (default)
+- "prebuilt-read": Fast OCR for text extraction
+- "prebuilt-layout": Enhanced layout analysis with better table/structure detection
+- Custom model IDs from your Azure resource
+- `store_full_path`: If True, stores complete file path in metadata.
+If False, stores only the filename (default).
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter.warm_up"></a>
+
+#### AzureDocumentIntelligenceConverter.warm\_up
+
+```python
+def warm_up()
+```
+
+Initializes the Azure Document Intelligence client.
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter.run"></a>
+
+#### AzureDocumentIntelligenceConverter.run
+
+```python
+@component.output_types(documents=list[Document],
+                        raw_azure_response=list[dict])
+def run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, list[Document] | list[dict]]
+```
+
+Convert a list of files to Documents using Azure's Document Intelligence service.
+
+**Arguments**:
+
+- `sources`: List of file paths or ByteStream objects.
+- `meta`: Optional metadata to attach to the Documents.
+This value can be either a list of dictionaries or a single dictionary.
+If it's a single dictionary, its content is added to the metadata of all produced Documents.
+If it's a list, the length of the list must match the number of sources, because the two lists will be
+zipped. If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `documents`: List of created Documents
+- `raw_azure_response`: List of raw Azure responses used to create the Documents
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter.to_dict"></a>
+
+#### AzureDocumentIntelligenceConverter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.converters.azure_doc_intelligence.converter.AzureDocumentIntelligenceConverter.from_dict"></a>
+
+#### AzureDocumentIntelligenceConverter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str,
+                              Any]) -> "AzureDocumentIntelligenceConverter"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/chroma.md

@@ -0,0 +1,976 @@
+---
+title: "Chroma"
+id: integrations-chroma
+description: "Chroma integration for Haystack"
+slug: "/integrations-chroma"
+---
+
+
+## haystack_integrations.components.retrievers.chroma.retriever
+
+### ChromaQueryTextRetriever
+
+A component for retrieving documents from a [Chroma database](https://docs.trychroma.com/) using the `query` API.
+
+Example usage:
+
+```python
+from haystack import Pipeline
+from haystack.components.converters import TextFileToDocument
+from haystack.components.writers import DocumentWriter
+
+from haystack_integrations.document_stores.chroma import ChromaDocumentStore
+from haystack_integrations.components.retrievers.chroma import ChromaQueryTextRetriever
+
+file_paths = ...
+
+# Chroma is used in-memory so we use the same instances in the two pipelines below
+document_store = ChromaDocumentStore()
+
+indexing = Pipeline()
+indexing.add_component("converter", TextFileToDocument())
+indexing.add_component("writer", DocumentWriter(document_store))
+indexing.connect("converter", "writer")
+indexing.run({"converter": {"sources": file_paths}})
+
+querying = Pipeline()
+querying.add_component("retriever", ChromaQueryTextRetriever(document_store))
+results = querying.run({"retriever": {"query": "Variable declarations", "top_k": 3}})
+
+for d in results["retriever"]["documents"]:
+    print(d.meta, d.score)
+```
+
+#### __init__
+
+```python
+__init__(
+    document_store: ChromaDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+)
+```
+
+**Parameters:**
+
+- **document_store** (<code>ChromaDocumentStore</code>) – an instance of `ChromaDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – filters to narrow down the search space.
+- **top_k** (<code>int</code>) – the maximum number of documents to retrieve.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+#### run
+
+```python
+run(
+    query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, Any]
+```
+
+Run the retriever on the given input data.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The input data for the retriever. In this case, a plain-text query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – The maximum number of documents to retrieve.
+  If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+**Raises:**
+
+- <code>ValueError</code> – If the specified document store is not found or is not a MemoryDocumentStore instance.
+
+#### run_async
+
+```python
+run_async(
+    query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously run the retriever on the given input data.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The input data for the retriever. In this case, a plain-text query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – The maximum number of documents to retrieve.
+  If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+**Raises:**
+
+- <code>ValueError</code> – If the specified document store is not found or is not a MemoryDocumentStore instance.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChromaQueryTextRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ChromaQueryTextRetriever</code> – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+### ChromaEmbeddingRetriever
+
+A component for retrieving documents from a [Chroma database](https://docs.trychroma.com/) using embeddings.
+
+#### __init__
+
+```python
+__init__(
+    document_store: ChromaDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+)
+```
+
+**Parameters:**
+
+- **document_store** (<code>ChromaDocumentStore</code>) – an instance of `ChromaDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – filters to narrow down the search space.
+- **top_k** (<code>int</code>) – the maximum number of documents to retrieve.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, Any]
+```
+
+Run the retriever on the given input data.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – the query embeddings.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – the maximum number of documents to retrieve.
+  If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – a dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+#### run_async
+
+```python
+run_async(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, Any]
+```
+
+Asynchronously run the retriever on the given input data.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – the query embeddings.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – the maximum number of documents to retrieve.
+  If not specified, the default value from the constructor is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – a dictionary with the following keys:
+- `documents`: List of documents returned by the search engine.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChromaEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ChromaEmbeddingRetriever</code> – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.document_stores.chroma.document_store
+
+### ChromaDocumentStore
+
+A document store using [Chroma](https://docs.trychroma.com/) as the backend.
+
+We use the `collection.get` API to implement the document store protocol,
+the `collection.search` API will be used in the retriever instead.
+
+#### __init__
+
+```python
+__init__(
+    collection_name: str = "documents",
+    embedding_function: str = "default",
+    persist_path: str | None = None,
+    host: str | None = None,
+    port: int | None = None,
+    distance_function: Literal["l2", "cosine", "ip"] = "l2",
+    metadata: dict | None = None,
+    client_settings: dict[str, Any] | None = None,
+    **embedding_function_params: Any
+)
+```
+
+Creates a new ChromaDocumentStore instance.
+It is meant to be connected to a Chroma collection.
+
+Note: for the component to be part of a serializable pipeline, the __init__
+parameters must be serializable, reason why we use a registry to configure the
+embedding function passing a string.
+
+**Parameters:**
+
+- **collection_name** (<code>str</code>) – the name of the collection to use in the database.
+- **embedding_function** (<code>str</code>) – the name of the embedding function to use to embed the query
+- **persist_path** (<code>str | None</code>) – Path for local persistent storage. Cannot be used in combination with `host` and `port`.
+  If none of `persist_path`, `host`, and `port` is specified, the database will be `in-memory`.
+- **host** (<code>str | None</code>) – The host address for the remote Chroma HTTP client connection. Cannot be used with `persist_path`.
+- **port** (<code>int | None</code>) – The port number for the remote Chroma HTTP client connection. Cannot be used with `persist_path`.
+- **distance_function** (<code>Literal['l2', 'cosine', 'ip']</code>) – The distance metric for the embedding space.
+- `"l2"` computes the Euclidean (straight-line) distance between vectors,
+  where smaller scores indicate more similarity.
+- `"cosine"` computes the cosine similarity between vectors,
+  with higher scores indicating greater similarity.
+- `"ip"` stands for inner product, where higher scores indicate greater similarity between vectors.
+  **Note**: `distance_function` can only be set during the creation of a collection.
+  To change the distance metric of an existing collection, consider cloning the collection.
+- **metadata** (<code>dict | None</code>) – a dictionary of chromadb collection parameters passed directly to chromadb's client
+  method `create_collection`. If it contains the key `"hnsw:space"`, the value will take precedence over the
+  `distance_function` parameter above.
+- **client_settings** (<code>dict\[str, Any\] | None</code>) – a dictionary of Chroma Settings configuration options passed to
+  `chromadb.config.Settings`. These settings configure the underlying Chroma client behavior.
+  For available options, see [Chroma's config.py](https://github.com/chroma-core/chroma/blob/main/chromadb/config.py).
+  **Note**: specifying these settings may interfere with standard client initialization parameters.
+  This option is intended for advanced customization.
+- **embedding_function_params** (<code>Any</code>) – additional parameters to pass to the embedding function.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – how many documents are present in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns how many documents are present in the document store.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Returns:**
+
+- <code>int</code> – how many documents are present in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – the filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – a list of Documents that match the given filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+Asynchronous methods are only supported for HTTP connections.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – the filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – a list of Documents that match the given filters.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.FAIL
+) -> int
+```
+
+Writes (or overwrites) documents into the store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to write into the document store.
+- **policy** (<code>DuplicatePolicy</code>) – Not supported at the moment.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written
+
+**Raises:**
+
+- <code>ValueError</code> – When input is not valid.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.FAIL
+) -> int
+```
+
+Asynchronously writes (or overwrites) documents into the store.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to write into the document store.
+- **policy** (<code>DuplicatePolicy</code>) – Not supported at the moment.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written
+
+**Raises:**
+
+- <code>ValueError</code> – When input is not valid.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with a matching document_ids from the document store.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – the document ids to delete
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes all documents with a matching document_ids from the document store.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – the document ids to delete
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for deletion.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for deletion.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Note**: This operation is not atomic. Documents matching the filter are fetched first,
+then updated. If documents are modified between the fetch and update operations,
+those changes may be lost.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Note**: This operation is not atomic. Documents matching the filter are fetched first,
+then updated. If documents are modified between the fetch and update operations,
+those changes may be lost.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update. This will be merged with existing metadata.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+#### delete_all_documents
+
+```python
+delete_all_documents(*, recreate_index: bool = False) -> None
+```
+
+Deletes all documents in the document store.
+
+A fast way to clear all documents from the document store while preserving any collection settings and mappings.
+
+**Parameters:**
+
+- **recreate_index** (<code>bool</code>) – Whether to recreate the index after deleting all documents.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async(*, recreate_index: bool = False) -> None
+```
+
+Asynchronously deletes all documents in the document store.
+
+A fast way to clear all documents from the document store while preserving any collection settings and mappings.
+
+**Parameters:**
+
+- **recreate_index** (<code>bool</code>) – Whether to recreate the index after deleting all documents.
+
+#### search
+
+```python
+search(
+    queries: list[str], top_k: int, filters: dict[str, Any] | None = None
+) -> list[list[Document]]
+```
+
+Search the documents in the store using the provided text queries.
+
+**Parameters:**
+
+- **queries** (<code>list\[str\]</code>) – the list of queries to search for.
+- **top_k** (<code>int</code>) – top_k documents to return for each query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- <code>list\[list\[Document\]\]</code> – matching documents for each query.
+
+#### search_async
+
+```python
+search_async(
+    queries: list[str], top_k: int, filters: dict[str, Any] | None = None
+) -> list[list[Document]]
+```
+
+Asynchronously search the documents in the store using the provided text queries.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **queries** (<code>list\[str\]</code>) – the list of queries to search for.
+- **top_k** (<code>int</code>) – top_k documents to return for each query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- <code>list\[list\[Document\]\]</code> – matching documents for each query.
+
+#### search_embeddings
+
+```python
+search_embeddings(
+    query_embeddings: list[list[float]],
+    top_k: int,
+    filters: dict[str, Any] | None = None,
+) -> list[list[Document]]
+```
+
+Perform vector search on the stored document, pass the embeddings of the queries instead of their text.
+
+**Parameters:**
+
+- **query_embeddings** (<code>list\[list\[float\]\]</code>) – a list of embeddings to use as queries.
+- **top_k** (<code>int</code>) – the maximum number of documents to retrieve.
+- **filters** (<code>dict\[str, Any\] | None</code>) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- <code>list\[list\[Document\]\]</code> – a list of lists of documents that match the given filters.
+
+#### search_embeddings_async
+
+```python
+search_embeddings_async(
+    query_embeddings: list[list[float]],
+    top_k: int,
+    filters: dict[str, Any] | None = None,
+) -> list[list[Document]]
+```
+
+Asynchronously perform vector search on the stored document, pass the embeddings of the queries instead of
+their text.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **query_embeddings** (<code>list\[list\[float\]\]</code>) – a list of embeddings to use as queries.
+- **top_k** (<code>int</code>) – the maximum number of documents to retrieve.
+- **filters** (<code>dict\[str, Any\] | None</code>) – a dictionary of filters to apply to the search. Accepts filters in haystack format.
+
+**Returns:**
+
+- <code>list\[list\[Document\]\]</code> – a list of lists of documents that match the given filters.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filters.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the number of documents that match the provided filters.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the number of unique values for each specified metadata field
+of the documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (<code>list\[str\]</code>) – List of field names to calculate unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary mapping each metadata field name to the count of
+  its unique values among the filtered documents.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously returns the number of unique values for each specified metadata field
+of the documents that match the provided filters.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (<code>list\[str\]</code>) – List of field names to calculate unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary mapping each metadata field name to the count of
+  its unique values among the filtered documents.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns information about the metadata fields in the collection.
+
+Since ChromaDB doesn't maintain a schema, this method samples documents
+to infer field types.
+
+If we populated the collection with documents like:
+
+```python
+Document(content="Doc 1", meta={"category": "A", "status": "active", "priority": 1})
+Document(content="Doc 2", meta={"category": "B", "status": "inactive"})
+```
+
+This method would return:
+
+```python
+{
+    'category': {'type': 'keyword'},
+    'status': {'type': 'keyword'},
+    'priority': {'type': 'long'},
+}
+```
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – Dictionary mapping field names to their type information.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns information about the metadata fields in the collection.
+
+Asynchronous methods are only supported for HTTP connections.
+
+Since ChromaDB doesn't maintain a schema, this method samples documents
+to infer field types.
+
+If we populated the collection with documents like:
+
+```python
+Document(content="Doc 1", meta={"category": "A", "status": "active", "priority": 1})
+Document(content="Doc 2", meta={"category": "B", "status": "inactive"})
+```
+
+This method would return:
+
+```python
+{
+    'category': {'type': 'keyword'},
+    'status': {'type': 'keyword'},
+    'priority': {'type': 'long'},
+}
+```
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – Dictionary mapping field names to their type information.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get the minimum and maximum values for.
+  Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the keys "min" and "max", where each value is
+  the minimum or maximum value of the metadata field across all documents.
+  Returns:
+
+```python
+  {"min": None, "max": None}
+```
+
+if field doesn't exist or has no values.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously returns the minimum and maximum values for the given metadata field.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get the minimum and maximum values for.
+  Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the keys "min" and "max", where each value is
+  the minimum or maximum value of the metadata field across all documents.
+  Returns:
+
+```python
+  {"min": None, "max": None}
+```
+
+if field doesn't exist or has no values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Returns unique values for a metadata field, optionally filtered by
+a search term in the content field, with pagination support.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get unique values for.
+  Can include or omit the "meta." prefix.
+- **search_term** (<code>str | None</code>) – Optional search term to filter documents by matching
+  in the content field.
+- **from\_** (<code>int</code>) – The offset to start returning values from (for pagination).
+- **size** (<code>int</code>) – The maximum number of unique values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing list of unique values and total count of unique values.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously returns unique values for a metadata field, optionally filtered by
+a search term in the content field, with pagination support.
+
+Asynchronous methods are only supported for HTTP connections.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get unique values for.
+  Can include or omit the "meta." prefix.
+- **search_term** (<code>str | None</code>) – Optional search term to filter documents by matching
+  in the content field.
+- **from\_** (<code>int</code>) – The offset to start returning values from (for pagination).
+- **size** (<code>int</code>) – The maximum number of unique values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing list of unique values and total count of unique values.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ChromaDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ChromaDocumentStore</code> – Deserialized component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.document_stores.chroma.errors
+
+### ChromaDocumentStoreError
+
+Bases: <code>DocumentStoreError</code>
+
+Parent class for all ChromaDocumentStore exceptions.
+
+### ChromaDocumentStoreFilterError
+
+Bases: <code>FilterError</code>, <code>ValueError</code>
+
+Raised when a filter is not valid for a ChromaDocumentStore.
+
+### ChromaDocumentStoreConfigError
+
+Bases: <code>ChromaDocumentStoreError</code>
+
+Raised when a configuration is not valid for a ChromaDocumentStore.
+
+## haystack_integrations.document_stores.chroma.utils
+
+### get_embedding_function
+
+```python
+get_embedding_function(function_name: str, **kwargs: Any) -> EmbeddingFunction
+```
+
+Load an embedding function by name.
+
+**Parameters:**
+
+- **function_name** (<code>str</code>) – the name of the embedding function.
+- **kwargs** (<code>Any</code>) – additional arguments to pass to the embedding function.
+
+**Returns:**
+
+- <code>EmbeddingFunction</code> – the loaded embedding function.
+
+**Raises:**
+
+- <code>ChromaDocumentStoreConfigError</code> – if the function name is invalid.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/cometapi.md

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

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/deepeval.md

@@ -0,0 +1,193 @@
+---
+title: "DeepEval"
+id: integrations-deepeval
+description: "DeepEval integration for Haystack"
+slug: "/integrations-deepeval"
+---
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator"></a>
+
+## Module haystack\_integrations.components.evaluators.deepeval.evaluator
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator.DeepEvalEvaluator"></a>
+
+### DeepEvalEvaluator
+
+A component that uses the [DeepEval framework](https://docs.confident-ai.com/docs/evaluation-introduction)
+to evaluate inputs against a specific metric. Supported metrics are defined by `DeepEvalMetric`.
+
+Usage example:
+```python
+from haystack_integrations.components.evaluators.deepeval import DeepEvalEvaluator, DeepEvalMetric
+
+evaluator = DeepEvalEvaluator(
+    metric=DeepEvalMetric.FAITHFULNESS,
+    metric_params={"model": "gpt-4"},
+)
+output = evaluator.run(
+    questions=["Which is the most popular global sport?"],
+    contexts=[
+        [
+            "Football is undoubtedly the world's most popular sport with"
+            "major events like the FIFA World Cup and sports personalities"
+            "like Ronaldo and Messi, drawing a followership of more than 4"
+            "billion people."
+        ]
+    ],
+    responses=["Football is the most popular sport with around 4 billion" "followers worldwide"],
+)
+print(output["results"])
+```
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator.DeepEvalEvaluator.__init__"></a>
+
+#### DeepEvalEvaluator.\_\_init\_\_
+
+```python
+def __init__(metric: str | DeepEvalMetric,
+             metric_params: dict[str, Any] | None = None)
+```
+
+Construct a new DeepEval evaluator.
+
+**Arguments**:
+
+- `metric`: The metric to use for evaluation.
+- `metric_params`: Parameters to pass to the metric's constructor.
+Refer to the `RagasMetric` class for more details
+on required parameters.
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator.DeepEvalEvaluator.run"></a>
+
+#### DeepEvalEvaluator.run
+
+```python
+@component.output_types(results=list[list[dict[str, Any]]])
+def run(**inputs: Any) -> dict[str, Any]
+```
+
+Run the DeepEval evaluator on the provided inputs.
+
+**Arguments**:
+
+- `inputs`: The inputs to evaluate. These are determined by the
+metric being calculated. See `DeepEvalMetric` for more
+information.
+
+**Returns**:
+
+A dictionary with a single `results` entry that contains
+a nested list of metric results. Each input can have one or more
+results, depending on the metric. Each result is a dictionary
+containing the following keys and values:
+- `name` - The name of the metric.
+- `score` - The score of the metric.
+- `explanation` - An optional explanation of the score.
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator.DeepEvalEvaluator.to_dict"></a>
+
+#### DeepEvalEvaluator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Raises**:
+
+- `DeserializationError`: If the component cannot be serialized.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.evaluators.deepeval.evaluator.DeepEvalEvaluator.from_dict"></a>
+
+#### DeepEvalEvaluator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "DeepEvalEvaluator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics"></a>
+
+## Module haystack\_integrations.components.evaluators.deepeval.metrics
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric"></a>
+
+### DeepEvalMetric
+
+Metrics supported by DeepEval.
+
+All metrics require a `model` parameter, which specifies
+the model to use for evaluation. Refer to the DeepEval
+documentation for information on the supported models.
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.ANSWER_RELEVANCY"></a>
+
+#### ANSWER\_RELEVANCY
+
+Answer relevancy.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]`
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.FAITHFULNESS"></a>
+
+#### FAITHFULNESS
+
+Faithfulness.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]`
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.CONTEXTUAL_PRECISION"></a>
+
+#### CONTEXTUAL\_PRECISION
+
+Contextual precision.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str], ground_truths: List[str]`\
+The ground truth is the expected response.
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.CONTEXTUAL_RECALL"></a>
+
+#### CONTEXTUAL\_RECALL
+
+Contextual recall.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str], ground_truths: List[str]`\
+The ground truth is the expected response.\
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.CONTEXTUAL_RELEVANCE"></a>
+
+#### CONTEXTUAL\_RELEVANCE
+
+Contextual relevance.\
+Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]`
+
+<a id="haystack_integrations.components.evaluators.deepeval.metrics.DeepEvalMetric.from_str"></a>
+
+#### DeepEvalMetric.from\_str
+
+```python
+@classmethod
+def from_str(cls, string: str) -> "DeepEvalMetric"
+```
+
+Create a metric type from a string.
+
+**Arguments**:
+
+- `string`: The string to convert.
+
+**Returns**:
+
+The metric.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/docling.md

@@ -0,0 +1,133 @@
+---
+title: "Docling"
+id: integrations-docling
+description: "Docling integration for Haystack"
+slug: "/integrations-docling"
+---
+
+
+## haystack_integrations.components.converters.docling.converter
+
+Docling Haystack converter module.
+
+### ExportType
+
+Bases: <code>str</code>, <code>Enum</code>
+
+Enumeration of available export types.
+
+### BaseMetaExtractor
+
+Bases: <code>ABC</code>
+
+BaseMetaExtractor.
+
+#### extract_chunk_meta
+
+```python
+extract_chunk_meta(chunk: BaseChunk) -> dict[str, Any]
+```
+
+Extract chunk meta.
+
+#### extract_dl_doc_meta
+
+```python
+extract_dl_doc_meta(dl_doc: DoclingDocument) -> dict[str, Any]
+```
+
+Extract Docling document meta.
+
+### MetaExtractor
+
+Bases: <code>BaseMetaExtractor</code>
+
+MetaExtractor.
+
+#### extract_chunk_meta
+
+```python
+extract_chunk_meta(chunk: BaseChunk) -> dict[str, Any]
+```
+
+Extract chunk meta.
+
+#### extract_dl_doc_meta
+
+```python
+extract_dl_doc_meta(dl_doc: DoclingDocument) -> dict[str, Any]
+```
+
+Extract Docling document meta.
+
+### DoclingConverter
+
+Docling Haystack converter.
+
+#### __init__
+
+```python
+__init__(
+    converter: DocumentConverter | None = None,
+    convert_kwargs: dict[str, Any] | None = None,
+    export_type: ExportType = ExportType.DOC_CHUNKS,
+    md_export_kwargs: dict[str, Any] | None = None,
+    chunker: BaseChunker | None = None,
+    meta_extractor: BaseMetaExtractor | None = None,
+) -> None
+```
+
+Create a Docling Haystack converter.
+
+**Parameters:**
+
+- **converter** (<code>DocumentConverter | None</code>) – The Docling `DocumentConverter` to use; if not set, a system
+  default is used.
+- **convert_kwargs** (<code>dict\[str, Any\] | None</code>) – Any parameters to pass to Docling conversion; if not set, a
+  system default is used.
+- **export_type** (<code>ExportType</code>) – The export mode to use:
+
+* `ExportType.MARKDOWN` captures each input document as a single
+  markdown `Document`.
+* `ExportType.DOC_CHUNKS` (default) first chunks each input document
+  and then returns one `Document` per chunk.
+* `ExportType.JSON` serializes the full Docling document to a JSON string.
+
+- **md_export_kwargs** (<code>dict\[str, Any\] | None</code>) – Any parameters to pass to Markdown export (applicable in
+  case of `ExportType.MARKDOWN`).
+- **chunker** (<code>BaseChunker | None</code>) – The Docling chunker instance to use; if not set, a system default
+  is used.
+- **meta_extractor** (<code>BaseMetaExtractor | None</code>) – The extractor instance to use for populating the output
+  document metadata; if not set, a system default is used.
+
+#### run
+
+```python
+run(
+    paths: list[str | Path] | None = None,
+    sources: list[str | Path | ByteStream] | None = None,
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Run the DoclingConverter.
+
+**Parameters:**
+
+- **paths** (<code>list\[str | Path\] | None</code>) – Deprecated. Use `sources` instead.
+- **sources** (<code>list\[str | Path | ByteStream\] | None</code>) – List of file paths, URLs, or ByteStream objects to convert.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the Documents.
+  This value can be either a list of dictionaries or a single dictionary.
+  If it's a single dictionary, its content is added to the metadata of all produced Documents.
+  If it's a list, the length of the list must match the number of sources, because the two lists will
+  be zipped.
+  If a source is a ByteStream, its own metadata is also merged into the output.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with key `"documents"` containing the output Haystack Documents.
+
+**Raises:**
+
+- <code>ValueError</code> – If `meta` is a list whose length does not match the number of sources.
+- <code>RuntimeError</code> – If an unexpected `export_type` is encountered.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/faiss.md

@@ -0,0 +1,456 @@
+---
+title: "FAISS"
+id: integrations-faiss
+description: "FAISS integration for Haystack"
+slug: "/integrations-faiss"
+---
+
+
+## haystack_integrations.components.retrievers.faiss.embedding_retriever
+
+### FAISSEmbeddingRetriever
+
+Retrieves documents from the `FAISSDocumentStore`, based on their dense embeddings.
+
+Example usage:
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack.document_stores.types import DuplicatePolicy
+
+from haystack_integrations.document_stores.faiss import FAISSDocumentStore
+from haystack_integrations.components.retrievers.faiss import FAISSEmbeddingRetriever
+
+document_store = FAISSDocumentStore(embedding_dim=768)
+
+documents = [
+    Document(content="There are over 7,000 languages spoken around the world today."),
+    Document(content="Elephants have been observed to behave in a way that indicates a high level of intelligence."),
+    Document(content="In certain places, you can witness the phenomenon of bioluminescent waves."),
+]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)["documents"]
+
+document_store.write_documents(documents_with_embeddings, policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", FAISSEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+res = query_pipeline.run({"text_embedder": {"text": query}})
+
+assert res["retriever"]["documents"][0].content == "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: FAISSDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize FAISSEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>FAISSDocumentStore</code>) – An instance of `FAISSDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents at initialisation time. At runtime, these are merged
+  with any runtime filters according to the `filter_policy`.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how init-time and runtime filters are combined.
+  See `FilterPolicy` for details. Defaults to `FilterPolicy.REPLACE`.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `FAISSDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FAISSEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>FAISSEmbeddingRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `FAISSDocumentStore`, based on their embeddings.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – Maximum number of Documents to return. Overrides the value set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of `Document`s that are similar to `query_embedding`.
+
+#### run_async
+
+```python
+run_async(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the `FAISSDocumentStore`, based on their embeddings.
+
+Since FAISS search is CPU-bound and fully in-memory, this delegates directly to the synchronous
+`run()` method. No I/O or network calls are involved.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – Maximum number of Documents to return. Overrides the value set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of `Document`s that are similar to `query_embedding`.
+
+## haystack_integrations.document_stores.faiss.document_store
+
+### FAISSDocumentStore
+
+A Document Store using FAISS for vector search and a simple JSON file for metadata storage.
+
+This Document Store is suitable for small to medium-sized datasets where simplicity is preferred over scalability.
+It supports basic persistence by saving the FAISS index to a `.faiss` file and documents to a `.json` file.
+
+#### __init__
+
+```python
+__init__(
+    index_path: str | None = None,
+    index_string: str = "Flat",
+    embedding_dim: int = 768,
+) -> None
+```
+
+Initializes the FAISSDocumentStore.
+
+**Parameters:**
+
+- **index_path** (<code>str | None</code>) – Path to save/load the index and documents. If None, the store is in-memory only.
+- **index_string** (<code>str</code>) – The FAISS index factory string. Default is "Flat".
+- **embedding_dim** (<code>int</code>) – The dimension of the embeddings. Default is 768.
+
+**Raises:**
+
+- <code>DocumentStoreError</code> – If the FAISS index cannot be initialized.
+- <code>ValueError</code> – If `index_path` points to a missing `.faiss` file when loading persisted data.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns the number of documents in the store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – A dictionary of filters to apply.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of matching Documents.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.FAIL
+) -> int
+```
+
+Writes documents to the store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – The list of documents to write.
+- **policy** (<code>DuplicatePolicy</code>) – The policy to handle duplicate documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` is not an iterable of `Document` objects.
+- <code>DuplicateDocumentError</code> – If a duplicate document is found and `policy` is `DuplicatePolicy.FAIL`.
+- <code>DocumentStoreError</code> – If the FAISS index is unexpectedly unavailable when adding embeddings.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents from the store.
+
+**Raises:**
+
+- <code>DocumentStoreError</code> – If the FAISS index is unexpectedly unavailable when removing embeddings.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents from the store.
+
+#### search
+
+```python
+search(
+    query_embedding: list[float],
+    top_k: int = 10,
+    filters: dict[str, Any] | None = None,
+) -> list[Document]
+```
+
+Performs a vector search.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – The query embedding.
+- **top_k** (<code>int</code>) – The number of results to return.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters to apply.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of matching Documents.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes documents that match the provided filters from the store.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – A dictionary of filters to apply to find documents to delete.
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>DocumentStoreError</code> – If the FAISS index is unexpectedly unavailable when removing embeddings.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – A dictionary of filters to apply.
+
+**Returns:**
+
+- <code>int</code> – The number of matching documents.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates documents that match the provided filters with the new metadata.
+
+Note: Updates are performed in-memory only. To persist these changes,
+you must explicitly call `save()` after updating.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – A dictionary of filters to apply to find documents to update.
+- **meta** (<code>dict\[str, Any\]</code>) – A dictionary of metadata key-value pairs to update in the matching documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, Any]]
+```
+
+Infers and returns the types of all metadata fields from the stored documents.
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, Any\]\]</code> – A dictionary mapping field names to dictionaries with a "type" key
+  (e.g. `{"field": {"type": "long"}}`).
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(field_name: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for a specific metadata field.
+
+**Parameters:**
+
+- **field_name** (<code>str</code>) – The name of the metadata field.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with keys "min" and "max" containing the respective min and max values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(field_name: str) -> list[Any]
+```
+
+Returns all unique values for a specific metadata field.
+
+**Parameters:**
+
+- **field_name** (<code>str</code>) – The name of the metadata field.
+
+**Returns:**
+
+- <code>list\[Any\]</code> – A list of unique values for the specified field.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns a count of unique values for multiple metadata fields, optionally scoped by a filter.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – A dictionary of filters to apply.
+- **metadata_fields** (<code>list\[str\]</code>) – A list of metadata field names to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary mapping each field name to the count of its unique values.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the store to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FAISSDocumentStore
+```
+
+Deserializes the store from a dictionary.
+
+#### save
+
+```python
+save(index_path: str | Path) -> None
+```
+
+Saves the index and documents to disk.
+
+**Raises:**
+
+- <code>DocumentStoreError</code> – If the FAISS index is unexpectedly unavailable.
+
+#### load
+
+```python
+load(index_path: str | Path) -> None
+```
+
+Loads the index and documents from disk.
+
+**Raises:**
+
+- <code>ValueError</code> – If the `.faiss` file does not exist.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/fastembed.md

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

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/firecrawl.md

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

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/github.md

@@ -0,0 +1,687 @@
+---
+title: "GitHub"
+id: integrations-github
+description: "GitHub integration for Haystack"
+slug: "/integrations-github"
+---
+
+<a id="haystack_integrations.components.connectors.github.file_editor"></a>
+
+## Module haystack\_integrations.components.connectors.github.file\_editor
+
+<a id="haystack_integrations.components.connectors.github.file_editor.Command"></a>
+
+### Command
+
+Available commands for file operations in GitHub.
+
+**Attributes**:
+
+- `EDIT` - Edit an existing file by replacing content
+- `UNDO` - Revert the last commit if made by the same user
+- `CREATE` - Create a new file
+- `DELETE` - Delete an existing file
+
+<a id="haystack_integrations.components.connectors.github.file_editor.GitHubFileEditor"></a>
+
+### GitHubFileEditor
+
+A Haystack component for editing files in GitHub repositories.
+
+Supports editing, undoing changes, deleting files, and creating new files
+through the GitHub API.
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import Command, GitHubFileEditor
+from haystack.utils import Secret
+
+# Initialize with default repo and branch
+editor = GitHubFileEditor(
+    github_token=Secret.from_env_var("GITHUB_TOKEN"),
+    repo="owner/repo",
+    branch="main"
+)
+
+# Edit a file using default repo and branch
+result = editor.run(
+    command=Command.EDIT,
+    payload={
+        "path": "path/to/file.py",
+        "original": "def old_function():",
+        "replacement": "def new_function():",
+        "message": "Renamed function for clarity"
+    }
+)
+
+# Edit a file in a different repo/branch
+result = editor.run(
+    command=Command.EDIT,
+    repo="other-owner/other-repo",  # Override default repo
+    branch="feature",  # Override default branch
+    payload={
+        "path": "path/to/file.py",
+        "original": "def old_function():",
+        "replacement": "def new_function():",
+        "message": "Renamed function for clarity"
+    }
+)
+```
+
+<a id="haystack_integrations.components.connectors.github.file_editor.GitHubFileEditor.__init__"></a>
+
+#### GitHubFileEditor.\_\_init\_\_
+
+```python
+def __init__(*,
+             github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+             repo: str | None = None,
+             branch: str = "main",
+             raise_on_failure: bool = True)
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for API authentication
+- `repo`: Default repository in owner/repo format
+- `branch`: Default branch to work with
+- `raise_on_failure`: If True, raises exceptions on API errors
+
+**Raises**:
+
+- `TypeError`: If github_token is not a Secret
+
+<a id="haystack_integrations.components.connectors.github.file_editor.GitHubFileEditor.run"></a>
+
+#### GitHubFileEditor.run
+
+```python
+@component.output_types(result=str)
+def run(command: Command | str,
+        payload: dict[str, Any],
+        repo: str | None = None,
+        branch: str | None = None) -> dict[str, str]
+```
+
+Process GitHub file operations.
+
+**Arguments**:
+
+- `command`: Operation to perform ("edit", "undo", "create", "delete")
+- `payload`: Dictionary containing command-specific parameters
+- `repo`: Repository in owner/repo format (overrides default if provided)
+- `branch`: Branch to perform operations on (overrides default if provided)
+
+**Raises**:
+
+- `ValueError`: If command is not a valid Command enum value
+
+**Returns**:
+
+Dictionary containing operation result
+
+<a id="haystack_integrations.components.connectors.github.file_editor.GitHubFileEditor.to_dict"></a>
+
+#### GitHubFileEditor.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+<a id="haystack_integrations.components.connectors.github.file_editor.GitHubFileEditor.from_dict"></a>
+
+#### GitHubFileEditor.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubFileEditor"
+```
+
+Deserialize the component from a dictionary.
+
+<a id="haystack_integrations.components.connectors.github.issue_commenter"></a>
+
+## Module haystack\_integrations.components.connectors.github.issue\_commenter
+
+<a id="haystack_integrations.components.connectors.github.issue_commenter.GitHubIssueCommenter"></a>
+
+### GitHubIssueCommenter
+
+Posts comments to GitHub issues.
+
+The component takes a GitHub issue URL and comment text, then posts the comment
+to the specified issue using the GitHub API.
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import GitHubIssueCommenter
+from haystack.utils import Secret
+
+commenter = GitHubIssueCommenter(github_token=Secret.from_env_var("GITHUB_TOKEN"))
+result = commenter.run(
+    url="https://github.com/owner/repo/issues/123",
+    comment="Thanks for reporting this issue! We'll look into it."
+)
+
+print(result["success"])
+```
+
+<a id="haystack_integrations.components.connectors.github.issue_commenter.GitHubIssueCommenter.__init__"></a>
+
+#### GitHubIssueCommenter.\_\_init\_\_
+
+```python
+def __init__(*,
+             github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+             raise_on_failure: bool = True,
+             retry_attempts: int = 2)
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for API authentication as a Secret
+- `raise_on_failure`: If True, raises exceptions on API errors
+- `retry_attempts`: Number of retry attempts for failed requests
+
+<a id="haystack_integrations.components.connectors.github.issue_commenter.GitHubIssueCommenter.to_dict"></a>
+
+#### GitHubIssueCommenter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.connectors.github.issue_commenter.GitHubIssueCommenter.from_dict"></a>
+
+#### GitHubIssueCommenter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubIssueCommenter"
+```
+
+Deserialize the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.connectors.github.issue_commenter.GitHubIssueCommenter.run"></a>
+
+#### GitHubIssueCommenter.run
+
+```python
+@component.output_types(success=bool)
+def run(url: str, comment: str) -> dict
+```
+
+Post a comment to a GitHub issue.
+
+**Arguments**:
+
+- `url`: GitHub issue URL
+- `comment`: Comment text to post
+
+**Returns**:
+
+Dictionary containing success status
+
+<a id="haystack_integrations.components.connectors.github.issue_viewer"></a>
+
+## Module haystack\_integrations.components.connectors.github.issue\_viewer
+
+<a id="haystack_integrations.components.connectors.github.issue_viewer.GitHubIssueViewer"></a>
+
+### GitHubIssueViewer
+
+Fetches and parses GitHub issues into Haystack documents.
+
+The component takes a GitHub issue URL and returns a list of documents where:
+- First document contains the main issue content
+- Subsequent documents contain the issue comments
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import GitHubIssueViewer
+
+viewer = GitHubIssueViewer()
+docs = viewer.run(
+    url="https://github.com/owner/repo/issues/123"
+)["documents"]
+
+print(docs)
+```
+
+<a id="haystack_integrations.components.connectors.github.issue_viewer.GitHubIssueViewer.__init__"></a>
+
+#### GitHubIssueViewer.\_\_init\_\_
+
+```python
+def __init__(*,
+             github_token: Secret | None = None,
+             raise_on_failure: bool = True,
+             retry_attempts: int = 2)
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for API authentication as a Secret
+- `raise_on_failure`: If True, raises exceptions on API errors
+- `retry_attempts`: Number of retry attempts for failed requests
+
+<a id="haystack_integrations.components.connectors.github.issue_viewer.GitHubIssueViewer.to_dict"></a>
+
+#### GitHubIssueViewer.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.connectors.github.issue_viewer.GitHubIssueViewer.from_dict"></a>
+
+#### GitHubIssueViewer.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubIssueViewer"
+```
+
+Deserialize the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.connectors.github.issue_viewer.GitHubIssueViewer.run"></a>
+
+#### GitHubIssueViewer.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(url: str) -> dict
+```
+
+Process a GitHub issue URL and return documents.
+
+**Arguments**:
+
+- `url`: GitHub issue URL
+
+**Returns**:
+
+Dictionary containing list of documents
+
+<a id="haystack_integrations.components.connectors.github.pr_creator"></a>
+
+## Module haystack\_integrations.components.connectors.github.pr\_creator
+
+<a id="haystack_integrations.components.connectors.github.pr_creator.GitHubPRCreator"></a>
+
+### GitHubPRCreator
+
+A Haystack component for creating pull requests from a fork back to the original repository.
+
+Uses the authenticated user's fork to create the PR and links it to an existing issue.
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import GitHubPRCreator
+from haystack.utils import Secret
+
+pr_creator = GitHubPRCreator(
+    github_token=Secret.from_env_var("GITHUB_TOKEN")  # Token from the fork owner
+)
+
+# Create a PR from your fork
+result = pr_creator.run(
+    issue_url="https://github.com/owner/repo/issues/123",
+    title="Fix issue `123`",
+    body="This PR addresses issue `123`",
+    branch="feature-branch",     # The branch in your fork with the changes
+    base="main"                  # The branch in the original repo to merge into
+)
+```
+
+<a id="haystack_integrations.components.connectors.github.pr_creator.GitHubPRCreator.__init__"></a>
+
+#### GitHubPRCreator.\_\_init\_\_
+
+```python
+def __init__(*,
+             github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+             raise_on_failure: bool = True)
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for authentication (from the fork owner)
+- `raise_on_failure`: If True, raises exceptions on API errors
+
+<a id="haystack_integrations.components.connectors.github.pr_creator.GitHubPRCreator.run"></a>
+
+#### GitHubPRCreator.run
+
+```python
+@component.output_types(result=str)
+def run(issue_url: str,
+        title: str,
+        branch: str,
+        base: str,
+        body: str = "",
+        draft: bool = False) -> dict[str, str]
+```
+
+Create a new pull request from your fork to the original repository, linked to the specified issue.
+
+**Arguments**:
+
+- `issue_url`: URL of the GitHub issue to link the PR to
+- `title`: Title of the pull request
+- `branch`: Name of the branch in your fork where changes are implemented
+- `base`: Name of the branch in the original repo you want to merge into
+- `body`: Additional content for the pull request description
+- `draft`: Whether to create a draft pull request
+
+**Returns**:
+
+Dictionary containing operation result
+
+<a id="haystack_integrations.components.connectors.github.pr_creator.GitHubPRCreator.to_dict"></a>
+
+#### GitHubPRCreator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+<a id="haystack_integrations.components.connectors.github.pr_creator.GitHubPRCreator.from_dict"></a>
+
+#### GitHubPRCreator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubPRCreator"
+```
+
+Deserialize the component from a dictionary.
+
+<a id="haystack_integrations.components.connectors.github.repo_forker"></a>
+
+## Module haystack\_integrations.components.connectors.github.repo\_forker
+
+<a id="haystack_integrations.components.connectors.github.repo_forker.GitHubRepoForker"></a>
+
+### GitHubRepoForker
+
+Forks a GitHub repository from an issue URL.
+
+The component takes a GitHub issue URL, extracts the repository information,
+creates or syncs a fork of that repository, and optionally creates an issue-specific branch.
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import GitHubRepoForker
+from haystack.utils import Secret
+
+# Using direct token with auto-sync and branch creation
+forker = GitHubRepoForker(
+    github_token=Secret.from_env_var("GITHUB_TOKEN"),
+    auto_sync=True,
+    create_branch=True
+)
+
+result = forker.run(url="https://github.com/owner/repo/issues/123")
+print(result)
+# Will create or sync fork and create branch "fix-123"
+```
+
+<a id="haystack_integrations.components.connectors.github.repo_forker.GitHubRepoForker.__init__"></a>
+
+#### GitHubRepoForker.\_\_init\_\_
+
+```python
+def __init__(*,
+             github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"),
+             raise_on_failure: bool = True,
+             wait_for_completion: bool = False,
+             max_wait_seconds: int = 300,
+             poll_interval: int = 2,
+             auto_sync: bool = True,
+             create_branch: bool = True)
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for API authentication
+- `raise_on_failure`: If True, raises exceptions on API errors
+- `wait_for_completion`: If True, waits until fork is fully created
+- `max_wait_seconds`: Maximum time to wait for fork completion in seconds
+- `poll_interval`: Time between status checks in seconds
+- `auto_sync`: If True, syncs fork with original repository if it already exists
+- `create_branch`: If True, creates a fix branch based on the issue number
+
+<a id="haystack_integrations.components.connectors.github.repo_forker.GitHubRepoForker.to_dict"></a>
+
+#### GitHubRepoForker.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.connectors.github.repo_forker.GitHubRepoForker.from_dict"></a>
+
+#### GitHubRepoForker.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubRepoForker"
+```
+
+Deserialize the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.connectors.github.repo_forker.GitHubRepoForker.run"></a>
+
+#### GitHubRepoForker.run
+
+```python
+@component.output_types(repo=str, issue_branch=str)
+def run(url: str) -> dict
+```
+
+Process a GitHub issue URL and create or sync a fork of the repository.
+
+**Arguments**:
+
+- `url`: GitHub issue URL
+
+**Returns**:
+
+Dictionary containing repository path in owner/repo format
+
+<a id="haystack_integrations.components.connectors.github.repo_viewer"></a>
+
+## Module haystack\_integrations.components.connectors.github.repo\_viewer
+
+<a id="haystack_integrations.components.connectors.github.repo_viewer.GitHubItem"></a>
+
+### GitHubItem
+
+Represents an item (file or directory) in a GitHub repository
+
+<a id="haystack_integrations.components.connectors.github.repo_viewer.GitHubItem.type"></a>
+
+#### type
+
+"file" or "dir"
+
+<a id="haystack_integrations.components.connectors.github.repo_viewer.GitHubRepoViewer"></a>
+
+### GitHubRepoViewer
+
+Navigates and fetches content from GitHub repositories.
+
+For directories:
+- Returns a list of Documents, one for each item
+- Each Document's content is the item name
+- Full path and metadata in Document.meta
+
+For files:
+- Returns a single Document
+- Document's content is the file content
+- Full path and metadata in Document.meta
+
+For errors:
+- Returns a single Document
+- Document's content is the error message
+- Document's meta contains type="error"
+
+### Usage example
+```python
+from haystack_integrations.components.connectors.github import GitHubRepoViewer
+
+viewer = GitHubRepoViewer()
+
+# List directory contents - returns multiple documents
+result = viewer.run(
+    repo="owner/repository",
+    path="docs/",
+    branch="main"
+)
+print(result)
+
+# Get specific file - returns single document
+result = viewer.run(
+    repo="owner/repository",
+    path="README.md",
+    branch="main"
+)
+print(result)
+```
+
+<a id="haystack_integrations.components.connectors.github.repo_viewer.GitHubRepoViewer.__init__"></a>
+
+#### GitHubRepoViewer.\_\_init\_\_
+
+```python
+def __init__(*,
+             github_token: Secret | None = None,
+             raise_on_failure: bool = True,
+             max_file_size: int = 1_000_000,
+             repo: str | None = None,
+             branch: str = "main")
+```
+
+Initialize the component.
+
+**Arguments**:
+
+- `github_token`: GitHub personal access token for API authentication
+- `raise_on_failure`: If True, raises exceptions on API errors
+- `max_file_size`: Maximum file size in bytes to fetch (default: 1MB)
+- `repo`: Repository in format "owner/repo"
+- `branch`: Git reference (branch, tag, commit) to use
+
+<a id="haystack_integrations.components.connectors.github.repo_viewer.GitHubRepoViewer.to_dict"></a>
+
+#### GitHubRepoViewer.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.connectors.github.repo_viewer.GitHubRepoViewer.from_dict"></a>
+
+#### GitHubRepoViewer.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "GitHubRepoViewer"
+```
+
+Deserialize the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.connectors.github.repo_viewer.GitHubRepoViewer.run"></a>
+
+#### GitHubRepoViewer.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(path: str,
+        repo: str | None = None,
+        branch: str | None = None) -> dict[str, list[Document]]
+```
+
+Process a GitHub repository path and return documents.
+
+**Arguments**:
+
+- `repo`: Repository in format "owner/repo"
+- `path`: Path within repository (default: root)
+- `branch`: Git reference (branch, tag, commit) to use
+
+**Returns**:
+
+Dictionary containing list of documents
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/google_ai.md

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

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/google_genai.md

@@ -0,0 +1,822 @@
+---
+title: "Google GenAI"
+id: integrations-google-genai
+description: "Google GenAI integration for Haystack"
+slug: "/integrations-google-genai"
+---
+
+
+## haystack_integrations.components.embedders.google_genai.document_embedder
+
+### GoogleGenAIDocumentEmbedder
+
+Computes document embeddings using Google AI models.
+
+### Authentication examples
+
+**1. Gemini Developer API (API Key Authentication)**
+
+````python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+document_embedder = GoogleGenAIDocumentEmbedder(model="gemini-embedding-001")
+
+**2. Vertex AI (Application Default Credentials)**
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
+
+# Using Application Default Credentials (requires gcloud auth setup)
+document_embedder = GoogleGenAIDocumentEmbedder(
+    api="vertex",
+    vertex_ai_project="my-project",
+    vertex_ai_location="us-central1",
+    model="gemini-embedding-001"
+)
+````
+
+**3. Vertex AI (API Key Authentication)**
+
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+document_embedder = GoogleGenAIDocumentEmbedder(
+    api="vertex",
+    model="gemini-embedding-001"
+)
+```
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = GoogleGenAIDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var(
+        ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
+    ),
+    api: Literal["gemini", "vertex"] = "gemini",
+    vertex_ai_project: str | None = None,
+    vertex_ai_location: str | None = None,
+    model: str = "gemini-embedding-001",
+    prefix: str = "",
+    suffix: str = "",
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    config: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an GoogleGenAIDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
+  Not needed if using Vertex AI with Application Default Credentials.
+  Go to https://aistudio.google.com/app/apikey for a Gemini API key.
+  Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
+- **api** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+  Application Default Credentials.
+- **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+  Required when using Vertex AI with Application Default Credentials.
+- **model** (<code>str</code>) – The name of the model to use for calculating embeddings.
+  The default model is `gemini-embedding-001`.
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **batch_size** (<code>int</code>) – Number of documents to embed at once.
+- **progress_bar** (<code>bool</code>) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the metadata fields to the document text.
+- **config** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure embedding content configuration `types.EmbedContentConfig`.
+  If not specified, it defaults to `{"task_type": "SEMANTIC_SIMILARITY"}`.
+  For more information, see the [Google AI Task types](https://ai.google.dev/gemini-api/docs/embeddings#task-types).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAIDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GoogleGenAIDocumentEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]] | dict[str, Any]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(
+    documents: list[Document],
+) -> dict[str, list[Document]] | dict[str, Any]
+```
+
+Embeds a list of documents asynchronously.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.embedders.google_genai.multimodal_document_embedder
+
+### GoogleGenAIMultimodalDocumentEmbedder
+
+Computes non-textual document embeddings using Google AI models.
+
+It supports images, PDFs, video and audio files. They are mapped to vectors in a single vector space.
+
+To embed textual documents, use the GoogleGenAIDocumentEmbedder.
+To embed a string, like a user query, use the GoogleGenAITextEmbedder.
+
+### Authentication examples
+
+**1. Gemini Developer API (API Key Authentication)**
+
+````python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+document_embedder = GoogleGenAIMultimodalDocumentEmbedder(model="gemini-embedding-2-preview")
+
+**2. Vertex AI (Application Default Credentials)**
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
+
+# Using Application Default Credentials (requires gcloud auth setup)
+document_embedder = GoogleGenAIMultimodalDocumentEmbedder(
+    api="vertex",
+    vertex_ai_project="my-project",
+    vertex_ai_location="us-central1",
+    model="gemini-embedding-2-preview"
+)
+````
+
+**3. Vertex AI (API Key Authentication)**
+
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+document_embedder = GoogleGenAIMultimodalDocumentEmbedder(
+    api="vertex",
+    model="gemini-embedding-2-preview"
+)
+```
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder
+
+doc = Document(content=None, meta={"file_path": "path/to/image.jpg"})
+
+document_embedder = GoogleGenAIMultimodalDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var(
+        ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
+    ),
+    api: Literal["gemini", "vertex"] = "gemini",
+    vertex_ai_project: str | None = None,
+    vertex_ai_location: str | None = None,
+    file_path_meta_field: str = "file_path",
+    root_path: str | None = None,
+    image_size: tuple[int, int] | None = None,
+    model: str = "gemini-embedding-2-preview",
+    batch_size: int = 6,
+    progress_bar: bool = True,
+    config: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an GoogleGenAIMultimodalDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
+  Not needed if using Vertex AI with Application Default Credentials.
+  Go to https://aistudio.google.com/app/apikey for a Gemini API key.
+  Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
+- **api** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+  Application Default Credentials.
+- **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+  Required when using Vertex AI with Application Default Credentials.
+- **file_path_meta_field** (<code>str</code>) – The metadata field in the Document that contains the file path to the file to embed.
+- **root_path** (<code>str | None</code>) – The root directory path where document files are located. If provided, file paths in
+  document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **image_size** (<code>tuple\[int, int\] | None</code>) – Only used for images and PDF pages. If provided, resizes the image to fit within the specified dimensions
+  (width, height) while maintaining aspect ratio. This reduces file size, memory usage, and processing time,
+  which is beneficial when working with models that have resolution constraints or when transmitting images
+  to remote services.
+- **model** (<code>str</code>) – The name of the model to use for calculating embeddings.
+- **batch_size** (<code>int</code>) – Number of documents to embed at once. Maximum batch size varies depending on the input type.
+  See [Google AI documentation](https://ai.google.dev/gemini-api/docs/embeddings#supported-modalities) for
+  more information.
+- **progress_bar** (<code>bool</code>) – If `True`, shows a progress bar when running.
+- **config** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure embedding content configuration `types.EmbedContentConfig`.
+  You can for example set the output dimensionality of the embedding: `{"output_dimensionality": 768}`.
+  It also allows customizing the task type. If the task type is not specified, it defaults to
+  `{"task_type": "RETRIEVAL_DOCUMENT"}`.
+  For more information, see the [Google AI documentation](https://ai.google.dev/gemini-api/docs/embeddings#task-types).
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]] | dict[str, Any]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(
+    documents: list[Document],
+) -> dict[str, list[Document]] | dict[str, Any]
+```
+
+Embeds a list of documents asynchronously.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.embedders.google_genai.text_embedder
+
+### GoogleGenAITextEmbedder
+
+Embeds strings using Google AI models.
+
+You can use it to embed user query and send it to an embedding Retriever.
+
+### Authentication examples
+
+**1. Gemini Developer API (API Key Authentication)**
+
+````python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+text_embedder = GoogleGenAITextEmbedder(model="gemini-embedding-001")
+
+**2. Vertex AI (Application Default Credentials)**
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+# Using Application Default Credentials (requires gcloud auth setup)
+text_embedder = GoogleGenAITextEmbedder(
+    api="vertex",
+    vertex_ai_project="my-project",
+    vertex_ai_location="us-central1",
+    model="gemini-embedding-001"
+)
+````
+
+**3. Vertex AI (API Key Authentication)**
+
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+text_embedder = GoogleGenAITextEmbedder(
+    api="vertex",
+    model="gemini-embedding-001"
+)
+```
+
+### Usage example
+
+```python
+from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = GoogleGenAITextEmbedder()
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+# 'meta': {'model': 'gemini-embedding-001-v2',
+#          'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var(
+        ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
+    ),
+    api: Literal["gemini", "vertex"] = "gemini",
+    vertex_ai_project: str | None = None,
+    vertex_ai_location: str | None = None,
+    model: str = "gemini-embedding-001",
+    prefix: str = "",
+    suffix: str = "",
+    config: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an GoogleGenAITextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
+  Not needed if using Vertex AI with Application Default Credentials.
+  Go to https://aistudio.google.com/app/apikey for a Gemini API key.
+  Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
+- **api** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+  Application Default Credentials.
+- **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+  Required when using Vertex AI with Application Default Credentials.
+- **model** (<code>str</code>) – The name of the model to use for calculating embeddings.
+  The default model is `gemini-embedding-001`.
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text to embed.
+- **suffix** (<code>str</code>) – A string to add at the end of each text to embed.
+- **config** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure embedding content configuration `types.EmbedContentConfig`.
+  If not specified, it defaults to `{"task_type": "SEMANTIC_SIMILARITY"}`.
+  For more information, see the [Google AI Task types](https://ai.google.dev/gemini-api/docs/embeddings#task-types).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAITextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GoogleGenAITextEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float]] | dict[str, Any]
+```
+
+Embeds a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, list[float]] | dict[str, Any]
+```
+
+Asynchronously embed a single string.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\]\] | dict\[str, Any\]</code> – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.generators.google_genai.chat.chat_generator
+
+### GoogleGenAIChatGenerator
+
+A component for generating chat completions using Google's Gemini models via the Google Gen AI SDK.
+
+Supports models like gemini-2.5-flash and other Gemini variants. For Gemini 2.5 series models,
+enables thinking features via `generation_kwargs={"thinking_budget": value}`.
+
+### Thinking Support (Gemini 2.5 Series)
+
+- **Reasoning transparency**: Models can show their reasoning process
+- **Thought signatures**: Maintains thought context across multi-turn conversations with tools
+- **Configurable thinking budgets**: Control token allocation for reasoning
+
+Configure thinking behavior:
+
+- `thinking_budget: -1`: Dynamic allocation (default)
+- `thinking_budget: 0`: Disable thinking (Flash/Flash-Lite only)
+- `thinking_budget: N`: Set explicit token budget
+
+### Multi-Turn Thinking with Thought Signatures
+
+Gemini uses **thought signatures** when tools are present - encrypted "save states" that maintain
+context across turns. Include previous assistant responses in chat history for context preservation.
+
+### Authentication
+
+**Gemini Developer API**: Set `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable
+**Vertex AI**: Use `api="vertex"` with Application Default Credentials or API key
+
+### Authentication Examples
+
+**1. Gemini Developer API (API Key Authentication)**
+
+```python
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+chat_generator = GoogleGenAIChatGenerator(model="gemini-2.5-flash")
+```
+
+**2. Vertex AI (Application Default Credentials)**
+
+```python
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# Using Application Default Credentials (requires gcloud auth setup)
+chat_generator = GoogleGenAIChatGenerator(
+    api="vertex",
+    vertex_ai_project="my-project",
+    vertex_ai_location="us-central1",
+    model="gemini-2.5-flash",
+)
+```
+
+**3. Vertex AI (API Key Authentication)**
+
+```python
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
+chat_generator = GoogleGenAIChatGenerator(
+    api="vertex",
+    model="gemini-2.5-flash",
+)
+```
+
+### Usage example
+
+```python
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack.tools import Tool, Toolset
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+# Initialize the chat generator with thinking support
+chat_generator = GoogleGenAIChatGenerator(
+    model="gemini-2.5-flash",
+    generation_kwargs={"thinking_budget": 1024}  # Enable thinking with 1024 token budget
+)
+
+# Generate a response
+messages = [ChatMessage.from_user("Tell me about the future of AI")]
+response = chat_generator.run(messages=messages)
+print(response["replies"][0].text)
+
+# Access reasoning content if available
+message = response["replies"][0]
+if message.reasonings:
+    for reasoning in message.reasonings:
+        print("Reasoning:", reasoning.reasoning_text)
+
+# Tool usage example with thinking
+def weather_function(city: str):
+    return f"The weather in {city} is sunny and 25°C"
+
+weather_tool = Tool(
+    name="weather",
+    description="Get weather information for a city",
+    parameters={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
+    function=weather_function
+)
+
+# Can use either List[Tool] or Toolset
+chat_generator_with_tools = GoogleGenAIChatGenerator(
+    model="gemini-2.5-flash",
+    tools=[weather_tool],  # or tools=Toolset([weather_tool])
+    generation_kwargs={"thinking_budget": -1}  # Dynamic thinking allocation
+)
+
+messages = [ChatMessage.from_user("What's the weather in Paris?")]
+response = chat_generator_with_tools.run(messages=messages)
+```
+
+### Usage example with structured output
+
+```python
+from pydantic import BaseModel
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+class City(BaseModel):
+    name: str
+    country: str
+    population: int
+
+chat_generator = GoogleGenAIChatGenerator(
+    model="gemini-2.5-flash",
+    generation_kwargs={"response_format": City}
+)
+
+messages = [ChatMessage.from_user("Tell me about Paris")]
+response = chat_generator.run(messages=messages)
+print(response["replies"][0].text)  # JSON output matching the City schema
+```
+
+### Usage example with FileContent embedded in a ChatMessage
+
+```python
+from haystack.dataclasses import ChatMessage, FileContent
+from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator
+
+file_content = FileContent.from_url("https://arxiv.org/pdf/2309.08632")
+chat_message = ChatMessage.from_user(content_parts=[file_content, "Summarize this paper in 100 words."])
+chat_generator = GoogleGenAIChatGenerator()
+response = chat_generator.run(messages=[chat_message])
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "gemini-3.1-pro-preview",
+    "gemini-3-flash-preview",
+    "gemini-3.1-flash-lite-preview",
+    "gemini-2.5-pro",
+    "gemini-2.5-flash",
+    "gemini-2.5-flash-lite",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+
+See https://ai.google.dev/gemini-api/docs/models for the full list of models and up-to-date model IDs.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var(
+        ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False
+    ),
+    api: Literal["gemini", "vertex"] = "gemini",
+    vertex_ai_project: str | None = None,
+    vertex_ai_location: str | None = None,
+    model: str = "gemini-2.5-flash",
+    generation_kwargs: dict[str, Any] | None = None,
+    safety_settings: list[dict[str, Any]] | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    tools: ToolsType | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None
+) -> None
+```
+
+Initialize a GoogleGenAIChatGenerator instance.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables.
+  Not needed if using Vertex AI with Application Default Credentials.
+  Go to https://aistudio.google.com/app/apikey for a Gemini API key.
+  Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key.
+- **api** (<code>Literal['gemini', 'vertex']</code>) – Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI.
+- **vertex_ai_project** (<code>str | None</code>) – Google Cloud project ID for Vertex AI. Required when using Vertex AI with
+  Application Default Credentials.
+- **vertex_ai_location** (<code>str | None</code>) – Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1").
+  Required when using Vertex AI with Application Default Credentials.
+- **model** (<code>str</code>) – Name of the model to use (e.g., "gemini-2.5-flash")
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Configuration for generation (temperature, max_tokens, etc.).
+  For Gemini 2.5 series, supports `thinking_budget` to configure thinking behavior:
+- `thinking_budget`: int, controls thinking token allocation
+  - `-1`: Dynamic (default for most models)
+  - `0`: Disable thinking (Flash/Flash-Lite only)
+  - Positive integer: Set explicit budget
+    For Gemini 3 series and newer, supports `thinking_level` to configure thinking depth:
+- `thinking_level`: str, controls thinking (https://ai.google.dev/gemini-api/docs/thinking#levels-budgets)
+  - `minimal`: Matches the "no thinking" setting for most queries. The model may think very minimally for
+    complex coding tasks. Minimizes latency for chat or high throughput applications.
+  - `low`: Minimizes latency and cost. Best for simple instruction following, chat, or high-throughput
+    applications.
+  - `medium`: Balanced thinking for most tasks.
+  - `high`: (Default, dynamic): Maximizes reasoning depth. The model may take significantly longer to reach
+    a first token, but the output will be more carefully reasoned.
+- **safety_settings** (<code>list\[dict\[str, Any\]\] | None</code>) – Safety settings for content filtering
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  Each tool should have a unique name.
+- **timeout** (<code>float | None</code>) – Timeout for Google GenAI client calls. If not set, it defaults to the default set by the Google GenAI
+  client.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by
+  the Google GenAI client.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleGenAIChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>GoogleGenAIChatGenerator</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage],
+    generation_kwargs: dict[str, Any] | None = None,
+    safety_settings: list[dict[str, Any]] | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    tools: ToolsType | None = None,
+) -> dict[str, Any]
+```
+
+Run the Google Gen AI chat generator on the given input data.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Configuration for generation. If provided, it will override
+  the default config. Supports `thinking_budget` for Gemini 2.5 series thinking configuration.
+- **safety_settings** (<code>list\[dict\[str, Any\]\] | None</code>) – Safety settings for content filtering. If provided, it will override the
+  default settings.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is
+  received from the stream.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If provided, it will override the tools set during initialization.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `replies`: A list containing the generated ChatMessage responses.
+
+**Raises:**
+
+- <code>RuntimeError</code> – If there is an error in the Google Gen AI chat generation.
+- <code>ValueError</code> – If a ChatMessage does not contain at least one of TextContent, ToolCall, or
+  ToolCallResult or if the role in ChatMessage is different from User, System, Assistant.
+
+#### run_async
+
+```python
+run_async(
+    messages: list[ChatMessage],
+    generation_kwargs: dict[str, Any] | None = None,
+    safety_settings: list[dict[str, Any]] | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    tools: ToolsType | None = None,
+) -> dict[str, Any]
+```
+
+Async version of the run method. Run the Google Gen AI chat generator on the given input data.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Configuration for generation. If provided, it will override
+  the default config. Supports `thinking_budget` for Gemini 2.5 series thinking configuration.
+  See https://ai.google.dev/gemini-api/docs/thinking for possible values.
+- **safety_settings** (<code>list\[dict\[str, Any\]\] | None</code>) – Safety settings for content filtering. If provided, it will override the
+  default settings.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is
+  received from the stream.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If provided, it will override the tools set during initialization.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `replies`: A list containing the generated ChatMessage responses.
+
+**Raises:**
+
+- <code>RuntimeError</code> – If there is an error in the async Google Gen AI chat generation.
+- <code>ValueError</code> – If a ChatMessage does not contain at least one of TextContent, ToolCall, or
+  ToolCallResult or if the role in ChatMessage is different from User, System, Assistant.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/hanlp.md

@@ -0,0 +1,157 @@
+---
+title: "HanLP"
+id: integrations-hanlp
+description: "HanLP integration for Haystack"
+slug: "/integrations-hanlp"
+---
+
+<a id="haystack_integrations.components.preprocessors.hanlp.chinese_document_splitter"></a>
+
+## Module haystack\_integrations.components.preprocessors.hanlp.chinese\_document\_splitter
+
+<a id="haystack_integrations.components.preprocessors.hanlp.chinese_document_splitter.ChineseDocumentSplitter"></a>
+
+### ChineseDocumentSplitter
+
+A DocumentSplitter for Chinese text.
+
+'coarse' represents coarse granularity Chinese word segmentation, 'fine' represents fine granularity word
+segmentation, default is coarse granularity word segmentation.
+
+Unlike English where words are usually separated by spaces,
+Chinese text is written continuously without spaces between words.
+Chinese words can consist of multiple characters.
+For example, the English word "America" is translated to "美国" in Chinese,
+which consists of two characters but is treated as a single word.
+Similarly, "Portugal" is "葡萄牙" in Chinese, three characters but one word.
+Therefore, splitting by word means splitting by these multi-character tokens,
+not simply by single characters or spaces.
+
+### Usage example
+```python
+doc = Document(content=
+    "这是第一句话，这是第二句话，这是第三句话。"
+    "这是第四句话，这是第五句话，这是第六句话！"
+    "这是第七句话，这是第八句话，这是第九句话？"
+)
+
+splitter = ChineseDocumentSplitter(
+    split_by="word", split_length=10, split_overlap=3, respect_sentence_boundary=True
+)
+result = splitter.run(documents=[doc])
+print(result["documents"])
+```
+
+<a id="haystack_integrations.components.preprocessors.hanlp.chinese_document_splitter.ChineseDocumentSplitter.__init__"></a>
+
+#### ChineseDocumentSplitter.\_\_init\_\_
+
+```python
+def __init__(split_by: Literal["word", "sentence", "passage", "page", "line",
+                               "period", "function"] = "word",
+             split_length: int = 1000,
+             split_overlap: int = 200,
+             split_threshold: int = 0,
+             respect_sentence_boundary: bool = False,
+             splitting_function: Callable | None = None,
+             granularity: Literal["coarse", "fine"] = "coarse") -> None
+```
+
+Initialize the ChineseDocumentSplitter component.
+
+**Arguments**:
+
+- `split_by`: The unit for splitting your documents. Choose from:
+- `word` for splitting by spaces (" ")
+- `period` for splitting by periods (".")
+- `page` for splitting by form feed ("\f")
+- `passage` for splitting by double line breaks ("\n\n")
+- `line` for splitting each line ("\n")
+- `sentence` for splitting by HanLP sentence tokenizer
+- `split_length`: The maximum number of units in each split.
+- `split_overlap`: The number of overlapping units for each split.
+- `split_threshold`: The minimum number of units per split. If a split has fewer units
+than the threshold, it's attached to the previous split.
+- `respect_sentence_boundary`: Choose whether to respect sentence boundaries when splitting by "word".
+If True, uses HanLP to detect sentence boundaries, ensuring splits occur only between sentences.
+- `splitting_function`: Necessary when `split_by` is set to "function".
+This is a function which must accept a single `str` as input and return a `list` of `str` as output,
+representing the chunks after splitting.
+- `granularity`: The granularity of Chinese word segmentation, either 'coarse' or 'fine'.
+
+**Raises**:
+
+- `ValueError`: If the granularity is not 'coarse' or 'fine'.
+
+<a id="haystack_integrations.components.preprocessors.hanlp.chinese_document_splitter.ChineseDocumentSplitter.run"></a>
+
+#### ChineseDocumentSplitter.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Split documents into smaller chunks.
+
+**Arguments**:
+
+- `documents`: The documents to split.
+
+**Raises**:
+
+- `RuntimeError`: If the Chinese word segmentation model is not loaded.
+
+**Returns**:
+
+A dictionary containing the split documents.
+
+<a id="haystack_integrations.components.preprocessors.hanlp.chinese_document_splitter.ChineseDocumentSplitter.warm_up"></a>
+
+#### ChineseDocumentSplitter.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Warm up the component by loading the necessary models.
+
+<a id="haystack_integrations.components.preprocessors.hanlp.chinese_document_splitter.ChineseDocumentSplitter.chinese_sentence_split"></a>
+
+#### ChineseDocumentSplitter.chinese\_sentence\_split
+
+```python
+def chinese_sentence_split(text: str) -> list[dict[str, Any]]
+```
+
+Split Chinese text into sentences.
+
+**Arguments**:
+
+- `text`: The text to split.
+
+**Returns**:
+
+A list of split sentences.
+
+<a id="haystack_integrations.components.preprocessors.hanlp.chinese_document_splitter.ChineseDocumentSplitter.to_dict"></a>
+
+#### ChineseDocumentSplitter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+<a id="haystack_integrations.components.preprocessors.hanlp.chinese_document_splitter.ChineseDocumentSplitter.from_dict"></a>
+
+#### ChineseDocumentSplitter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "ChineseDocumentSplitter"
+```
+
+Deserializes the component from a dictionary.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/jina.md

@@ -0,0 +1,685 @@
+---
+title: "Jina"
+id: integrations-jina
+description: "Jina integration for Haystack"
+slug: "/integrations-jina"
+---
+
+
+## haystack_integrations.components.connectors.jina.reader
+
+### JinaReaderConnector
+
+A component that interacts with Jina AI's reader service to process queries and return documents.
+
+This component supports different modes of operation: `read`, `search`, and `ground`.
+
+Usage example:
+
+```python
+from haystack_integrations.components.connectors.jina import JinaReaderConnector
+
+reader = JinaReaderConnector(mode="read")
+query = "https://example.com"
+result = reader.run(query=query)
+document = result["documents"][0]
+print(document.content)
+
+>>> "This domain is for use in illustrative examples..."
+```
+
+#### __init__
+
+```python
+__init__(
+    mode: JinaReaderMode | str,
+    api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+    json_response: bool = True,
+) -> None
+```
+
+Initialize a JinaReader instance.
+
+**Parameters:**
+
+- **mode** (<code>JinaReaderMode | str</code>) – The operation mode for the reader (`read`, `search` or `ground`).
+- `read`: process a URL and return the textual content of the page.
+- `search`: search the web and return textual content of the most relevant pages.
+- `ground`: call the grounding engine to perform fact checking.
+  For more information on the modes, see the [Jina Reader documentation](https://jina.ai/reader/).
+- **api_key** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
+  environment variable JINA_API_KEY (recommended).
+- **json_response** (<code>bool</code>) – Controls the response format from the Jina Reader API.
+  If `True`, requests a JSON response, resulting in Documents with rich structured metadata.
+  If `False`, requests a raw response, resulting in one Document with minimal metadata.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaReaderConnector
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>JinaReaderConnector</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query: str, headers: dict[str, str] | None = None
+) -> dict[str, list[Document]]
+```
+
+Process the query/URL using the Jina AI reader service.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The query string or URL to process.
+- **headers** (<code>dict\[str, str\] | None</code>) – Optional headers to include in the request for customization. Refer to the
+  [Jina Reader documentation](https://jina.ai/reader/) for more information.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+  - `documents`: A list of `Document` objects.
+
+#### run_async
+
+```python
+run_async(
+    query: str, headers: dict[str, str] | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously process the query/URL using the Jina AI reader service.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The query string or URL to process.
+- **headers** (<code>dict\[str, str\] | None</code>) – Optional headers to include in the request for customization. Refer to the
+  [Jina Reader documentation](https://jina.ai/reader/) for more information.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+  - `documents`: A list of `Document` objects.
+
+## haystack_integrations.components.embedders.jina.document_embedder
+
+### JinaDocumentEmbedder
+
+A component for computing Document embeddings using Jina AI models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.jina import JinaDocumentEmbedder
+
+# Make sure that the environment variable JINA_API_KEY is set
+
+document_embedder = JinaDocumentEmbedder(task="retrieval.query")
+
+doc = Document(content="I love pizza!")
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+    model: str = "jina-embeddings-v3",
+    prefix: str = "",
+    suffix: str = "",
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    task: str | None = None,
+    dimensions: int | None = None,
+    late_chunking: bool | None = None,
+    *,
+    base_url: str = JINA_API_URL
+) -> None
+```
+
+Create a JinaDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Jina API key.
+- **model** (<code>str</code>) – The name of the Jina model to use.
+  Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **batch_size** (<code>int</code>) – Number of Documents to encode at once.
+- **progress_bar** (<code>bool</code>) – Whether to show a progress bar or not. Can be helpful to disable in production deployments
+  to keep the logs clean.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
+- **task** (<code>str | None</code>) – The downstream task for which the embeddings will be used.
+  The model will return the optimized embeddings for that task.
+  Check the list of available tasks on [Jina documentation](https://jina.ai/embeddings/).
+- **dimensions** (<code>int | None</code>) – Number of desired dimension.
+  Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
+- **late_chunking** (<code>bool | None</code>) – A boolean to enable or disable late chunking.
+  Apply the late chunking technique to leverage the model's long-context capabilities for
+  generating contextual chunk embeddings.
+- **base_url** (<code>str</code>) – The base URL of the Jina API.
+
+The support of `task` and `late_chunking` parameters is only available for jina-embeddings-v3.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>JinaDocumentEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, Any]
+```
+
+Compute the embeddings for a list of Documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with following keys:
+- `documents`: List of Documents, each with an `embedding` field containing the computed embedding.
+- `meta`: A dictionary with metadata including the model name and usage statistics.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a list of Documents.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, Any]
+```
+
+Asynchronously compute the embeddings for a list of Documents.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with following keys:
+- `documents`: List of Documents, each with an `embedding` field containing the computed embedding.
+- `meta`: A dictionary with metadata including the model name and usage statistics.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.jina.document_image_embedder
+
+### JinaDocumentImageEmbedder
+
+A component for computing Document embeddings based on images using Jina AI multimodal models.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+The JinaDocumentImageEmbedder supports models from the jina-clip series and jina-embeddings-v4
+which can encode images into vector representations in the same embedding space as text.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.jina import JinaDocumentImageEmbedder
+
+# Make sure that the environment variable JINA_API_KEY is set
+
+embedder = JinaDocumentImageEmbedder(model="jina-clip-v2")
+
+documents = [
+    Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
+    Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}),
+]
+
+result = embedder.run(documents=documents)
+documents_with_embeddings = result["documents"]
+print(documents_with_embeddings[0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+    model: str = "jina-clip-v2",
+    base_url: str = JINA_API_URL,
+    file_path_meta_field: str = "file_path",
+    root_path: str | None = None,
+    embedding_dimension: int | None = None,
+    image_size: tuple[int, int] | None = None,
+    batch_size: int = 5
+) -> None
+```
+
+Create a JinaDocumentImageEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
+  environment variable `JINA_API_KEY` (recommended).
+- **model** (<code>str</code>) – The name of the Jina multimodal model to use.
+  Supported models include:
+- "jina-clip-v1"
+- "jina-clip-v2" (default)
+- "jina-embeddings-v4"
+  Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
+- **base_url** (<code>str</code>) – The base URL of the Jina API.
+- **file_path_meta_field** (<code>str</code>) – The metadata field in the Document that contains the file path to the image or PDF.
+- **root_path** (<code>str | None</code>) – The root directory path where document files are located. If provided, file paths in
+  document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- **embedding_dimension** (<code>int | None</code>) – Number of desired dimensions for the embedding.
+  Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
+  Only supported by jina-embeddings-v4.
+- **image_size** (<code>tuple\[int, int\] | None</code>) – If provided, resizes the image to fit within the specified dimensions (width, height) while
+  maintaining aspect ratio. This reduces file size, memory usage, and processing time.
+- **batch_size** (<code>int</code>) – Number of images to send in each API request. Defaults to 5.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaDocumentImageEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>JinaDocumentImageEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embed a list of image documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: Documents with embeddings.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Asynchronously embed a list of image documents.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: Documents with embeddings.
+
+## haystack_integrations.components.embedders.jina.text_embedder
+
+### JinaTextEmbedder
+
+A component for embedding strings using Jina AI models.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.jina import JinaTextEmbedder
+
+# Make sure that the environment variable JINA_API_KEY is set
+
+text_embedder = JinaTextEmbedder(task="retrieval.query")
+
+text_to_embed = "I love pizza!"
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+# 'meta': {'model': 'jina-embeddings-v3',
+#          'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+    model: str = "jina-embeddings-v3",
+    prefix: str = "",
+    suffix: str = "",
+    task: str | None = None,
+    dimensions: int | None = None,
+    late_chunking: bool | None = None,
+    *,
+    base_url: str = JINA_API_URL
+) -> None
+```
+
+Create a JinaTextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
+  environment variable `JINA_API_KEY` (recommended).
+- **model** (<code>str</code>) – The name of the Jina model to use.
+  Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **task** (<code>str | None</code>) – The downstream task for which the embeddings will be used.
+  The model will return the optimized embeddings for that task.
+  Check the list of available tasks on [Jina documentation](https://jina.ai/embeddings/).
+- **dimensions** (<code>int | None</code>) – Number of desired dimension.
+  Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
+- **late_chunking** (<code>bool | None</code>) – A boolean to enable or disable late chunking.
+  Apply the late chunking technique to leverage the model's long-context capabilities for
+  generating contextual chunk embeddings.
+- **base_url** (<code>str</code>) – The base URL of the Jina API.
+
+The support of `task` and `late_chunking` parameters is only available for jina-embeddings-v3.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>JinaTextEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embed a string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – The string to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with following keys:
+- `embedding`: The embedding of the input string.
+- `meta`: A dictionary with metadata including the model name and usage statistics.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, Any]
+```
+
+Asynchronously embed a string.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – The string to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with following keys:
+- `embedding`: The embedding of the input string.
+- `meta`: A dictionary with metadata including the model name and usage statistics.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.
+
+## haystack_integrations.components.rankers.jina.ranker
+
+### JinaRanker
+
+Ranks Documents based on their similarity to the query using Jina AI models.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.jina import JinaRanker
+
+ranker = JinaRanker()
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "City in Germany"
+result = ranker.run(query=query, documents=docs)
+docs = result["documents"]
+print(docs[0].content)
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str = "jina-reranker-v1-base-en",
+    api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
+    top_k: int | None = None,
+    score_threshold: float | None = None,
+    *,
+    base_url: str = JINA_API_URL
+) -> None
+```
+
+Creates an instance of JinaRanker.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
+  environment variable JINA_API_KEY (recommended).
+- **model** (<code>str</code>) – The name of the Jina model to use. Check the list of available models on `https://jina.ai/reranker/`
+- **top_k** (<code>int | None</code>) – The maximum number of Documents to return per query. If `None`, all documents are returned
+- **score_threshold** (<code>float | None</code>) – If provided only returns documents with a score above this threshold.
+- **base_url** (<code>str</code>) – The base URL of the Jina API.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> JinaRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>JinaRanker</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query: str,
+    documents: list[Document],
+    top_k: int | None = None,
+    score_threshold: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Returns a list of Documents ranked by their similarity to the given query.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Query string.
+- **documents** (<code>list\[Document\]</code>) – List of Documents.
+- **top_k** (<code>int | None</code>) – The maximum number of Documents you want the Ranker to return.
+- **score_threshold** (<code>float | None</code>) – If provided only returns documents with a score above this threshold.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.
+
+#### run_async
+
+```python
+run_async(
+    query: str,
+    documents: list[Document],
+    top_k: int | None = None,
+    score_threshold: float | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously returns a list of Documents ranked by their similarity to the given query.
+
+This is the asynchronous version of the `run` method. It has the same parameters and return values
+but can be used with `await` in async code.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Query string.
+- **documents** (<code>list\[Document\]</code>) – List of Documents.
+- **top_k** (<code>int | None</code>) – The maximum number of Documents you want the Ranker to return.
+- **score_threshold** (<code>float | None</code>) – If provided only returns documents with a score above this threshold.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given query in descending order of similarity.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/kreuzberg.md

@@ -0,0 +1,152 @@
+---
+title: "Kreuzberg"
+id: integrations-kreuzberg
+description: "Kreuzberg integration for Haystack"
+slug: "/integrations-kreuzberg"
+---
+
+
+## haystack_integrations.components.converters.kreuzberg.converter
+
+### KreuzbergConverter
+
+Converts files to Documents using [Kreuzberg](https://docs.kreuzberg.dev/).
+
+Kreuzberg is a document intelligence framework that extracts text from
+PDFs, Office documents, images, and 75+ other formats. All processing
+is performed locally with no external API calls.
+
+**Usage Example:**
+
+```python
+from haystack_integrations.components.converters.kreuzberg import (
+    KreuzbergConverter,
+)
+
+converter = KreuzbergConverter()
+result = converter.run(sources=["document.pdf", "report.docx"])
+documents = result["documents"]
+```
+
+You can also pass kreuzberg's `ExtractionConfig` to customize extraction:
+
+```python
+from kreuzberg import ExtractionConfig, OcrConfig
+
+converter = KreuzbergConverter(
+    config=ExtractionConfig(
+        output_format="markdown",
+        ocr=OcrConfig(backend="tesseract", language="eng"),
+    ),
+)
+```
+
+**Token reduction** can be configured via
+`ExtractionConfig(token_reduction=TokenReductionConfig(mode="moderate"))`
+to reduce output size for LLM consumption. Five levels are available:
+`"off"`, `"light"`, `"moderate"`, `"aggressive"`, `"maximum"`.
+The reduced text appears directly in `Document.content`.
+
+**Image preprocessing for OCR** can be tuned via
+`OcrConfig(tesseract_config=TesseractConfig(preprocessing=ImagePreprocessingConfig(...)))`
+with options for target DPI, auto-rotate, deskew, denoise,
+contrast enhancement, and binarization method.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    config: ExtractionConfig | None = None,
+    config_path: str | Path | None = None,
+    store_full_path: bool = False,
+    batch: bool = True,
+    easyocr_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Create a `KreuzbergConverter` component.
+
+**Parameters:**
+
+- **config** (<code>ExtractionConfig | None</code>) – An optional `kreuzberg.ExtractionConfig` object to customize
+  extraction behavior. Use this to set output format, OCR backend
+  and language, force-OCR mode, per-page extraction, chunking,
+  keyword extraction, and other kreuzberg options. If not provided,
+  kreuzberg's defaults are used.
+  See the [kreuzberg API reference](https://docs.kreuzberg.dev/reference/api-python/)
+  for the full list of configuration options.
+- **config_path** (<code>str | Path | None</code>) – Path to a kreuzberg configuration file (`.toml`, `.yaml`, or
+  `.json`). Cannot be used together with `config`.
+- **store_full_path** (<code>bool</code>) – If `True`, the full file path is stored in the Document metadata.
+  If `False`, only the file name is stored.
+- **batch** (<code>bool</code>) – If `True`, use kreuzberg's batch extraction APIs, which leverage
+  Rust's rayon thread pool for parallel processing. If `False`,
+  sources are extracted one at a time.
+- **easyocr_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional keyword arguments to pass to EasyOCR when using the
+  `"easyocr"` backend. Supports GPU, beam width, model storage,
+  and other EasyOCR-specific options.
+  See the [EasyOCR documentation](https://www.jaided.ai/easyocr/documentation/)
+  for the full list of supported arguments.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> KreuzbergConverter
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>KreuzbergConverter</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Convert files to Documents using Kreuzberg.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths, directory paths, or ByteStream objects to
+  convert. Directory paths are expanded to their direct file children
+  (non-recursive, sorted alphabetically).
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the Documents.
+  This value can be either a list of dictionaries or a single
+  dictionary. If it's a single dictionary, its content is added to
+  the metadata of all produced Documents. If it's a list, the length
+  of the list must match the number of sources, because the two
+  lists will be zipped. If `sources` contains ByteStream objects,
+  their `meta` will be added to the output Documents.
+
+**Note:** When directories are present in `sources`, `meta` must
+be a single dictionary (not a list), since the number of files in
+a directory is not known in advance.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following key:
+
+- `documents`: A list of created Documents.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/langfuse.md

@@ -0,0 +1,495 @@
+---
+title: "langfuse"
+id: integrations-langfuse
+description: "Langfuse integration for Haystack"
+slug: "/integrations-langfuse"
+---
+
+
+## haystack_integrations.components.connectors.langfuse.langfuse_connector
+
+### LangfuseConnector
+
+LangfuseConnector connects Haystack LLM framework with [Langfuse](https://langfuse.com) in order to enable the
+
+tracing of operations and data flow within various components of a pipeline.
+
+To use LangfuseConnector, add it to your pipeline without connecting it to any other components.
+It will automatically trace all pipeline operations when tracing is enabled.
+
+**Environment Configuration:**
+
+- `LANGFUSE_SECRET_KEY` and `LANGFUSE_PUBLIC_KEY`: Required Langfuse API credentials.
+- `HAYSTACK_CONTENT_TRACING_ENABLED`: Must be set to `"true"` to enable tracing.
+- `HAYSTACK_LANGFUSE_ENFORCE_FLUSH`: (Optional) If set to `"false"`, disables flushing after each component.
+  Be cautious: this may cause data loss on crashes unless you manually flush before shutdown.
+  By default, the data is flushed after each component and blocks the thread until the data is sent to Langfuse.
+
+If you disable flushing after each component make sure you will call langfuse.flush() explicitly before the
+program exits. For example:
+
+```python
+from haystack.tracing import tracer
+
+try:
+    # your code here
+finally:
+    tracer.actual_tracer.flush()
+```
+
+or in FastAPI by defining a shutdown event handler:
+
+```python
+from haystack.tracing import tracer
+
+# ...
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    tracer.actual_tracer.flush()
+```
+
+Here is an example of how to use LangfuseConnector in a pipeline:
+
+```python
+import os
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.connectors.langfuse import (
+    LangfuseConnector,
+)
+
+pipe = Pipeline()
+pipe.add_component("tracer", LangfuseConnector("Chat example"))
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+messages = [
+    ChatMessage.from_system(
+        "Always respond in German even if some input data is in other languages."
+    ),
+    ChatMessage.from_user("Tell me about {{location}}"),
+]
+
+response = pipe.run(
+    data={
+        "prompt_builder": {
+            "template_variables": {"location": "Berlin"},
+            "template": messages,
+        }
+    }
+)
+print(response["llm"]["replies"][0])
+print(response["tracer"]["trace_url"])
+print(response["tracer"]["trace_id"])
+```
+
+For advanced use cases, you can also customize how spans are created and processed by providing a custom
+SpanHandler. This allows you to add custom metrics, set warning levels, or attach additional metadata to your
+Langfuse traces:
+
+```python
+from haystack_integrations.tracing.langfuse import DefaultSpanHandler, LangfuseSpan
+from typing import Optional
+
+class CustomSpanHandler(DefaultSpanHandler):
+
+    def handle(self, span: LangfuseSpan, component_type: Optional[str]) -> None:
+        # Custom span handling logic, customize Langfuse spans however it fits you
+        # see DefaultSpanHandler for how we create and process spans by default
+        pass
+
+connector = LangfuseConnector(span_handler=CustomSpanHandler())
+```
+
+#### __init__
+
+```python
+__init__(
+    name: str,
+    public: bool = False,
+    public_key: Secret | None = Secret.from_env_var("LANGFUSE_PUBLIC_KEY"),
+    secret_key: Secret | None = Secret.from_env_var("LANGFUSE_SECRET_KEY"),
+    httpx_client: httpx.Client | None = None,
+    span_handler: SpanHandler | None = None,
+    *,
+    host: str | None = None,
+    langfuse_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Initialize the LangfuseConnector component.
+
+**Parameters:**
+
+- **name** (<code>str</code>) – The name for the trace. This name will be used to identify the tracing run in the Langfuse
+  dashboard.
+- **public** (<code>bool</code>) – Whether the tracing data should be public or private. If set to `True`, the tracing data will be
+  publicly accessible to anyone with the tracing URL. If set to `False`, the tracing data will be private and
+  only accessible to the Langfuse account owner. The default is `False`.
+- **public_key** (<code>Secret | None</code>) – The Langfuse public key. Defaults to reading from LANGFUSE_PUBLIC_KEY environment variable.
+- **secret_key** (<code>Secret | None</code>) – The Langfuse secret key. Defaults to reading from LANGFUSE_SECRET_KEY environment variable.
+- **httpx_client** (<code>Client | None</code>) – Optional custom httpx.Client instance to use for Langfuse API calls. Note that when
+  deserializing a pipeline from YAML, any custom client is discarded and Langfuse will create its own default
+  client, since HTTPX clients cannot be serialized.
+- **span_handler** (<code>SpanHandler | None</code>) – Optional custom handler for processing spans. If None, uses DefaultSpanHandler.
+  The span handler controls how spans are created and processed, allowing customization of span types
+  based on component types and additional processing after spans are yielded. See SpanHandler class for
+  details on implementing custom handlers.
+  host: Host of Langfuse API. Can also be set via `LANGFUSE_HOST` environment variable.
+  By default it is set to `https://cloud.langfuse.com`.
+- **langfuse_client_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional custom configuration for the Langfuse client. This is a dictionary
+  containing any additional configuration options for the Langfuse client. See the Langfuse documentation
+  for more details on available configuration options.
+
+#### run
+
+```python
+run(invocation_context: dict[str, Any] | None = None) -> dict[str, str]
+```
+
+Runs the LangfuseConnector component.
+
+**Parameters:**
+
+- **invocation_context** (<code>dict\[str, Any\] | None</code>) – A dictionary with additional context for the invocation. This parameter
+  is useful when users want to mark this particular invocation with additional information, e.g.
+  a run id from their own execution framework, user id, etc. These key-value pairs are then visible
+  in the Langfuse traces.
+
+**Returns:**
+
+- <code>dict\[str, str\]</code> – A dictionary with the following keys:
+- `name`: The name of the tracing component.
+- `trace_url`: The URL to the tracing data.
+- `trace_id`: The ID of the trace.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LangfuseConnector
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>LangfuseConnector</code> – The deserialized component instance.
+
+## haystack_integrations.tracing.langfuse.tracer
+
+### LangfuseSpan
+
+Bases: <code>Span</code>
+
+Internal class representing a bridge between the Haystack span tracing API and Langfuse.
+
+#### __init__
+
+```python
+__init__(context_manager: AbstractContextManager) -> None
+```
+
+Initialize a LangfuseSpan instance.
+
+**Parameters:**
+
+- **context_manager** (<code>AbstractContextManager</code>) – The context manager from Langfuse created with
+  `langfuse.get_client().start_as_current_observation`.
+
+#### set_tag
+
+```python
+set_tag(key: str, value: Any) -> None
+```
+
+Set a generic tag for this span.
+
+**Parameters:**
+
+- **key** (<code>str</code>) – The tag key.
+- **value** (<code>Any</code>) – The tag value.
+
+#### set_content_tag
+
+```python
+set_content_tag(key: str, value: Any) -> None
+```
+
+Set a content-specific tag for this span.
+
+**Parameters:**
+
+- **key** (<code>str</code>) – The content tag key.
+- **value** (<code>Any</code>) – The content tag value.
+
+#### raw_span
+
+```python
+raw_span() -> LangfuseClientSpan
+```
+
+Return the underlying span instance.
+
+**Returns:**
+
+- <code>LangfuseSpan</code> – The Langfuse span instance.
+
+#### get_data
+
+```python
+get_data() -> dict[str, Any]
+```
+
+Return the data associated with the span.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The data associated with the span.
+
+#### get_correlation_data_for_logs
+
+```python
+get_correlation_data_for_logs() -> dict[str, Any]
+```
+
+Return correlation data for log enrichment.
+
+### SpanContext
+
+Context for creating spans in Langfuse.
+
+Encapsulates the information needed to create and configure a span in Langfuse tracing.
+Used by SpanHandler to determine the span type (trace, generation, or default) and its configuration.
+
+**Parameters:**
+
+- **name** (<code>str</code>) – The name of the span to create. For components, this is typically the component name.
+- **operation_name** (<code>str</code>) – The operation being traced (e.g. "haystack.pipeline.run"). Used to determine
+  if a new trace should be created without warning.
+- **component_type** (<code>str | None</code>) – The type of component creating the span (e.g. "OpenAIChatGenerator").
+  Can be used to determine the type of span to create.
+- **tags** (<code>dict\[str, Any\]</code>) – Additional metadata to attach to the span. Contains component input/output data
+  and other trace information.
+- **parent_span** (<code>Span | None</code>) – The parent span if this is a child span. If None, a new trace will be created.
+- **trace_name** (<code>str</code>) – The name to use for the trace when creating a parent span. Defaults to "Haystack".
+- **public** (<code>bool</code>) – Whether traces should be publicly accessible. Defaults to False.
+
+### SpanHandler
+
+Bases: <code>ABC</code>
+
+Abstract base class for customizing how Langfuse spans are created and processed.
+
+This class defines two key extension points:
+
+1. create_span: Controls what type of span to create (default or generation)
+1. handle: Processes the span after component execution (adding metadata, metrics, etc.)
+
+To implement a custom handler:
+
+- Extend this class or DefaultSpanHandler
+- Override create_span and handle methods. It is more common to override handle.
+- Pass your handler to LangfuseConnector init method
+
+#### init_tracer
+
+```python
+init_tracer(tracer: langfuse.Langfuse) -> None
+```
+
+Initialize with Langfuse tracer. Called internally by LangfuseTracer.
+
+**Parameters:**
+
+- **tracer** (<code>Langfuse</code>) – The Langfuse client instance to use for creating spans
+
+#### create_span
+
+```python
+create_span(context: SpanContext) -> LangfuseSpan
+```
+
+Create a span of appropriate type based on the context.
+
+This method determines what kind of span to create:
+
+- A new trace if there's no parent span
+- A generation span for LLM components
+- A default span for other components
+
+**Parameters:**
+
+- **context** (<code>SpanContext</code>) – The context containing all information needed to create the span
+
+**Returns:**
+
+- <code>LangfuseSpan</code> – A new LangfuseSpan instance configured according to the context
+
+#### handle
+
+```python
+handle(span: LangfuseSpan, component_type: str | None) -> None
+```
+
+Process a span after component execution by attaching metadata and metrics.
+
+This method is called after the component or pipeline yields its span, allowing you to:
+
+- Extract and attach token usage statistics
+- Add model information
+- Record timing data (e.g., time-to-first-token)
+- Set log levels for quality monitoring
+- Add custom metrics and observations
+
+**Parameters:**
+
+- **span** (<code>LangfuseSpan</code>) – The span that was yielded by the component
+- **component_type** (<code>str | None</code>) – The type of component that created the span, used to determine
+  what metadata to extract and how to process it
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SpanHandler
+```
+
+Deserialize a SpanHandler from a dictionary.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this SpanHandler to a dictionary.
+
+### DefaultSpanHandler
+
+Bases: <code>SpanHandler</code>
+
+DefaultSpanHandler provides the default Langfuse tracing behavior for Haystack.
+
+#### create_span
+
+```python
+create_span(context: SpanContext) -> LangfuseSpan
+```
+
+Create a Langfuse span based on the given context.
+
+#### handle
+
+```python
+handle(span: LangfuseSpan, component_type: str | None) -> None
+```
+
+Process and enrich a span after component execution.
+
+### LangfuseTracer
+
+Bases: <code>Tracer</code>
+
+Internal class representing a bridge between the Haystack tracer and Langfuse.
+
+#### __init__
+
+```python
+__init__(
+    tracer: langfuse.Langfuse,
+    name: str = "Haystack",
+    public: bool = False,
+    span_handler: SpanHandler | None = None,
+) -> None
+```
+
+Initialize a LangfuseTracer instance.
+
+**Parameters:**
+
+- **tracer** (<code>Langfuse</code>) – The Langfuse tracer instance.
+- **name** (<code>str</code>) – The name of the pipeline or component. This name will be used to identify the tracing run on the
+  Langfuse dashboard.
+- **public** (<code>bool</code>) – Whether the tracing data should be public or private. If set to `True`, the tracing data will
+  be publicly accessible to anyone with the tracing URL. If set to `False`, the tracing data will be private
+  and only accessible to the Langfuse account owner.
+- **span_handler** (<code>SpanHandler | None</code>) – Custom handler for processing spans. If None, uses DefaultSpanHandler.
+
+#### trace
+
+```python
+trace(
+    operation_name: str,
+    tags: dict[str, Any] | None = None,
+    parent_span: Span | None = None,
+) -> Iterator[Span]
+```
+
+Create and manage a tracing span as a context manager.
+
+#### flush
+
+```python
+flush() -> None
+```
+
+Flush all pending spans to Langfuse.
+
+#### current_span
+
+```python
+current_span() -> Span | None
+```
+
+Return the current active span.
+
+**Returns:**
+
+- <code>Span | None</code> – The current span if available, else None.
+
+#### get_trace_url
+
+```python
+get_trace_url() -> str
+```
+
+Return the URL to the tracing data.
+
+**Returns:**
+
+- <code>str</code> – The URL to the tracing data.
+
+#### get_trace_id
+
+```python
+get_trace_id() -> str
+```
+
+Return the trace ID.
+
+**Returns:**
+
+- <code>str</code> – The trace ID.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/lara.md

@@ -0,0 +1,177 @@
+---
+title: "Lara"
+id: integrations-lara
+description: "Lara integration for Haystack"
+slug: "/integrations-lara"
+---
+
+
+## haystack_integrations.components.translators.lara.document_translator
+
+### LaraDocumentTranslator
+
+Translates the text content of Haystack Documents using translated's Lara translation API.
+
+Lara is an adaptive translation AI that combines the fluency and context handling
+of LLMs with low hallucination and latency. It adapts to domains at inference time
+using optional context, instructions, translation memories, and glossaries. You can find
+more detailed information in the [Lara documentation](https://developers.laratranslate.com/docs/introduction).
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack.utils import Secret
+from haystack_integrations.components.lara import LaraDocumentTranslator
+
+translator = LaraDocumentTranslator(
+    access_key_id=Secret.from_env_var("LARA_ACCESS_KEY_ID"),
+    access_key_secret=Secret.from_env_var("LARA_ACCESS_KEY_SECRET"),
+    source_lang="en-US",
+    target_lang="de-DE",
+)
+
+doc = Document(content="Hello, world!")
+result = translator.run(documents=[doc])
+print(result["documents"][0].content)
+```
+
+#### __init__
+
+```python
+__init__(
+    access_key_id: Secret = Secret.from_env_var("LARA_ACCESS_KEY_ID"),
+    access_key_secret: Secret = Secret.from_env_var("LARA_ACCESS_KEY_SECRET"),
+    source_lang: str | None = None,
+    target_lang: str | None = None,
+    context: str | None = None,
+    instructions: str | None = None,
+    style: Literal["faithful", "fluid", "creative"] = "faithful",
+    adapt_to: list[str] | None = None,
+    glossaries: list[str] | None = None,
+    reasoning: bool = False,
+)
+```
+
+Creats an instance of the LaraDocumentTranslator component.
+
+**Parameters:**
+
+- **access_key_id** (<code>Secret</code>) – Lara API access key ID. Defaults to the `LARA_ACCESS_KEY_ID` environment variable.
+- **access_key_secret** (<code>Secret</code>) – Lara API access key secret. Defaults to the `LARA_ACCESS_KEY_SECRET` environment variable.
+- **source_lang** (<code>str | None</code>) – Language code of the source text. If `None`, Lara auto-detects the source language.
+  Use locale codes from the
+  [supported languages list](https://developers.laratranslate.com/docs/supported-languages).
+- **target_lang** (<code>str | None</code>) – Language code of the target text.
+  Use locale codes from the
+  [supported languages list](https://developers.laratranslate.com/docs/supported-languages).
+- **context** (<code>str | None</code>) – Optional external context: text that is not translated but is sent to Lara to
+  improve translation quality (e.g. surrounding sentences, prior messages).
+  You can find more detailed information in the
+  [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-context).
+- **instructions** (<code>str | None</code>) – Optional natural-language instructions to guide translation and
+  specify domain-specific terminology (e.g. "Be formal", "Use a professional tone").
+  You can find more detailed information in the
+  [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-instructions).
+- **style** (<code>Literal['faithful', 'fluid', 'creative']</code>) – One of `"faithful"`, `"fluid"`, or `"creative"`.
+  Default is `"faithful"`.
+  Style description:
+- `"faithful"`: For accuracy and precision. Keeps original structure and meaning.
+  Ideal for manuals, legal documents.
+- `"fluid"`: For readability and natural flow. Smooth, conversational. Good for general content.
+- `"creative"`: For artistic and creative expression. Best for literature, marketing, or content
+  where impact and tone matter more than literal wording.
+  You can find more detailed information in the
+  [Lara documentation](https://support.laratranslate.com/en/translation-styles).
+- **adapt_to** (<code>list\[str\] | None</code>) – Optional list of translation memory IDs. Lara adapts to the style and terminology of these memories
+  at inference time. Domain adaptation is available depending on your plan. You can find more
+  detailed information in the
+  [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-translation-memories).
+- **glossaries** (<code>list\[str\] | None</code>) – Optional list of glossary IDs. Lara applies these glossaries at inference time to enforce
+  consistent terminology (e.g. brand names, product terms, legal or technical phrases) across translations.
+  Glossary management and availability depends on your plan.
+  You can find more detailed information in the
+  [Lara documentation](https://developers.laratranslate.com/docs/manage-glossaries).
+- **reasoning** (<code>bool</code>) – If `True`, uses the Lara Think model for higher-quality translation (multi-step linguistic analysis).
+  Increases latency and cost. Availability depends on your plan. You can find more detailed information in the
+  [Lara documentation](https://developers.laratranslate.com/docs/translate-text#reasoning-lara-think).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Lara translator by initializing the client.
+
+#### run
+
+```python
+run(
+    documents: list[Document],
+    source_lang: str | list[str | None] | None = None,
+    target_lang: str | list[str] | None = None,
+    context: str | list[str] | None = None,
+    instructions: str | list[str] | None = None,
+    style: str | list[str] | None = None,
+    adapt_to: list[str] | list[list[str]] | None = None,
+    glossaries: list[str] | list[list[str]] | None = None,
+    reasoning: bool | list[bool] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Translate the text content of each input Document using the Lara API.
+
+Any of the translation parameters (source_lang, target_lang, context,
+instructions, style, adapt_to, glossaries, reasoning) can be passed here
+to override the defaults set when creating the component. They can be a single value
+(applied to all documents) or a list of values with the same length as
+`documents` for per-document settings.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of Haystack Documents whose `content` is to be translated.
+- **source_lang** (<code>str | list\[str | None\] | None</code>) – Source language code(s). Use locale codes from the
+  [supported languages list](https://developers.laratranslate.com/docs/supported-languages).
+  If `None`, Lara auto-detects the source language. Single value or list (one per document).
+- **target_lang** (<code>str | list\[str\] | None</code>) – Target language code(s). Use locale codes from the
+  [supported languages list](https://developers.laratranslate.com/docs/supported-languages).
+  Single value or list (one per document).
+- **context** (<code>str | list\[str\] | None</code>) – Optional external context: text that is not translated but is sent to Lara to
+  improve translation quality (e.g. surrounding sentences, prior messages).
+  You can find more detailed information in the
+  [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-context).
+- **instructions** (<code>str | list\[str\] | None</code>) – Optional natural-language instructions to guide translation and specify
+  domain-specific terminology (e.g. "Be formal", "Use a professional tone").
+  You can find more detailed information in the
+  [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-instructions).
+- **style** (<code>str | list\[str\] | None</code>) – One of `"faithful"`, `"fluid"`, or `"creative"`.
+  Style description:
+- `"faithful"`: For accuracy and precision. Keeps original structure and meaning.
+  Ideal for manuals, legal documents.
+- `"fluid"`: For readability and natural flow. Smooth, conversational. Good for general content.
+- `"creative"`: For artistic and creative expression. Best for literature, marketing, or content
+  where impact and tone matter more than literal wording.
+  You can find more detailed information in the
+  [Lara documentation](https://support.laratranslate.com/en/translation-styles).
+- **adapt_to** (<code>list\[str\] | list\[list\[str\]\] | None</code>) – Optional list of translation memory IDs. Lara adapts to the style and terminology
+  of these memories at inference time. Domain adaptation is available depending on your plan.
+  You can find more detailed information in the
+  [Lara documentation](https://developers.laratranslate.com/docs/adapt-to-translation-memories).
+- **glossaries** (<code>list\[str\] | list\[list\[str\]\] | None</code>) – Optional list of glossary IDs. Lara applies these glossaries at inference time to enforce
+  consistent terminology (e.g. brand names, product terms, legal or technical phrases) across translations.
+  Glossary management and availability depends on your plan.
+  You can find more detailed information in the
+  [Lara documentation](https://developers.laratranslate.com/docs/manage-glossaries).
+- **reasoning** (<code>bool | list\[bool\] | None</code>) – If `True`, uses the Lara Think model for higher-quality translation (multi-step linguistic analysis).
+  Increases latency and cost. Availability depends on your plan. You can find more detailed information in the
+  [Lara documentation](https://developers.laratranslate.com/docs/translate-text#reasoning-lara-think).
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of translated documents.
+
+**Raises:**
+
+- <code>ValueError</code> – If any list-valued parameter has length != `len(documents)`.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/libreoffice.md

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

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/llama_cpp.md

@@ -0,0 +1,275 @@
+---
+title: "Llama.cpp"
+id: integrations-llama-cpp
+description: "Llama.cpp integration for Haystack"
+slug: "/integrations-llama-cpp"
+---
+
+<a id="haystack_integrations.components.generators.llama_cpp.chat.chat_generator"></a>
+
+## Module haystack\_integrations.components.generators.llama\_cpp.chat.chat\_generator
+
+<a id="haystack_integrations.components.generators.llama_cpp.chat.chat_generator.LlamaCppChatGenerator"></a>
+
+### LlamaCppChatGenerator
+
+Provides an interface to generate text using LLM via llama.cpp.
+
+[llama.cpp](https://github.com/ggml-org/llama.cpp) is a project written in C/C++ for efficient inference of LLMs.
+It employs the quantized GGUF format, suitable for running these models on standard machines (even without GPUs).
+Supports both text-only and multimodal (text + image) models like LLaVA.
+
+Usage example:
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator
+user_message = [ChatMessage.from_user("Who is the best American actor?")]
+generator = LlamaCppGenerator(model="zephyr-7b-beta.Q4_0.gguf", n_ctx=2048, n_batch=512)
+
+print(generator.run(user_message, generation_kwargs={"max_tokens": 128}))
+# {"replies": [ChatMessage(content="John Cusack", role=<ChatRole.ASSISTANT: "assistant">, name=None, meta={...})}
+```
+
+Usage example with multimodal (image + text):
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+
+# Create an image from file path or base64
+image_content = ImageContent.from_file_path("path/to/your/image.jpg")
+
+# Create a multimodal message with both text and image
+messages = [ChatMessage.from_user(content_parts=["What's in this image?", image_content])]
+
+# Initialize with multimodal support
+generator = LlamaCppChatGenerator(
+    model="llava-v1.5-7b-q4_0.gguf",
+    chat_handler_name="Llava15ChatHandler",  # Use llava-1-5 handler
+    model_clip_path="mmproj-model-f16.gguf",  # CLIP model
+    n_ctx=4096  # Larger context for image processing
+)
+generator.warm_up()
+
+result = generator.run(messages)
+print(result)
+```
+
+<a id="haystack_integrations.components.generators.llama_cpp.chat.chat_generator.LlamaCppChatGenerator.__init__"></a>
+
+#### LlamaCppChatGenerator.\_\_init\_\_
+
+```python
+def __init__(model: str,
+             n_ctx: int | None = 0,
+             n_batch: int | None = 512,
+             model_kwargs: dict[str, Any] | None = None,
+             generation_kwargs: dict[str, Any] | None = None,
+             *,
+             tools: ToolsType | None = None,
+             streaming_callback: StreamingCallbackT | None = None,
+             chat_handler_name: str | None = None,
+             model_clip_path: str | None = None) -> None
+```
+
+**Arguments**:
+
+- `model`: The path of a quantized model for text generation, for example, "zephyr-7b-beta.Q4_0.gguf".
+If the model path is also specified in the `model_kwargs`, this parameter will be ignored.
+- `n_ctx`: The number of tokens in the context. When set to 0, the context will be taken from the model.
+- `n_batch`: Prompt processing maximum batch size.
+- `model_kwargs`: Dictionary containing keyword arguments used to initialize the LLM for text generation.
+These keyword arguments provide fine-grained control over the model loading.
+In case of duplication, these kwargs override `model`, `n_ctx`, and `n_batch` init parameters.
+For more information on the available kwargs, see
+[llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/`llama_cpp.Llama.__init__`).
+- `generation_kwargs`: A dictionary containing keyword arguments to customize text generation.
+For more information on the available kwargs, see
+[llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/`llama_cpp.Llama.create_chat_completion`).
+- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+Each tool should have a unique name.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+- `chat_handler_name`: Name of the chat handler for multimodal models.
+Common options include: "Llava16ChatHandler", "MoondreamChatHandler", "Qwen25VLChatHandler".
+For other handlers, check
+[llama-cpp-python documentation](https://llama-cpp-python.readthedocs.io/en/latest/`multi`-modal-models).
+- `model_clip_path`: Path to the CLIP model for vision processing (e.g., "mmproj.bin").
+Required when chat_handler_name is provided for multimodal models.
+
+<a id="haystack_integrations.components.generators.llama_cpp.chat.chat_generator.LlamaCppChatGenerator.to_dict"></a>
+
+#### LlamaCppChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.generators.llama_cpp.chat.chat_generator.LlamaCppChatGenerator.from_dict"></a>
+
+#### LlamaCppChatGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "LlamaCppChatGenerator"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.generators.llama_cpp.chat.chat_generator.LlamaCppChatGenerator.run"></a>
+
+#### LlamaCppChatGenerator.run
+
+```python
+@component.output_types(replies=list[ChatMessage])
+def run(
+    messages: list[ChatMessage],
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    tools: ToolsType | None = None,
+    streaming_callback: StreamingCallbackT | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Run the text generation model on the given list of ChatMessages.
+
+**Arguments**:
+
+- `messages`: A list of ChatMessage instances representing the input messages.
+- `generation_kwargs`: A dictionary containing keyword arguments to customize text generation.
+For more information on the available kwargs, see
+[llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/`llama_cpp.Llama.create_chat_completion`).
+- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+Each tool should have a unique name. If set, it will override the `tools` parameter set during
+component initialization.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+If set, it will override the `streaming_callback` parameter set during component initialization.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: The responses from the model
+
+<a id="haystack_integrations.components.generators.llama_cpp.chat.chat_generator.LlamaCppChatGenerator.run_async"></a>
+
+#### LlamaCppChatGenerator.run\_async
+
+```python
+@component.output_types(replies=list[ChatMessage])
+async def run_async(
+    messages: list[ChatMessage],
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    tools: ToolsType | None = None,
+    streaming_callback: StreamingCallbackT | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Async version of run. Runs the text generation model on the given list of ChatMessages.
+
+Uses a thread pool to avoid blocking the event loop, since llama-cpp-python provides
+only synchronous inference.
+
+**Arguments**:
+
+- `messages`: A list of ChatMessage instances representing the input messages.
+- `generation_kwargs`: A dictionary containing keyword arguments to customize text generation.
+For more information on the available kwargs, see
+[llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/`llama_cpp.Llama.create_chat_completion`).
+- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+Each tool should have a unique name. If set, it will override the `tools` parameter set during
+component initialization.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+If set, it will override the `streaming_callback` parameter set during component initialization.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: The responses from the model
+
+<a id="haystack_integrations.components.generators.llama_cpp.generator"></a>
+
+## Module haystack\_integrations.components.generators.llama\_cpp.generator
+
+<a id="haystack_integrations.components.generators.llama_cpp.generator.LlamaCppGenerator"></a>
+
+### LlamaCppGenerator
+
+Provides an interface to generate text using LLM via llama.cpp.
+
+[llama.cpp](https://github.com/ggml-org/llama.cpp) is a project written in C/C++ for efficient inference of LLMs.
+It employs the quantized GGUF format, suitable for running these models on standard machines (even without GPUs).
+
+Usage example:
+```python
+from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator
+generator = LlamaCppGenerator(model="zephyr-7b-beta.Q4_0.gguf", n_ctx=2048, n_batch=512)
+
+print(generator.run("Who is the best American actor?", generation_kwargs={"max_tokens": 128}))
+# {'replies': ['John Cusack'], 'meta': [{"object": "text_completion", ...}]}
+```
+
+<a id="haystack_integrations.components.generators.llama_cpp.generator.LlamaCppGenerator.__init__"></a>
+
+#### LlamaCppGenerator.\_\_init\_\_
+
+```python
+def __init__(model: str,
+             n_ctx: int | None = 0,
+             n_batch: int | None = 512,
+             model_kwargs: dict[str, Any] | None = None,
+             generation_kwargs: dict[str, Any] | None = None) -> None
+```
+
+**Arguments**:
+
+- `model`: The path of a quantized model for text generation, for example, "zephyr-7b-beta.Q4_0.gguf".
+If the model path is also specified in the `model_kwargs`, this parameter will be ignored.
+- `n_ctx`: The number of tokens in the context. When set to 0, the context will be taken from the model.
+- `n_batch`: Prompt processing maximum batch size.
+- `model_kwargs`: Dictionary containing keyword arguments used to initialize the LLM for text generation.
+These keyword arguments provide fine-grained control over the model loading.
+In case of duplication, these kwargs override `model`, `n_ctx`, and `n_batch` init parameters.
+For more information on the available kwargs, see
+[llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/`llama_cpp.Llama.__init__`).
+- `generation_kwargs`: A dictionary containing keyword arguments to customize text generation.
+For more information on the available kwargs, see
+[llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/`llama_cpp.Llama.create_completion`).
+
+<a id="haystack_integrations.components.generators.llama_cpp.generator.LlamaCppGenerator.run"></a>
+
+#### LlamaCppGenerator.run
+
+```python
+@component.output_types(replies=list[str], meta=list[dict[str, Any]])
+def run(
+    prompt: str,
+    generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Run the text generation model on the given prompt.
+
+**Arguments**:
+
+- `prompt`: the prompt to be sent to the generative model.
+- `generation_kwargs`: A dictionary containing keyword arguments to customize text generation.
+For more information on the available kwargs, see
+[llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/`llama_cpp.Llama.create_completion`).
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: the list of replies generated by the model.
+- `meta`: metadata about the request.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/llama_stack.md

@@ -0,0 +1,144 @@
+---
+title: "Llama Stack"
+id: integrations-llama-stack
+description: "Llama Stack integration for Haystack"
+slug: "/integrations-llama-stack"
+---
+
+<a id="haystack_integrations.components.generators.llama_stack.chat.chat_generator"></a>
+
+## Module haystack\_integrations.components.generators.llama\_stack.chat.chat\_generator
+
+<a id="haystack_integrations.components.generators.llama_stack.chat.chat_generator.LlamaStackChatGenerator"></a>
+
+### LlamaStackChatGenerator
+
+Enables text generation using Llama Stack framework.
+Llama Stack Server supports multiple inference providers, including Ollama, Together,
+and vLLM and other cloud providers.
+For a complete list of inference providers, see [Llama Stack docs](https://llama-stack.readthedocs.io/en/latest/providers/inference/index.html).
+
+Users can pass any text generation parameters valid for the OpenAI chat completion API
+directly to this component using the `generation_kwargs`
+parameter in `__init__` or the `generation_kwargs` parameter in `run` method.
+
+This component uses the `ChatMessage` format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the `ChatMessage` format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage)
+
+Usage example:
+You need to setup Llama Stack Server before running this example and have a model available. For a quick start on
+how to setup server with Ollama, see [Llama Stack docs](https://llama-stack.readthedocs.io/en/latest/getting_started/index.html).
+
+```python
+from haystack_integrations.components.generators.llama_stack import LlamaStackChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = LlamaStackChatGenerator(model="ollama/llama3.2:3b")
+response = client.run(messages)
+print(response)
+
+>>{'replies': [ChatMessage(_content=[TextContent(text='Natural Language Processing (NLP)
+is a branch of artificial intelligence
+>>that focuses on enabling computers to understand, interpret, and generate human language in a way that is
+>>meaningful and useful.')], _role=<ChatRole.ASSISTANT: 'assistant'>, _name=None,
+>>_meta={'model': 'ollama/llama3.2:3b', 'index': 0, 'finish_reason': 'stop',
+>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]}
+
+<a id="haystack_integrations.components.generators.llama_stack.chat.chat_generator.LlamaStackChatGenerator.__init__"></a>
+
+#### LlamaStackChatGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+             model: str,
+             api_base_url: str = "http://localhost:8321/v1",
+             organization: str | None = None,
+             streaming_callback: StreamingCallbackT | None = None,
+             generation_kwargs: dict[str, Any] | None = None,
+             timeout: int | None = None,
+             tools: ToolsType | None = None,
+             tools_strict: bool = False,
+             max_retries: int | None = None,
+             http_client_kwargs: dict[str, Any] | None = None)
+```
+
+Creates an instance of LlamaStackChatGenerator. To use this chat generator,
+
+you need to setup Llama Stack Server with an inference provider and have a model available.
+
+**Arguments**:
+
+- `model`: The name of the model to use for chat completion.
+This depends on the inference provider used for the Llama Stack Server.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+The callback function accepts StreamingChunk as an argument.
+- `api_base_url`: The Llama Stack API base url. If not specified, the localhost is used with the default port 8321.
+- `organization`: Your organization ID, defaults to `None`.
+- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to
+the Llama Stack endpoint. See [Llama Stack API docs](https://llama-stack.readthedocs.io/) for more details.
+Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+    Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+    considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+    comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+    events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+    If provided, the output will always be validated against this
+    format (unless the model returns a tool call).
+    For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+    Notes:
+    - For structured outputs with streaming,
+      the `response_format` must be a JSON schema and not a Pydantic model.
+- `timeout`: Timeout for client calls using OpenAI API. If not set, it defaults to either the
+`OPENAI_TIMEOUT` environment variable, or 30 seconds.
+- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+Each tool should have a unique name.
+- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly
+the schema provided in the `parameters` field of the tool definition, but this may increase latency.
+- `max_retries`: Maximum number of retries to contact OpenAI after an internal error.
+If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`).
+
+<a id="haystack_integrations.components.generators.llama_stack.chat.chat_generator.LlamaStackChatGenerator.to_dict"></a>
+
+#### LlamaStackChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns**:
+
+The serialized component as a dictionary.
+
+<a id="haystack_integrations.components.generators.llama_stack.chat.chat_generator.LlamaStackChatGenerator.from_dict"></a>
+
+#### LlamaStackChatGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "LlamaStackChatGenerator"
+```
+
+Deserialize this component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary representation of this component.
+
+**Returns**:
+
+The deserialized component instance.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/markitdown.md

@@ -0,0 +1,61 @@
+---
+title: "Markitdown"
+id: integrations-markitdown
+description: "Markitdown integration for Haystack"
+slug: "/integrations-markitdown"
+---
+
+
+## haystack_integrations.components.converters.markitdown.markitdown_converter
+
+### MarkItDownConverter
+
+Converts files to Haystack Documents using [MarkItDown](https://github.com/microsoft/markitdown).
+
+MarkItDown is a Microsoft library that converts many file formats to Markdown,
+including PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), HTML, images,
+audio, and more. All processing is performed locally.
+
+### Usage example
+
+```python
+from haystack_integrations.components.converters.markitdown import MarkItDownConverter
+
+converter = MarkItDownConverter()
+result = converter.run(sources=["document.pdf", "report.docx"])
+documents = result["documents"]
+```
+
+#### __init__
+
+```python
+__init__(store_full_path: bool = False) -> None
+```
+
+Initializes the MarkItDownConverter.
+
+**Parameters:**
+
+- **store_full_path** (<code>bool</code>) – If `True`, the full file path is stored in the Document metadata.
+  If `False`, only the file name is stored. Defaults to `False`.
+
+#### run
+
+```python
+run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Converts files to Documents using MarkItDown.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths or ByteStream objects to convert.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the Documents. Can be a single dict
+  applied to all Documents, or a list of dicts aligned with `sources`.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with key `documents` containing the converted Documents.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/mcp.md

@@ -0,0 +1,982 @@
+---
+title: "MCP"
+id: integrations-mcp
+description: "MCP integration for Haystack"
+slug: "/integrations-mcp"
+---
+
+
+## haystack_integrations.tools.mcp.mcp_tool
+
+### AsyncExecutor
+
+Thread-safe event loop executor for running async code from sync contexts.
+
+#### get_instance
+
+```python
+get_instance() -> AsyncExecutor
+```
+
+Get or create the global singleton executor instance.
+
+#### __init__
+
+```python
+__init__() -> None
+```
+
+Initialize a dedicated event loop
+
+#### run
+
+```python
+run(coro: Coroutine[Any, Any, Any], timeout: float | None = None) -> Any
+```
+
+Run a coroutine in the event loop.
+
+**Parameters:**
+
+- **coro** (<code>Coroutine\[Any, Any, Any\]</code>) – Coroutine to execute
+- **timeout** (<code>float | None</code>) – Optional timeout in seconds
+
+**Returns:**
+
+- <code>Any</code> – Result of the coroutine
+
+**Raises:**
+
+- <code>TimeoutError</code> – If execution exceeds timeout
+
+#### get_loop
+
+```python
+get_loop() -> asyncio.AbstractEventLoop
+```
+
+Get the event loop.
+
+**Returns:**
+
+- <code>AbstractEventLoop</code> – The event loop
+
+#### run_background
+
+```python
+run_background(
+    coro_factory: Callable[[asyncio.Event], Coroutine[Any, Any, Any]],
+    timeout: float | None = None,
+) -> tuple[concurrent.futures.Future[Any], asyncio.Event]
+```
+
+Schedule `coro_factory` to run in the executor's event loop **without** blocking the caller thread.
+
+The factory receives an :class:`asyncio.Event` that can be used to cooperatively shut
+the coroutine down. The method returns **both** the concurrent future (to observe
+completion or failure) and the created *stop_event* so that callers can signal termination.
+
+**Parameters:**
+
+- **coro_factory** (<code>Callable\\[[Event\], Coroutine\[Any, Any, Any\]\]</code>) – A callable receiving the stop_event and returning the coroutine to execute.
+- **timeout** (<code>float | None</code>) – Optional timeout while waiting for the stop_event to be created.
+
+**Returns:**
+
+- <code>tuple\[Future\[Any\], Event\]</code> – Tuple `(future, stop_event)`.
+
+#### shutdown
+
+```python
+shutdown(timeout: float = 2) -> None
+```
+
+Shut down the background event loop and thread.
+
+**Parameters:**
+
+- **timeout** (<code>float</code>) – Timeout in seconds for shutting down the event loop
+
+### MCPError
+
+Bases: <code>Exception</code>
+
+Base class for MCP-related errors.
+
+#### __init__
+
+```python
+__init__(message: str) -> None
+```
+
+Initialize the MCPError.
+
+**Parameters:**
+
+- **message** (<code>str</code>) – Descriptive error message
+
+### MCPConnectionError
+
+Bases: <code>MCPError</code>
+
+Error connecting to MCP server.
+
+#### __init__
+
+```python
+__init__(
+    message: str,
+    server_info: MCPServerInfo | None = None,
+    operation: str | None = None,
+) -> None
+```
+
+Initialize the MCPConnectionError.
+
+**Parameters:**
+
+- **message** (<code>str</code>) – Descriptive error message
+- **server_info** (<code>MCPServerInfo | None</code>) – Server connection information that was used
+- **operation** (<code>str | None</code>) – Name of the operation that was being attempted
+
+### MCPToolNotFoundError
+
+Bases: <code>MCPError</code>
+
+Error when a tool is not found on the server.
+
+#### __init__
+
+```python
+__init__(
+    message: str, tool_name: str, available_tools: list[str] | None = None
+) -> None
+```
+
+Initialize the MCPToolNotFoundError.
+
+**Parameters:**
+
+- **message** (<code>str</code>) – Descriptive error message
+- **tool_name** (<code>str</code>) – Name of the tool that was requested but not found
+- **available_tools** (<code>list\[str\] | None</code>) – List of available tool names, if known
+
+### MCPInvocationError
+
+Bases: <code>ToolInvocationError</code>
+
+Error during tool invocation.
+
+#### __init__
+
+```python
+__init__(
+    message: str, tool_name: str, tool_args: dict[str, Any] | None = None
+) -> None
+```
+
+Initialize the MCPInvocationError.
+
+**Parameters:**
+
+- **message** (<code>str</code>) – Descriptive error message
+- **tool_name** (<code>str</code>) – Name of the tool that was being invoked
+- **tool_args** (<code>dict\[str, Any\] | None</code>) – Arguments that were passed to the tool
+
+### MCPClient
+
+Bases: <code>ABC</code>
+
+Abstract base class for MCP clients.
+
+This class defines the common interface and shared functionality for all MCP clients,
+regardless of the transport mechanism used.
+
+#### connect
+
+```python
+connect() -> list[types.Tool]
+```
+
+Connect to an MCP server.
+
+**Returns:**
+
+- <code>list\[Tool\]</code> – List of available tools on the server
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – If connection to the server fails
+
+#### call_tool
+
+```python
+call_tool(tool_name: str, tool_args: dict[str, Any]) -> str
+```
+
+Call a tool on the connected MCP server.
+
+**Parameters:**
+
+- **tool_name** (<code>str</code>) – Name of the tool to call
+- **tool_args** (<code>dict\[str, Any\]</code>) – Arguments to pass to the tool
+
+**Returns:**
+
+- <code>str</code> – JSON string representation of the tool invocation result
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – If not connected to an MCP server
+- <code>MCPInvocationError</code> – If the tool invocation fails
+
+#### aclose
+
+```python
+aclose() -> None
+```
+
+Close the connection and clean up resources.
+
+This method ensures all resources are properly released, even if errors occur.
+
+### StdioClient
+
+Bases: <code>MCPClient</code>
+
+MCP client that connects to servers using stdio transport.
+
+#### __init__
+
+```python
+__init__(
+    command: str,
+    args: list[str] | None = None,
+    env: dict[str, str | Secret] | None = None,
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+    max_delay: float = 30.0,
+) -> None
+```
+
+Initialize a stdio MCP client.
+
+**Parameters:**
+
+- **command** (<code>str</code>) – Command to run (e.g., "python", "node")
+- **args** (<code>list\[str\] | None</code>) – Arguments to pass to the command
+- **env** (<code>dict\[str, str | Secret\] | None</code>) – Environment variables for the command
+- **max_retries** (<code>int</code>) – Maximum number of reconnection attempts
+- **base_delay** (<code>float</code>) – Base delay for exponential backoff in seconds
+
+#### connect
+
+```python
+connect() -> list[types.Tool]
+```
+
+Connect to an MCP server using stdio transport.
+
+**Returns:**
+
+- <code>list\[Tool\]</code> – List of available tools on the server
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – If connection to the server fails
+
+### SSEClient
+
+Bases: <code>MCPClient</code>
+
+MCP client that connects to servers using SSE transport.
+
+#### __init__
+
+```python
+__init__(
+    server_info: SSEServerInfo,
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+    max_delay: float = 30.0,
+) -> None
+```
+
+Initialize an SSE MCP client using server configuration.
+
+**Parameters:**
+
+- **server_info** (<code>SSEServerInfo</code>) – Configuration object containing URL, token, timeout, etc.
+- **max_retries** (<code>int</code>) – Maximum number of reconnection attempts
+- **base_delay** (<code>float</code>) – Base delay for exponential backoff in seconds
+
+#### connect
+
+```python
+connect() -> list[types.Tool]
+```
+
+Connect to an MCP server using SSE transport.
+
+Note: If both custom headers and token are provided, custom headers take precedence.
+
+**Returns:**
+
+- <code>list\[Tool\]</code> – List of available tools on the server
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – If connection to the server fails
+
+### StreamableHttpClient
+
+Bases: <code>MCPClient</code>
+
+MCP client that connects to servers using streamable HTTP transport.
+
+#### __init__
+
+```python
+__init__(
+    server_info: StreamableHttpServerInfo,
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+    max_delay: float = 30.0,
+) -> None
+```
+
+Initialize a streamable HTTP MCP client using server configuration.
+
+**Parameters:**
+
+- **server_info** (<code>StreamableHttpServerInfo</code>) – Configuration object containing URL, token, timeout, etc.
+- **max_retries** (<code>int</code>) – Maximum number of reconnection attempts
+- **base_delay** (<code>float</code>) – Base delay for exponential backoff in seconds
+
+#### connect
+
+```python
+connect() -> list[types.Tool]
+```
+
+Connect to an MCP server using streamable HTTP transport.
+
+Note: If both custom headers and token are provided, custom headers take precedence.
+
+**Returns:**
+
+- <code>list\[Tool\]</code> – List of available tools on the server
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – If connection to the server fails
+
+### MCPServerInfo
+
+Bases: <code>ABC</code>
+
+Abstract base class for MCP server connection parameters.
+
+This class defines the common interface for all MCP server connection types.
+
+#### create_client
+
+```python
+create_client() -> MCPClient
+```
+
+Create an appropriate MCP client for this server info.
+
+**Returns:**
+
+- <code>MCPClient</code> – An instance of MCPClient configured with this server info
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this server info to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary representation of this server info
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MCPServerInfo
+```
+
+Deserialize server info from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary containing serialized server info
+
+**Returns:**
+
+- <code>MCPServerInfo</code> – Instance of the appropriate server info class
+
+### SSEServerInfo
+
+Bases: <code>MCPServerInfo</code>
+
+Data class that encapsulates SSE MCP server connection parameters.
+
+For authentication tokens containing sensitive data, you can use Secret objects
+for secure handling and serialization:
+
+```python
+server_info = SSEServerInfo(
+    url="https://my-mcp-server.com",
+    token=Secret.from_env_var("API_KEY"),
+)
+```
+
+For custom headers (e.g., non-standard authentication):
+
+```python
+# Single custom header with Secret
+server_info = SSEServerInfo(
+    url="https://my-mcp-server.com",
+    headers={"X-API-Key": Secret.from_env_var("API_KEY")},
+)
+
+# Multiple headers (mix of Secret and plain strings)
+server_info = SSEServerInfo(
+    url="https://my-mcp-server.com",
+    headers={
+        "X-API-Key": Secret.from_env_var("API_KEY"),
+        "X-Client-ID": "my-client-id",
+    },
+)
+```
+
+**Parameters:**
+
+- **url** (<code>str | None</code>) – Full URL of the MCP server (including /sse endpoint)
+- **base_url** (<code>str | None</code>) – Base URL of the MCP server (deprecated, use url instead)
+- **token** (<code>str | Secret | None</code>) – Authentication token for the server (optional, generates "Authorization: Bearer `<token>`" header)
+- **headers** (<code>dict\[str, str | Secret\] | None</code>) – Custom HTTP headers (optional, takes precedence over token parameter if provided)
+- **timeout** (<code>int</code>) – Connection timeout in seconds
+
+#### create_client
+
+```python
+create_client() -> MCPClient
+```
+
+Create an SSE MCP client.
+
+**Returns:**
+
+- <code>MCPClient</code> – Configured MCPClient instance
+
+### StreamableHttpServerInfo
+
+Bases: <code>MCPServerInfo</code>
+
+Data class that encapsulates streamable HTTP MCP server connection parameters.
+
+For authentication tokens containing sensitive data, you can use Secret objects
+for secure handling and serialization:
+
+```python
+server_info = StreamableHttpServerInfo(
+    url="https://my-mcp-server.com",
+    token=Secret.from_env_var("API_KEY"),
+)
+```
+
+For custom headers (e.g., non-standard authentication):
+
+```python
+# Single custom header with Secret
+server_info = StreamableHttpServerInfo(
+    url="https://my-mcp-server.com",
+    headers={"X-API-Key": Secret.from_env_var("API_KEY")},
+)
+
+# Multiple headers (mix of Secret and plain strings)
+server_info = StreamableHttpServerInfo(
+    url="https://my-mcp-server.com",
+    headers={
+        "X-API-Key": Secret.from_env_var("API_KEY"),
+        "X-Client-ID": "my-client-id",
+    },
+)
+```
+
+**Parameters:**
+
+- **url** (<code>str</code>) – Full URL of the MCP server (streamable HTTP endpoint)
+- **token** (<code>str | Secret | None</code>) – Authentication token for the server (optional, generates "Authorization: Bearer `<token>`" header)
+- **headers** (<code>dict\[str, str | Secret\] | None</code>) – Custom HTTP headers (optional, takes precedence over token parameter if provided)
+- **timeout** (<code>int</code>) – Connection timeout in seconds
+
+#### create_client
+
+```python
+create_client() -> MCPClient
+```
+
+Create a streamable HTTP MCP client.
+
+**Returns:**
+
+- <code>MCPClient</code> – Configured StreamableHttpClient instance
+
+### StdioServerInfo
+
+Bases: <code>MCPServerInfo</code>
+
+Data class that encapsulates stdio MCP server connection parameters.
+
+**Parameters:**
+
+- **command** (<code>str</code>) – Command to run (e.g., "python", "node")
+- **args** (<code>list\[str\] | None</code>) – Arguments to pass to the command
+- **env** (<code>dict\[str, str | Secret\] | None</code>) – Environment variables for the command
+
+For environment variables containing sensitive data, you can use Secret objects
+for secure handling and serialization:
+
+```python
+server_info = StdioServerInfo(
+    command="uv",
+    args=["run", "my-mcp-server"],
+    env={
+        "WORKSPACE_PATH": "/path/to/workspace",  # Plain string
+        "API_KEY": Secret.from_env_var("API_KEY"),  # Secret object
+    }
+)
+```
+
+Secret objects will be properly serialized and deserialized without exposing
+the secret value, while plain strings will be preserved as-is. Use Secret objects
+for sensitive data that needs to be handled securely.
+
+#### create_client
+
+```python
+create_client() -> MCPClient
+```
+
+Create a stdio MCP client.
+
+**Returns:**
+
+- <code>MCPClient</code> – Configured StdioMCPClient instance
+
+### MCPTool
+
+Bases: <code>Tool</code>
+
+A Tool that represents a single tool from an MCP server.
+
+This implementation uses the official MCP SDK for protocol handling while maintaining
+compatibility with the Haystack tool ecosystem.
+
+Response handling:
+
+- Text and image content are supported and returned as JSON strings
+- The JSON contains the structured response from the MCP server
+- Use json.loads() to parse the response into a dictionary
+
+State-mapping support:
+
+- MCPTool supports state-mapping parameters (`outputs_to_string`, `inputs_from_state`, `outputs_to_state`)
+- These enable integration with Agent state for automatic parameter injection and output handling
+- See the `__init__` method documentation for details on each parameter
+
+Example using Streamable HTTP:
+
+```python
+import json
+from haystack_integrations.tools.mcp import MCPTool, StreamableHttpServerInfo
+
+# Create tool instance
+tool = MCPTool(
+    name="multiply",
+    server_info=StreamableHttpServerInfo(url="http://localhost:8000/mcp")
+)
+
+# Use the tool and parse result
+result_json = tool.invoke(a=5, b=3)
+result = json.loads(result_json)
+```
+
+Example using SSE (deprecated):
+
+```python
+import json
+from haystack.tools import MCPTool, SSEServerInfo
+
+# Create tool instance
+tool = MCPTool(
+    name="add",
+    server_info=SSEServerInfo(url="http://localhost:8000/sse")
+)
+
+# Use the tool and parse result
+result_json = tool.invoke(a=5, b=3)
+result = json.loads(result_json)
+```
+
+Example using stdio:
+
+```python
+import json
+from haystack.tools import MCPTool, StdioServerInfo
+
+# Create tool instance
+tool = MCPTool(
+    name="get_current_time",
+    server_info=StdioServerInfo(command="python", args=["path/to/server.py"])
+)
+
+# Use the tool and parse result
+result_json = tool.invoke(timezone="America/New_York")
+result = json.loads(result_json)
+```
+
+#### __init__
+
+```python
+__init__(
+    name: str,
+    server_info: MCPServerInfo,
+    description: str | None = None,
+    connection_timeout: int = 30,
+    invocation_timeout: int = 30,
+    eager_connect: bool = False,
+    outputs_to_string: dict[str, Any] | None = None,
+    inputs_from_state: dict[str, str] | None = None,
+    outputs_to_state: dict[str, dict[str, Any]] | None = None,
+) -> None
+```
+
+Initialize the MCP tool.
+
+**Parameters:**
+
+- **name** (<code>str</code>) – Name of the tool to use
+- **server_info** (<code>MCPServerInfo</code>) – Server connection information
+- **description** (<code>str | None</code>) – Custom description (if None, server description will be used)
+- **connection_timeout** (<code>int</code>) – Timeout in seconds for server connection
+- **invocation_timeout** (<code>int</code>) – Default timeout in seconds for tool invocations
+- **eager_connect** (<code>bool</code>) – If True, connect to server during initialization.
+  If False (default), defer connection until warm_up or first tool use,
+  whichever comes first.
+- **outputs_to_string** (<code>dict\[str, Any\] | None</code>) – Optional dictionary defining how tool outputs should be converted into a string.
+  If the source is provided only the specified output key is sent to the handler.
+  If the source is omitted the whole tool result is sent to the handler.
+  Example: `{"source": "docs", "handler": my_custom_function}`
+- **inputs_from_state** (<code>dict\[str, str\] | None</code>) – Optional dictionary mapping state keys to tool parameter names.
+  Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- **outputs_to_state** (<code>dict\[str, dict\[str, Any\]\] | None</code>) – Optional dictionary defining how tool outputs map to keys within state as well as
+  optional handlers. If the source is provided only the specified output key is sent
+  to the handler.
+  Example with source: `{"documents": {"source": "docs", "handler": custom_handler}}`
+  Example without source: `{"documents": {"handler": custom_handler}}`
+
+**Raises:**
+
+- <code>MCPConnectionError</code> – If connection to the server fails
+- <code>MCPToolNotFoundError</code> – If no tools are available or the requested tool is not found
+- <code>TimeoutError</code> – If connection times out
+
+#### ainvoke
+
+```python
+ainvoke(**kwargs: Any) -> str | dict[str, Any]
+```
+
+Asynchronous tool invocation.
+
+**Parameters:**
+
+- **kwargs** (<code>Any</code>) – Arguments to pass to the tool
+
+**Returns:**
+
+- <code>str | dict\[str, Any\]</code> – JSON string or dictionary representation of the tool invocation result.
+  Returns a dictionary when outputs_to_state is configured to enable state updates.
+
+**Raises:**
+
+- <code>MCPInvocationError</code> – If the tool invocation fails
+- <code>TimeoutError</code> – If the operation times out
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Connect and fetch the tool schema if eager_connect is turned off.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the MCPTool to a dictionary.
+
+The serialization preserves all information needed to recreate the tool,
+including server connection parameters, timeout settings, and state-mapping parameters.
+Note that the active connection is not maintained.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data in the format:
+  `{"type": fully_qualified_class_name, "data": {parameters}}`
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Tool
+```
+
+Deserializes the MCPTool from a dictionary.
+
+This method reconstructs an MCPTool instance from a serialized dictionary,
+including recreating the server_info object and state-mapping parameters.
+A new connection will be established to the MCP server during initialization.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary containing serialized tool data
+
+**Returns:**
+
+- <code>Tool</code> – A fully initialized MCPTool instance
+
+**Raises:**
+
+- <code>Exception</code> – if connection fails
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the tool synchronously.
+
+## haystack_integrations.tools.mcp.mcp_toolset
+
+### MCPToolset
+
+Bases: <code>Toolset</code>
+
+A Toolset that connects to an MCP (Model Context Protocol) server and provides access to its tools.
+
+MCPToolset dynamically discovers and loads all tools from any MCP-compliant server,
+supporting both network-based streaming connections (Streamable HTTP, SSE) and local
+process-based stdio connections.
+This dual connectivity allows for integrating with both remote and local MCP servers.
+
+Example using MCPToolset in a Haystack Pipeline:
+
+```python
+# Prerequisites:
+# 1. pip install uvx mcp-server-time  # Install required MCP server and tools
+# 2. export OPENAI_API_KEY="your-api-key"  # Set up your OpenAI API key
+
+import os
+from haystack import Pipeline
+from haystack.components.converters import OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.tools import ToolInvoker
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.tools.mcp import MCPToolset, StdioServerInfo
+
+# Create server info for the time service (can also use SSEServerInfo for remote servers)
+server_info = StdioServerInfo(command="uvx", args=["mcp-server-time", "--local-timezone=Europe/Berlin"])
+
+# Create the toolset - this will automatically discover all available tools
+# You can optionally specify which tools to include
+mcp_toolset = MCPToolset(
+    server_info=server_info,
+    tool_names=["get_current_time"]  # Only include the get_current_time tool
+)
+
+# Create a pipeline with the toolset
+pipeline = Pipeline()
+pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini", tools=mcp_toolset))
+pipeline.add_component("tool_invoker", ToolInvoker(tools=mcp_toolset))
+pipeline.add_component(
+    "adapter",
+    OutputAdapter(
+        template="{{ initial_msg + initial_tool_messages + tool_messages }}",
+        output_type=list[ChatMessage],
+        unsafe=True,
+    ),
+)
+pipeline.add_component("response_llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+pipeline.connect("llm.replies", "tool_invoker.messages")
+pipeline.connect("llm.replies", "adapter.initial_tool_messages")
+pipeline.connect("tool_invoker.tool_messages", "adapter.tool_messages")
+pipeline.connect("adapter.output", "response_llm.messages")
+
+# Run the pipeline with a user question
+user_input = "What is the time in New York? Be brief."
+user_input_msg = ChatMessage.from_user(text=user_input)
+
+result = pipeline.run({"llm": {"messages": [user_input_msg]}, "adapter": {"initial_msg": [user_input_msg]}})
+print(result["response_llm"]["replies"][0].text)
+```
+
+You can also use the toolset via Streamable HTTP to talk to remote servers:
+
+```python
+from haystack_integrations.tools.mcp import MCPToolset, StreamableHttpServerInfo
+
+# Create the toolset with streamable HTTP connection
+toolset = MCPToolset(
+    server_info=StreamableHttpServerInfo(url="http://localhost:8000/mcp"),
+    tool_names=["multiply"]  # Optional: only include specific tools
+)
+# Use the toolset as shown in the pipeline example above
+```
+
+Example with state configuration for Agent integration:
+
+```python
+from haystack_integrations.tools.mcp import MCPToolset, StdioServerInfo
+
+# Create the toolset with per-tool state configuration
+# This enables tools to read from and write to the Agent's State
+toolset = MCPToolset(
+    server_info=StdioServerInfo(command="uvx", args=["mcp-server-git"]),
+    tool_names=["git_status", "git_diff", "git_log"],
+
+    # Maps the state key "repository" to the tool parameter "repo_path" for each tool
+    inputs_from_state={
+        "git_status": {"repository": "repo_path"},
+        "git_diff": {"repository": "repo_path"},
+        "git_log": {"repository": "repo_path"},
+    },
+    # Map tool outputs to state keys for each tool
+    outputs_to_state={
+        "git_status": {"status_result": {"source": "status"}},  # Extract "status" from output
+        "git_diff": {"diff_result": {}},  # use full output with default handling
+    },
+)
+```
+
+Example using SSE (deprecated):
+
+```python
+from haystack_integrations.tools.mcp import MCPToolset, SSEServerInfo
+from haystack.components.tools import ToolInvoker
+
+# Create the toolset with an SSE connection
+sse_toolset = MCPToolset(
+    server_info=SSEServerInfo(url="http://some-remote-server.com:8000/sse"),
+    tool_names=["add", "subtract"]  # Only include specific tools
+)
+
+# Use the toolset as shown in the pipeline example above
+```
+
+#### __init__
+
+```python
+__init__(
+    server_info: MCPServerInfo,
+    tool_names: list[str] | None = None,
+    connection_timeout: float = 30.0,
+    invocation_timeout: float = 30.0,
+    eager_connect: bool = False,
+    inputs_from_state: dict[str, dict[str, str]] | None = None,
+    outputs_to_state: dict[str, dict[str, dict[str, Any]]] | None = None,
+    outputs_to_string: dict[str, dict[str, Any]] | None = None,
+) -> None
+```
+
+Initialize the MCP toolset.
+
+**Parameters:**
+
+- **server_info** (<code>MCPServerInfo</code>) – Connection information for the MCP server
+- **tool_names** (<code>list\[str\] | None</code>) – Optional list of tool names to include. If provided, only tools with
+  matching names will be added to the toolset.
+- **connection_timeout** (<code>float</code>) – Timeout in seconds for server connection
+- **invocation_timeout** (<code>float</code>) – Default timeout in seconds for tool invocations
+- **eager_connect** (<code>bool</code>) – If True, connect to server and load tools during initialization.
+  If False (default), defer connection to warm_up.
+- **inputs_from_state** (<code>dict\[str, dict\[str, str\]\] | None</code>) – Optional dictionary mapping tool names to their inputs_from_state config.
+  Each config maps state keys to tool parameter names.
+  Tool names should match available tools from the server; a warning is logged for
+  unknown tools. Note: With Haystack >= 2.22.0, parameter names are validated;
+  ValueError is raised for invalid parameters. With earlier versions, invalid
+  parameters fail at runtime.
+  Example: `{"git_status": {"repository": "repo_path"}}`
+- **outputs_to_state** (<code>dict\[str, dict\[str, dict\[str, Any\]\]\] | None</code>) – Optional dictionary mapping tool names to their outputs_to_state config.
+  Each config defines how tool outputs map to state keys with optional handlers.
+  Tool names should match available tools from the server; a warning is logged for
+  unknown tools.
+  Example: `{"git_status": {"status_result": {"source": "status"}}}`
+- **outputs_to_string** (<code>dict\[str, dict\[str, Any\]\] | None</code>) – Optional dictionary mapping tool names to their outputs_to_string config.
+  Each config defines how tool outputs are converted to strings.
+  Tool names should match available tools from the server; a warning is logged for
+  unknown tools.
+  Example: `{"git_diff": {"source": "diff", "handler": format_diff}}`
+
+**Raises:**
+
+- <code>MCPToolNotFoundError</code> – If any of the specified tool names are not found on the server
+- <code>ValueError</code> – If parameter names in inputs_from_state are invalid (Haystack >= 2.22.0 only)
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Connect and load tools when eager_connect is turned off.
+
+This method is automatically called by `ToolInvoker.warm_up()` and `Pipeline.warm_up()`.
+You can also call it directly before using the toolset to ensure all tool schemas
+are available without performing a real invocation.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the MCPToolset to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary representation of the MCPToolset
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MCPToolset
+```
+
+Deserialize an MCPToolset from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary representation of the MCPToolset
+
+**Returns:**
+
+- <code>MCPToolset</code> – A new MCPToolset instance
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the underlying MCP client safely.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/meta_llama.md

@@ -0,0 +1,127 @@
+---
+title: "Meta Llama API"
+id: integrations-meta-llama
+description: "Meta Llama API integration for Haystack"
+slug: "/integrations-meta-llama"
+---
+
+
+## haystack_integrations.components.generators.meta_llama.chat.chat_generator
+
+### MetaLlamaChatGenerator
+
+Bases: <code>OpenAIChatGenerator</code>
+
+Enables text generation using Llama generative models.
+For supported models, see [Llama API Docs](https://llama.developer.meta.com/docs/).
+
+Users can pass any text generation parameters valid for the Llama Chat Completion API
+directly to this component via the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+Key Features and Compatibility:
+
+- **Primary Compatibility**: Designed to work seamlessly with the Llama API Chat Completion endpoint.
+- **Streaming Support**: Supports streaming responses from the Llama API Chat Completion endpoint.
+- **Customizability**: Supports parameters supported by the Llama API Chat Completion endpoint.
+- **Response Format**: Currently only supports json_schema response format.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage)
+
+For more details on the parameters supported by the Llama API, refer to the
+[Llama API Docs](https://llama.developer.meta.com/docs/).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.llama import LlamaChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = LlamaChatGenerator()
+response = client.run(messages)
+print(response)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "Llama-4-Maverick-17B-128E-Instruct-FP8",
+    "Llama-4-Scout-17B-16E-Instruct-FP8",
+    "Llama-3.3-70B-Instruct",
+    "Llama-3.3-8B-Instruct",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+See https://llama.developer.meta.com/docs/models for the full list.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("LLAMA_API_KEY"),
+    model: str = "Llama-4-Scout-17B-16E-Instruct-FP8",
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: str | None = "https://api.llama.com/compat/v1/",
+    generation_kwargs: dict[str, Any] | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    tools: ToolsType | None = None
+)
+```
+
+Creates an instance of LlamaChatGenerator. Unless specified otherwise in the `model`, this is for Llama's
+`Llama-4-Scout-17B-16E-Instruct-FP8` model.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Llama API key.
+- **model** (<code>str</code>) – The name of the Llama chat completion model to use.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts StreamingChunk as an argument.
+- **api_base_url** (<code>str | None</code>) – The Llama API Base url.
+  For more details, see LlamaAPI [docs](https://llama.developer.meta.com/docs/features/compatibility/).
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Other parameters to use for the model. These parameters are all sent directly to
+  the Llama API endpoint. See [Llama API docs](https://llama.developer.meta.com/docs/features/compatibility/)
+  for more details.
+  Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+  Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+  considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+  comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+  events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+  If provided, the output will always be validated against this
+  format (unless the model returns a tool call).
+  For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+  For structured outputs with streaming, the `response_format` must be a JSON
+  schema and not a Pydantic model.
+- **timeout** (<code>float | None</code>) – Timeout for Llama API client calls.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to attempt for failed requests.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  Each tool should have a unique name.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/mistral.md

@@ -0,0 +1,558 @@
+---
+title: "Mistral"
+id: integrations-mistral
+description: "Mistral integration for Haystack"
+slug: "/integrations-mistral"
+---
+
+
+## haystack_integrations.components.converters.mistral.ocr_document_converter
+
+### MistralOCRDocumentConverter
+
+This component extracts text from documents using Mistral's OCR API, with optional structured
+annotations for both individual image regions (bounding boxes) and full documents.
+
+Accepts document sources in various formats (str/Path for local files, ByteStream for in-memory data,
+DocumentURLChunk for document URLs, ImageURLChunk for image URLs, or FileChunk for Mistral file IDs)
+and retrieves the recognized text via Mistral's OCR service. Local files are automatically uploaded
+to Mistral's storage.
+Returns Haystack Documents (one per source) containing all pages concatenated with form feed characters (\\f),
+ensuring compatibility with Haystack's DocumentSplitter for accurate page-wise splitting and overlap handling.
+
+**How Annotations Work:**
+When annotation schemas (`bbox_annotation_schema` or `document_annotation_schema`) are provided,
+the OCR model first extracts text and structure from the document. Then, a Vision LLM is called
+to analyze the content and generate structured annotations according to your defined schemas.
+For more details, see: https://docs.mistral.ai/capabilities/document_ai/annotations/#how-it-works
+
+**Usage Example:**
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.mistral import MistralOCRDocumentConverter
+from mistralai.models import DocumentURLChunk, ImageURLChunk, FileChunk
+
+converter = MistralOCRDocumentConverter(
+    api_key=Secret.from_env_var("MISTRAL_API_KEY"),
+    model="mistral-ocr-2505"
+)
+
+# Process multiple sources
+sources = [
+    DocumentURLChunk(document_url="https://example.com/document.pdf"),
+    ImageURLChunk(image_url="https://example.com/receipt.jpg"),
+    FileChunk(file_id="file-abc123"),
+]
+result = converter.run(sources=sources)
+
+documents = result["documents"]  # List of 3 Documents
+raw_responses = result["raw_mistral_response"]  # List of 3 raw responses
+```
+
+**Structured Output Example:**
+
+```python
+from pydantic import BaseModel, Field
+from haystack_integrations.mistral import MistralOCRDocumentConverter
+
+# Define schema for structured image annotations
+class ImageAnnotation(BaseModel):
+    image_type: str = Field(..., description="The type of image content")
+    short_description: str = Field(..., description="Short natural-language description")
+    summary: str = Field(..., description="Detailed summary of the image content")
+
+# Define schema for structured document annotations
+class DocumentAnnotation(BaseModel):
+    language: str = Field(..., description="Primary language of the document")
+    chapter_titles: List[str] = Field(..., description="Detected chapter or section titles")
+    urls: List[str] = Field(..., description="URLs found in the text")
+
+converter = MistralOCRDocumentConverter(
+    model="mistral-ocr-2505",
+)
+
+sources = [DocumentURLChunk(document_url="https://example.com/report.pdf")]
+result = converter.run(
+    sources=sources,
+    bbox_annotation_schema=ImageAnnotation,
+    document_annotation_schema=DocumentAnnotation,
+)
+
+documents = result["documents"]
+raw_responses = result["raw_mistral_response"]
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "mistral-ocr-2512",
+    "mistral-ocr-latest",
+    "mistral-ocr-2503",
+    "mistral-ocr-2505",
+]
+
+```
+
+A list of models supported by Mistral AI
+see [Mistral AI docs](https://docs.mistral.ai/getting-started/models) for more information
+and send a GET HTTP request to "https://api.mistral.ai/v1/models" for a full list of model IDs.
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"),
+    model: str = "mistral-ocr-2505",
+    include_image_base64: bool = False,
+    pages: list[int] | None = None,
+    image_limit: int | None = None,
+    image_min_size: int | None = None,
+    cleanup_uploaded_files: bool = True,
+)
+```
+
+Creates a MistralOCRDocumentConverter component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Mistral API key. Defaults to the MISTRAL_API_KEY environment variable.
+- **model** (<code>str</code>) – The OCR model to use. Default is "mistral-ocr-2505".
+  See more: https://docs.mistral.ai/getting-started/models/models_overview/
+- **include_image_base64** (<code>bool</code>) – If True, includes base64 encoded images in the response.
+  This may significantly increase response size and processing time.
+- **pages** (<code>list\[int\] | None</code>) – Specific page numbers to process (0-indexed). If None, processes all pages.
+- **image_limit** (<code>int | None</code>) – Maximum number of images to extract from the document.
+- **image_min_size** (<code>int | None</code>) – Minimum height and width (in pixels) for images to be extracted.
+- **cleanup_uploaded_files** (<code>bool</code>) – If True, automatically deletes files uploaded to Mistral after processing.
+  Only affects files uploaded from local sources (str, Path, ByteStream).
+  Files provided as FileChunk are not deleted. Default is True.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MistralOCRDocumentConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>MistralOCRDocumentConverter</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    sources: list[
+        str | Path | ByteStream | DocumentURLChunk | FileChunk | ImageURLChunk
+    ],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+    bbox_annotation_schema: type[BaseModel] | None = None,
+    document_annotation_schema: type[BaseModel] | None = None,
+) -> dict[str, Any]
+```
+
+Extract text from documents using Mistral OCR.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream | DocumentURLChunk | FileChunk | ImageURLChunk\]</code>) – List of document sources to process. Each source can be one of:
+- str: File path to a local document
+- Path: Path object to a local document
+- ByteStream: Haystack ByteStream object containing document data
+- DocumentURLChunk: Mistral chunk for document URLs (signed or public URLs to PDFs, etc.)
+- ImageURLChunk: Mistral chunk for image URLs (signed or public URLs to images)
+- FileChunk: Mistral chunk for file IDs (files previously uploaded to Mistral)
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the Documents.
+  This value can be either a list of dictionaries or a single dictionary.
+  If it's a single dictionary, its content is added to the metadata of all produced Documents.
+  If it's a list, the length of the list must match the number of sources, because they will be zipped.
+- **bbox_annotation_schema** (<code>type\[BaseModel\] | None</code>) – Optional Pydantic model for structured annotations per bounding box.
+  When provided, a Vision LLM analyzes each image region and returns structured data.
+- **document_annotation_schema** (<code>type\[BaseModel\] | None</code>) – Optional Pydantic model for structured annotations for the full document.
+  When provided, a Vision LLM analyzes the entire document and returns structured data.
+  Note: Document annotation is limited to a maximum of 8 pages. Documents exceeding
+  this limit will not be processed for document annotation.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: List of Haystack Documents (one per source). Each Document has the following structure:
+  - `content`: All pages joined with form feed (\\f) separators in markdown format.
+    When using bbox_annotation_schema, image tags will be enriched with your defined descriptions.
+  - `meta`: Aggregated metadata dictionary with structure:
+    `{"source_page_count": int, "source_total_images": int, "source_*": any}`.
+    If document_annotation_schema was provided, all annotation fields are unpacked
+    with 'source\_' prefix (e.g., source_language, source_chapter_titles, source_urls).
+- `raw_mistral_response`:
+  List of dictionaries containing raw OCR responses from Mistral API (one per source).
+  Each response includes per-page details, images, annotations, and usage info.
+
+## haystack_integrations.components.embedders.mistral.document_embedder
+
+### MistralDocumentEmbedder
+
+Bases: <code>OpenAIDocumentEmbedder</code>
+
+A component for computing Document embeddings using Mistral models.
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.mistral import MistralDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = MistralDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "mistral-embed-2312",
+    "mistral-embed",
+    "codestral-embed",
+    "codestral-embed-2505",
+]
+
+```
+
+A list of models supported by Mistral AI
+see [Mistral AI docs](https://docs.mistral.ai/getting-started/models) for more information
+and send a GET HTTP request to "https://api.mistral.ai/v1/models" for a full list of model IDs.
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"),
+    model: str = "mistral-embed",
+    api_base_url: str | None = "https://api.mistral.ai/v1",
+    prefix: str = "",
+    suffix: str = "",
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates a MistralDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Mistral API key.
+- **model** (<code>str</code>) – The name of the model to use.
+- **api_base_url** (<code>str | None</code>) – The Mistral API Base url. For more details, see Mistral [docs](https://docs.mistral.ai/api/).
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **batch_size** (<code>int</code>) – Number of Documents to encode at once.
+- **progress_bar** (<code>bool</code>) – Whether to show a progress bar or not. Can be helpful to disable in production deployments to keep
+  the logs clean.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
+- **timeout** (<code>float | None</code>) – Timeout for Mistral client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to contact Mistral after an internal error.
+  If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.components.embedders.mistral.text_embedder
+
+### MistralTextEmbedder
+
+Bases: <code>OpenAITextEmbedder</code>
+
+A component for embedding strings using Mistral models.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.mistral.text_embedder import MistralTextEmbedder
+
+text_to_embed = "I love pizza!"
+text_embedder = MistralTextEmbedder()
+print(text_embedder.run(text_to_embed))
+
+# output:
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+# 'meta': {'model': 'mistral-embed',
+#          'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "mistral-embed-2312",
+    "mistral-embed",
+    "codestral-embed",
+    "codestral-embed-2505",
+]
+
+```
+
+A list of models supported by Mistral AI
+see [Mistral AI docs](https://docs.mistral.ai/getting-started/models) for more information
+and send a GET HTTP request to "https://api.mistral.ai/v1/models" for a full list of model IDs.
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"),
+    model: str = "mistral-embed",
+    api_base_url: str | None = "https://api.mistral.ai/v1",
+    prefix: str = "",
+    suffix: str = "",
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates an MistralTextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Mistral API key.
+- **model** (<code>str</code>) – The name of the Mistral embedding model to be used.
+- **api_base_url** (<code>str | None</code>) – The Mistral API Base url.
+  For more details, see Mistral [docs](https://docs.mistral.ai/api/).
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **timeout** (<code>float | None</code>) – Timeout for Mistral client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to contact Mistral after an internal error.
+  If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.components.generators.mistral.chat.chat_generator
+
+### MistralChatGenerator
+
+Bases: <code>OpenAIChatGenerator</code>
+
+Enables text generation using Mistral AI generative models.
+For supported models, see [Mistral AI docs](https://docs.mistral.ai/getting-started/models).
+
+Users can pass any text generation parameters valid for the Mistral Chat Completion API
+directly to this component via the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+Key Features and Compatibility:
+
+- **Primary Compatibility**: Designed to work seamlessly with the Mistral API Chat Completion endpoint.
+- **Streaming Support**: Supports streaming responses from the Mistral API Chat Completion endpoint.
+- **Customizability**: Supports all parameters supported by the Mistral API Chat Completion endpoint.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage)
+
+For more details on the parameters supported by the Mistral API, refer to the
+[Mistral API Docs](https://docs.mistral.ai/api/).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.mistral import MistralChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = MistralChatGenerator()
+response = client.run(messages)
+print(response)
+
+>>{'replies': [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _content=[TextContent(text=
+>> "Natural Language Processing (NLP) is a branch of artificial intelligence
+>> that focuses on enabling computers to understand, interpret, and generate human language in a way that is
+>> meaningful and useful.")], _name=None,
+>> _meta={'model': 'mistral-small-latest', 'index': 0, 'finish_reason': 'stop',
+>> 'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]}
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "mistral-medium-2505",
+    "mistral-medium-2508",
+    "mistral-medium-latest",
+    "mistral-medium",
+    "mistral-vibe-cli-with-tools",
+    "open-mistral-nemo",
+    "open-mistral-nemo-2407",
+    "mistral-tiny-2407",
+    "mistral-tiny-latest",
+    "codestral-2508",
+    "codestral-latest",
+    "devstral-2512",
+    "mistral-vibe-cli-latest",
+    "devstral-medium-latest",
+    "devstral-latest",
+    "mistral-small-2506",
+    "mistral-small-latest",
+    "labs-mistral-small-creative",
+    "magistral-medium-2509",
+    "magistral-medium-latest",
+    "magistral-small-2509",
+    "magistral-small-latest",
+    "voxtral-small-2507",
+    "voxtral-small-latest",
+    "mistral-large-2512",
+    "mistral-large-latest",
+    "ministral-3b-2512",
+    "ministral-3b-latest",
+    "ministral-8b-2512",
+    "ministral-8b-latest",
+    "ministral-14b-2512",
+    "ministral-14b-latest",
+    "mistral-large-2411",
+    "pixtral-large-2411",
+    "pixtral-large-latest",
+    "mistral-large-pixtral-2411",
+    "devstral-small-2507",
+    "devstral-medium-2507",
+    "labs-devstral-small-2512",
+    "devstral-small-latest",
+    "voxtral-mini-2507",
+    "voxtral-mini-latest",
+    "voxtral-mini-2602",
+    "voxtral-mini-latest",
+    "voxtral-mini-2507",
+]
+
+```
+
+A list of models supported by Mistral AI
+see [Mistral AI docs](https://docs.mistral.ai/getting-started/models) for more information
+and send a GET HTTP request to "https://api.mistral.ai/v1/models" for a full list of model IDs.
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"),
+    model: str = "mistral-small-latest",
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: str | None = "https://api.mistral.ai/v1",
+    generation_kwargs: dict[str, Any] | None = None,
+    tools: ToolsType | None = None,
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates an instance of MistralChatGenerator. Unless specified otherwise in the `model`, this is for Mistral's
+`mistral-small-latest` model.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Mistral API key.
+- **model** (<code>str</code>) – The name of the Mistral chat completion model to use.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts StreamingChunk as an argument.
+- **api_base_url** (<code>str | None</code>) – The Mistral API Base url.
+  For more details, see Mistral [docs](https://docs.mistral.ai/api/).
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Other parameters to use for the model. These parameters are all sent directly to
+  the Mistral endpoint. See [Mistral API docs](https://docs.mistral.ai/api/) for more details.
+  Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+  Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+  considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+  comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+  events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+  If provided, the output will always be validated against this
+  format (unless the model returns a tool call).
+  For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+  Notes:
+  - For structured outputs with streaming,
+    the `response_format` must be a JSON schema and not a Pydantic model.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  Each tool should have a unique name.
+- **timeout** (<code>float | None</code>) – The timeout for the Mistral API call. If not set, it defaults to either the `OPENAI_TIMEOUT`
+  environment variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to contact OpenAI after an internal error.
+  If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/mongodb_atlas.md

@@ -0,0 +1,841 @@
+---
+title: "MongoDB Atlas"
+id: integrations-mongodb-atlas
+description: "MongoDB Atlas integration for Haystack"
+slug: "/integrations-mongodb-atlas"
+---
+
+
+## haystack_integrations.components.retrievers.mongodb_atlas.embedding_retriever
+
+### MongoDBAtlasEmbeddingRetriever
+
+Retrieves documents from the MongoDBAtlasDocumentStore by embedding similarity.
+
+The similarity is dependent on the vector_search_index used in the MongoDBAtlasDocumentStore and the chosen metric
+during the creation of the index (i.e. cosine, dot product, or euclidean). See MongoDBAtlasDocumentStore for more
+information.
+
+Usage example:
+
+```python
+import numpy as np
+from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore
+from haystack_integrations.components.retrievers.mongodb_atlas import MongoDBAtlasEmbeddingRetriever
+
+store = MongoDBAtlasDocumentStore(database_name="haystack_integration_test",
+                                  collection_name="test_embeddings_collection",
+                                  vector_search_index="cosine_index",
+                                  full_text_search_index="full_text_index")
+retriever = MongoDBAtlasEmbeddingRetriever(document_store=store)
+
+results = retriever.run(query_embedding=np.random.random(768).tolist())
+print(results["documents"])
+```
+
+The example above retrieves the 10 most similar documents to a random query embedding from the
+MongoDBAtlasDocumentStore. Note that dimensions of the query_embedding must match the dimensions of the embeddings
+stored in the MongoDBAtlasDocumentStore.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: MongoDBAtlasDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+)
+```
+
+Create the MongoDBAtlasDocumentStore component.
+
+**Parameters:**
+
+- **document_store** (<code>MongoDBAtlasDocumentStore</code>) – An instance of MongoDBAtlasDocumentStore.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. Make sure that the fields used in the filters are
+  included in the configuration of the `vector_search_index`. The configuration must be done manually
+  in the Web UI of MongoDB Atlas.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `MongoDBAtlasDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MongoDBAtlasEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>MongoDBAtlasEmbeddingRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the MongoDBAtlasDocumentStore, based on the provided embedding similarity.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given `query_embedding`
+
+#### run_async
+
+```python
+run_async(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the MongoDBAtlasDocumentStore, based on the provided embedding
+similarity.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given `query_embedding`
+
+## haystack_integrations.components.retrievers.mongodb_atlas.full_text_retriever
+
+### MongoDBAtlasFullTextRetriever
+
+Retrieves documents from the MongoDBAtlasDocumentStore by full-text search.
+
+The full-text search is dependent on the full_text_search_index used in the MongoDBAtlasDocumentStore.
+See MongoDBAtlasDocumentStore for more information.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore
+from haystack_integrations.components.retrievers.mongodb_atlas import MongoDBAtlasFullTextRetriever
+
+store = MongoDBAtlasDocumentStore(database_name="your_existing_db",
+                                  collection_name="your_existing_collection",
+                                  vector_search_index="your_existing_index",
+                                  full_text_search_index="your_existing_index")
+retriever = MongoDBAtlasFullTextRetriever(document_store=store)
+
+results = retriever.run(query="Lorem ipsum")
+print(results["documents"])
+```
+
+The example above retrieves the 10 most similar documents to the query "Lorem ipsum" from the
+MongoDBAtlasDocumentStore.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: MongoDBAtlasDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+)
+```
+
+**Parameters:**
+
+- **document_store** (<code>MongoDBAtlasDocumentStore</code>) – An instance of MongoDBAtlasDocumentStore.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. Make sure that the fields used in the filters are
+  included in the configuration of the `full_text_search_index`. The configuration must be done manually
+  in the Web UI of MongoDB Atlas.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of MongoDBAtlasDocumentStore.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MongoDBAtlasFullTextRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>MongoDBAtlasFullTextRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query: str | list[str],
+    fuzzy: dict[str, int] | None = None,
+    match_criteria: Literal["any", "all"] | None = None,
+    score: dict[str, dict] | None = None,
+    synonyms: str | None = None,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the MongoDBAtlasDocumentStore by full-text search.
+
+**Parameters:**
+
+- **query** (<code>str | list\[str\]</code>) – The query string or a list of query strings to search for.
+  If the query contains multiple terms, Atlas Search evaluates each term separately for matches.
+- **fuzzy** (<code>dict\[str, int\] | None</code>) – Enables finding strings similar to the search term(s).
+  Note, `fuzzy` cannot be used with `synonyms`. Configurable options include `maxEdits`, `prefixLength`,
+  and `maxExpansions`. For more details refer to MongoDB Atlas
+  [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **match_criteria** (<code>Literal['any', 'all'] | None</code>) – Defines how terms in the query are matched. Supported options are `"any"` and `"all"`.
+  For more details refer to MongoDB Atlas
+  [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **score** (<code>dict\[str, dict\] | None</code>) – Specifies the scoring method for matching results. Supported options include `boost`, `constant`,
+  and `function`. For more details refer to MongoDB Atlas
+  [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **synonyms** (<code>str | None</code>) – The name of the synonym mapping definition in the index. This value cannot be an empty string.
+  Note, `synonyms` can not be used with `fuzzy`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given `query`
+
+#### run_async
+
+```python
+run_async(
+    query: str | list[str],
+    fuzzy: dict[str, int] | None = None,
+    match_criteria: Literal["any", "all"] | None = None,
+    score: dict[str, dict] | None = None,
+    synonyms: str | None = None,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the MongoDBAtlasDocumentStore by full-text search.
+
+**Parameters:**
+
+- **query** (<code>str | list\[str\]</code>) – The query string or a list of query strings to search for.
+  If the query contains multiple terms, Atlas Search evaluates each term separately for matches.
+- **fuzzy** (<code>dict\[str, int\] | None</code>) – Enables finding strings similar to the search term(s).
+  Note, `fuzzy` cannot be used with `synonyms`. Configurable options include `maxEdits`, `prefixLength`,
+  and `maxExpansions`. For more details refer to MongoDB Atlas
+  [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **match_criteria** (<code>Literal['any', 'all'] | None</code>) – Defines how terms in the query are matched. Supported options are `"any"` and `"all"`.
+  For more details refer to MongoDB Atlas
+  [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **score** (<code>dict\[str, dict\] | None</code>) – Specifies the scoring method for matching results. Supported options include `boost`, `constant`,
+  and `function`. For more details refer to MongoDB Atlas
+  [documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/#fields).
+- **synonyms** (<code>str | None</code>) – The name of the synonym mapping definition in the index. This value cannot be an empty string.
+  Note, `synonyms` can not be used with `fuzzy`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return. Overrides the value specified at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of Documents most similar to the given `query`
+
+## haystack_integrations.document_stores.mongodb_atlas.document_store
+
+### MongoDBAtlasDocumentStore
+
+A MongoDBAtlasDocumentStore implementation that uses the
+[MongoDB Atlas](https://www.mongodb.com/atlas/database) service that is easy to deploy, operate, and scale.
+
+To connect to MongoDB Atlas, you need to provide a connection string in the format:
+`"mongodb+srv://{mongo_atlas_username}:{mongo_atlas_password}@{mongo_atlas_host}/?{mongo_atlas_params_string}"`.
+
+This connection string can be obtained on the MongoDB Atlas Dashboard by clicking on the `CONNECT` button, selecting
+Python as the driver, and copying the connection string. The connection string can be provided as an environment
+variable `MONGO_CONNECTION_STRING` or directly as a parameter to the `MongoDBAtlasDocumentStore` constructor.
+
+After providing the connection string, you'll need to specify the `database_name` and `collection_name` to use.
+Most likely that you'll create these via the MongoDB Atlas web UI but one can also create them via the MongoDB
+Python driver. Creating databases and collections is beyond the scope of MongoDBAtlasDocumentStore. The primary
+purpose of this document store is to read and write documents to an existing collection.
+
+Users must provide both a `vector_search_index` for vector search operations and a `full_text_search_index`
+for full-text search operations. The `vector_search_index` supports a chosen metric
+(e.g., cosine, dot product, or Euclidean), while the `full_text_search_index` enables efficient text-based searches.
+Both indexes can be created through the Atlas web UI.
+
+For more details on MongoDB Atlas, see the official
+MongoDB Atlas [documentation](https://www.mongodb.com/docs/atlas/getting-started/).
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore
+
+store = MongoDBAtlasDocumentStore(database_name="your_existing_db",
+                                  collection_name="your_existing_collection",
+                                  vector_search_index="your_existing_index",
+                                  full_text_search_index="your_existing_index")
+print(store.count_documents())
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    mongo_connection_string: Secret = Secret.from_env_var(
+        "MONGO_CONNECTION_STRING"
+    ),
+    database_name: str,
+    collection_name: str,
+    vector_search_index: str,
+    full_text_search_index: str,
+    embedding_field: str = "embedding",
+    content_field: str = "content"
+)
+```
+
+Creates a new MongoDBAtlasDocumentStore instance.
+
+**Parameters:**
+
+- **mongo_connection_string** (<code>Secret</code>) – MongoDB Atlas connection string in the format:
+  `"mongodb+srv://{mongo_atlas_username}:{mongo_atlas_password}@{mongo_atlas_host}/?{mongo_atlas_params_string}"`.
+  This can be obtained on the MongoDB Atlas Dashboard by clicking on the `CONNECT` button.
+  This value will be read automatically from the env var "MONGO_CONNECTION_STRING".
+- **database_name** (<code>str</code>) – Name of the database to use.
+- **collection_name** (<code>str</code>) – Name of the collection to use. To use this document store for embedding retrieval,
+  this collection needs to have a vector search index set up on the `embedding` field.
+- **vector_search_index** (<code>str</code>) – The name of the vector search index to use for vector search operations.
+  Create a vector_search_index in the Atlas web UI and specify the init params of MongoDBAtlasDocumentStore. For more details refer to MongoDB
+  Atlas [documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/create-index/#std-label-avs-create-index).
+- **full_text_search_index** (<code>str</code>) – The name of the search index to use for full-text search operations.
+  Create a full_text_search_index in the Atlas web UI and specify the init params of
+  MongoDBAtlasDocumentStore. For more details refer to MongoDB Atlas
+  [documentation](https://www.mongodb.com/docs/atlas/atlas-search/create-index/).
+- **embedding_field** (<code>str</code>) – The name of the field containing document embeddings. Default is "embedding".
+- **content_field** (<code>str</code>) – The name of the field containing the document content. Default is "content".
+  This field allows defining which field to load into the Haystack Document object as content.
+  It can be particularly useful when integrating with an existing collection for retrieval. We discourage
+  using this parameter when working with collections created by Haystack.
+
+**Raises:**
+
+- <code>ValueError</code> – If the collection name contains invalid characters.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MongoDBAtlasDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>MongoDBAtlasDocumentStore</code> – Deserialized component.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – The number of documents in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – The number of documents in the document store.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Applies a filter and counts the documents that matched it.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filter.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously applies a filter and counts the documents that matched it.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filter.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Applies a filter selecting documents and counts the unique values for each meta field of the matched documents.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+- **metadata_fields** (<code>list\[str\]</code>) – The metadata fields to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary where the keys are the metadata field names and the values are the count of unique
+  values.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously applies a filter selecting documents and counts the unique values for each meta field of the
+matched documents.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to the document list.
+- **metadata_fields** (<code>list\[str\]</code>) – The metadata fields to count unique values for.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary where the keys are the metadata field names and the values are the count of unique
+  values.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict]
+```
+
+Returns the metadata fields and their corresponding types.
+
+Since MongoDB is schemaless, this method samples the latest 50 documents to infer the fields and their types.
+
+**Returns:**
+
+- <code>dict\[str, dict\]</code> – A dictionary where the keys are the metadata field names and the values are dictionary with 'type'.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict]
+```
+
+Asynchronously returns the metadata fields and their corresponding types.
+
+Since MongoDB is schemaless, this method samples the latest 50 documents to infer the fields and their types.
+
+**Returns:**
+
+- <code>dict\[str, dict\]</code> – A dictionary where the keys are the metadata field names and the values are dictionary with 'type'.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+For a given metadata field, find its max and min value.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get the min and max values for.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with 'min' and 'max' keys.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously for a given metadata field, find its max and min value.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to get the min and max values for.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with 'min' and 'max' keys.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a field matching a search_term or all possible values if no search term is given.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to retrieve unique values for.
+- **search_term** (<code>str | None</code>) – The search term to filter values. Matches as a case-insensitive substring.
+- **from\_** (<code>int</code>) – The starting index for pagination.
+- **size** (<code>int</code>) – The number of values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing a list of unique values and the total count of unique values matching the
+  search term.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously retrieves unique values for a field matching a search_term or all possible values if no search
+term is given.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The metadata field to retrieve unique values for.
+- **search_term** (<code>str | None</code>) – The search term to filter values. Matches as a case-insensitive substring.
+- **from\_** (<code>int</code>) – The starting index for pagination.
+- **size** (<code>int</code>) – The number of values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing a list of unique values and the total count of unique values matching the
+  search term.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the Haystack [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – The filters to apply. It returns only the documents that match the filters.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the Haystack [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – The filters to apply. It returns only the documents that match the filters.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents into the MongoDB Atlas collection.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>DuplicateDocumentError</code> – If a document with the same ID already exists in the document store
+  and the policy is set to DuplicatePolicy.FAIL (or not specified).
+- <code>ValueError</code> – If the documents are not of type Document.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents into the MongoDB Atlas collection.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>DuplicateDocumentError</code> – If a document with the same ID already exists in the document store
+  and the policy is set to DuplicatePolicy.FAIL (or not specified).
+- <code>ValueError</code> – If the documents are not of type Document.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with a matching document_ids from the document store.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – the document ids to delete
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes all documents with a matching document_ids from the document store.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – the document ids to delete
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for deletion.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for deletion.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+#### delete_all_documents
+
+```python
+delete_all_documents(*, recreate_collection: bool = False) -> None
+```
+
+Deletes all documents in the document store.
+
+**Parameters:**
+
+- **recreate_collection** (<code>bool</code>) – If True, the collection will be dropped and recreated with the original
+  configuration and indexes. If False, all documents will be deleted while preserving the collection.
+  Recreating the collection is faster for very large collections.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async(*, recreate_collection: bool = False) -> None
+```
+
+Asynchronously deletes all documents in the document store.
+
+**Parameters:**
+
+- **recreate_collection** (<code>bool</code>) – If True, the collection will be dropped and recreated with the original
+  configuration and indexes. If False, all documents will be deleted while preserving the collection.
+  Recreating the collection is faster for very large collections.
+
+## haystack_integrations.document_stores.mongodb_atlas.filters

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/nvidia.md

@@ -0,0 +1,730 @@
+---
+title: "Nvidia"
+id: integrations-nvidia
+description: "Nvidia integration for Haystack"
+slug: "/integrations-nvidia"
+---
+
+
+## haystack_integrations.components.embedders.nvidia.document_embedder
+
+### NvidiaDocumentEmbedder
+
+A component for embedding documents using embedding models provided by [NVIDIA NIMs](https://ai.nvidia.com).
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.nvidia import NvidiaDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+text_embedder = NvidiaDocumentEmbedder(model="nvidia/nv-embedqa-e5-v5", api_url="https://integrate.api.nvidia.com/v1")
+# Components warm up automatically on first run.
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str | None = None,
+    api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+    api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+    prefix: str = "",
+    suffix: str = "",
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    truncate: EmbeddingTruncateMode | str | None = None,
+    timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaTextEmbedder component.
+
+**Parameters:**
+
+- **model** (<code>str | None</code>) – Embedding model to use.
+  If no specific model along with locally hosted API URL is provided,
+  the system defaults to the available model found using /models API.
+- **api_key** (<code>Secret | None</code>) – API key for the NVIDIA NIM.
+- **api_url** (<code>str</code>) – Custom API URL for the NVIDIA NIM.
+  Format for API URL is `http://host:port`
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **batch_size** (<code>int</code>) – Number of Documents to encode at once.
+  Cannot be greater than 50.
+- **progress_bar** (<code>bool</code>) – Whether to show a progress bar or not.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
+- **truncate** (<code>EmbeddingTruncateMode | str | None</code>) – Specifies how inputs longer than the maximum token length should be truncated.
+  If None the behavior is model-dependent, see the official documentation for more information.
+- **timeout** (<code>float | None</code>) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+  or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### default_model
+
+```python
+default_model() -> None
+```
+
+Set default model in local NIM mode.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### available_models
+
+```python
+available_models: list[Model]
+```
+
+Get a list of available models that work with NvidiaDocumentEmbedder.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NvidiaDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>NvidiaDocumentEmbedder</code> – The deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Embed a list of Documents.
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with the following keys and values:
+- `documents` - List of processed Documents with embeddings.
+- `meta` - Metadata on usage statistics, etc.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.nvidia.text_embedder
+
+### NvidiaTextEmbedder
+
+A component for embedding strings using embedding models provided by [NVIDIA NIMs](https://ai.nvidia.com).
+
+For models that differentiate between query and document inputs,
+this component embeds the input string as a query.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.nvidia import NvidiaTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = NvidiaTextEmbedder(model="nvidia/nv-embedqa-e5-v5", api_url="https://integrate.api.nvidia.com/v1")
+# Components warm up automatically on first run.
+
+print(text_embedder.run(text_to_embed))
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str | None = None,
+    api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+    api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+    prefix: str = "",
+    suffix: str = "",
+    truncate: EmbeddingTruncateMode | str | None = None,
+    timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaTextEmbedder component.
+
+**Parameters:**
+
+- **model** (<code>str | None</code>) – Embedding model to use.
+  If no specific model along with locally hosted API URL is provided,
+  the system defaults to the available model found using /models API.
+- **api_key** (<code>Secret | None</code>) – API key for the NVIDIA NIM.
+- **api_url** (<code>str</code>) – Custom API URL for the NVIDIA NIM.
+  Format for API URL is `http://host:port`
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **truncate** (<code>EmbeddingTruncateMode | str | None</code>) – Specifies how inputs longer that the maximum token length should be truncated.
+  If None the behavior is model-dependent, see the official documentation for more information.
+- **timeout** (<code>float | None</code>) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+  or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### default_model
+
+```python
+default_model() -> None
+```
+
+Set default model in local NIM mode.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### available_models
+
+```python
+available_models: list[Model]
+```
+
+Get a list of available models that work with NvidiaTextEmbedder.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NvidiaTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>NvidiaTextEmbedder</code> – The deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Embed a string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – The text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – A dictionary with the following keys and values:
+- `embedding` - Embedding of the text.
+- `meta` - Metadata on usage statistics, etc.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.
+- <code>ValueError</code> – If the input string is empty.
+
+## haystack_integrations.components.embedders.nvidia.truncate
+
+### EmbeddingTruncateMode
+
+Bases: <code>Enum</code>
+
+Specifies how inputs to the NVIDIA embedding components are truncated.
+
+If START, the input will be truncated from the start.
+If END, the input will be truncated from the end.
+If NONE, an error will be returned (if the input is too long).
+
+#### from_str
+
+```python
+from_str(string: str) -> EmbeddingTruncateMode
+```
+
+Create an truncate mode from a string.
+
+**Parameters:**
+
+- **string** (<code>str</code>) – String to convert.
+
+**Returns:**
+
+- <code>EmbeddingTruncateMode</code> – Truncate mode.
+
+## haystack_integrations.components.generators.nvidia.chat.chat_generator
+
+### NvidiaChatGenerator
+
+Bases: <code>OpenAIChatGenerator</code>
+
+Enables text generation using NVIDIA generative models.
+
+For supported models, see [NVIDIA Docs](https://build.nvidia.com/models).
+
+Users can pass any text generation parameters valid for the NVIDIA Chat Completion API
+directly to this component via the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage)
+
+For more details on the parameters supported by the NVIDIA API, refer to the
+[NVIDIA Docs](https://build.nvidia.com/models).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = NvidiaChatGenerator()
+response = client.run(messages)
+print(response)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("NVIDIA_API_KEY"),
+    model: str = "meta/llama-3.1-8b-instruct",
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: str | None = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+    generation_kwargs: dict[str, Any] | None = None,
+    tools: ToolsType | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of NvidiaChatGenerator.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The NVIDIA API key.
+- **model** (<code>str</code>) – The name of the NVIDIA chat completion model to use.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts StreamingChunk as an argument.
+- **api_base_url** (<code>str | None</code>) – The NVIDIA API Base url.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Other parameters to use for the model. These parameters are all sent directly to
+  the NVIDIA API endpoint. See [NVIDIA API docs](https://docs.nvcf.nvidia.com/ai/generative-models/)
+  for more details.
+  Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+  Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+  considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+  comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+  events as they become available, with the stream terminated by a data: [DONE] message.
+- `response_format`: For NVIDIA NIM servers, this parameter has limited support.
+  The basic JSON mode with `{"type": "json_object"}` is supported by compatible models, to produce
+  valid JSON output.
+  To generate structured JSON output, use the `response_format` parameter.
+  Example:
+  ```python
+  generation_kwargs={
+      "response_format": {
+          "type": "json_schema",
+          "json_schema": {
+              "name": "my_schema",
+              "schema": json_schema,
+          },
+      }
+  }
+  ```
+  For more details, see the [NVIDIA NIM documentation](https://docs.nvidia.com/nim/vision-language-models/latest/structured-generation.html).
+- **tools** (<code>ToolsType | None</code>) – A list of tools or a Toolset for which the model can prepare calls. This parameter can accept either a
+  list of `Tool` objects or a `Toolset` instance.
+- **timeout** (<code>float | None</code>) – The timeout for the NVIDIA API call.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to contact NVIDIA after an internal error.
+  If not set, it defaults to either the `NVIDIA_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+## haystack_integrations.components.generators.nvidia.generator
+
+### NvidiaGenerator
+
+Generates text using generative models hosted with [NVIDIA NIM](https://ai.nvidia.com).
+
+Available via the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover).
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.nvidia import NvidiaGenerator
+
+generator = NvidiaGenerator(
+    model="meta/llama3-8b-instruct",
+    model_arguments={
+        "temperature": 0.2,
+        "top_p": 0.7,
+        "max_tokens": 1024,
+    },
+)
+# Components warm up automatically on first run.
+
+result = generator.run(prompt="What is the answer?")
+print(result["replies"])
+print(result["meta"])
+print(result["usage"])
+```
+
+You need an NVIDIA API key for this component to work.
+
+#### __init__
+
+```python
+__init__(
+    model: str | None = None,
+    api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+    api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+    model_arguments: dict[str, Any] | None = None,
+    timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaGenerator component.
+
+**Parameters:**
+
+- **model** (<code>str | None</code>) – Name of the model to use for text generation.
+  See the [NVIDIA NIMs](https://ai.nvidia.com)
+  for more information on the supported models.
+  `Note`: If no specific model along with locally hosted API URL is provided,
+  the system defaults to the available model found using /models API.
+  Check supported models at [NVIDIA NIM](https://ai.nvidia.com).
+- **api_key** (<code>Secret | None</code>) – API key for the NVIDIA NIM. Set it as the `NVIDIA_API_KEY` environment
+  variable or pass it here.
+- **api_url** (<code>str</code>) – Custom API URL for the NVIDIA NIM.
+- **model_arguments** (<code>dict\[str, Any\] | None</code>) – Additional arguments to pass to the model provider. These arguments are
+  specific to a model.
+  Search your model in the [NVIDIA NIM](https://ai.nvidia.com)
+  to find the arguments it accepts.
+- **timeout** (<code>float | None</code>) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+  or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### default_model
+
+```python
+default_model() -> None
+```
+
+Set default model in local NIM mode.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### available_models
+
+```python
+available_models: list[Model]
+```
+
+Get a list of available models that work with ChatNVIDIA.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NvidiaGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>NvidiaGenerator</code> – Deserialized component.
+
+#### run
+
+```python
+run(prompt: str) -> dict[str, list[str] | list[dict[str, Any]]]
+```
+
+Queries the model with the provided prompt.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – Text to be sent to the generative model.
+
+**Returns:**
+
+- <code>dict\[str, list\[str\] | list\[dict\[str, Any\]\]\]</code> – A dictionary with the following keys:
+- `replies` - Replies generated by the model.
+- `meta` - Metadata for each reply.
+
+## haystack_integrations.components.rankers.nvidia.ranker
+
+### NvidiaRanker
+
+A component for ranking documents using ranking models provided by [NVIDIA NIMs](https://ai.nvidia.com).
+
+Usage example:
+
+```python
+from haystack_integrations.components.rankers.nvidia import NvidiaRanker
+from haystack import Document
+from haystack.utils import Secret
+
+ranker = NvidiaRanker(
+    model="nvidia/nv-rerankqa-mistral-4b-v3",
+    api_key=Secret.from_env_var("NVIDIA_API_KEY"),
+)
+# Components warm up automatically on first run.
+
+query = "What is the capital of Germany?"
+documents = [
+    Document(content="Berlin is the capital of Germany."),
+    Document(content="The capital of Germany is Berlin."),
+    Document(content="Germany's capital is Berlin."),
+]
+
+result = ranker.run(query, documents, top_k=2)
+print(result["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str | None = None,
+    truncate: RankerTruncateMode | str | None = None,
+    api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL),
+    api_key: Secret | None = Secret.from_env_var("NVIDIA_API_KEY"),
+    top_k: int = 5,
+    query_prefix: str = "",
+    document_prefix: str = "",
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    timeout: float | None = None,
+) -> None
+```
+
+Create a NvidiaRanker component.
+
+**Parameters:**
+
+- **model** (<code>str | None</code>) – Ranking model to use.
+- **truncate** (<code>RankerTruncateMode | str | None</code>) – Truncation strategy to use. Can be "NONE", "END", or RankerTruncateMode. Defaults to NIM's default.
+- **api_key** (<code>Secret | None</code>) – API key for the NVIDIA NIM.
+- **api_url** (<code>str</code>) – Custom API URL for the NVIDIA NIM.
+- **top_k** (<code>int</code>) – Number of documents to return.
+- **query_prefix** (<code>str</code>) – A string to add at the beginning of the query text before ranking.
+  Use it to prepend the text with an instruction, as required by reranking models like `bge`.
+- **document_prefix** (<code>str</code>) – A string to add at the beginning of each document before ranking. You can use it to prepend the document
+  with an instruction, as required by embedding models like `bge`.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of metadata fields to embed with the document.
+- **embedding_separator** (<code>str</code>) – Separator to concatenate metadata fields to the document.
+- **timeout** (<code>float | None</code>) – Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
+  or set to 60 by default.
+
+#### class_name
+
+```python
+class_name() -> str
+```
+
+Return the class name identifier for serialization.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the ranker to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary containing the ranker's attributes.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> NvidiaRanker
+```
+
+Deserialize the ranker from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – A dictionary containing the ranker's attributes.
+
+**Returns:**
+
+- <code>NvidiaRanker</code> – The deserialized ranker.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the ranker.
+
+**Raises:**
+
+- <code>ValueError</code> – If the API key is required for hosted NVIDIA NIMs.
+
+#### run
+
+```python
+run(
+    query: str, documents: list[Document], top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Rank a list of documents based on a given query.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The query to rank the documents against.
+- **documents** (<code>list\[Document\]</code>) – The list of documents to rank.
+- **top_k** (<code>int | None</code>) – The number of documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary containing the ranked documents.
+
+**Raises:**
+
+- <code>TypeError</code> – If the arguments are of the wrong type.
+
+## haystack_integrations.components.rankers.nvidia.truncate
+
+### RankerTruncateMode
+
+Bases: <code>str</code>, <code>Enum</code>
+
+Specifies how inputs to the NVIDIA ranker components are truncated.
+
+If NONE, the input will not be truncated and an error returned instead.
+If END, the input will be truncated from the end.
+
+#### from_str
+
+```python
+from_str(string: str) -> RankerTruncateMode
+```
+
+Create an truncate mode from a string.
+
+**Parameters:**
+
+- **string** (<code>str</code>) – String to convert.
+
+**Returns:**
+
+- <code>RankerTruncateMode</code> – Truncate mode.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/ollama.md

@@ -0,0 +1,486 @@
+---
+title: "Ollama"
+id: integrations-ollama
+description: "Ollama integration for Haystack"
+slug: "/integrations-ollama"
+---
+
+
+## haystack_integrations.components.embedders.ollama.document_embedder
+
+### OllamaDocumentEmbedder
+
+Computes the embeddings of a list of Documents and stores the obtained vectors in each Document's embedding field.
+
+It uses embedding models compatible with the Ollama Library.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.ollama import OllamaDocumentEmbedder
+
+doc = Document(content="What do llamas say once you have thanked them? No probllama!")
+document_embedder = OllamaDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str = "nomic-embed-text",
+    url: str = "http://localhost:11434",
+    generation_kwargs: dict[str, Any] | None = None,
+    timeout: int = 120,
+    keep_alive: float | str | None = None,
+    prefix: str = "",
+    suffix: str = "",
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    batch_size: int = 32,
+) -> None
+```
+
+Create a new OllamaDocumentEmbedder instance.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the model to use. The model should be available in the running Ollama instance.
+- **url** (<code>str</code>) – The URL of a running Ollama instance.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature, top_p, and others.
+  See the available arguments in
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **timeout** (<code>int</code>) – The number of seconds before throwing a timeout error from the Ollama API.
+- **keep_alive** (<code>float | str | None</code>) – The option that controls how long the model will stay loaded into memory following the request.
+  If not set, it will use the default value from the Ollama (5 minutes).
+  The value can be set to:
+- a duration string (such as "10m" or "24h")
+- a number in seconds (such as 3600)
+- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m")
+- '0' which will unload the model immediately after generating a response.
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **progress_bar** (<code>bool</code>) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the metadata fields to the document text.
+- **batch_size** (<code>int</code>) – Number of documents to process at once.
+
+#### run
+
+```python
+run(
+    documents: list[Document], generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Runs an Ollama Model to compute embeddings of the provided documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to be converted to an embedding.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+  top_p, etc. See the
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with the following keys:
+- `documents`: Documents with embedding information attached
+- `meta`: The metadata collected during the embedding process
+
+#### run_async
+
+```python
+run_async(
+    documents: list[Document], generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Asynchronously run an Ollama Model to compute embeddings of the provided documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to be converted to an embedding.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+  top_p, etc. See the
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with the following keys:
+- `documents`: Documents with embedding information attached
+- `meta`: The metadata collected during the embedding process
+
+## haystack_integrations.components.embedders.ollama.text_embedder
+
+### OllamaTextEmbedder
+
+Computes the embeddings of a list of Documents and stores the obtained vectors in each Document's embedding field.
+
+It uses embedding models compatible with the Ollama Library.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.ollama import OllamaTextEmbedder
+
+embedder = OllamaTextEmbedder()
+result = embedder.run(text="What do llamas say once you have thanked them? No probllama!")
+print(result['embedding'])
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str = "nomic-embed-text",
+    url: str = "http://localhost:11434",
+    generation_kwargs: dict[str, Any] | None = None,
+    timeout: int = 120,
+    keep_alive: float | str | None = None,
+) -> None
+```
+
+Create a new OllamaTextEmbedder instance.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the model to use. The model should be available in the running Ollama instance.
+- **url** (<code>str</code>) – The URL of a running Ollama instance.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+  top_p, and others. See the available arguments in
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **timeout** (<code>int</code>) – The number of seconds before throwing a timeout error from the Ollama API.
+- **keep_alive** (<code>float | str | None</code>) – The option that controls how long the model will stay loaded into memory following the request.
+  If not set, it will use the default value from the Ollama (5 minutes).
+  The value can be set to:
+- a duration string (such as "10m" or "24h")
+- a number in seconds (such as 3600)
+- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m")
+- '0' which will unload the model immediately after generating a response.
+
+#### run
+
+```python
+run(
+    text: str, generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Runs an Ollama Model to compute embeddings of the provided text.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to be converted to an embedding.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+  top_p, etc. See the
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+
+**Returns:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – A dictionary with the following keys:
+- `embedding`: The computed embeddings
+- `meta`: The metadata collected during the embedding process
+
+#### run_async
+
+```python
+run_async(
+    text: str, generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Asynchronously run an Ollama Model to compute embeddings of the provided text.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to be converted to an embedding.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+  top_p, etc. See the
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+
+**Returns:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – A dictionary with the following keys:
+- `embedding`: The computed embeddings
+- `meta`: The metadata collected during the embedding process
+
+## haystack_integrations.components.generators.ollama.chat.chat_generator
+
+### OllamaChatGenerator
+
+Haystack Chat Generator for models served with Ollama (https://ollama.ai).
+
+Supports streaming, tool calls, reasoning, and structured outputs.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.ollama.chat import OllamaChatGenerator
+from haystack.dataclasses import ChatMessage
+
+llm = OllamaChatGenerator(model="qwen3:0.6b")
+result = llm.run(messages=[ChatMessage.from_user("What is the capital of France?")])
+print(result)
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str = "qwen3:0.6b",
+    url: str = "http://localhost:11434",
+    generation_kwargs: dict[str, Any] | None = None,
+    timeout: int = 120,
+    max_retries: int = 0,
+    keep_alive: float | str | None = None,
+    streaming_callback: Callable[[StreamingChunk], None] | None = None,
+    tools: ToolsType | None = None,
+    response_format: None | Literal["json"] | JsonSchemaValue | None = None,
+    think: bool | Literal["low", "medium", "high"] = False,
+) -> None
+```
+
+Create a new OllamaChatGenerator instance.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the model to use. The model must already be present (pulled) in the running Ollama instance.
+- **url** (<code>str</code>) – The base URL of the Ollama server (default "http://localhost:11434").
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+  top_p, and others. See the available arguments in
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **timeout** (<code>int</code>) – The number of seconds before throwing a timeout error from the Ollama API.
+- **max_retries** (<code>int</code>) – Maximum number of retries to attempt for failed requests (HTTP 429, 5xx, connection/timeout errors).
+  Uses exponential backoff between attempts. Set to 0 (default) to disable retries.
+- **think** (<code>bool | Literal['low', 'medium', 'high']</code>) – If True, the model will "think" before producing a response.
+  Only [thinking models](https://ollama.com/search?c=thinking) support this feature.
+  Some models like gpt-oss support different levels of thinking: "low", "medium", "high".
+  The intermediate "thinking" output can be found by inspecting the `reasoning` property of the returned
+  `ChatMessage`.
+- **keep_alive** (<code>float | str | None</code>) – The option that controls how long the model will stay loaded into memory following the request.
+  If not set, it will use the default value from the Ollama (5 minutes).
+  The value can be set to:
+- a duration string (such as "10m" or "24h")
+- a number in seconds (such as 3600)
+- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m")
+- '0' which will unload the model immediately after generating a response.
+- **streaming_callback** (<code>Callable\\[[StreamingChunk\], None\] | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts StreamingChunk as an argument.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  Each tool should have a unique name. Not all models support tools. For a list of models compatible
+  with tools, see the [models page](https://ollama.com/search?c=tools).
+- **response_format** (<code>None | Literal['json'] | JsonSchemaValue | None</code>) – The format for structured model outputs. The value can be:
+- None: No specific structure or format is applied to the response. The response is returned as-is.
+- "json": The response is formatted as a JSON object.
+- JSON Schema: The response is formatted as a JSON object
+  that adheres to the specified JSON Schema. (needs Ollama ≥ 0.1.34)
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OllamaChatGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OllamaChatGenerator</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage],
+    generation_kwargs: dict[str, Any] | None = None,
+    tools: ToolsType | None = None,
+    *,
+    streaming_callback: StreamingCallbackT | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Runs an Ollama Model on a given chat history.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Per-call overrides for Ollama inference options.
+  These are merged on top of the instance-level `generation_kwargs`.
+  Optional arguments to pass to the Ollama generation endpoint, such as temperature, top_p, etc. See the
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter set during component initialization.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callable to receive `StreamingChunk` objects as they
+  arrive. Supplying a callback (here or in the constructor) switches
+  the component into streaming mode.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `replies`: A list of ChatMessages containing the model's response
+
+#### run_async
+
+```python
+run_async(
+    messages: list[ChatMessage],
+    generation_kwargs: dict[str, Any] | None = None,
+    tools: ToolsType | None = None,
+    *,
+    streaming_callback: StreamingCallbackT | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Async version of run. Runs an Ollama Model on a given chat history.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Per-call overrides for Ollama inference options.
+  These are merged on top of the instance-level `generation_kwargs`.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter set during component initialization.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callable to receive `StreamingChunk` objects as they arrive.
+  Supplying a callback switches the component into streaming mode.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `replies`: A list of ChatMessages containing the model's response
+
+## haystack_integrations.components.generators.ollama.generator
+
+### OllamaGenerator
+
+Provides an interface to generate text using an LLM running on Ollama.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.ollama import OllamaGenerator
+
+generator = OllamaGenerator(model="zephyr",
+                            url = "http://localhost:11434",
+                            generation_kwargs={
+                            "num_predict": 100,
+                            "temperature": 0.9,
+                            })
+
+print(generator.run("Who is the best American actor?"))
+```
+
+#### __init__
+
+```python
+__init__(
+    model: str = "orca-mini",
+    url: str = "http://localhost:11434",
+    generation_kwargs: dict[str, Any] | None = None,
+    system_prompt: str | None = None,
+    template: str | None = None,
+    raw: bool = False,
+    timeout: int = 120,
+    keep_alive: float | str | None = None,
+    streaming_callback: Callable[[StreamingChunk], None] | None = None,
+) -> None
+```
+
+Create a new OllamaGenerator instance.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the model to use. The model should be available in the running Ollama instance.
+- **url** (<code>str</code>) – The URL of a running Ollama instance.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+  top_p, and others. See the available arguments in
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **system_prompt** (<code>str | None</code>) – Optional system message (overrides what is defined in the Ollama Modelfile).
+- **template** (<code>str | None</code>) – The full prompt template (overrides what is defined in the Ollama Modelfile).
+- **raw** (<code>bool</code>) – If True, no formatting will be applied to the prompt. You may choose to use the raw parameter
+  if you are specifying a full templated prompt in your API request.
+- **timeout** (<code>int</code>) – The number of seconds before throwing a timeout error from the Ollama API.
+- **streaming_callback** (<code>Callable\\[[StreamingChunk\], None\] | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts StreamingChunk as an argument.
+- **keep_alive** (<code>float | str | None</code>) – The option that controls how long the model will stay loaded into memory following the request.
+  If not set, it will use the default value from the Ollama (5 minutes).
+  The value can be set to:
+- a duration string (such as "10m" or "24h")
+- a number in seconds (such as 3600)
+- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m")
+- '0' which will unload the model immediately after generating a response.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OllamaGenerator
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OllamaGenerator</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    prompt: str,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    streaming_callback: Callable[[StreamingChunk], None] | None = None
+) -> dict[str, list[Any]]
+```
+
+Runs an Ollama Model on the given prompt.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – The prompt to generate a response for.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Optional arguments to pass to the Ollama generation endpoint, such as temperature,
+  top_p, and others. See the available arguments in
+  [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
+- **streaming_callback** (<code>Callable\\[[StreamingChunk\], None\] | None</code>) – A callback function that is called when a new token is received from the stream.
+
+**Returns:**
+
+- <code>dict\[str, list\[Any\]\]</code> – A dictionary with the following keys:
+- `replies`: The responses from the model
+- `meta`: The metadata collected during the run

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/openrouter.md

@@ -0,0 +1,129 @@
+---
+title: "OpenRouter"
+id: integrations-openrouter
+description: "OpenRouter integration for Haystack"
+slug: "/integrations-openrouter"
+---
+
+<a id="haystack_integrations.components.generators.openrouter.chat.chat_generator"></a>
+
+## Module haystack\_integrations.components.generators.openrouter.chat.chat\_generator
+
+<a id="haystack_integrations.components.generators.openrouter.chat.chat_generator.OpenRouterChatGenerator"></a>
+
+### OpenRouterChatGenerator
+
+Enables text generation using OpenRouter generative models.
+For supported models, see [OpenRouter docs](https://openrouter.ai/models).
+
+Users can pass any text generation parameters valid for the OpenRouter chat completion API
+directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+Key Features and Compatibility:
+- **Primary Compatibility**: Designed to work seamlessly with the OpenRouter chat completion endpoint.
+- **Streaming Support**: Supports streaming responses from the OpenRouter chat completion endpoint.
+- **Customizability**: Supports all parameters supported by the OpenRouter chat completion endpoint.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage)
+
+For more details on the parameters supported by the OpenRouter API, refer to the
+[OpenRouter API Docs](https://openrouter.ai/docs/quickstart).
+
+Usage example:
+```python
+from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = OpenRouterChatGenerator()
+response = client.run(messages)
+print(response)
+
+>>{'replies': [ChatMessage(_content='Natural Language Processing (NLP) is a branch of artificial intelligence
+>>that focuses on enabling computers to understand, interpret, and generate human language in a way that is
+>>meaningful and useful.', _role=<ChatRole.ASSISTANT: 'assistant'>, _name=None,
+>>_meta={'model': 'openai/gpt-5-mini', 'index': 0, 'finish_reason': 'stop',
+>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]}
+```
+
+<a id="haystack_integrations.components.generators.openrouter.chat.chat_generator.OpenRouterChatGenerator.__init__"></a>
+
+#### OpenRouterChatGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+             api_key: Secret = Secret.from_env_var("OPENROUTER_API_KEY"),
+             model: str = "openai/gpt-5-mini",
+             streaming_callback: StreamingCallbackT | None = None,
+             api_base_url: str | None = "https://openrouter.ai/api/v1",
+             generation_kwargs: dict[str, Any] | None = None,
+             tools: ToolsType | None = None,
+             timeout: float | None = None,
+             extra_headers: dict[str, Any] | None = None,
+             max_retries: int | None = None,
+             http_client_kwargs: dict[str, Any] | None = None)
+```
+
+Creates an instance of OpenRouterChatGenerator. Unless specified otherwise,
+
+the default model is `openai/gpt-5-mini`.
+
+**Arguments**:
+
+- `api_key`: The OpenRouter API key.
+- `model`: The name of the OpenRouter chat completion model to use.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+The callback function accepts StreamingChunk as an argument.
+- `api_base_url`: The OpenRouter API Base url.
+For more details, see OpenRouter [docs](https://openrouter.ai/docs/quickstart).
+- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to
+the OpenRouter endpoint. See [OpenRouter API docs](https://openrouter.ai/docs/quickstart) for more details.
+Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+    Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+    considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+    comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+    events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+    If provided, the output will always be validated against this
+    format (unless the model returns a tool call).
+    For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+    Notes:
+    - This parameter accepts Pydantic models and JSON schemas for latest models starting from GPT-4o.
+    - For structured outputs with streaming,
+      the `response_format` must be a JSON schema and not a Pydantic model.
+- `tools`: A list of tools or a Toolset for which the model can prepare calls. This parameter can accept either a
+list of `Tool` objects or a `Toolset` instance.
+- `timeout`: The timeout for the OpenRouter API call.
+- `extra_headers`: Additional HTTP headers to include in requests to the OpenRouter API.
+This can be useful for adding site URL or title for rankings on openrouter.ai
+For more details, see OpenRouter [docs](https://openrouter.ai/docs/quickstart).
+- `max_retries`: Maximum number of retries to contact OpenAI after an internal error.
+If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`).
+
+<a id="haystack_integrations.components.generators.openrouter.chat.chat_generator.OpenRouterChatGenerator.to_dict"></a>
+
+#### OpenRouterChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns**:
+
+The serialized component as a dictionary.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/optimum.md

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

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/oracle.md

@@ -0,0 +1,326 @@
+---
+title: "Oracle AI Vector Search"
+id: integrations-oracle
+description: "Oracle AI Vector Search integration for Haystack"
+slug: "/integrations-oracle"
+---
+
+
+## haystack_integrations.components.retrievers.oracle.embedding_retriever
+
+### OracleEmbeddingRetriever
+
+Retrieves documents from an OracleDocumentStore using vector similarity.
+
+Use inside a Haystack pipeline after a text embedder::
+
+```
+pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
+pipeline.add_component("retriever", OracleEmbeddingRetriever(
+    document_store=store, top_k=5
+))
+pipeline.connect("embedder.embedding", "retriever.query_embedding")
+```
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by vector similarity.
+
+Args:
+query_embedding: Dense float vector from an embedder component.
+filters: Runtime filters, merged with constructor filters according to filter_policy.
+top_k: Override the constructor top_k for this call.
+
+Returns:
+`{"documents": [Document, ...]}`
+
+#### run_async
+
+```python
+run_async(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Async variant of :meth:`run`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OracleEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OracleEmbeddingRetriever</code> – Deserialized component.
+
+## haystack_integrations.document_stores.oracle.document_store
+
+### OracleConnectionConfig
+
+Connection parameters for Oracle Database.
+
+Supports both thin (direct TCP) and thick (wallet / ADB-S) modes.
+Thin mode requires no Oracle Instant Client; thick mode is activated
+automatically when *wallet_location* is provided.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OracleConnectionConfig
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OracleConnectionConfig</code> – Deserialized component.
+
+### OracleDocumentStore
+
+Haystack DocumentStore backed by Oracle AI Vector Search.
+
+Requires Oracle Database 23ai or later (for VECTOR data type and
+IF NOT EXISTS DDL support).
+
+Usage::
+
+```
+from haystack.utils import Secret
+from haystack_integrations.document_stores.oracle import (
+    OracleDocumentStore, OracleConnectionConfig,
+)
+
+store = OracleDocumentStore(
+    connection_config=OracleConnectionConfig(
+        user=Secret.from_env_var("ORACLE_USER"),
+        password=Secret.from_env_var("ORACLE_PASSWORD"),
+        dsn=Secret.from_env_var("ORACLE_DSN"),
+    ),
+    embedding_dim=1536,
+)
+```
+
+#### create_hnsw_index
+
+```python
+create_hnsw_index() -> None
+```
+
+Create an HNSW vector index on the embedding column.
+
+Safe to call multiple times — uses IF NOT EXISTS.
+
+#### create_hnsw_index_async
+
+```python
+create_hnsw_index_async() -> None
+```
+
+Async variant of create_hnsw_index.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>DuplicateDocumentError</code> – If a document with the same id already exists in the document store
+  and the policy is set to `DuplicatePolicy.FAIL` or `DuplicatePolicy.NONE`.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>DuplicateDocumentError</code> – If a document with the same id already exists in the document store
+  and the policy is set to `DuplicatePolicy.FAIL` or `DuplicatePolicy.NONE`.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – the document ids to delete
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – the document ids to delete
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – Number of documents in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – Number of documents in the document store.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OracleDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OracleDocumentStore</code> – Deserialized component.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/paddleocr.md

@@ -0,0 +1,198 @@
+---
+title: "PaddleOCR"
+id: integrations-paddleocr
+description: "PaddleOCR integration for Haystack"
+slug: "/integrations-paddleocr"
+---
+
+<a id="haystack_integrations.components.converters.paddleocr.paddleocr_vl_document_converter"></a>
+
+## Module haystack\_integrations.components.converters.paddleocr.paddleocr\_vl\_document\_converter
+
+<a id="haystack_integrations.components.converters.paddleocr.paddleocr_vl_document_converter.PaddleOCRVLDocumentConverter"></a>
+
+### PaddleOCRVLDocumentConverter
+
+This component extracts text from documents using PaddleOCR's large model
+document parsing API.
+
+PaddleOCR-VL is used behind the scenes. For more information, please
+refer to:
+https://www.paddleocr.ai/latest/en/version3.x/algorithm/PaddleOCR-VL/PaddleOCR-VL.html
+
+**Usage Example:**
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.converters.paddleocr import (
+    PaddleOCRVLDocumentConverter,
+)
+
+converter = PaddleOCRVLDocumentConverter(
+    api_url="http://xxxxx.aistudio-app.com/layout-parsing",
+    access_token=Secret.from_env_var("AISTUDIO_ACCESS_TOKEN"),
+)
+
+result = converter.run(sources=["sample.pdf"])
+
+documents = result["documents"]
+raw_responses = result["raw_paddleocr_responses"]
+```
+
+<a id="haystack_integrations.components.converters.paddleocr.paddleocr_vl_document_converter.PaddleOCRVLDocumentConverter.__init__"></a>
+
+#### PaddleOCRVLDocumentConverter.\_\_init\_\_
+
+```python
+def __init__(
+        *,
+        api_url: str,
+        access_token: Secret = Secret.from_env_var("AISTUDIO_ACCESS_TOKEN"),
+        file_type: FileTypeInput = None,
+        use_doc_orientation_classify: bool | None = False,
+        use_doc_unwarping: bool | None = False,
+        use_layout_detection: bool | None = None,
+        use_chart_recognition: bool | None = None,
+        use_seal_recognition: bool | None = None,
+        use_ocr_for_image_block: bool | None = None,
+        layout_threshold: float | dict | None = None,
+        layout_nms: bool | None = None,
+        layout_unclip_ratio: float | tuple[float, float] | dict | None = None,
+        layout_merge_bboxes_mode: str | dict | None = None,
+        layout_shape_mode: str | None = None,
+        prompt_label: str | None = None,
+        format_block_content: bool | None = None,
+        repetition_penalty: float | None = None,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        min_pixels: int | None = None,
+        max_pixels: int | None = None,
+        max_new_tokens: int | None = None,
+        merge_layout_blocks: bool | None = None,
+        markdown_ignore_labels: list[str] | None = None,
+        vlm_extra_args: dict | None = None,
+        prettify_markdown: bool | None = None,
+        show_formula_number: bool | None = None,
+        restructure_pages: bool | None = None,
+        merge_tables: bool | None = None,
+        relevel_titles: bool | None = None,
+        visualize: bool | None = None,
+        additional_params: dict[str, Any] | None = None)
+```
+
+Create a `PaddleOCRVLDocumentConverter` component.
+
+**Arguments**:
+
+- `api_url`: API URL. To obtain the API URL, visit the [PaddleOCR official
+website](https://aistudio.baidu.com/paddleocr), click the
+**API** button, choose the example code for PaddleOCR-VL, and copy
+the `API_URL`.
+- `access_token`: AI Studio access token. You can obtain it from [this
+page](https://aistudio.baidu.com/account/accessToken).
+- `file_type`: File type. Can be "pdf" for PDF files, "image" for
+image files, or `None` for auto-detection. If not specified, the
+file type will be inferred from the file extension.
+- `use_doc_orientation_classify`: Whether to enable the document orientation classification
+function. Enabling this feature allows the input image to be
+automatically rotated to the correct orientation.
+- `use_doc_unwarping`: Whether to enable the text image unwarping function. Enabling
+this feature allows automatic correction of distorted text images.
+- `use_layout_detection`: Whether to enable the layout detection function.
+- `use_chart_recognition`: Whether to enable the chart recognition function.
+- `use_seal_recognition`: Whether to enable the seal recognition function.
+- `use_ocr_for_image_block`: Whether to recognize text in image blocks.
+- `layout_threshold`: Layout detection threshold. Can be a float or a dict with
+page-specific thresholds.
+- `layout_nms`: Whether to perform NMS (Non-Maximum Suppression) on layout
+detection results.
+- `layout_unclip_ratio`: Layout unclip ratio. Can be a float, a tuple of (min, max), or a
+dict with page-specific values.
+- `layout_merge_bboxes_mode`: Layout merge bounding boxes mode. Can be a string or a dict.
+- `layout_shape_mode`: Layout shape mode.
+- `prompt_label`: Prompt type for the VLM. Possible values are "ocr", "formula",
+"table", "chart", "seal", and "spotting".
+- `format_block_content`: Whether to format block content.
+- `repetition_penalty`: Repetition penalty parameter used in VLM sampling.
+- `temperature`: Temperature parameter used in VLM sampling.
+- `top_p`: Top-p parameter used in VLM sampling.
+- `min_pixels`: Minimum number of pixels allowed during VLM preprocessing.
+- `max_pixels`: Maximum number of pixels allowed during VLM preprocessing.
+- `max_new_tokens`: Maximum number of tokens generated by the VLM.
+- `merge_layout_blocks`: Whether to merge the layout detection boxes for cross-column or
+staggered top and bottom columns.
+- `markdown_ignore_labels`: Layout labels that need to be ignored in Markdown.
+- `vlm_extra_args`: Additional configuration parameters for the VLM.
+- `prettify_markdown`: Whether to prettify the output Markdown text.
+- `show_formula_number`: Whether to include formula numbers in the output markdown text.
+- `restructure_pages`: Whether to restructure results across multiple pages.
+- `merge_tables`: Whether to merge tables across pages.
+- `relevel_titles`: Whether to relevel titles.
+- `visualize`: Whether to return visualization results.
+- `additional_params`: Additional parameters for calling the PaddleOCR API.
+
+<a id="haystack_integrations.components.converters.paddleocr.paddleocr_vl_document_converter.PaddleOCRVLDocumentConverter.to_dict"></a>
+
+#### PaddleOCRVLDocumentConverter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.converters.paddleocr.paddleocr_vl_document_converter.PaddleOCRVLDocumentConverter.from_dict"></a>
+
+#### PaddleOCRVLDocumentConverter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "PaddleOCRVLDocumentConverter"
+```
+
+Deserialize the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.converters.paddleocr.paddleocr_vl_document_converter.PaddleOCRVLDocumentConverter.run"></a>
+
+#### PaddleOCRVLDocumentConverter.run
+
+```python
+@component.output_types(documents=list[Document],
+                        raw_paddleocr_responses=list[dict[str, Any]])
+def run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, Any]
+```
+
+Convert image or PDF files to Documents.
+
+**Arguments**:
+
+- `sources`: List of image or PDF file paths or ByteStream objects.
+- `meta`: Optional metadata to attach to the Documents.
+This value can be either a list of dictionaries or a single
+dictionary. If it's a single dictionary, its content is added to
+the metadata of all produced Documents. If it's a list, the length
+of the list must match the number of sources, because the two
+lists will be zipped. If `sources` contains ByteStream objects,
+their `meta` will be added to the output Documents.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `documents`: A list of created Documents.
+- `raw_paddleocr_responses`: A list of raw PaddleOCR API responses.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/pgvector.md

@@ -0,0 +1,890 @@
+---
+title: "Pgvector"
+id: integrations-pgvector
+description: "Pgvector integration for Haystack"
+slug: "/integrations-pgvector"
+---
+
+
+## haystack_integrations.components.retrievers.pgvector.embedding_retriever
+
+### PgvectorEmbeddingRetriever
+
+Retrieves documents from the `PgvectorDocumentStore`, based on their dense embeddings.
+
+Example usage:
+
+```python
+from haystack.document_stores import DuplicatePolicy
+from haystack import Document, Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack_integrations.components.retrievers.pgvector import PgvectorEmbeddingRetriever
+
+# Set an environment variable `PG_CONN_STR` with the connection string to your PostgreSQL database.
+# e.g., "postgresql://USER:PASSWORD@HOST:PORT/DB_NAME"
+
+document_store = PgvectorDocumentStore(
+    embedding_dimension=768,
+    vector_function="cosine_similarity",
+    recreate_table=True,
+)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+             Document(content="Elephants have been observed to behave in a way that indicates..."),
+             Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", PgvectorEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+res = query_pipeline.run({"text_embedder": {"text": query}})
+
+assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: PgvectorDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    vector_function: (
+        Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+    ) = None,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+)
+```
+
+**Parameters:**
+
+- **document_store** (<code>PgvectorDocumentStore</code>) – An instance of `PgvectorDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – The similarity function to use when searching for similar embeddings.
+  Defaults to the one set in the `document_store` instance.
+  `"cosine_similarity"` and `"inner_product"` are similarity functions and
+  higher scores indicate greater similarity between the documents.
+  `"l2_distance"` returns the straight-line distance between vectors,
+  and the most similar documents are the ones with the smallest score.
+  **Important**: if the document store is using the `"hnsw"` search strategy, the vector function
+  should match the one utilized during index creation to take advantage of the index.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `PgvectorDocumentStore` or if `vector_function`
+  is not one of the valid options.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PgvectorEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PgvectorEmbeddingRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+    vector_function: (
+        Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+    ) = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `PgvectorDocumentStore`, based on their embeddings.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – Maximum number of Documents to return.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – The similarity function to use when searching for similar embeddings.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of `Document`s that are similar to `query_embedding`.
+
+#### run_async
+
+```python
+run_async(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+    vector_function: (
+        Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+    ) = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the `PgvectorDocumentStore`, based on their embeddings.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – Maximum number of Documents to return.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – The similarity function to use when searching for similar embeddings.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of `Document`s that are similar to `query_embedding`.
+
+## haystack_integrations.components.retrievers.pgvector.keyword_retriever
+
+### PgvectorKeywordRetriever
+
+Retrieve documents from the `PgvectorDocumentStore`, based on keywords.
+
+To rank the documents, the `ts_rank_cd` function of PostgreSQL is used.
+It considers how often the query terms appear in the document, how close together the terms are in the document,
+and how important is the part of the document where they occur.
+For more details, see
+[Postgres documentation](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-RANKING).
+
+Usage example:
+
+````python
+from haystack.document_stores import DuplicatePolicy
+from haystack import Document
+
+from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+from haystack_integrations.components.retrievers.pgvector import PgvectorKeywordRetriever
+
+# Set an environment variable `PG_CONN_STR` with the connection string to your PostgreSQL database.
+# e.g., "postgresql://USER:PASSWORD@HOST:PORT/DB_NAME"
+
+document_store = PgvectorDocumentStore(language="english", recreate_table=True)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+    Document(content="Elephants have been observed to behave in a way that indicates..."),
+    Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+retriever = PgvectorKeywordRetriever(document_store=document_store)
+
+result = retriever.run(query="languages")
+
+assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today."
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: PgvectorDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+)
+````
+
+**Parameters:**
+
+- **document_store** (<code>PgvectorDocumentStore</code>) – An instance of `PgvectorDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `PgvectorDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PgvectorKeywordRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PgvectorKeywordRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `PgvectorDocumentStore`, based on keywords.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – String to search in `Document`s' content.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – Maximum number of Documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of `Document`s that match the query.
+
+#### run_async
+
+```python
+run_async(
+    query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the `PgvectorDocumentStore`, based on keywords.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – String to search in `Document`s' content.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – Maximum number of Documents to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: List of `Document`s that match the query.
+
+## haystack_integrations.document_stores.pgvector.document_store
+
+### PgvectorDocumentStore
+
+A Document Store using PostgreSQL with the [pgvector extension](https://github.com/pgvector/pgvector) installed.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    connection_string: Secret = Secret.from_env_var("PG_CONN_STR"),
+    create_extension: bool = True,
+    schema_name: str = "public",
+    table_name: str = "haystack_documents",
+    language: str = "english",
+    embedding_dimension: int = 768,
+    vector_type: Literal["vector", "halfvec"] = "vector",
+    vector_function: Literal[
+        "cosine_similarity", "inner_product", "l2_distance"
+    ] = "cosine_similarity",
+    recreate_table: bool = False,
+    search_strategy: Literal[
+        "exact_nearest_neighbor", "hnsw"
+    ] = "exact_nearest_neighbor",
+    hnsw_recreate_index_if_exists: bool = False,
+    hnsw_index_creation_kwargs: dict[str, int] | None = None,
+    hnsw_index_name: str = "haystack_hnsw_index",
+    hnsw_ef_search: int | None = None,
+    keyword_index_name: str = "haystack_keyword_index"
+)
+```
+
+Creates a new PgvectorDocumentStore instance.
+It is meant to be connected to a PostgreSQL database with the pgvector extension installed.
+A specific table to store Haystack documents will be created if it doesn't exist yet.
+
+**Parameters:**
+
+- **connection_string** (<code>Secret</code>) – The connection string to use to connect to the PostgreSQL database, defined as an
+  environment variable. Supported formats:
+- URI, e.g. `PG_CONN_STR="postgresql://USER:PASSWORD@HOST:PORT/DB_NAME"` (use percent-encoding for special
+  characters)
+- keyword/value format, e.g. `PG_CONN_STR="host=HOST port=PORT dbname=DBNAME user=USER password=PASSWORD"`
+  See [PostgreSQL Documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING)
+  for more details.
+- **create_extension** (<code>bool</code>) – Whether to create the pgvector extension if it doesn't exist.
+  Set this to `True` (default) to automatically create the extension if it is missing.
+  Creating the extension may require superuser privileges.
+  If set to `False`, ensure the extension is already installed; otherwise, an error will be raised.
+- **schema_name** (<code>str</code>) – The name of the schema the table is created in. The schema must already exist.
+- **table_name** (<code>str</code>) – The name of the table to use to store Haystack documents.
+- **language** (<code>str</code>) – The language to be used to parse query and document content in keyword retrieval.
+  To see the list of available languages, you can run the following SQL query in your PostgreSQL database:
+  `SELECT cfgname FROM pg_ts_config;`.
+  More information can be found in this [StackOverflow answer](https://stackoverflow.com/a/39752553).
+- **embedding_dimension** (<code>int</code>) – The dimension of the embedding.
+- **vector_type** (<code>Literal['vector', 'halfvec']</code>) – The type of vector used for embedding storage.
+  "vector" is the default.
+  "halfvec" stores embeddings in half-precision, which is particularly useful for high-dimensional embeddings
+  (dimension greater than 2,000 and up to 4,000). Requires pgvector versions 0.7.0 or later. For more
+  information, see the [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file).
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance']</code>) – The similarity function to use when searching for similar embeddings.
+  `"cosine_similarity"` and `"inner_product"` are similarity functions and
+  higher scores indicate greater similarity between the documents.
+  `"l2_distance"` returns the straight-line distance between vectors,
+  and the most similar documents are the ones with the smallest score.
+  **Important**: when using the `"hnsw"` search strategy, an index will be created that depends on the
+  `vector_function` passed here. Make sure subsequent queries will keep using the same
+  vector similarity function in order to take advantage of the index.
+- **recreate_table** (<code>bool</code>) – Whether to recreate the table if it already exists.
+- **search_strategy** (<code>Literal['exact_nearest_neighbor', 'hnsw']</code>) – The search strategy to use when searching for similar embeddings.
+  `"exact_nearest_neighbor"` provides perfect recall but can be slow for large numbers of documents.
+  `"hnsw"` is an approximate nearest neighbor search strategy,
+  which trades off some accuracy for speed; it is recommended for large numbers of documents.
+  **Important**: when using the `"hnsw"` search strategy, an index will be created that depends on the
+  `vector_function` passed here. Make sure subsequent queries will keep using the same
+  vector similarity function in order to take advantage of the index.
+- **hnsw_recreate_index_if_exists** (<code>bool</code>) – Whether to recreate the HNSW index if it already exists.
+  Only used if search_strategy is set to `"hnsw"`.
+- **hnsw_index_creation_kwargs** (<code>dict\[str, int\] | None</code>) – Additional keyword arguments to pass to the HNSW index creation.
+  Only used if search_strategy is set to `"hnsw"`. You can find the list of valid arguments in the
+  [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw)
+- **hnsw_index_name** (<code>str</code>) – Index name for the HNSW index.
+- **hnsw_ef_search** (<code>int | None</code>) – The `ef_search` parameter to use at query time. Only used if search_strategy is set to
+  `"hnsw"`. You can find more information about this parameter in the
+  [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw).
+- **keyword_index_name** (<code>str</code>) – Index name for the Keyword index.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> PgvectorDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>PgvectorDocumentStore</code> – Deserialized component.
+
+#### delete_table
+
+```python
+delete_table()
+```
+
+Deletes the table used to store Haystack documents.
+The name of the schema (`schema_name`) and the name of the table (`table_name`)
+are defined when initializing the `PgvectorDocumentStore`.
+
+#### delete_table_async
+
+```python
+delete_table_async()
+```
+
+Async method to delete the table used to store Haystack documents.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – Number of documents in the document store.
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Returns how many documents are present in the document store.
+
+**Returns:**
+
+- <code>int</code> – Number of documents in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+**Raises:**
+
+- <code>TypeError</code> – If `filters` is not a dictionary.
+- <code>ValueError</code> – If `filters` syntax is invalid.
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+**Raises:**
+
+- <code>TypeError</code> – If `filters` is not a dictionary.
+- <code>ValueError</code> – If `filters` syntax is invalid.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` contains objects that are not of type `Document`.
+- <code>DuplicateDocumentError</code> – If a document with the same id already exists in the document store
+  and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+- <code>DocumentStoreError</code> – If the write operation fails for any other reason.
+
+#### write_documents_async
+
+```python
+write_documents_async(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` contains objects that are not of type `Document`.
+- <code>DuplicateDocumentError</code> – If a document with the same id already exists in the document store
+  and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+- <code>DocumentStoreError</code> – If the write operation fails for any other reason.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – the document ids to delete
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – the document ids to delete
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents in the document store.
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async() -> None
+```
+
+Asynchronously deletes all documents in the document store.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for deletion.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for deletion.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filters.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the count of unique values for each specified metadata field,
+considering only documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names to count unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary mapping field names to their unique value counts.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously returns the count of unique values for each specified metadata field,
+considering only documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names to count unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary mapping field names to their unique value counts.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns the information about the metadata fields in the document store.
+
+Since metadata is stored in a JSONB field, this method analyzes actual data
+to infer field types.
+
+Example return:
+
+```python
+{
+    'content': {'type': 'text'},
+    'category': {'type': 'text'},
+    'status': {'type': 'text'},
+    'priority': {'type': 'integer'},
+}
+```
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – A dictionary mapping field names to their type information.
+
+#### get_metadata_fields_info_async
+
+```python
+get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns the information about the metadata fields in the document store.
+
+Since metadata is stored in a JSONB field, this method analyzes actual data
+to infer field types.
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – A dictionary mapping field names to their type information.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for a given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The name of the metadata field. Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with 'min' and 'max' keys containing the minimum and maximum values.
+  For numeric fields (integer, real), returns numeric min/max.
+  For text fields, returns lexicographic min/max based on database collation.
+
+**Raises:**
+
+- <code>ValueError</code> – If the field doesn't exist or has no values.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously returns the minimum and maximum values for a given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The name of the metadata field. Can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with 'min' and 'max' keys containing the minimum and maximum values.
+  For numeric fields (integer, real), returns numeric min/max.
+  For text fields, returns lexicographic min/max based on database collation.
+
+**Raises:**
+
+- <code>ValueError</code> – If the field doesn't exist or has no values.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str, search_term: str | None, from_: int, size: int
+) -> tuple[list[str], int]
+```
+
+Returns unique values for a given metadata field, optionally filtered by a search term.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The name of the metadata field. Can include or omit the "meta." prefix.
+- **search_term** (<code>str | None</code>) – Optional search term to filter documents by content before extracting unique values.
+  If None, all documents are considered.
+- **from\_** (<code>int</code>) – The offset for pagination (0-based).
+- **size** (<code>int</code>) – The number of unique values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing:
+- A list of unique values (as strings)
+- The total count of unique values
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str, search_term: str | None, from_: int, size: int
+) -> tuple[list[str], int]
+```
+
+Asynchronously returns unique values for a given metadata field, optionally filtered by a search term.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – The name of the metadata field. Can include or omit the "meta." prefix.
+- **search_term** (<code>str | None</code>) – Optional search term to filter documents by content before extracting unique values.
+  If None, all documents are considered.
+- **from\_** (<code>int</code>) – The offset for pagination (0-based).
+- **size** (<code>int</code>) – The number of unique values to return.
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – A tuple containing:
+- A list of unique values (as strings)
+- The total count of unique values

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/pinecone.md

@@ -0,0 +1,771 @@
+---
+title: "Pinecone"
+id: integrations-pinecone
+description: "Pinecone integration for Haystack"
+slug: "/integrations-pinecone"
+---
+
+<a id="haystack_integrations.components.retrievers.pinecone.embedding_retriever"></a>
+
+## Module haystack\_integrations.components.retrievers.pinecone.embedding\_retriever
+
+<a id="haystack_integrations.components.retrievers.pinecone.embedding_retriever.PineconeEmbeddingRetriever"></a>
+
+### PineconeEmbeddingRetriever
+
+Retrieves documents from the `PineconeDocumentStore`, based on their dense embeddings.
+
+Usage example:
+```python
+import os
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack_integrations.components.retrievers.pinecone import PineconeEmbeddingRetriever
+from haystack_integrations.document_stores.pinecone import PineconeDocumentStore
+
+os.environ["PINECONE_API_KEY"] = "YOUR_PINECONE_API_KEY"
+document_store = PineconeDocumentStore(index="my_index", namespace="my_namespace", dimension=768)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+             Document(content="Elephants have been observed to behave in a way that indicates..."),
+             Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", PineconeEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+res = query_pipeline.run({"text_embedder": {"text": query}})
+assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today."
+```
+
+<a id="haystack_integrations.components.retrievers.pinecone.embedding_retriever.PineconeEmbeddingRetriever.__init__"></a>
+
+#### PineconeEmbeddingRetriever.\_\_init\_\_
+
+```python
+def __init__(*,
+             document_store: PineconeDocumentStore,
+             filters: dict[str, Any] | None = None,
+             top_k: int = 10,
+             filter_policy: str | FilterPolicy = FilterPolicy.REPLACE)
+```
+
+**Arguments**:
+
+- `document_store`: The Pinecone Document Store.
+- `filters`: Filters applied to the retrieved Documents.
+- `top_k`: Maximum number of Documents to return.
+- `filter_policy`: Policy to determine how filters are applied.
+
+**Raises**:
+
+- `ValueError`: If `document_store` is not an instance of `PineconeDocumentStore`.
+
+<a id="haystack_integrations.components.retrievers.pinecone.embedding_retriever.PineconeEmbeddingRetriever.to_dict"></a>
+
+#### PineconeEmbeddingRetriever.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.retrievers.pinecone.embedding_retriever.PineconeEmbeddingRetriever.from_dict"></a>
+
+#### PineconeEmbeddingRetriever.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "PineconeEmbeddingRetriever"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.retrievers.pinecone.embedding_retriever.PineconeEmbeddingRetriever.run"></a>
+
+#### PineconeEmbeddingRetriever.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(query_embedding: list[float],
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `PineconeDocumentStore`, based on their dense embeddings.
+
+**Arguments**:
+
+- `query_embedding`: Embedding of the query.
+- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+the `filter_policy` chosen at retriever initialization. See init method docstring for more
+details.
+- `top_k`: Maximum number of `Document`s to return.
+
+**Returns**:
+
+List of Document similar to `query_embedding`.
+
+<a id="haystack_integrations.components.retrievers.pinecone.embedding_retriever.PineconeEmbeddingRetriever.run_async"></a>
+
+#### PineconeEmbeddingRetriever.run\_async
+
+```python
+@component.output_types(documents=list[Document])
+async def run_async(query_embedding: list[float],
+                    filters: dict[str, Any] | None = None,
+                    top_k: int | None = None) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the `PineconeDocumentStore`, based on their dense embeddings.
+
+**Arguments**:
+
+- `query_embedding`: Embedding of the query.
+- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+the `filter_policy` chosen at retriever initialization. See init method docstring for more
+details.
+- `top_k`: Maximum number of `Document`s to return.
+
+**Returns**:
+
+List of Document similar to `query_embedding`.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store"></a>
+
+## Module haystack\_integrations.document\_stores.pinecone.document\_store
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.METADATA_SUPPORTED_TYPES"></a>
+
+#### METADATA\_SUPPORTED\_TYPES
+
+List[str] is supported and checked separately
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore"></a>
+
+### PineconeDocumentStore
+
+A Document Store using [Pinecone vector database](https://www.pinecone.io/).
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.__init__"></a>
+
+#### PineconeDocumentStore.\_\_init\_\_
+
+```python
+def __init__(*,
+             api_key: Secret = Secret.from_env_var("PINECONE_API_KEY"),
+             index: str = "default",
+             namespace: str = "default",
+             batch_size: int = 100,
+             dimension: int = 768,
+             spec: dict[str, Any] | None = None,
+             metric: Literal["cosine", "euclidean", "dotproduct"] = "cosine")
+```
+
+Creates a new PineconeDocumentStore instance.
+
+It is meant to be connected to a Pinecone index and namespace.
+
+**Arguments**:
+
+- `api_key`: The Pinecone API key.
+- `index`: The Pinecone index to connect to. If the index does not exist, it will be created.
+- `namespace`: The Pinecone namespace to connect to. If the namespace does not exist, it will be created
+at the first write.
+- `batch_size`: The number of documents to write in a single batch. When setting this parameter,
+consider [documented Pinecone limits](https://docs.pinecone.io/reference/quotas-and-limits).
+- `dimension`: The dimension of the embeddings. This parameter is only used when creating a new index.
+- `spec`: The Pinecone spec to use when creating a new index. Allows choosing between serverless and pod
+deployment options and setting additional parameters. Refer to the
+[Pinecone documentation](https://docs.pinecone.io/reference/api/control-plane/create_index) for more
+details.
+If not provided, a default spec with serverless deployment in the `us-east-1` region will be used
+(compatible with the free tier).
+- `metric`: The metric to use for similarity search. This parameter is only used when creating a new index.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.close"></a>
+
+#### PineconeDocumentStore.close
+
+```python
+def close()
+```
+
+Close the associated synchronous resources.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.close_async"></a>
+
+#### PineconeDocumentStore.close\_async
+
+```python
+async def close_async()
+```
+
+Close the associated asynchronous resources. To be invoked manually when the Document Store is no longer needed.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.from_dict"></a>
+
+#### PineconeDocumentStore.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "PineconeDocumentStore"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.to_dict"></a>
+
+#### PineconeDocumentStore.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.count_documents"></a>
+
+#### PineconeDocumentStore.count\_documents
+
+```python
+def count_documents() -> int
+```
+
+Returns how many documents are present in the document store.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.count_documents_async"></a>
+
+#### PineconeDocumentStore.count\_documents\_async
+
+```python
+async def count_documents_async() -> int
+```
+
+Asynchronously returns how many documents are present in the document store.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.write_documents"></a>
+
+#### PineconeDocumentStore.write\_documents
+
+```python
+def write_documents(documents: list[Document],
+                    policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int
+```
+
+Writes Documents to Pinecone.
+
+**Arguments**:
+
+- `documents`: A list of Documents to write to the document store.
+- `policy`: The duplicate policy to use when writing documents.
+PineconeDocumentStore only supports `DuplicatePolicy.OVERWRITE`.
+
+**Returns**:
+
+The number of documents written to the document store.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.write_documents_async"></a>
+
+#### PineconeDocumentStore.write\_documents\_async
+
+```python
+async def write_documents_async(
+        documents: list[Document],
+        policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int
+```
+
+Asynchronously writes Documents to Pinecone.
+
+**Arguments**:
+
+- `documents`: A list of Documents to write to the document store.
+- `policy`: The duplicate policy to use when writing documents.
+PineconeDocumentStore only supports `DuplicatePolicy.OVERWRITE`.
+
+**Returns**:
+
+The number of documents written to the document store.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.filter_documents"></a>
+
+#### PineconeDocumentStore.filter\_documents
+
+```python
+def filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Arguments**:
+
+- `filters`: The filters to apply to the document list.
+
+**Returns**:
+
+A list of Documents that match the given filters.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.filter_documents_async"></a>
+
+#### PineconeDocumentStore.filter\_documents\_async
+
+```python
+async def filter_documents_async(
+        filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously returns the documents that match the filters provided.
+
+**Arguments**:
+
+- `filters`: The filters to apply to the document list.
+
+**Returns**:
+
+A list of Documents that match the given filters.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.delete_documents"></a>
+
+#### PineconeDocumentStore.delete\_documents
+
+```python
+def delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents that match the provided `document_ids` from the document store.
+
+**Arguments**:
+
+- `document_ids`: the document ids to delete
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.delete_documents_async"></a>
+
+#### PineconeDocumentStore.delete\_documents\_async
+
+```python
+async def delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously deletes documents that match the provided `document_ids` from the document store.
+
+**Arguments**:
+
+- `document_ids`: the document ids to delete
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.delete_all_documents"></a>
+
+#### PineconeDocumentStore.delete\_all\_documents
+
+```python
+def delete_all_documents() -> None
+```
+
+Deletes all documents in the document store.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.delete_all_documents_async"></a>
+
+#### PineconeDocumentStore.delete\_all\_documents\_async
+
+```python
+async def delete_all_documents_async() -> None
+```
+
+Asynchronously deletes all documents in the document store.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.delete_by_filter"></a>
+
+#### PineconeDocumentStore.delete\_by\_filter
+
+```python
+def delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+Pinecone does not support server-side delete by filter, so this method
+first searches for matching documents, then deletes them by ID.
+
+**Arguments**:
+
+- `filters`: The filters to apply to select documents for deletion.
+For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns**:
+
+The number of documents deleted.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.delete_by_filter_async"></a>
+
+#### PineconeDocumentStore.delete\_by\_filter\_async
+
+```python
+async def delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously deletes all documents that match the provided filters.
+
+Pinecone does not support server-side delete by filter, so this method
+first searches for matching documents, then deletes them by ID.
+
+**Arguments**:
+
+- `filters`: The filters to apply to select documents for deletion.
+For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns**:
+
+The number of documents deleted.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.update_by_filter"></a>
+
+#### PineconeDocumentStore.update\_by\_filter
+
+```python
+def update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+Pinecone does not support server-side update by filter, so this method
+first searches for matching documents, then updates their metadata and re-writes them.
+
+**Arguments**:
+
+- `filters`: The filters to apply to select documents for updating.
+For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- `meta`: The metadata fields to update. This will be merged with existing metadata.
+
+**Returns**:
+
+The number of documents updated.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.update_by_filter_async"></a>
+
+#### PineconeDocumentStore.update\_by\_filter\_async
+
+```python
+async def update_by_filter_async(filters: dict[str, Any],
+                                 meta: dict[str, Any]) -> int
+```
+
+Asynchronously updates the metadata of all documents that match the provided filters.
+
+Pinecone does not support server-side update by filter, so this method
+first searches for matching documents, then updates their metadata and re-writes them.
+
+**Arguments**:
+
+- `filters`: The filters to apply to select documents for updating.
+For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- `meta`: The metadata fields to update. This will be merged with existing metadata.
+
+**Returns**:
+
+The number of documents updated.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.count_documents_by_filter"></a>
+
+#### PineconeDocumentStore.count\_documents\_by\_filter
+
+```python
+def count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the count of documents that match the provided filters.
+
+Note: Due to Pinecone's limitations, this method fetches documents and counts them.
+For large result sets, this is subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Arguments**:
+
+- `filters`: The filters to apply to the document list.
+For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns**:
+
+The number of documents that match the filters.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.count_documents_by_filter_async"></a>
+
+#### PineconeDocumentStore.count\_documents\_by\_filter\_async
+
+```python
+async def count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously returns the count of documents that match the provided filters.
+
+Note: Due to Pinecone's limitations, this method fetches documents and counts them.
+For large result sets, this is subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Arguments**:
+
+- `filters`: The filters to apply to the document list.
+
+**Returns**:
+
+The number of documents that match the filters.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.count_unique_metadata_by_filter"></a>
+
+#### PineconeDocumentStore.count\_unique\_metadata\_by\_filter
+
+```python
+def count_unique_metadata_by_filter(
+        filters: dict[str, Any], metadata_fields: list[str]) -> dict[str, int]
+```
+
+Counts unique values for each specified metadata field in documents matching the filters.
+
+Note: Due to Pinecone's limitations, this method fetches documents and aggregates in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Arguments**:
+
+- `filters`: The filters to apply to select documents.
+- `metadata_fields`: List of metadata field names to count unique values for.
+
+**Returns**:
+
+Dictionary mapping field names to counts of unique values.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.count_unique_metadata_by_filter_async"></a>
+
+#### PineconeDocumentStore.count\_unique\_metadata\_by\_filter\_async
+
+```python
+async def count_unique_metadata_by_filter_async(
+        filters: dict[str, Any], metadata_fields: list[str]) -> dict[str, int]
+```
+
+Asynchronously counts unique values for each specified metadata field in documents matching the filters.
+
+Note: Due to Pinecone's limitations, this method fetches documents and aggregates in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Arguments**:
+
+- `filters`: The filters to apply to select documents.
+- `metadata_fields`: List of metadata field names to count unique values for.
+
+**Returns**:
+
+Dictionary mapping field names to counts of unique values.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.get_metadata_fields_info"></a>
+
+#### PineconeDocumentStore.get\_metadata\_fields\_info
+
+```python
+def get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns information about metadata fields and their types by sampling documents.
+
+Note: Pinecone doesn't provide a schema introspection API, so this method infers field types
+by examining the metadata of documents stored in the index (up to 1000 documents).
+
+Type mappings:
+- 'text': Document content field
+- 'keyword': String metadata values
+- 'long': Numeric metadata values (int or float)
+- 'boolean': Boolean metadata values
+
+**Returns**:
+
+Dictionary mapping field names to type information.
+Example:
+```python
+{
+    'content': {'type': 'text'},
+    'category': {'type': 'keyword'},
+    'priority': {'type': 'long'},
+}
+```
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.get_metadata_fields_info_async"></a>
+
+#### PineconeDocumentStore.get\_metadata\_fields\_info\_async
+
+```python
+async def get_metadata_fields_info_async() -> dict[str, dict[str, str]]
+```
+
+Asynchronously returns information about metadata fields and their types by sampling documents.
+
+Note: Pinecone doesn't provide a schema introspection API, so this method infers field types
+by examining the metadata of documents stored in the index (up to 1000 documents).
+
+Type mappings:
+- 'text': Document content field
+- 'keyword': String metadata values
+- 'long': Numeric metadata values (int or float)
+- 'boolean': Boolean metadata values
+
+**Returns**:
+
+Dictionary mapping field names to type information.
+Example:
+```python
+{
+    'content': {'type': 'text'},
+    'category': {'type': 'keyword'},
+    'priority': {'type': 'long'},
+}
+```
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.get_metadata_field_min_max"></a>
+
+#### PineconeDocumentStore.get\_metadata\_field\_min\_max
+
+```python
+def get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for a metadata field.
+
+Supports numeric (int, float), boolean, and string (keyword) types:
+- Numeric: Returns min/max based on numeric value
+- Boolean: Returns False as min, True as max
+- String: Returns min/max based on alphabetical ordering
+
+Note: This method fetches all documents and computes min/max in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Arguments**:
+
+- `metadata_field`: The metadata field name to analyze.
+
+**Raises**:
+
+- `ValueError`: If the field doesn't exist or has no values.
+
+**Returns**:
+
+Dictionary with 'min' and 'max' keys.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.get_metadata_field_min_max_async"></a>
+
+#### PineconeDocumentStore.get\_metadata\_field\_min\_max\_async
+
+```python
+async def get_metadata_field_min_max_async(
+        metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously returns the minimum and maximum values for a metadata field.
+
+Supports numeric (int, float), boolean, and string (keyword) types:
+- Numeric: Returns min/max based on numeric value
+- Boolean: Returns False as min, True as max
+- String: Returns min/max based on alphabetical ordering
+
+Note: This method fetches all documents and computes min/max in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Arguments**:
+
+- `metadata_field`: The metadata field name to analyze.
+
+**Raises**:
+
+- `ValueError`: If the field doesn't exist or has no values.
+
+**Returns**:
+
+Dictionary with 'min' and 'max' keys.
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.get_metadata_field_unique_values"></a>
+
+#### PineconeDocumentStore.get\_metadata\_field\_unique\_values
+
+```python
+def get_metadata_field_unique_values(metadata_field: str,
+                                     search_term: str | None = None,
+                                     from_: int = 0,
+                                     size: int = 10) -> tuple[list[str], int]
+```
+
+Retrieves unique values for a metadata field with optional search and pagination.
+
+Note: This method fetches documents and extracts unique values in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Arguments**:
+
+- `metadata_field`: The metadata field name to get unique values for.
+- `search_term`: Optional search term to filter values (case-insensitive substring match).
+- `from_`: Starting offset for pagination (default: 0).
+- `size`: Number of values to return (default: 10).
+
+**Returns**:
+
+Tuple of (list of unique values, total count of matching values).
+
+<a id="haystack_integrations.document_stores.pinecone.document_store.PineconeDocumentStore.get_metadata_field_unique_values_async"></a>
+
+#### PineconeDocumentStore.get\_metadata\_field\_unique\_values\_async
+
+```python
+async def get_metadata_field_unique_values_async(
+        metadata_field: str,
+        search_term: str | None = None,
+        from_: int = 0,
+        size: int = 10) -> tuple[list[str], int]
+```
+
+Asynchronously retrieves unique values for a metadata field with optional search and pagination.
+
+Note: This method fetches documents and extracts unique values in Python.
+Subject to Pinecone's TOP_K_LIMIT of 1000 documents.
+
+**Arguments**:
+
+- `metadata_field`: The metadata field name to get unique values for.
+- `search_term`: Optional search term to filter values (case-insensitive substring match).
+- `from_`: Starting offset for pagination (default: 0).
+- `size`: Number of values to return (default: 10).
+
+**Returns**:
+
+Tuple of (list of unique values, total count of matching values).
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/pyversity.md

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

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/ragas.md

@@ -0,0 +1,97 @@
+---
+title: "Ragas"
+id: integrations-ragas
+description: "Ragas integration for Haystack"
+slug: "/integrations-ragas"
+---
+
+<a id="haystack_integrations.components.evaluators.ragas.evaluator"></a>
+
+## Module haystack\_integrations.components.evaluators.ragas.evaluator
+
+<a id="haystack_integrations.components.evaluators.ragas.evaluator.RagasEvaluator"></a>
+
+### RagasEvaluator
+
+A component that uses the [Ragas framework](https://docs.ragas.io/) to evaluate
+inputs against specified Ragas metrics.
+
+Usage example:
+```python
+from haystack.components.generators import OpenAIGenerator
+from haystack_integrations.components.evaluators.ragas import RagasEvaluator
+from ragas.metrics import ContextPrecision
+from ragas.llms import HaystackLLMWrapper
+
+llm = OpenAIGenerator(model="gpt-4o-mini")
+evaluator_llm = HaystackLLMWrapper(llm)
+
+evaluator = RagasEvaluator(
+    ragas_metrics=[ContextPrecision()],
+    evaluator_llm=evaluator_llm
+)
+output = evaluator.run(
+    query="Which is the most popular global sport?",
+    documents=[
+        "Football is undoubtedly the world's most popular sport with"
+        " major events like the FIFA World Cup and sports personalities"
+        " like Ronaldo and Messi, drawing a followership of more than 4"
+        " billion people."
+    ],
+    reference="Football is the most popular sport with around 4 billion"
+              " followers worldwide",
+)
+
+output['result']
+```
+
+<a id="haystack_integrations.components.evaluators.ragas.evaluator.RagasEvaluator.__init__"></a>
+
+#### RagasEvaluator.\_\_init\_\_
+
+```python
+def __init__(ragas_metrics: list[Metric],
+             evaluator_llm: BaseRagasLLM | None = None,
+             evaluator_embedding: BaseRagasEmbeddings | None = None)
+```
+
+Constructs a new Ragas evaluator.
+
+**Arguments**:
+
+- `ragas_metrics`: A list of evaluation metrics from the [Ragas](https://docs.ragas.io/) library.
+- `evaluator_llm`: A language model used by metrics that require LLMs for evaluation.
+- `evaluator_embedding`: An embedding model used by metrics that require embeddings for evaluation.
+
+<a id="haystack_integrations.components.evaluators.ragas.evaluator.RagasEvaluator.run"></a>
+
+#### RagasEvaluator.run
+
+```python
+@component.output_types(result=EvaluationResult)
+def run(query: str | None = None,
+        response: list[ChatMessage] | str | None = None,
+        documents: list[Document | str] | None = None,
+        reference_contexts: list[str] | None = None,
+        multi_responses: list[str] | None = None,
+        reference: str | None = None,
+        rubrics: dict[str, str] | None = None) -> dict[str, Any]
+```
+
+Evaluates the provided query against the documents and returns the evaluation result.
+
+**Arguments**:
+
+- `query`: The input query from the user.
+- `response`: A list of ChatMessage responses (typically from a language model or agent).
+- `documents`: A list of Haystack Document or strings that were retrieved for the query.
+- `reference_contexts`: A list of reference contexts that should have been retrieved for the query.
+- `multi_responses`: List of multiple responses generated for the query.
+- `reference`: A string reference answer for the query.
+- `rubrics`: A dictionary of evaluation rubric, where keys represent the score
+and the values represent the corresponding evaluation criteria.
+
+**Returns**:
+
+A dictionary containing the evaluation result.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/snowflake.md

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

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/sqlalchemy.md

@@ -0,0 +1,118 @@
+---
+title: "SQLAlchemy"
+id: integrations-sqlalchemy
+description: "SQLAlchemy integration for Haystack"
+slug: "/integrations-sqlalchemy"
+---
+
+
+## haystack_integrations.components.retrievers.sqlalchemy.sqlalchemy_table_retriever
+
+### SQLAlchemyTableRetriever
+
+Connects to any SQLAlchemy-supported database and executes a SQL query.
+
+Returns results as a Pandas DataFrame and an optional Markdown-formatted table string.
+Supports any database backend that SQLAlchemy supports, including PostgreSQL, MySQL,
+SQLite, and MSSQL.
+
+### Usage example:
+
+```python
+from haystack_integrations.components.retrievers.sqlalchemy import SQLAlchemyTableRetriever
+
+retriever = SQLAlchemyTableRetriever(drivername="sqlite", database=":memory:")
+retriever.warm_up()
+result = retriever.run(query="SELECT 1 AS value")
+print(result["dataframe"])
+print(result["table"])
+```
+
+#### __init__
+
+```python
+__init__(
+    drivername: str,
+    username: str | None = None,
+    password: Secret | None = None,
+    host: str | None = None,
+    port: int | None = None,
+    database: str | None = None,
+    init_script: list[str] | None = None,
+) -> None
+```
+
+Initialize SQLAlchemyTableRetriever.
+
+**Parameters:**
+
+- **drivername** (<code>str</code>) – The SQLAlchemy driver name (e.g., `"sqlite"`,
+  `"postgresql+psycopg2"`).
+- **username** (<code>str | None</code>) – Database username.
+- **password** (<code>Secret | None</code>) – Database password as a Haystack `Secret`.
+- **host** (<code>str | None</code>) – Database host.
+- **port** (<code>int | None</code>) – Database port.
+- **database** (<code>str | None</code>) – Database name or path (e.g., `":memory:"` for SQLite in-memory).
+- **init_script** (<code>list\[str\] | None</code>) – Optional list of SQL statements executed once on `warm_up()`
+  (e.g., to create tables or insert seed data). Each statement should be a
+  separate string in the list.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the database engine and execute `init_script` if provided.
+
+Called automatically by `run()` on first invocation if not already warmed up.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SQLAlchemyTableRetriever
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SQLAlchemyTableRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(query: str) -> dict[str, Any]
+```
+
+Execute a SQL query and return the results.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The SQL query to execute.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with:
+
+- `dataframe`: A Pandas DataFrame with the query results.
+
+- `table`: A Markdown-formatted string of the results.
+
+- `error`: An error message if the query failed, otherwise an empty string.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/stackit.md

@@ -0,0 +1,295 @@
+---
+title: "STACKIT"
+id: integrations-stackit
+description: "STACKIT integration for Haystack"
+slug: "/integrations-stackit"
+---
+
+
+## haystack_integrations.components.embedders.stackit.document_embedder
+
+### STACKITDocumentEmbedder
+
+Bases: <code>OpenAIDocumentEmbedder</code>
+
+A component for computing Document embeddings using STACKIT as model provider.
+The embedding of each Document is stored in the `embedding` field of the Document.
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.stackit import STACKITDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = STACKITDocumentEmbedder()
+
+result = document_embedder.run([doc])
+print(result['documents'][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "intfloat/e5-mistral-7b-instruct",
+    "Qwen/Qwen3-VL-Embedding-8B",
+]
+
+```
+
+A non-exhaustive list of embedding models supported by this component.
+See https://docs.stackit.cloud/products/data-and-ai/ai-model-serving/basics/available-shared-models
+for the full list.
+
+#### __init__
+
+```python
+__init__(
+    model: str,
+    api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"),
+    api_base_url: (
+        str | None
+    ) = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1",
+    prefix: str = "",
+    suffix: str = "",
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates a STACKITDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The STACKIT API key.
+- **model** (<code>str</code>) – The name of the model to use.
+- **api_base_url** (<code>str | None</code>) – The STACKIT API Base url.
+  For more details, see STACKIT [docs](https://docs.stackit.cloud/stackit/en/basic-concepts-stackit-model-serving-319914567.html).
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **batch_size** (<code>int</code>) – Number of Documents to encode at once.
+- **progress_bar** (<code>bool</code>) – Whether to show a progress bar or not. Can be helpful to disable in production deployments to keep
+  the logs clean.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
+- **timeout** (<code>float | None</code>) – Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to contact STACKIT after an internal error.
+  If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.components.embedders.stackit.text_embedder
+
+### STACKITTextEmbedder
+
+Bases: <code>OpenAITextEmbedder</code>
+
+A component for embedding strings using STACKIT as model provider.
+
+Usage example:
+
+```python
+from haystack_integrations.components.embedders.stackit import STACKITTextEmbedder
+
+text_to_embed = "I love pizza!"
+text_embedder = STACKITTextEmbedder()
+print(text_embedder.run(text_to_embed))
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "intfloat/e5-mistral-7b-instruct",
+    "Qwen/Qwen3-VL-Embedding-8B",
+]
+
+```
+
+A non-exhaustive list of embedding models supported by this component.
+See https://docs.stackit.cloud/products/data-and-ai/ai-model-serving/basics/available-shared-models
+for the full list.
+
+#### __init__
+
+```python
+__init__(
+    model: str,
+    api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"),
+    api_base_url: (
+        str | None
+    ) = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1",
+    prefix: str = "",
+    suffix: str = "",
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates a STACKITTextEmbedder component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The STACKIT API key.
+- **model** (<code>str</code>) – The name of the STACKIT embedding model to be used.
+- **api_base_url** (<code>str | None</code>) – The STACKIT API Base url.
+  For more details, see STACKIT [docs](https://docs.stackit.cloud/stackit/en/basic-concepts-stackit-model-serving-319914567.html).
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add to the end of each text.
+- **timeout** (<code>float | None</code>) – Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to contact STACKIT after an internal error.
+  If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+## haystack_integrations.components.generators.stackit.chat.chat_generator
+
+### STACKITChatGenerator
+
+Bases: <code>OpenAIChatGenerator</code>
+
+Enables text generation using STACKIT generative models through their model serving service.
+
+Users can pass any text generation parameters valid for the STACKIT Chat Completion API
+directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage)
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.stackit import STACKITChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = STACKITChatGenerator(model="neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8")
+
+result = generator.run([ChatMessage.from_user("Tell me a joke.")])
+print(result)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "Qwen/Qwen3-VL-235B-A22B-Instruct-FP8",
+    "cortecs/Llama-3.3-70B-Instruct-FP8-Dynamic",
+    "openai/gpt-oss-120b",
+    "google/gemma-3-27b-it",
+    "openai/gpt-oss-20b",
+    "neuralmagic/Mistral-Nemo-Instruct-2407-FP8",
+    "neuralmagic/Meta-Llama-3.1-8B-Instruct-FP8",
+]
+
+```
+
+A non-exhaustive list of chat models supported by this component.
+See https://docs.stackit.cloud/products/data-and-ai/ai-model-serving/basics/available-shared-models
+for the full list.
+
+#### __init__
+
+```python
+__init__(
+    model: str,
+    api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"),
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: (
+        str | None
+    ) = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1",
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+)
+```
+
+Creates an instance of STACKITChatGenerator class.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the chat completion model to use.
+- **api_key** (<code>Secret</code>) – The STACKIT API key.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts StreamingChunk as an argument.
+- **api_base_url** (<code>str | None</code>) – The STACKIT API Base url.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Other parameters to use for the model. These parameters are all sent directly to
+  the STACKIT endpoint.
+  Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+  Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+  considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+  comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+  events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+  If provided, the output will always be validated against this
+  format (unless the model returns a tool call).
+  For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+  Notes:
+  - For structured outputs with streaming,
+    the `response_format` must be a JSON schema and not a Pydantic model.
+- **timeout** (<code>float | None</code>) – Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment
+  variable, or 30 seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to contact STACKIT after an internal error.
+  If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/tavily.md

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

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/togetherai.md

@@ -0,0 +1,294 @@
+---
+title: "Together AI"
+id: integrations-togetherai
+description: "Together AI integration for Haystack"
+slug: "/integrations-togetherai"
+---
+
+<a id="haystack_integrations.components.generators.togetherai.chat.chat_generator"></a>
+
+## Module haystack\_integrations.components.generators.togetherai.chat.chat\_generator
+
+<a id="haystack_integrations.components.generators.togetherai.chat.chat_generator.TogetherAIChatGenerator"></a>
+
+### TogetherAIChatGenerator
+
+Enables text generation using Together AI generative models.
+For supported models, see [Together AI docs](https://docs.together.ai/docs).
+
+Users can pass any text generation parameters valid for the Together AI chat completion API
+directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+Key Features and Compatibility:
+- **Primary Compatibility**: Designed to work seamlessly with the Together AI chat completion endpoint.
+- **Streaming Support**: Supports streaming responses from the Together AI chat completion endpoint.
+- **Customizability**: Supports all parameters supported by the Together AI chat completion endpoint.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage)
+
+For more details on the parameters supported by the Together AI API, refer to the
+[Together AI API Docs](https://docs.together.ai/reference/chat-completions-1).
+
+Usage example:
+```python
+from haystack_integrations.components.generators.togetherai import TogetherAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = TogetherAIChatGenerator()
+response = client.run(messages)
+print(response)
+
+>>{'replies': [ChatMessage(_content='Natural Language Processing (NLP) is a branch of artificial intelligence
+>>that focuses on enabling computers to understand, interpret, and generate human language in a way that is
+>>meaningful and useful.', _role=<ChatRole.ASSISTANT: 'assistant'>, _name=None,
+>>_meta={'model': 'meta-llama/Llama-3.3-70B-Instruct-Turbo', 'index': 0, 'finish_reason': 'stop',
+>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]}
+```
+
+<a id="haystack_integrations.components.generators.togetherai.chat.chat_generator.TogetherAIChatGenerator.__init__"></a>
+
+#### TogetherAIChatGenerator.\_\_init\_\_
+
+```python
+def __init__(*,
+             api_key: Secret = Secret.from_env_var("TOGETHER_API_KEY"),
+             model: str = "meta-llama/Llama-3.3-70B-Instruct-Turbo",
+             streaming_callback: StreamingCallbackT | None = None,
+             api_base_url: str | None = "https://api.together.xyz/v1",
+             generation_kwargs: dict[str, Any] | None = None,
+             tools: ToolsType | None = None,
+             timeout: float | None = None,
+             max_retries: int | None = None,
+             http_client_kwargs: dict[str, Any] | None = None)
+```
+
+Creates an instance of TogetherAIChatGenerator. Unless specified otherwise,
+
+the default model is `meta-llama/Llama-3.3-70B-Instruct-Turbo`.
+
+**Arguments**:
+
+- `api_key`: The Together API key.
+- `model`: The name of the Together AI chat completion model to use.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+The callback function accepts StreamingChunk as an argument.
+- `api_base_url`: The Together AI API Base url.
+For more details, see Together AI [docs](https://docs.together.ai/docs/openai-api-compatibility).
+- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to
+the Together AI endpoint. See [Together AI API docs](https://docs.together.ai/reference/chat-completions-1)
+for more details.
+Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+    Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+    considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+    comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+    events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+    If provided, the output will always be validated against this
+    format (unless the model returns a tool call).
+    For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs).
+    Notes:
+    - For structured outputs with streaming,
+      the `response_format` must be a JSON schema and not a Pydantic model.
+- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+Each tool should have a unique name.
+- `timeout`: The timeout for the Together AI API call.
+- `max_retries`: Maximum number of retries to contact Together AI after an internal error.
+If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`).
+
+<a id="haystack_integrations.components.generators.togetherai.chat.chat_generator.TogetherAIChatGenerator.to_dict"></a>
+
+#### TogetherAIChatGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns**:
+
+The serialized component as a dictionary.
+
+<a id="haystack_integrations.components.generators.togetherai.generator"></a>
+
+## Module haystack\_integrations.components.generators.togetherai.generator
+
+<a id="haystack_integrations.components.generators.togetherai.generator.TogetherAIGenerator"></a>
+
+### TogetherAIGenerator
+
+Provides an interface to generate text using an LLM running on Together AI.
+
+Usage example:
+```python
+from haystack_integrations.components.generators.togetherai import TogetherAIGenerator
+
+generator = TogetherAIGenerator(model="deepseek-ai/DeepSeek-R1",
+                            generation_kwargs={
+                            "temperature": 0.9,
+                            })
+
+print(generator.run("Who is the best Italian actor?"))
+```
+
+<a id="haystack_integrations.components.generators.togetherai.generator.TogetherAIGenerator.__init__"></a>
+
+#### TogetherAIGenerator.\_\_init\_\_
+
+```python
+def __init__(api_key: Secret = Secret.from_env_var("TOGETHER_API_KEY"),
+             model: str = "meta-llama/Llama-3.3-70B-Instruct-Turbo",
+             api_base_url: str | None = "https://api.together.xyz/v1",
+             streaming_callback: StreamingCallbackT | None = None,
+             system_prompt: str | None = None,
+             generation_kwargs: dict[str, Any] | None = None,
+             timeout: float | None = None,
+             max_retries: int | None = None)
+```
+
+Initialize the TogetherAIGenerator.
+
+**Arguments**:
+
+- `api_key`: The Together API key.
+- `model`: The name of the model to use.
+- `api_base_url`: The base URL of the Together AI API.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+The callback function accepts StreamingChunk as an argument.
+- `system_prompt`: The system prompt to use for text generation. If not provided, the system prompt is
+omitted, and the default system prompt of the model is used.
+- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to
+the Together AI endpoint. See Together AI
+[documentation](https://docs.together.ai/reference/chat-completions-1) for more details.
+Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+    Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+    considers the results of the tokens with top_p probability mass. So, 0.1 means only the tokens
+    comprising the top 10% probability mass are considered.
+- `n`: How many completions to generate for each prompt. For example, if the LLM gets 3 prompts and n is 2,
+    it will generate two completions for each of the three prompts, ending up with 6 completions in total.
+- `stop`: One or more sequences after which the LLM should stop generating tokens.
+- `presence_penalty`: What penalty to apply if a token is already present at all. Bigger values mean
+    the model will be less likely to repeat the same token in the text.
+- `frequency_penalty`: What penalty to apply if a token has already been generated in the text.
+    Bigger values mean the model will be less likely to repeat the same token in the text.
+- `logit_bias`: Add a logit bias to specific tokens. The keys of the dictionary are tokens, and the
+    values are the bias to add to that token.
+- `timeout`: Timeout for together.ai Client calls, if not set it is inferred from the `OPENAI_TIMEOUT` environment
+variable or set to 30.
+- `max_retries`: Maximum retries to establish contact with Together AI if it returns an internal error, if not set it is
+inferred from the `OPENAI_MAX_RETRIES` environment variable or set to 5.
+
+<a id="haystack_integrations.components.generators.togetherai.generator.TogetherAIGenerator.to_dict"></a>
+
+#### TogetherAIGenerator.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns**:
+
+The serialized component as a dictionary.
+
+<a id="haystack_integrations.components.generators.togetherai.generator.TogetherAIGenerator.from_dict"></a>
+
+#### TogetherAIGenerator.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "TogetherAIGenerator"
+```
+
+Deserialize this component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary representation of this component.
+
+**Returns**:
+
+The deserialized component instance.
+
+<a id="haystack_integrations.components.generators.togetherai.generator.TogetherAIGenerator.run"></a>
+
+#### TogetherAIGenerator.run
+
+```python
+@component.output_types(replies=list[str], meta=list[dict[str, Any]])
+def run(*,
+        prompt: str,
+        system_prompt: str | None = None,
+        streaming_callback: StreamingCallbackT | None = None,
+        generation_kwargs: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Generate text completions synchronously.
+
+**Arguments**:
+
+- `prompt`: The input prompt string for text generation.
+- `system_prompt`: An optional system prompt to provide context or instructions for the generation.
+If not provided, the system prompt set in the `__init__` method will be used.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+If provided, this will override the `streaming_callback` set in the `__init__` method.
+- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters
+passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list of generated text completions as strings.
+- `meta`: A list of metadata dictionaries containing information about each generation,
+including model name, finish reason, and token usage statistics.
+
+<a id="haystack_integrations.components.generators.togetherai.generator.TogetherAIGenerator.run_async"></a>
+
+#### TogetherAIGenerator.run\_async
+
+```python
+@component.output_types(replies=list[str], meta=list[dict[str, Any]])
+async def run_async(
+        *,
+        prompt: str,
+        system_prompt: str | None = None,
+        streaming_callback: StreamingCallbackT | None = None,
+        generation_kwargs: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Generate text completions asynchronously.
+
+**Arguments**:
+
+- `prompt`: The input prompt string for text generation.
+- `system_prompt`: An optional system prompt to provide context or instructions for the generation.
+- `streaming_callback`: A callback function that is called when a new token is received from the stream.
+If provided, this will override the `streaming_callback` set in the `__init__` method.
+- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters
+passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `replies`: A list of generated text completions as strings.
+- `meta`: A list of metadata dictionaries containing information about each generation,
+including model name, finish reason, and token usage statistics.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/unstructured.md

@@ -0,0 +1,136 @@
+---
+title: "Unstructured"
+id: integrations-unstructured
+description: "Unstructured integration for Haystack"
+slug: "/integrations-unstructured"
+---
+
+<a id="haystack_integrations.components.converters.unstructured.converter"></a>
+
+## Module haystack\_integrations.components.converters.unstructured.converter
+
+<a id="haystack_integrations.components.converters.unstructured.converter.UnstructuredFileConverter"></a>
+
+### UnstructuredFileConverter
+
+A component for converting files to Haystack Documents using the Unstructured API (hosted or running locally).
+
+For the supported file types and the specific API parameters, see
+[Unstructured docs](https://docs.unstructured.io/api-reference/api-services/overview).
+
+Usage example:
+```python
+from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter
+
+# make sure to either set the environment variable UNSTRUCTURED_API_KEY
+# or run the Unstructured API locally:
+# docker run -p 8000:8000 -d --rm --name unstructured-api quay.io/unstructured-io/unstructured-api:latest
+# --port 8000 --host 0.0.0.0
+
+converter = UnstructuredFileConverter(
+    # api_url="http://localhost:8000/general/v0/general"  # <-- Uncomment this if running Unstructured locally
+)
+documents = converter.run(paths = ["a/file/path.pdf", "a/directory/path"])["documents"]
+```
+
+<a id="haystack_integrations.components.converters.unstructured.converter.UnstructuredFileConverter.__init__"></a>
+
+#### UnstructuredFileConverter.\_\_init\_\_
+
+```python
+def __init__(api_url: str = UNSTRUCTURED_HOSTED_API_URL,
+             api_key: Secret | None = Secret.from_env_var(
+                 "UNSTRUCTURED_API_KEY", strict=False),
+             document_creation_mode: Literal[
+                 "one-doc-per-file", "one-doc-per-page",
+                 "one-doc-per-element"] = "one-doc-per-file",
+             separator: str = "\n\n",
+             unstructured_kwargs: dict[str, Any] | None = None,
+             progress_bar: bool = True)
+```
+
+**Arguments**:
+
+- `api_url`: URL of the Unstructured API. Defaults to the URL of the hosted version.
+If you run the API locally, specify the URL of your local API (e.g. `"http://localhost:8000/general/v0/general"`).
+- `api_key`: API key for the Unstructured API.
+It can be explicitly passed or read the environment variable `UNSTRUCTURED_API_KEY` (recommended).
+If you run the API locally, it is not needed.
+- `document_creation_mode`: How to create Haystack Documents from the elements returned by Unstructured.
+`"one-doc-per-file"`: One Haystack Document per file. All elements are concatenated into one text field.
+`"one-doc-per-page"`: One Haystack Document per page.
+All elements on a page are concatenated into one text field.
+`"one-doc-per-element"`: One Haystack Document per element. Each element is converted to a Haystack Document.
+- `separator`: Separator between elements when concatenating them into one text field.
+- `unstructured_kwargs`: Additional parameters that are passed to the Unstructured API.
+For the available parameters, see
+[Unstructured API docs](https://docs.unstructured.io/api-reference/api-services/api-parameters).
+- `progress_bar`: Whether to show a progress bar during the conversion.
+
+<a id="haystack_integrations.components.converters.unstructured.converter.UnstructuredFileConverter.to_dict"></a>
+
+#### UnstructuredFileConverter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="haystack_integrations.components.converters.unstructured.converter.UnstructuredFileConverter.from_dict"></a>
+
+#### UnstructuredFileConverter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "UnstructuredFileConverter"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.components.converters.unstructured.converter.UnstructuredFileConverter.run"></a>
+
+#### UnstructuredFileConverter.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(
+    paths: list[str] | list[os.PathLike],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None
+) -> dict[str, list[Document]]
+```
+
+Convert files to Haystack Documents using the Unstructured API.
+
+**Arguments**:
+
+- `paths`: List of paths to convert. Paths can be files or directories.
+If a path is a directory, all files in the directory are converted. Subdirectories are ignored.
+- `meta`: Optional metadata to attach to the Documents.
+This value can be either a list of dictionaries or a single dictionary.
+If it's a single dictionary, its content is added to the metadata of all produced Documents.
+If it's a list, the length of the list must match the number of paths, because the two lists will be zipped.
+Please note that if the paths contain directories, `meta` can only be a single dictionary
+(same metadata for all files).
+
+**Raises**:
+
+- `ValueError`: If `meta` is a list and `paths` contains directories.
+
+**Returns**:
+
+A dictionary with the following key:
+- `documents`: List of Haystack Documents.
+

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/valkey.md

@@ -0,0 +1,977 @@
+---
+title: "Valkey"
+id: integrations-valkey
+description: "Valkey integration for Haystack"
+slug: "/integrations-valkey"
+---
+
+
+## haystack_integrations.components.retrievers.valkey.embedding_retriever
+
+### ValkeyEmbeddingRetriever
+
+A component for retrieving documents from a ValkeyDocumentStore using vector similarity search.
+
+This retriever uses dense embeddings to find semantically similar documents. It supports
+filtering by metadata fields and configurable similarity thresholds.
+
+Key features:
+
+- Vector similarity search using HNSW algorithm
+- Metadata filtering with tag and numeric field support
+- Configurable top-k results
+- Filter policy management for runtime filter application
+
+Usage example:
+
+```python
+from haystack.document_stores.types import DuplicatePolicy
+from haystack import Document
+from haystack import Pipeline
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+from haystack_integrations.components.retrievers.valkey import ValkeyEmbeddingRetriever
+from haystack_integrations.document_stores.valkey import ValkeyDocumentStore
+
+document_store = ValkeyDocumentStore(index_name="my_index", embedding_dim=768)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+             Document(content="Elephants have been observed to behave in a way that indicates..."),
+             Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", ValkeyEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+res = query_pipeline.run({"text_embedder": {"text": query}})
+assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: ValkeyDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+)
+```
+
+**Parameters:**
+
+- **document_store** (<code>ValkeyDocumentStore</code>) – The Valkey Document Store.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `ValkeyDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ValkeyEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ValkeyEmbeddingRetriever</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `ValkeyDocumentStore`, based on their dense embeddings.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – Maximum number of `Document`s to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – List of Document similar to `query_embedding`.
+
+#### run_async
+
+```python
+run_async(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously retrieve documents from the `ValkeyDocumentStore`, based on their dense embeddings.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Embedding of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents. The way runtime filters are applied depends on
+  the `filter_policy` chosen at retriever initialization. See init method docstring for more
+  details.
+- **top_k** (<code>int | None</code>) – Maximum number of `Document`s to return.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – List of Document similar to `query_embedding`.
+
+## haystack_integrations.document_stores.valkey.document_store
+
+### ValkeyDocumentStore
+
+Bases: <code>DocumentStore</code>
+
+A document store implementation using Valkey with vector search capabilities.
+
+This document store provides persistent storage for documents with embeddings and supports
+vector similarity search using the Valkey Search module. It's designed for high-performance
+retrieval applications requiring both semantic search and metadata filtering.
+
+Key features:
+
+- Vector similarity search with HNSW algorithm
+- Metadata filtering on tag and numeric fields
+- Configurable distance metrics (L2, cosine, inner product)
+- Batch operations for efficient document management
+- Both synchronous and asynchronous operations
+- Cluster and standalone mode support
+
+Supported filterable Document metadata fields:
+
+- meta_category (TagField): exact string matches
+- meta_status (TagField): status filtering
+- meta_priority (NumericField): numeric comparisons
+- meta_score (NumericField): score filtering
+- meta_timestamp (NumericField): date/time filtering
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack_integrations.document_stores.valkey import ValkeyDocumentStore
+
+# Initialize document store
+document_store = ValkeyDocumentStore(
+    nodes_list=[("localhost", 6379)],
+    index_name="my_documents",
+    embedding_dim=768,
+    distance_metric="cosine"
+)
+
+# Store documents with embeddings
+documents = [
+    Document(
+        content="Valkey is a Redis-compatible database",
+        embedding=[0.1, 0.2, ...],  # 768-dim vector
+        meta={"category": "database", "priority": 1}
+    )
+]
+document_store.write_documents(documents)
+
+# Search with filters
+results = document_store._embedding_retrival(
+    embedding=[0.1, 0.15, ...],
+    filters={"field": "meta.category", "operator": "==", "value": "database"},
+    limit=10
+)
+```
+
+#### __init__
+
+```python
+__init__(
+    nodes_list: list[tuple[str, int]] | None = None,
+    *,
+    cluster_mode: bool = False,
+    use_tls: bool = False,
+    username: Secret | None = Secret.from_env_var(
+        "VALKEY_USERNAME", strict=False
+    ),
+    password: Secret | None = Secret.from_env_var(
+        "VALKEY_PASSWORD", strict=False
+    ),
+    request_timeout: int = 500,
+    retry_attempts: int = 3,
+    retry_base_delay_ms: int = 1000,
+    retry_exponent_base: int = 2,
+    batch_size: int = 100,
+    index_name: str = "default",
+    distance_metric: Literal["l2", "cosine", "ip"] = "cosine",
+    embedding_dim: int = 768,
+    metadata_fields: dict[str, type[str] | type[int]] | None = None
+)
+```
+
+Creates a new ValkeyDocumentStore instance.
+
+**Parameters:**
+
+- **nodes_list** (<code>list\[tuple\[str, int\]\] | None</code>) – List of (host, port) tuples for Valkey nodes. Defaults to [("localhost", 6379)].
+- **cluster_mode** (<code>bool</code>) – Whether to connect in cluster mode. Defaults to False.
+- **use_tls** (<code>bool</code>) – Whether to use TLS for connections. Defaults to False.
+- **username** (<code>Secret | None</code>) – Username for authentication. If not provided, reads from VALKEY_USERNAME environment variable.
+  Defaults to None.
+- **password** (<code>Secret | None</code>) – Password for authentication. If not provided, reads from VALKEY_PASSWORD environment variable.
+  Defaults to None.
+- **request_timeout** (<code>int</code>) – Request timeout in milliseconds. Defaults to 500.
+- **retry_attempts** (<code>int</code>) – Number of retry attempts for failed operations. Defaults to 3.
+- **retry_base_delay_ms** (<code>int</code>) – Base delay in milliseconds for exponential backoff. Defaults to 1000.
+- **retry_exponent_base** (<code>int</code>) – Exponent base for exponential backoff calculation. Defaults to 2.
+- **batch_size** (<code>int</code>) – Number of documents to process in a single batch for async operations. Defaults to 100.
+- **index_name** (<code>str</code>) – Name of the search index. Defaults to "haystack_document".
+- **distance_metric** (<code>Literal['l2', 'cosine', 'ip']</code>) – Distance metric for vector similarity. Options: "l2", "cosine", "ip" (inner product).
+  Defaults to "cosine".
+- **embedding_dim** (<code>int</code>) – Dimension of document embeddings. Defaults to 768.
+- **metadata_fields** (<code>dict\[str, type\[str\] | type\[int\]\] | None</code>) – Dictionary mapping metadata field names to Python types for filtering.
+  Supported types: str (for exact matching), int (for numeric comparisons).
+  Example: `{"category": str, "priority": int}`.
+  If not provided, no metadata fields will be indexed for filtering.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes this store to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ValkeyDocumentStore
+```
+
+Deserializes the store from a dictionary.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Return the number of documents stored in the document store.
+
+This method queries the Valkey Search index to get the total count of indexed documents.
+If the index doesn't exist, it returns 0.
+
+**Returns:**
+
+- <code>int</code> – The number of documents in the document store.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error accessing the index or counting documents.
+
+Example:
+
+```python
+document_store = ValkeyDocumentStore()
+count = document_store.count_documents()
+print(f"Total documents: {count}")
+```
+
+#### count_documents_async
+
+```python
+count_documents_async() -> int
+```
+
+Asynchronously return the number of documents stored in the document store.
+
+This method queries the Valkey Search index to get the total count of indexed documents.
+If the index doesn't exist, it returns 0. This is the async version of count_documents().
+
+**Returns:**
+
+- <code>int</code> – The number of documents in the document store.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error accessing the index or counting documents.
+
+Example:
+
+```python
+document_store = ValkeyDocumentStore()
+count = await document_store.count_documents_async()
+print(f"Total documents: {count}")
+```
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Filter documents by metadata without vector search.
+
+This method retrieves documents based on metadata filters without performing vector similarity search.
+Since Valkey Search requires vector queries, this method uses a dummy vector internally and removes
+the similarity scores from results.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional metadata filters in Haystack format. Supports filtering on:
+- meta.category (string equality)
+- meta.status (string equality)
+- meta.priority (numeric comparisons)
+- meta.score (numeric comparisons)
+- meta.timestamp (numeric comparisons)
+
+**Returns:**
+
+- <code>list\[Document\]</code> – List of documents matching the filters, with score set to None.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error filtering documents.
+
+Example:
+
+```python
+# Filter by category
+docs = document_store.filter_documents(
+    filters={"field": "meta.category", "operator": "==", "value": "news"}
+)
+
+# Filter by numeric range
+docs = document_store.filter_documents(
+    filters={"field": "meta.priority", "operator": ">=", "value": 5}
+)
+```
+
+#### filter_documents_async
+
+```python
+filter_documents_async(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Asynchronously filter documents by metadata without vector search.
+
+This is the async version of filter_documents(). It retrieves documents based on metadata filters
+without performing vector similarity search. Since Valkey Search requires vector queries, this method
+uses a dummy vector internally and removes the similarity scores from results.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional metadata filters in Haystack format. Supports filtering on:
+- meta.category (string equality)
+- meta.status (string equality)
+- meta.priority (numeric comparisons)
+- meta.score (numeric comparisons)
+- meta.timestamp (numeric comparisons)
+
+**Returns:**
+
+- <code>list\[Document\]</code> – List of documents matching the filters, with score set to None.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error filtering documents.
+
+Example:
+
+```python
+# Filter by category
+docs = await document_store.filter_documents_async(
+    filters={"field": "meta.category", "operator": "==", "value": "news"}
+)
+
+# Filter by numeric range
+docs = await document_store.filter_documents_async(
+    filters={"field": "meta.priority", "operator": ">=", "value": 5}
+)
+```
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to the document store.
+
+This method stores documents with their embeddings and metadata in Valkey. The search index is
+automatically created if it doesn't exist. Documents without embeddings will be assigned a
+dummy vector for indexing purposes.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of Document objects to store. Each document should have:
+- content: The document text
+- embedding: Vector representation (optional, dummy vector used if missing)
+- meta: Optional metadata dict with supported fields (category, status, priority, score, timestamp)
+- **policy** (<code>DuplicatePolicy</code>) – How to handle duplicate documents. Only NONE and OVERWRITE are supported.
+  Defaults to DuplicatePolicy.NONE.
+
+**Returns:**
+
+- <code>int</code> – Number of documents successfully written.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error writing documents.
+- <code>ValueError</code> – If documents list contains invalid objects.
+
+Example:
+
+```python
+documents = [
+    Document(
+        content="First document",
+        embedding=[0.1, 0.2, 0.3],
+        meta={"category": "news", "priority": 1}
+    ),
+    Document(
+        content="Second document",
+        embedding=[0.4, 0.5, 0.6],
+        meta={"category": "blog", "priority": 2}
+    )
+]
+count = document_store.write_documents(documents)
+print(f"Wrote {count} documents")
+```
+
+#### write_documents_async
+
+```python
+write_documents_async(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Asynchronously write documents to the document store.
+
+This is the async version of write_documents(). It stores documents with their embeddings and
+metadata in Valkey using batch processing for improved performance. The search index is
+automatically created if it doesn't exist.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of Document objects to store. Each document should have:
+- content: The document text
+- embedding: Vector representation (optional, dummy vector used if missing)
+- meta: Optional metadata dict with supported fields (category, status, priority, score, timestamp)
+- **policy** (<code>DuplicatePolicy</code>) – How to handle duplicate documents. Only NONE and OVERWRITE are supported.
+  Defaults to DuplicatePolicy.NONE.
+
+**Returns:**
+
+- <code>int</code> – Number of documents successfully written.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error writing documents.
+- <code>ValueError</code> – If documents list contains invalid objects.
+
+Example:
+
+```python
+documents = [
+    Document(
+        content="First document",
+        embedding=[0.1, 0.2, 0.3],
+        meta={"category": "news", "priority": 1}
+    ),
+    Document(
+        content="Second document",
+        embedding=[0.4, 0.5, 0.6],
+        meta={"category": "blog", "priority": 2}
+    )
+]
+count = await document_store.write_documents_async(documents)
+print(f"Wrote {count} documents")
+```
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents from the document store by their IDs.
+
+This method removes documents from both the Valkey database and the search index.
+If some documents are not found, a warning is logged but the operation continues.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – List of document IDs to delete. These should be the same IDs
+  used when the documents were originally stored.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error deleting documents.
+
+Example:
+
+```python
+# Delete specific documents
+document_store.delete_documents(["doc1", "doc2", "doc3"])
+
+# Delete a single document
+document_store.delete_documents(["single_doc_id"])
+```
+
+#### delete_documents_async
+
+```python
+delete_documents_async(document_ids: list[str]) -> None
+```
+
+Asynchronously delete documents from the document store by their IDs.
+
+This is the async version of delete_documents(). It removes documents from both the Valkey
+database and the search index. If some documents are not found, a warning is logged but
+the operation continues.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – List of document IDs to delete. These should be the same IDs
+  used when the documents were originally stored.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error deleting documents.
+
+Example:
+
+```python
+# Delete specific documents
+await document_store.delete_documents_async(["doc1", "doc2", "doc3"])
+
+# Delete a single document
+await document_store.delete_documents_async(["single_doc_id"])
+```
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Delete all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents to delete.
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – If deletion fails.
+
+#### delete_by_filter_async
+
+```python
+delete_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously delete all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents to delete.
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – If deletion fails.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Update metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents to update.
+- **meta** (<code>dict\[str, Any\]</code>) – Metadata key-value pairs to set on matching documents (merged with existing meta).
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – If update or write fails.
+
+#### update_by_filter_async
+
+```python
+update_by_filter_async(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Asynchronously update metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents to update.
+- **meta** (<code>dict\[str, Any\]</code>) – Metadata key-value pairs to set on matching documents (merged with existing meta).
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – If update or write fails.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Return the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to apply.
+
+**Returns:**
+
+- <code>int</code> – The number of matching documents.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – If counting fails.
+
+#### count_documents_by_filter_async
+
+```python
+count_documents_by_filter_async(filters: dict[str, Any]) -> int
+```
+
+Asynchronously return the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to apply.
+
+**Returns:**
+
+- <code>int</code> – The number of matching documents.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValkeyDocumentStoreError</code> – If counting fails.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Count unique values for each specified metadata field in documents matching the filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents.
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names (e.g. "category" or "meta.category").
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – Dictionary mapping each field name to the count of its unique values.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValueError</code> – If a field in metadata_fields is not configured for filtering.
+- <code>ValkeyDocumentStoreError</code> – If the operation fails.
+
+#### count_unique_metadata_by_filter_async
+
+```python
+count_unique_metadata_by_filter_async(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Asynchronously count unique values for each specified metadata field in documents matching the filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dictionary to select documents.
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names (e.g. "category" or "meta.category").
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – Dictionary mapping each field name to the count of its unique values.
+
+**Raises:**
+
+- <code>FilterError</code> – If the filter structure is invalid.
+- <code>ValueError</code> – If a field in metadata_fields is not configured for filtering.
+- <code>ValkeyDocumentStoreError</code> – If the operation fails.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Return information about metadata fields configured for filtering.
+
+Returns the store's configured metadata field names and their types (as used in the index).
+Field names are returned without the "meta." prefix (e.g. "category", "priority").
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – Dictionary mapping field name to a dict with "type" key ("keyword" for tag, "long" for numeric).
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Return the minimum and maximum values for a numeric metadata field.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name (e.g. "priority" or "meta.priority"). Must be a configured
+  numeric field.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with "min" and "max" keys (values are int/float or None if no values).
+
+**Raises:**
+
+- <code>ValueError</code> – If the field is not configured or is not numeric.
+- <code>ValkeyDocumentStoreError</code> – If the operation fails.
+
+#### get_metadata_field_min_max_async
+
+```python
+get_metadata_field_min_max_async(metadata_field: str) -> dict[str, Any]
+```
+
+Asynchronously return the minimum and maximum values for a numeric metadata field.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name (e.g. "priority" or "meta.priority"). Must be a configured
+  numeric field.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with "min" and "max" keys (values are int/float or None if no values).
+
+**Raises:**
+
+- <code>ValueError</code> – If the field is not configured or is not numeric.
+- <code>ValkeyDocumentStoreError</code> – If the operation fails.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Return unique values for a metadata field with optional search and pagination.
+
+Values are stringified. For tag fields the distinct values are returned; for numeric fields
+the string representation of each distinct value is returned.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name (e.g. "category" or "meta.category").
+- **search_term** (<code>str | None</code>) – Optional case-insensitive substring filter on the value.
+- **from\_** (<code>int</code>) – Start index for pagination (default 0).
+- **size** (<code>int</code>) – Number of values to return (default 10).
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – Tuple of (list of unique values for the requested page, total count of unique values).
+
+**Raises:**
+
+- <code>ValueError</code> – If the field is not configured for filtering.
+- <code>ValkeyDocumentStoreError</code> – If the operation fails.
+
+#### get_metadata_field_unique_values_async
+
+```python
+get_metadata_field_unique_values_async(
+    metadata_field: str,
+    search_term: str | None = None,
+    from_: int = 0,
+    size: int = 10,
+) -> tuple[list[str], int]
+```
+
+Asynchronously return unique values for a metadata field with optional search and pagination.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name (e.g. "category" or "meta.category").
+- **search_term** (<code>str | None</code>) – Optional case-insensitive substring filter on the value.
+- **from\_** (<code>int</code>) – Start index for pagination (default 0).
+- **size** (<code>int</code>) – Number of values to return (default 10).
+
+**Returns:**
+
+- <code>tuple\[list\[str\], int\]</code> – Tuple of (list of unique values for the requested page, total count of unique values).
+
+**Raises:**
+
+- <code>ValueError</code> – If the field is not configured for filtering.
+- <code>ValkeyDocumentStoreError</code> – If the operation fails.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Delete all documents from the document store.
+
+This method removes all documents by dropping the entire search index. This is an efficient
+way to clear all data but requires recreating the index for future operations. If the index
+doesn't exist, the operation completes without error.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error dropping the index.
+
+Warning:
+This operation is irreversible and will permanently delete all documents and the search index.
+
+Example:
+
+```python
+# Clear all documents from the store
+document_store.delete_all_documents()
+
+# The index will be automatically recreated on next write operation
+document_store.write_documents(new_documents)
+```
+
+#### delete_all_documents_async
+
+```python
+delete_all_documents_async() -> None
+```
+
+Asynchronously delete all documents from the document store.
+
+This is the async version of delete_all_documents(). It removes all documents by dropping
+the entire search index. This is an efficient way to clear all data but requires recreating
+the index for future operations. If the index doesn't exist, the operation completes without error.
+
+**Raises:**
+
+- <code>ValkeyDocumentStoreError</code> – If there's an error dropping the index.
+
+Warning:
+This operation is irreversible and will permanently delete all documents and the search index.
+
+Example:
+
+```python
+# Clear all documents from the store
+await document_store.delete_all_documents_async()
+
+# The index will be automatically recreated on next write operation
+await document_store.write_documents_async(new_documents)
+```
+
+## haystack_integrations.document_stores.valkey.filters
+
+Valkey document store filtering utilities.
+
+This module provides filter conversion from Haystack's filter format to Valkey Search query syntax.
+It supports both tag-based exact matching and numeric range filtering with logical operators.
+
+Supported filter operations:
+
+- TagField filters: ==, !=, in, not in (exact string matches)
+- NumericField filters: ==, !=, >, >=, \<, \<=, in, not in (numeric comparisons)
+- Logical operators: AND, OR for combining conditions
+
+Filter syntax examples:
+
+```python
+# Simple equality filter
+filters = {"field": "meta.category", "operator": "==", "value": "tech"}
+
+# Numeric range filter
+filters = {"field": "meta.priority", "operator": ">=", "value": 5}
+
+# List membership filter
+filters = {"field": "meta.status", "operator": "in", "value": ["active", "pending"]}
+
+# Complex logical filter
+filters = {
+    "operator": "AND",
+    "conditions": [
+        {"field": "meta.category", "operator": "==", "value": "tech"},
+        {"field": "meta.priority", "operator": ">=", "value": 3}
+    ]
+}
+```

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/vllm.md

@@ -0,0 +1,697 @@
+---
+title: "vLLM"
+id: integrations-vllm
+description: "vLLM integration for Haystack"
+slug: "/integrations-vllm"
+---
+
+
+## haystack_integrations.components.embedders.vllm.document_embedder
+
+### VLLMDocumentEmbedder
+
+A component for computing Document embeddings using models served with [vLLM](https://docs.vllm.ai/).
+
+The embedding of each Document is stored in the `embedding` field of the Document.
+It expects a vLLM server to be running and accessible at the `api_base_url` parameter and uses the
+OpenAI-compatible Embeddings API exposed by vLLM.
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server with an embedding model:
+
+```bash
+vllm serve google/embeddinggemma-300m
+```
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.vllm import VLLMDocumentEmbedder
+
+doc = Document(content="I love pizza!")
+
+document_embedder = VLLMDocumentEmbedder(model="google/embeddinggemma-300m")
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+```
+
+### Usage example with vLLM-specific parameters
+
+Pass vLLM-specific parameters via the `extra_parameters` dictionary. They are forwarded as `extra_body`
+to the OpenAI-compatible endpoint.
+
+```python
+document_embedder = VLLMDocumentEmbedder(
+    model="google/embeddinggemma-300m",
+    extra_parameters={"truncate_prompt_tokens": 256, "truncation_side": "right"},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    model: str,
+    api_key: Secret | None = Secret.from_env_var("VLLM_API_KEY", strict=False),
+    api_base_url: str = "http://localhost:8000/v1",
+    prefix: str = "",
+    suffix: str = "",
+    dimensions: int | None = None,
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None,
+    raise_on_failure: bool = False,
+    extra_parameters: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of VLLMDocumentEmbedder.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the model served by vLLM. Check
+  [vLLM documentation](https://docs.vllm.ai/en/stable/models/pooling_models) for more information.
+- **api_key** (<code>Secret | None</code>) – The vLLM API key. Defaults to the `VLLM_API_KEY` environment variable.
+  Only required if the vLLM server was started with `--api-key`.
+- **api_base_url** (<code>str</code>) – The base URL of the vLLM server.
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **dimensions** (<code>int | None</code>) – The number of dimensions of the resulting embedding. Only models trained with
+  Matryoshka Representation Learning support this parameter. See
+  [vLLM documentation](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#matryoshka-embeddings)
+  for more information.
+- **batch_size** (<code>int</code>) – Number of documents to encode at once.
+- **progress_bar** (<code>bool</code>) – Whether to show a progress bar.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields to embed along with the document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the document text.
+- **timeout** (<code>float | None</code>) – Timeout in seconds for vLLM client calls. If not set, the OpenAI client default applies.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries for failed requests. If not set, the OpenAI client
+  default applies.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client` or
+  `httpx.AsyncClient`. For more information, see the
+  [HTTPX documentation](https://www.python-httpx.org/api/#client).
+- **raise_on_failure** (<code>bool</code>) – Whether to raise an exception if the embedding request fails. If `False`,
+  the component logs the error and continues processing the remaining documents.
+- **extra_parameters** (<code>dict\[str, Any\] | None</code>) – Additional parameters forwarded as `extra_body` to the vLLM embeddings
+  endpoint. Use this to pass parameters not part of the standard OpenAI Embeddings API, such as
+  `truncate_prompt_tokens`, `truncation_side`, etc. See the
+  [vLLM Embeddings API docs](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#openai-compatible-embeddings-api).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the OpenAI clients.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Embed a list of Documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with:
+- `documents`: The input documents with their `embedding` field populated.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(
+    documents: list[Document],
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Asynchronously embed a list of Documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with:
+- `documents`: The input documents with their `embedding` field populated.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.embedders.vllm.text_embedder
+
+### VLLMTextEmbedder
+
+A component for embedding strings using models served with [vLLM](https://docs.vllm.ai/).
+
+It expects a vLLM server to be running and accessible at the `api_base_url` parameter and uses the
+OpenAI-compatible Embeddings API exposed by vLLM.
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server with an embedding model:
+
+```bash
+vllm serve google/embeddinggemma-300m
+```
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### Usage example
+
+```python
+from haystack_integrations.components.embedders.vllm import VLLMTextEmbedder
+
+text_embedder = VLLMTextEmbedder(model="google/embeddinggemma-300m")
+print(text_embedder.run("I love pizza!"))
+```
+
+### Usage example with vLLM-specific parameters
+
+Pass vLLM-specific parameters via the `extra_parameters` dictionary. They are forwarded as `extra_body`
+to the OpenAI-compatible endpoint.
+
+```python
+text_embedder = VLLMTextEmbedder(
+    model="google/embeddinggemma-300m",
+    extra_parameters={"truncate_prompt_tokens": 256, "truncation_side": "right"},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    model: str,
+    api_key: Secret | None = Secret.from_env_var("VLLM_API_KEY", strict=False),
+    api_base_url: str = "http://localhost:8000/v1",
+    prefix: str = "",
+    suffix: str = "",
+    dimensions: int | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None,
+    extra_parameters: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of VLLMTextEmbedder.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the model served by vLLM (e.g., "intfloat/e5-mistral-7b-instruct").
+- **api_key** (<code>Secret | None</code>) – The vLLM API key. Defaults to the `VLLM_API_KEY` environment variable.
+  Only required if the vLLM server was started with `--api-key`.
+- **api_base_url** (<code>str</code>) – The base URL of the vLLM server.
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text to embed.
+- **suffix** (<code>str</code>) – A string to add at the end of each text to embed.
+- **dimensions** (<code>int | None</code>) – The number of dimensions of the resulting embedding. Only models trained with
+  Matryoshka Representation Learning support this parameter. See
+  [vLLM documentation](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#matryoshka-embeddings)
+  for more information.
+- **timeout** (<code>float | None</code>) – Timeout in seconds for vLLM client calls. If not set, the OpenAI client default applies.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries for failed requests. If not set, the OpenAI client
+  default applies.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client` or
+  `httpx.AsyncClient`. For more information, see the
+  [HTTPX documentation](https://www.python-httpx.org/api/#client).
+- **extra_parameters** (<code>dict\[str, Any\] | None</code>) – Additional parameters forwarded as `extra_body` to the vLLM embeddings
+  endpoint. Use this to pass parameters not part of the standard OpenAI Embeddings API, such as
+  `truncate_prompt_tokens`, `truncation_side`, `additional_data`, `use_activation`, etc. See the
+  [vLLM Embeddings API docs](https://docs.vllm.ai/en/stable/models/pooling_models/embed/#openai-compatible-embeddings-api).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the OpenAI clients.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Embed a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – A dictionary with:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Asynchronously embed a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – A dictionary with:
+- `embedding`: The embedding of the input text.
+- `meta`: Information about the usage of the model.
+
+## haystack_integrations.components.generators.vllm.chat.chat_generator
+
+### VLLMChatGenerator
+
+A component for generating chat completions using models served with [vLLM](https://docs.vllm.ai/).
+
+It expects a vLLM server to be running and accessible at the `api_base_url` parameter.
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server:
+
+```bash
+vllm serve Qwen/Qwen3-4B-Instruct-2507
+```
+
+For reasoning models, start the server with the appropriate reasoning parser:
+
+```bash
+vllm serve Qwen/Qwen3-0.6B --reasoning-parser qwen3
+```
+
+For tool calling, the server must be started with `--enable-auto-tool-choice` and `--tool-call-parser`:
+
+```bash
+vllm serve Qwen/Qwen3-0.6B --enable-auto-tool-choice --tool-call-parser hermes
+```
+
+The available tool call parsers depend on the model. See the
+[vLLM tool calling docs](https://docs.vllm.ai/en/stable/features/tool_calling/) for the full list.
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### Usage example
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+generator = VLLMChatGenerator(
+    model="Qwen/Qwen3-0.6B",
+    generation_kwargs={"max_tokens": 512, "temperature": 0.7},
+)
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+response = generator.run(messages=messages)
+print(response["replies"][0].text)
+```
+
+### Usage example with vLLM-specific parameters
+
+Pass the vLLM-specific parameters inside the `generation_kwargs`["extra_body"] dictionary.
+
+```python
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+generator = VLLMChatGenerator(
+    model="Qwen/Qwen3-0.6B",
+    generation_kwargs={
+        "max_tokens": 512,
+        "extra_body": {
+            "top_k": 50,
+            "min_tokens": 10,
+            "repetition_penalty": 1.1,
+        },
+    },
+)
+```
+
+### Usage example with tool calling
+
+To use tool calling, start the vLLM server with `--enable-auto-tool-choice` and `--tool-call-parser`.
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack.tools import tool
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+@tool
+def weather(city: str) -> str:
+    """Get the weather in a given city."""
+    return f"The weather in {city} is sunny"
+
+generator = VLLMChatGenerator(model="Qwen/Qwen3-0.6B", tools=[weather])
+
+messages = [ChatMessage.from_user("What is the weather in Paris?")]
+response = generator.run(messages=messages)
+print(response["replies"][0].tool_calls)
+```
+
+### Usage example with reasoning models
+
+To use reasoning models, start the vLLM server with `--reasoning-parser`.
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.generators.vllm import VLLMChatGenerator
+
+generator = VLLMChatGenerator(model="Qwen/Qwen3-0.6B")
+
+messages = [ChatMessage.from_user("Solve step by step: what is 15 * 37?")]
+response = generator.run(messages=messages)
+reply = response["replies"][0]
+if reply.reasoning:
+    print("Reasoning:", reply.reasoning.reasoning_text)
+print("Answer:", reply.text)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    model: str,
+    api_key: Secret | None = Secret.from_env_var("VLLM_API_KEY", strict=False),
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: str = "http://localhost:8000/v1",
+    generation_kwargs: dict[str, Any] | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    tools: ToolsType | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of VLLMChatGenerator.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the model served by vLLM (e.g., "Qwen/Qwen3-0.6B").
+- **api_key** (<code>Secret | None</code>) – The vLLM API key. Defaults to the `VLLM_API_KEY` environment variable.
+  Only required if the vLLM server was started with `--api-key`.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts
+  [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk)
+  as an argument.
+- **api_base_url** (<code>str</code>) – The base URL of the vLLM server.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional parameters for text generation. These parameters are sent directly to
+  the vLLM OpenAI-compatible endpoint. See
+  [vLLM documentation](https://docs.vllm.ai/en/stable/serving/openai_compatible_server/)
+  for more details.
+  Some of the supported parameters:
+- `max_tokens`: Maximum number of tokens to generate.
+- `temperature`: Sampling temperature.
+- `top_p`: Nucleus sampling parameter.
+- `n`: Number of completions to generate for each prompt.
+- `stop`: One or more sequences after which the model should stop generating tokens.
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the response.
+- `extra_body`: A dictionary of vLLM-specific parameters not part of the standard OpenAI API
+  (e.g., `top_k`, `min_tokens`, `repetition_penalty`).
+- **timeout** (<code>float | None</code>) – Timeout for vLLM client calls. If not set, it defaults to the default set by the OpenAI client.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to attempt for failed requests. If not set, it defaults to the default
+  set by the OpenAI client.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  Each tool should have a unique name. Not all models support tools.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client` or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the OpenAI clients and warm up tools.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> VLLMChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>VLLMChatGenerator</code> – The deserialized component instance.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage],
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Run the VLLM chat generator on the given input data.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will
+  override the parameters passed during component initialization.
+  For details on vLLM API parameters, see
+  [vLLM documentation](https://docs.vllm.ai/en/stable/serving/openai_compatible_server/).
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+#### run_async
+
+```python
+run_async(
+    messages: list[ChatMessage],
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Run the VLLM chat generator on the given input data asynchronously.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances representing the input messages.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  Must be a coroutine.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will
+  override the parameters passed during component initialization.
+  For details on vLLM API parameters, see
+  [vLLM documentation](https://docs.vllm.ai/en/stable/serving/openai_compatible_server/).
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+## haystack_integrations.components.rankers.vllm.ranker
+
+### VLLMRanker
+
+Ranks Documents based on their similarity to a query using models served with [vLLM](https://docs.vllm.ai/).
+
+It expects a vLLM server to be running and accessible at the `api_base_url` parameter and uses the
+`/rerank` endpoint exposed by vLLM.
+
+### Starting the vLLM server
+
+Before using this component, start a vLLM server with a reranker model:
+
+```bash
+vllm serve BAAI/bge-reranker-base
+```
+
+For details on server options, see the [vLLM CLI docs](https://docs.vllm.ai/en/stable/cli/serve/).
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.vllm import VLLMRanker
+
+ranker = VLLMRanker(model="BAAI/bge-reranker-base")
+docs = [
+    Document(content="The capital of Brazil is Brasilia."),
+    Document(content="The capital of France is Paris."),
+]
+result = ranker.run(query="What is the capital of France?", documents=docs)
+print(result["documents"][0].content)
+```
+
+### Usage example with vLLM-specific parameters
+
+Pass vLLM-specific parameters via the `extra_parameters` dictionary. They are merged into the
+request body sent to the `/rerank` endpoint.
+
+```python
+ranker = VLLMRanker(
+    model="BAAI/bge-reranker-base",
+    extra_parameters={"truncate_prompt_tokens": 256},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    model: str,
+    api_key: Secret | None = Secret.from_env_var("VLLM_API_KEY", strict=False),
+    api_base_url: str = "http://localhost:8000/v1",
+    top_k: int | None = None,
+    score_threshold: float | None = None,
+    meta_fields_to_embed: list[str] | None = None,
+    meta_data_separator: str = "\n",
+    http_client_kwargs: dict[str, Any] | None = None,
+    extra_parameters: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of VLLMRanker.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the reranker model served by vLLM. Check
+  [vLLM documentation](https://docs.vllm.ai/en/stable/models/pooling_models/scoring/#supported-models) for
+  information on supported models.
+- **api_key** (<code>Secret | None</code>) – The vLLM API key. Defaults to the `VLLM_API_KEY` environment variable.
+  Only required if the vLLM server was started with `--api-key`.
+- **api_base_url** (<code>str</code>) – The base URL of the vLLM server.
+- **top_k** (<code>int | None</code>) – The maximum number of Documents to return. If `None`, all documents are returned.
+- **score_threshold** (<code>float | None</code>) – If set, documents with a relevance score below this value are dropped.
+  Applied after `top_k`, so the output may contain fewer than `top_k` documents.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be concatenated with the document
+  content before reranking.
+- **meta_data_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the document content.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client` or
+  `httpx.AsyncClient`. For more information, see the
+  [HTTPX documentation](https://www.python-httpx.org/api/#client).
+- **extra_parameters** (<code>dict\[str, Any\] | None</code>) – Additional parameters merged into the request body sent to the vLLM
+  `/rerank` endpoint. Use this to pass parameters not part of the standard rerank API, such as
+  `truncate_prompt_tokens`. See the
+  [vLLM docs](https://docs.vllm.ai/en/stable/models/pooling_models/scoring/#rerank-api) for more information.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the httpx clients.
+
+#### run
+
+```python
+run(
+    query: str,
+    documents: list[Document],
+    top_k: int | None = None,
+    score_threshold: float | None = None,
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Returns a list of Documents ranked by their similarity to the given query.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Query string.
+- **documents** (<code>list\[Document\]</code>) – List of Documents to rank.
+- **top_k** (<code>int | None</code>) – The maximum number of Documents to return. Overrides the value set at initialization.
+- **score_threshold** (<code>float | None</code>) – Minimum relevance score required for a document to be returned. Overrides
+  the value set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with:
+- `documents`: Documents sorted from most to least relevant.
+- `meta`: Information about the model and usage.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.
+
+#### run_async
+
+```python
+run_async(
+    query: str,
+    documents: list[Document],
+    top_k: int | None = None,
+    score_threshold: float | None = None,
+) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Asynchronously returns a list of Documents ranked by their similarity to the given query.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Query string.
+- **documents** (<code>list\[Document\]</code>) – List of Documents to rank.
+- **top_k** (<code>int | None</code>) – The maximum number of Documents to return. Overrides the value set at initialization.
+- **score_threshold** (<code>float | None</code>) – Minimum relevance score required for a document to be returned. Overrides
+  the value set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with:
+- `documents`: Documents sorted from most to least relevant.
+- `meta`: Information about the model and usage.
+
+**Raises:**
+
+- <code>ValueError</code> – If `top_k` is not > 0.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/watsonx.md

@@ -0,0 +1,699 @@
+---
+title: "IBM watsonx.ai"
+id: integrations-watsonx
+description: "IBM watsonx.ai integration for Haystack"
+slug: "/integrations-watsonx"
+---
+
+
+## haystack_integrations.components.embedders.watsonx.document_embedder
+
+### WatsonxDocumentEmbedder
+
+Computes document embeddings using IBM watsonx.ai models.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.watsonx.document_embedder import WatsonxDocumentEmbedder
+
+documents = [
+    Document(content="I love pizza!"),
+    Document(content="Pasta is great too"),
+]
+
+document_embedder = WatsonxDocumentEmbedder(
+    model="ibm/slate-30m-english-rtrvr-v2",
+    api_key=Secret.from_env_var("WATSONX_API_KEY"),
+    api_base_url="https://us-south.ml.cloud.ibm.com",
+    project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+
+result = document_embedder.run(documents=documents)
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    model: str = "ibm/slate-30m-english-rtrvr-v2",
+    api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"),
+    api_base_url: str = "https://us-south.ml.cloud.ibm.com",
+    project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"),
+    truncate_input_tokens: int | None = None,
+    prefix: str = "",
+    suffix: str = "",
+    batch_size: int = 1000,
+    concurrency_limit: int = 5,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n"
+)
+```
+
+Creates a WatsonxDocumentEmbedder component.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the model to use for calculating embeddings.
+  Default is "ibm/slate-30m-english-rtrvr-v2".
+- **api_key** (<code>Secret</code>) – The WATSONX API key. Can be set via environment variable WATSONX_API_KEY.
+- **api_base_url** (<code>str</code>) – The WATSONX URL for the watsonx.ai service.
+  Default is "https://us-south.ml.cloud.ibm.com".
+- **project_id** (<code>Secret</code>) – The ID of the Watson Studio project.
+  Can be set via environment variable WATSONX_PROJECT_ID.
+- **truncate_input_tokens** (<code>int | None</code>) – Maximum number of tokens to use from the input text.
+  If set to `None` (or not provided), the full input text is used, up to the model's maximum token limit.
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **batch_size** (<code>int</code>) – Number of documents to embed in one API call. Default is 1000.
+- **concurrency_limit** (<code>int</code>) – Number of parallel requests to make. Default is 5.
+- **timeout** (<code>float | None</code>) – Timeout for API requests in seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries for API requests.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> 'WatsonxDocumentEmbedder'
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>'WatsonxDocumentEmbedder'</code> – The deserialized component instance.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document] | dict[str, Any]]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\] | dict\[str, Any\]\]</code> – A dictionary with:
+- 'documents': List of Documents with embeddings added
+- 'meta': Information about the model usage
+
+## haystack_integrations.components.embedders.watsonx.text_embedder
+
+### WatsonxTextEmbedder
+
+Embeds strings using IBM watsonx.ai foundation models.
+
+You can use it to embed user query and send it to an embedding Retriever.
+
+### Usage example
+
+```python
+from haystack_integrations.components.embedders.watsonx.text_embedder import WatsonxTextEmbedder
+
+text_to_embed = "I love pizza!"
+
+text_embedder = WatsonxTextEmbedder(
+    model="ibm/slate-30m-english-rtrvr-v2",
+    api_key=Secret.from_env_var("WATSONX_API_KEY"),
+    api_base_url="https://us-south.ml.cloud.ibm.com",
+    project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+
+print(text_embedder.run(text_to_embed))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+#  'meta': {'model': 'ibm/slate-30m-english-rtrvr-v2',
+#           'truncated_input_tokens': 3}}
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    model: str = "ibm/slate-30m-english-rtrvr-v2",
+    api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"),
+    api_base_url: str = "https://us-south.ml.cloud.ibm.com",
+    project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"),
+    truncate_input_tokens: int | None = None,
+    prefix: str = "",
+    suffix: str = "",
+    timeout: float | None = None,
+    max_retries: int | None = None
+)
+```
+
+Creates an WatsonxTextEmbedder component.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – The name of the IBM watsonx model to use for calculating embeddings.
+  Default is "ibm/slate-30m-english-rtrvr-v2".
+- **api_key** (<code>Secret</code>) – The WATSONX API key. Can be set via environment variable WATSONX_API_KEY.
+- **api_base_url** (<code>str</code>) – The WATSONX URL for the watsonx.ai service.
+  Default is "https://us-south.ml.cloud.ibm.com".
+- **project_id** (<code>Secret</code>) – The ID of the Watson Studio project.
+  Can be set via environment variable WATSONX_PROJECT_ID.
+- **truncate_input_tokens** (<code>int | None</code>) – Maximum number of tokens to use from the input text.
+  If set to `None` (or not provided), the full input text is used, up to the model's maximum token limit.
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text to embed.
+- **suffix** (<code>str</code>) – A string to add at the end of each text to embed.
+- **timeout** (<code>float | None</code>) – Timeout for API requests in seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retries for API requests.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WatsonxTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>WatsonxTextEmbedder</code> – The deserialized component instance.
+
+#### run
+
+```python
+run(text: str) -> dict[str, list[float] | dict[str, Any]]
+```
+
+Embeds a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[float\] | dict\[str, Any\]\]</code> – A dictionary with:
+- 'embedding': The embedding of the input text
+- 'meta': Information about the model usage
+
+## haystack_integrations.components.generators.watsonx.chat.chat_generator
+
+### WatsonxChatGenerator
+
+Enables chat completions using IBM's watsonx.ai foundation models.
+
+This component interacts with IBM's watsonx.ai platform to generate chat responses using various foundation
+models. It supports the [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage) format for both input
+and output, including multimodal inputs with text and images.
+
+The generator works with IBM's foundation models that are listed
+[here](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx&audience=wdp).
+
+You can customize the generation behavior by passing parameters to the watsonx.ai API through the
+`generation_kwargs` argument. These parameters are passed directly to the watsonx.ai inference endpoint.
+
+For details on watsonx.ai API parameters, see
+[IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-parameters.html).
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.watsonx.chat.chat_generator import WatsonxChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+messages = [ChatMessage.from_user("Explain quantum computing in simple terms")]
+
+client = WatsonxChatGenerator(
+    api_key=Secret.from_env_var("WATSONX_API_KEY"),
+    model="ibm/granite-4-h-small",
+    project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+response = client.run(messages)
+print(response)
+```
+
+### Multimodal usage example
+
+```python
+from haystack.dataclasses import ChatMessage, ImageContent
+
+# Create an image from file path or base64
+image_content = ImageContent.from_file_path("path/to/your/image.jpg")
+
+# Create a multimodal message with both text and image
+messages = [ChatMessage.from_user(content_parts=["What's in this image?", image_content])]
+
+# Use a multimodal model
+client = WatsonxChatGenerator(
+    api_key=Secret.from_env_var("WATSONX_API_KEY"),
+    model="meta-llama/llama-3-2-11b-vision-instruct",
+    project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+response = client.run(messages)
+print(response)
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "ibm/granite-3-1-8b-base",
+    "ibm/granite-3-8b-instruct",
+    "ibm/granite-4-h-small",
+    "ibm/granite-8b-code-instruct",
+    "ibm/granite-guardian-3-8b",
+    "meta-llama/llama-3-1-70b-gptq",
+    "meta-llama/llama-3-1-8b",
+    "meta-llama/llama-3-2-11b-vision-instruct",
+    "meta-llama/llama-3-2-90b-vision-instruct",
+    "meta-llama/llama-3-3-70b-instruct",
+    "meta-llama/llama-3-405b-instruct",
+    "meta-llama/llama-4-maverick-17b-128e-instruct-fp8",
+    "meta-llama/llama-guard-3-11b-vision",
+    "mistral-large-2512",
+    "mistralai/mistral-medium-2505",
+    "mistralai/mistral-small-3-1-24b-instruct-2503",
+    "openai/gpt-oss-120b",
+]
+
+```
+
+A non-exhaustive list of models supported by this component.
+
+See https://www.ibm.com/docs/en/watsonx/saas?topic=solutions-supported-foundation-models for the
+full list of models and up-to-date model IDs.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"),
+    model: str = "ibm/granite-4-h-small",
+    project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"),
+    api_base_url: str = "https://us-south.ml.cloud.ibm.com",
+    generation_kwargs: dict[str, Any] | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    verify: bool | str | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    tools: ToolsType | None = None
+) -> None
+```
+
+Creates an instance of WatsonxChatGenerator.
+
+Before initializing the component, you can set environment variables:
+
+- `WATSONX_TIMEOUT` to override the default timeout
+- `WATSONX_MAX_RETRIES` to override the default retry count
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – IBM Cloud API key for watsonx.ai access.
+  Can be set via `WATSONX_API_KEY` environment variable or passed directly.
+- **model** (<code>str</code>) – The model ID to use for completions. Defaults to "ibm/granite-4-h-small".
+  Available models can be found in your IBM Cloud account.
+- **project_id** (<code>Secret</code>) – IBM Cloud project ID
+- **api_base_url** (<code>str</code>) – Custom base URL for the API endpoint.
+  Defaults to "https://us-south.ml.cloud.ibm.com".
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional parameters to control text generation.
+  These parameters are passed directly to the watsonx.ai inference endpoint.
+  Supported parameters include:
+- `temperature`: Controls randomness (lower = more deterministic)
+- `max_new_tokens`: Maximum number of tokens to generate
+- `min_new_tokens`: Minimum number of tokens to generate
+- `top_p`: Nucleus sampling probability threshold
+- `top_k`: Number of highest probability tokens to consider
+- `repetition_penalty`: Penalty for repeated tokens
+- `length_penalty`: Penalty based on output length
+- `stop_sequences`: List of sequences where generation should stop
+- `random_seed`: Seed for reproducible results
+- **timeout** (<code>float | None</code>) – Timeout in seconds for API requests.
+  Defaults to environment variable `WATSONX_TIMEOUT` or 30 seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retry attempts for failed requests.
+  Defaults to environment variable `WATSONX_MAX_RETRIES` or 5.
+- **verify** (<code>bool | str | None</code>) – SSL verification setting. Can be:
+- True: Verify SSL certificates (default)
+- False: Skip verification (insecure)
+- Path to CA bundle for custom certificates
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function for streaming responses.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WatsonxChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>WatsonxChatGenerator</code> – The deserialized component instance.
+
+#### run
+
+```python
+run(
+    *,
+    messages: list[ChatMessage],
+    generation_kwargs: dict[str, Any] | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Generate chat completions synchronously.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+  passed in the `__init__` method.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  If provided this will override the `streaming_callback` set in the `__init__` method.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+#### run_async
+
+```python
+run_async(
+    *,
+    messages: list[ChatMessage],
+    generation_kwargs: dict[str, Any] | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Generate chat completions asynchronously.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage instances representing the input messages.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+  passed in the `__init__` method.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  If provided this will override the `streaming_callback` set in the `__init__` method.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+## haystack_integrations.components.generators.watsonx.generator
+
+### WatsonxGenerator
+
+Bases: <code>WatsonxChatGenerator</code>
+
+Enables text completions using IBM's watsonx.ai foundation models.
+
+This component extends WatsonxChatGenerator to provide the standard Generator interface that works with prompt
+strings instead of ChatMessage objects.
+
+The generator works with IBM's foundation models that are listed
+[here](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx&audience=wdp).
+
+You can customize the generation behavior by passing parameters to the watsonx.ai API through the
+`generation_kwargs` argument. These parameters are passed directly to the watsonx.ai inference endpoint.
+
+For details on watsonx.ai API parameters, see
+[IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-parameters.html).
+
+### Usage example
+
+```python
+from haystack_integrations.components.generators.watsonx.generator import WatsonxGenerator
+from haystack.utils import Secret
+
+generator = WatsonxGenerator(
+    api_key=Secret.from_env_var("WATSONX_API_KEY"),
+    model="ibm/granite-4-h-small",
+    project_id=Secret.from_env_var("WATSONX_PROJECT_ID"),
+)
+
+response = generator.run(
+    prompt="Explain quantum computing in simple terms",
+    system_prompt="You are a helpful physics teacher.",
+)
+print(response)
+```
+
+Output:
+
+```
+{
+    "replies": ["Quantum computing uses quantum-mechanical phenomena like...."],
+    "meta": [
+        {
+            "model": "ibm/granite-4-h-small",
+            "project_id": "your-project-id",
+            "usage": {
+                "prompt_tokens": 12,
+                "completion_tokens": 45,
+                "total_tokens": 57,
+            },
+        }
+    ],
+}
+```
+
+#### SUPPORTED_MODELS
+
+```python
+SUPPORTED_MODELS: list[str] = [
+    "ibm/granite-3-1-8b-base",
+    "ibm/granite-3-8b-instruct",
+    "ibm/granite-4-h-small",
+    "ibm/granite-8b-code-instruct",
+    "ibm/granite-guardian-3-8b",
+    "meta-llama/llama-3-1-70b-gptq",
+    "meta-llama/llama-3-1-8b",
+    "meta-llama/llama-3-2-11b-vision-instruct",
+    "meta-llama/llama-3-2-90b-vision-instruct",
+    "meta-llama/llama-3-3-70b-instruct",
+    "meta-llama/llama-3-405b-instruct",
+    "meta-llama/llama-4-maverick-17b-128e-instruct-fp8",
+    "meta-llama/llama-guard-3-11b-vision",
+    "mistral-large-2512",
+    "mistralai/mistral-medium-2505",
+    "mistralai/mistral-small-3-1-24b-instruct-2503",
+    "openai/gpt-oss-120b",
+]
+
+```
+
+A non-exhaustive list of models supported by this component.
+
+See https://www.ibm.com/docs/en/watsonx/saas?topic=solutions-supported-foundation-models for the
+full list of models and up-to-date model IDs.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"),
+    model: str = "ibm/granite-4-h-small",
+    project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"),
+    api_base_url: str = "https://us-south.ml.cloud.ibm.com",
+    system_prompt: str | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    verify: bool | str | None = None,
+    streaming_callback: StreamingCallbackT | None = None
+) -> None
+```
+
+Creates an instance of WatsonxGenerator.
+
+Before initializing the component, you can set environment variables:
+
+- `WATSONX_TIMEOUT` to override the default timeout
+- `WATSONX_MAX_RETRIES` to override the default retry count
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – IBM Cloud API key for watsonx.ai access.
+  Can be set via `WATSONX_API_KEY` environment variable or passed directly.
+- **model** (<code>str</code>) – The model ID to use for completions. Defaults to "ibm/granite-4-h-small".
+  Available models can be found in your IBM Cloud account.
+- **project_id** (<code>Secret</code>) – IBM Cloud project ID
+- **api_base_url** (<code>str</code>) – Custom base URL for the API endpoint.
+  Defaults to "https://us-south.ml.cloud.ibm.com".
+- **system_prompt** (<code>str | None</code>) – The system prompt to use for text generation.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional parameters to control text generation.
+  These parameters are passed directly to the watsonx.ai inference endpoint.
+  Supported parameters include:
+- `temperature`: Controls randomness (lower = more deterministic)
+- `max_new_tokens`: Maximum number of tokens to generate
+- `min_new_tokens`: Minimum number of tokens to generate
+- `top_p`: Nucleus sampling probability threshold
+- `top_k`: Number of highest probability tokens to consider
+- `repetition_penalty`: Penalty for repeated tokens
+- `length_penalty`: Penalty based on output length
+- `stop_sequences`: List of sequences where generation should stop
+- `random_seed`: Seed for reproducible results
+- **timeout** (<code>float | None</code>) – Timeout in seconds for API requests.
+  Defaults to environment variable `WATSONX_TIMEOUT` or 30 seconds.
+- **max_retries** (<code>int | None</code>) – Maximum number of retry attempts for failed requests.
+  Defaults to environment variable `WATSONX_MAX_RETRIES` or 5.
+- **verify** (<code>bool | str | None</code>) – SSL verification setting. Can be:
+- True: Verify SSL certificates (default)
+- False: Skip verification (insecure)
+- Path to CA bundle for custom certificates
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function for streaming responses.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WatsonxGenerator
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>WatsonxGenerator</code> – The deserialized component instance.
+
+#### run
+
+```python
+run(
+    *,
+    prompt: str,
+    system_prompt: str | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Generate text completions synchronously.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – The input prompt string for text generation.
+- **system_prompt** (<code>str | None</code>) – An optional system prompt to provide context or instructions for the generation.
+  If not provided, the system prompt set in the `__init__` method will be used.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  If provided, this will override the `streaming_callback` set in the `__init__` method.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+  passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `replies`: A list of generated text completions as strings.
+- `meta`: A list of metadata dictionaries containing information about each generation,
+  including model name, finish reason, and token usage statistics.
+
+#### run_async
+
+```python
+run_async(
+    *,
+    prompt: str,
+    system_prompt: str | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Generate text completions asynchronously.
+
+**Parameters:**
+
+- **prompt** (<code>str</code>) – The input prompt string for text generation.
+- **system_prompt** (<code>str | None</code>) – An optional system prompt to provide context or instructions for the generation.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  If provided, this will override the `streaming_callback` set in the `__init__` method.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will potentially override the parameters
+  passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `replies`: A list of generated text completions as strings.
+- `meta`: A list of metadata dictionaries containing information about each generation,
+  including model name, finish reason, and token usage statistics.

docs-website/reference_versioned_docs/version-2.28-unstable/integrations-api/weave.md

@@ -0,0 +1,248 @@
+---
+title: "Weave"
+id: integrations-weave
+description: "Weights & Bias integration for Haystack"
+slug: "/integrations-weave"
+---
+
+<a id="haystack_integrations.components.connectors.weave.weave_connector"></a>
+
+## Module haystack\_integrations.components.connectors.weave.weave\_connector
+
+<a id="haystack_integrations.components.connectors.weave.weave_connector.WeaveConnector"></a>
+
+### WeaveConnector
+
+Collects traces from your pipeline and sends them to Weights & Biases.
+
+Add this component to your pipeline to integrate with the Weights & Biases Weave framework for tracing and
+monitoring your pipeline components.
+
+Note that you need to have the `WANDB_API_KEY` environment variable set to your Weights & Biases API key.
+
+NOTE: If you don't have a Weights & Biases account it will interactively ask you to set one and your input
+will then be stored in ~/.netrc
+
+In addition, you need to set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true` in order to
+enable Haystack tracing in your pipeline.
+
+To use this connector simply add it to your pipeline without any connections, and it will automatically start
+sending traces to Weights & Biases.
+
+**Example**:
+
+```python
+import os
+
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.components.connectors import WeaveConnector
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", OpenAIChatGenerator(model="gpt-3.5-turbo"))
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+connector = WeaveConnector(pipeline_name="test_pipeline")
+pipe.add_component("weave", connector)
+
+messages = [
+    ChatMessage.from_system(
+        "Always respond in German even if some input data is in other languages."
+    ),
+    ChatMessage.from_user("Tell me about {{location}}"),
+]
+
+response = pipe.run(
+    data={
+        "prompt_builder": {
+            "template_variables": {"location": "Berlin"},
+            "template": messages,
+        }
+    }
+)
+print(response["llm"]["replies"][0])
+```
+  
+  You should then head to `https://wandb.ai/<user_name>/projects` and see the complete trace for your pipeline under
+  the pipeline name you specified, when creating the `WeaveConnector`
+
+<a id="haystack_integrations.components.connectors.weave.weave_connector.WeaveConnector.__init__"></a>
+
+#### WeaveConnector.\_\_init\_\_
+
+```python
+def __init__(pipeline_name: str,
+             weave_init_kwargs: dict[str, Any] | None = None) -> None
+```
+
+Initialize WeaveConnector.
+
+**Arguments**:
+
+- `pipeline_name`: The name of the pipeline you want to trace.
+- `weave_init_kwargs`: Additional arguments to pass to the WeaveTracer client.
+
+<a id="haystack_integrations.components.connectors.weave.weave_connector.WeaveConnector.warm_up"></a>
+
+#### WeaveConnector.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Initialize the WeaveTracer.
+
+<a id="haystack_integrations.components.connectors.weave.weave_connector.WeaveConnector.to_dict"></a>
+
+#### WeaveConnector.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with all the necessary information to recreate this component.
+
+<a id="haystack_integrations.components.connectors.weave.weave_connector.WeaveConnector.from_dict"></a>
+
+#### WeaveConnector.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "WeaveConnector"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="haystack_integrations.tracing.weave.tracer"></a>
+
+## Module haystack\_integrations.tracing.weave.tracer
+
+<a id="haystack_integrations.tracing.weave.tracer.WeaveSpan"></a>
+
+### WeaveSpan
+
+A bridge between Haystack's Span interface and Weave's Call object.
+
+Stores metadata about a component execution and its inputs and outputs, and manages the attributes/tags
+that describe the operation.
+
+<a id="haystack_integrations.tracing.weave.tracer.WeaveSpan.set_tag"></a>
+
+#### WeaveSpan.set\_tag
+
+```python
+def set_tag(key: str, value: Any) -> None
+```
+
+Set a tag by adding it to the call's inputs.
+
+**Arguments**:
+
+- `key`: The tag key.
+- `value`: The tag value.
+
+<a id="haystack_integrations.tracing.weave.tracer.WeaveSpan.raw_span"></a>
+
+#### WeaveSpan.raw\_span
+
+```python
+def raw_span() -> Any
+```
+
+Access to the underlying Weave Call object.
+
+<a id="haystack_integrations.tracing.weave.tracer.WeaveSpan.get_correlation_data_for_logs"></a>
+
+#### WeaveSpan.get\_correlation\_data\_for\_logs
+
+```python
+def get_correlation_data_for_logs() -> dict[str, Any]
+```
+
+Correlation data for logging.
+
+<a id="haystack_integrations.tracing.weave.tracer.WeaveTracer"></a>
+
+### WeaveTracer
+
+Implements a Haystack's Tracer to make an interface with Weights and Bias Weave.
+
+It's responsible for creating and managing Weave calls, and for converting Haystack spans
+to Weave spans. It creates spans for each Haystack component run.
+
+<a id="haystack_integrations.tracing.weave.tracer.WeaveTracer.__init__"></a>
+
+#### WeaveTracer.\_\_init\_\_
+
+```python
+def __init__(project_name: str, **weave_init_kwargs: Any) -> None
+```
+
+Initialize the WeaveTracer.
+
+**Arguments**:
+
+- `project_name`: The name of the project to trace, this is will be the name appearing in Weave project.
+- `weave_init_kwargs`: Additional arguments to pass to the Weave client.
+
+<a id="haystack_integrations.tracing.weave.tracer.WeaveTracer.current_span"></a>
+
+#### WeaveTracer.current\_span
+
+```python
+def current_span() -> Span | None
+```
+
+Get the current active span.
+
+<a id="haystack_integrations.tracing.weave.tracer.WeaveTracer.trace"></a>
+
+#### WeaveTracer.trace
+
+```python
+@contextlib.contextmanager
+def trace(operation_name: str,
+          tags: dict[str, Any] | None = None,
+          parent_span: WeaveSpan | None = None) -> Iterator[WeaveSpan]
+```
+
+A context manager that creates and manages spans for tracking operations in Weights & Biases Weave.
+
+It has two main workflows:
+
+A) For regular operations (operation_name != "haystack.component.run"):
+    Creates a Weave Call immediately
+    Creates a WeaveSpan with this call
+    Sets any provided tags
+    Yields the span for use in the with block
+    When the block ends, updates the call with pipeline output data
+
+B) For component runs (operation_name == "haystack.component.run"):
+    Creates a WeaveSpan WITHOUT a call initially (deferred creation)
+    Sets any provided tags
+    Yields the span for use in the with block
+    Creates the actual Weave Call only at the end, when all component information is available
+    Updates the call with component output data
+
+This distinction is important because Weave's calls can't be updated once created, but the content
+tags are only set on the Span at a later stage. To get the inputs on call creation, we need to create
+the call after we yield the span.
+