chore: import upstream snapshot with attribution

docs-website/reference_versioned_docs/version-2.22/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.22/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.22/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.22/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.22/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.22/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.22/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.22/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.22/haystack-api/agents_api.md

@@ -0,0 +1,418 @@
+---
+title: "Agents"
+id: agents-api
+description: "Tool-using agents with provider-agnostic chat model support."
+slug: "/agents-api"
+---
+
+<a id="agent"></a>
+
+## Module agent
+
+<a id="agent.Agent"></a>
+
+### Agent
+
+A Haystack component that implements a tool-using agent with provider-agnostic chat model support.
+
+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.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")]
+)
+
+# The agent will:
+# 1. Search for tipping customs in France
+# 2. Use calculator to compute tip based on findings
+# 3. Return the final answer with context
+print(result["messages"][-1].text)
+```
+
+<a id="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,
+             tool_invoker_kwargs: dict[str, Any] | 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`: A list of Tool and/or Toolset objects, or a single 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.
+
+**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="agent.Agent.warm_up"></a>
+
+#### Agent.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Warm up the Agent.
+
+<a id="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="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="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,
+        **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.
+- `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**:
+
+- `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="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,
+                    **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.
+- `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**:
+
+- `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="state/state"></a>
+
+## Module state/state
+
+<a id="state/state.State"></a>
+
+### 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"}
+)
+```
+
+<a id="state/state.State.__init__"></a>
+
+#### State.\_\_init\_\_
+
+```python
+def __init__(schema: dict[str, Any], data: dict[str, Any] | None = None)
+```
+
+Initialize a State object with a schema and optional data.
+
+**Arguments**:
+
+- `schema`: 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`: Optional dictionary of initial data to populate the state
+
+<a id="state/state.State.get"></a>
+
+#### State.get
+
+```python
+def get(key: str, default: Any = None) -> Any
+```
+
+Retrieve a value from the state by key.
+
+**Arguments**:
+
+- `key`: Key to look up in the state
+- `default`: Value to return if key is not found
+
+**Returns**:
+
+Value associated with key or default if not found
+
+<a id="state/state.State.set"></a>
+
+#### State.set
+
+```python
+def 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'
+
+**Arguments**:
+
+- `key`: Key to store the value under
+- `value`: Value to store or merge
+- `handler_override`: Optional function to override the default merge behavior
+
+<a id="state/state.State.data"></a>
+
+#### State.data
+
+```python
+@property
+def data()
+```
+
+All current data of the state.
+
+<a id="state/state.State.has"></a>
+
+#### State.has
+
+```python
+def has(key: str) -> bool
+```
+
+Check if a key exists in the state.
+
+**Arguments**:
+
+- `key`: Key to check for existence
+
+**Returns**:
+
+True if key exists in state, False otherwise
+
+<a id="state/state.State.to_dict"></a>
+
+#### State.to\_dict
+
+```python
+def to_dict()
+```
+
+Convert the State object to a dictionary.
+
+<a id="state/state.State.from_dict"></a>
+
+#### State.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any])
+```
+
+Convert a dictionary back to a State object.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/audio_api.md

@@ -0,0 +1,267 @@
+---
+title: "Audio"
+id: audio-api
+description: "Transcribes audio files."
+slug: "/audio-api"
+---
+
+<a id="whisper_local"></a>
+
+## Module whisper\_local
+
+<a id="whisper_local.LocalWhisperTranscriber"></a>
+
+### LocalWhisperTranscriber
+
+Transcribes audio files using OpenAI's Whisper model on your local machine.
+
+For the supported audio formats, languages, and other parameters, see the
+[Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper
+[GitHub repository](https://github.com/openai/whisper).
+
+### Usage example
+
+```python
+from haystack.components.audio import LocalWhisperTranscriber
+
+whisper = LocalWhisperTranscriber(model="small")
+whisper.warm_up()
+transcription = whisper.run(sources=["test/test_files/audio/answer.wav"])
+```
+
+<a id="whisper_local.LocalWhisperTranscriber.__init__"></a>
+
+#### LocalWhisperTranscriber.\_\_init\_\_
+
+```python
+def __init__(model: WhisperLocalModel = "large",
+             device: ComponentDevice | None = None,
+             whisper_params: dict[str, Any] | None = None)
+```
+
+Creates an instance of the LocalWhisperTranscriber component.
+
+**Arguments**:
+
+- `model`: 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`: The device for loading the model. If `None`, automatically selects the default device.
+
+<a id="whisper_local.LocalWhisperTranscriber.warm_up"></a>
+
+#### LocalWhisperTranscriber.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Loads the model in memory.
+
+<a id="whisper_local.LocalWhisperTranscriber.to_dict"></a>
+
+#### LocalWhisperTranscriber.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="whisper_local.LocalWhisperTranscriber.from_dict"></a>
+
+#### LocalWhisperTranscriber.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "LocalWhisperTranscriber"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="whisper_local.LocalWhisperTranscriber.run"></a>
+
+#### LocalWhisperTranscriber.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(sources: list[str | Path | ByteStream],
+        whisper_params: dict[str, Any] | None = None)
+```
+
+Transcribes a list of audio files into a list of documents.
+
+**Arguments**:
+
+- `sources`: A list of paths or binary streams to transcribe.
+- `whisper_params`: 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**:
+
+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.
+
+<a id="whisper_local.LocalWhisperTranscriber.transcribe"></a>
+
+#### LocalWhisperTranscriber.transcribe
+
+```python
+def transcribe(sources: list[str | Path | ByteStream],
+               **kwargs) -> 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).
+
+**Arguments**:
+
+- `sources`: A list of paths or binary streams to transcribe.
+
+**Returns**:
+
+A list of Documents, one for each file.
+
+<a id="whisper_remote"></a>
+
+## Module whisper\_remote
+
+<a id="whisper_remote.RemoteWhisperTranscriber"></a>
+
+### 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"])
+```
+
+<a id="whisper_remote.RemoteWhisperTranscriber.__init__"></a>
+
+#### RemoteWhisperTranscriber.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Creates an instance of the RemoteWhisperTranscriber component.
+
+**Arguments**:
+
+- `api_key`: OpenAI API key.
+You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter
+during initialization.
+- `model`: Name of the model to use. Currently accepts only `whisper-1`.
+- `organization`: 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`: 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`: 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`: 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.
+
+<a id="whisper_remote.RemoteWhisperTranscriber.to_dict"></a>
+
+#### RemoteWhisperTranscriber.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="whisper_remote.RemoteWhisperTranscriber.from_dict"></a>
+
+#### RemoteWhisperTranscriber.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "RemoteWhisperTranscriber"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="whisper_remote.RemoteWhisperTranscriber.run"></a>
+
+#### RemoteWhisperTranscriber.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(sources: list[str | Path | ByteStream])
+```
+
+Transcribes the list of audio files into a list of documents.
+
+**Arguments**:
+
+- `sources`: A list of file paths or `ByteStream` objects containing the audio files to transcribe.
+
+**Returns**:
+
+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.22/haystack-api/builders_api.md

@@ -0,0 +1,553 @@
+---
+title: "Builders"
+id: builders-api
+description: "Extract the output of a Generator to an Answer format, and build prompts."
+slug: "/builders-api"
+---
+
+<a id="answer_builder"></a>
+
+## Module answer\_builder
+
+<a id="answer_builder.AnswerBuilder"></a>
+
+### 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
+
+
+### Usage example with documents and reference pattern
+
+```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."])
+```
+```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.
+```
+
+<a id="answer_builder.AnswerBuilder.__init__"></a>
+
+#### AnswerBuilder.\_\_init\_\_
+
+```python
+def __init__(pattern: str | None = None,
+             reference_pattern: str | None = None,
+             last_message_only: bool = False,
+             *,
+             return_only_referenced_documents: bool = True)
+```
+
+Creates an instance of the AnswerBuilder component.
+
+**Arguments**:
+
+- `pattern`: 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`: 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`: 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`: 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.
+
+<a id="answer_builder.AnswerBuilder.run"></a>
+
+#### AnswerBuilder.run
+
+```python
+@component.output_types(answers=list[GeneratedAnswer])
+def 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)
+```
+
+Turns the output of a Generator into `GeneratedAnswer` objects using regular expressions.
+
+**Arguments**:
+
+- `query`: The input query used as the Generator prompt.
+- `replies`: The output of the Generator. Can be a list of strings or a list of `ChatMessage` objects.
+- `meta`: The metadata returned by the Generator. If not specified, the generated answer will contain no metadata.
+- `documents`: 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`: 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`: 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**:
+
+A dictionary with the following keys:
+- `answers`: The answers received from the output of the Generator.
+
+<a id="chat_prompt_builder"></a>
+
+## Module chat\_prompt\_builder
+
+<a id="chat_prompt_builder.ChatPromptBuilder"></a>
+
+### 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)
+```
+
+<a id="chat_prompt_builder.ChatPromptBuilder.__init__"></a>
+
+#### ChatPromptBuilder.\_\_init\_\_
+
+```python
+def __init__(template: list[ChatMessage] | str | None = None,
+             required_variables: list[str] | Literal["*"] | None = None,
+             variables: list[str] | None = None)
+```
+
+Constructs a ChatPromptBuilder component.
+
+**Arguments**:
+
+- `template`: A list of `ChatMessage` objects or a string template. The component looks for Jinja2 template syntax and
+renders the prompt with the provided variables. Provide the template in either
+the `init` method` or the `run` method.
+- `required_variables`: List 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`: 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.
+
+<a id="chat_prompt_builder.ChatPromptBuilder.run"></a>
+
+#### ChatPromptBuilder.run
+
+```python
+@component.output_types(prompt=list[ChatMessage])
+def run(template: list[ChatMessage] | str | None = None,
+        template_variables: dict[str, Any] | None = None,
+        **kwargs)
+```
+
+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.
+
+**Arguments**:
+
+- `template`: 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`: An optional dictionary of template variables to overwrite the pipeline variables.
+- `kwargs`: Pipeline variables used for rendering the prompt.
+
+**Raises**:
+
+- `ValueError`: If `chat_messages` is empty or contains elements that are not instances of `ChatMessage`.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `prompt`: The updated list of `ChatMessage` objects after rendering the templates.
+
+<a id="chat_prompt_builder.ChatPromptBuilder.to_dict"></a>
+
+#### ChatPromptBuilder.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the component.
+
+**Returns**:
+
+Serialized dictionary representation of the component.
+
+<a id="chat_prompt_builder.ChatPromptBuilder.from_dict"></a>
+
+#### ChatPromptBuilder.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "ChatPromptBuilder"
+```
+
+Deserialize this component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize and create the component.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="prompt_builder"></a>
+
+## Module prompt\_builder
+
+<a id="prompt_builder.PromptBuilder"></a>
+
+### 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.
+
+<a id="prompt_builder.PromptBuilder.__init__"></a>
+
+#### PromptBuilder.\_\_init\_\_
+
+```python
+def __init__(template: str,
+             required_variables: list[str] | Literal["*"] | None = None,
+             variables: list[str] | None = None)
+```
+
+Constructs a PromptBuilder component.
+
+**Arguments**:
+
+- `template`: A prompt template that uses Jinja2 syntax to add variables. For example:
+`"Summarize this document: {{ documents[0].content }}\nSummary:"`
+It's used to render the prompt.
+The variables in the default template are input for PromptBuilder and are all optional,
+unless explicitly specified.
+If an optional variable is not provided, it's replaced with an empty string in the rendered prompt.
+- `required_variables`: List variables that must be provided as input to PromptBuilder.
+If a variable listed as required is not provided, an exception is raised.
+If set to "*", all variables found in the prompt are required. Optional.
+- `variables`: List input variables to use in prompt templates instead of the ones inferred from the
+`template` parameter. For example, to use more variables during prompt engineering than the ones present
+in the default template, you can provide them here.
+
+<a id="prompt_builder.PromptBuilder.to_dict"></a>
+
+#### PromptBuilder.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the component.
+
+**Returns**:
+
+Serialized dictionary representation of the component.
+
+<a id="prompt_builder.PromptBuilder.run"></a>
+
+#### PromptBuilder.run
+
+```python
+@component.output_types(prompt=str)
+def run(template: str | None = None,
+        template_variables: dict[str, Any] | None = None,
+        **kwargs)
+```
+
+Renders the prompt template with the provided variables.
+
+It applies the template variables to render the final prompt. You can provide variables via pipeline kwargs.
+In order to overwrite the default template, you can set the `template` parameter.
+In order to overwrite pipeline kwargs, you can set the `template_variables` parameter.
+
+**Arguments**:
+
+- `template`: An optional string template to overwrite PromptBuilder's default template. If None, the default template
+provided at initialization is used.
+- `template_variables`: An optional dictionary of template variables to overwrite the pipeline variables.
+- `kwargs`: Pipeline variables used for rendering the prompt.
+
+**Raises**:
+
+- `ValueError`: If any of the required template variables is not provided.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `prompt`: The updated prompt text after rendering the prompt template.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/cachings_api.md

@@ -0,0 +1,110 @@
+---
+title: "Caching"
+id: caching-api
+description: "Checks if any document coming from the given URL is already present in the store."
+slug: "/caching-api"
+---
+
+<a id="cache_checker"></a>
+
+## Module cache\_checker
+
+<a id="cache_checker.CacheChecker"></a>
+
+### 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"]}
+```
+
+<a id="cache_checker.CacheChecker.__init__"></a>
+
+#### CacheChecker.\_\_init\_\_
+
+```python
+def __init__(document_store: DocumentStore, cache_field: str)
+```
+
+Creates a CacheChecker component.
+
+**Arguments**:
+
+- `document_store`: Document Store to check for the presence of specific documents.
+- `cache_field`: Name of the document's metadata field
+to check for cache hits.
+
+<a id="cache_checker.CacheChecker.to_dict"></a>
+
+#### CacheChecker.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="cache_checker.CacheChecker.from_dict"></a>
+
+#### CacheChecker.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "CacheChecker"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="cache_checker.CacheChecker.run"></a>
+
+#### CacheChecker.run
+
+```python
+@component.output_types(hits=list[Document], misses=list)
+def run(items: list[Any])
+```
+
+Checks if any document associated with the specified cache field is already present in the store.
+
+**Arguments**:
+
+- `items`: Values to be checked against the cache field.
+
+**Returns**:
+
+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.22/haystack-api/classifiers_api.md

@@ -0,0 +1,270 @@
+---
+title: "Classifiers"
+id: classifiers-api
+description: "Classify documents based on the provided labels."
+slug: "/classifiers-api"
+---
+
+<a id="document_language_classifier"></a>
+
+## Module document\_language\_classifier
+
+<a id="document_language_classifier.DocumentLanguageClassifier"></a>
+
+### 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"})
+```
+
+<a id="document_language_classifier.DocumentLanguageClassifier.__init__"></a>
+
+#### DocumentLanguageClassifier.\_\_init\_\_
+
+```python
+def __init__(languages: list[str] | None = None)
+```
+
+Initializes the DocumentLanguageClassifier component.
+
+**Arguments**:
+
+- `languages`: 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"].
+
+<a id="document_language_classifier.DocumentLanguageClassifier.run"></a>
+
+#### DocumentLanguageClassifier.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: 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".
+
+**Arguments**:
+
+- `documents`: A list of documents for language classification.
+
+**Raises**:
+
+- `TypeError`: if the input is not a list of Documents.
+
+**Returns**:
+
+A dictionary with the following key:
+- `documents`: A list of documents with an added `language` metadata field.
+
+<a id="zero_shot_document_classifier"></a>
+
+## Module zero\_shot\_document\_classifier
+
+<a id="zero_shot_document_classifier.TransformersZeroShotDocumentClassifier"></a>
+
+### 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])
+```
+
+<a id="zero_shot_document_classifier.TransformersZeroShotDocumentClassifier.__init__"></a>
+
+#### TransformersZeroShotDocumentClassifier.\_\_init\_\_
+
+```python
+def __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)
+```
+
+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.
+
+**Arguments**:
+
+- `model`: The name or path of a Hugging Face model for zero shot document classification.
+- `labels`: The set of possible class labels to classify each document into, for example,
+["positive", "negative"]. The labels depend on the selected model.
+- `multi_label`: 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`: Name of document's meta field to be used for classification.
+If not set, `Document.content` is used by default.
+- `device`: The device on which the model is loaded. If `None`, the default device is automatically
+selected. If a device/device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter.
+- `token`: 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`: Dictionary containing keyword arguments used to initialize the
+Hugging Face pipeline for text classification.
+
+<a id="zero_shot_document_classifier.TransformersZeroShotDocumentClassifier.warm_up"></a>
+
+#### TransformersZeroShotDocumentClassifier.warm\_up
+
+```python
+def warm_up()
+```
+
+Initializes the component.
+
+<a id="zero_shot_document_classifier.TransformersZeroShotDocumentClassifier.to_dict"></a>
+
+#### TransformersZeroShotDocumentClassifier.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="zero_shot_document_classifier.TransformersZeroShotDocumentClassifier.from_dict"></a>
+
+#### TransformersZeroShotDocumentClassifier.from\_dict
+
+```python
+@classmethod
+def from_dict(
+        cls, data: dict[str, Any]) -> "TransformersZeroShotDocumentClassifier"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="zero_shot_document_classifier.TransformersZeroShotDocumentClassifier.run"></a>
+
+#### TransformersZeroShotDocumentClassifier.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document], batch_size: int = 1)
+```
+
+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.
+
+**Arguments**:
+
+- `documents`: Documents to process.
+- `batch_size`: Batch size used for processing the content in each document.
+
+**Returns**:
+
+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.22/haystack-api/connectors_api.md

@@ -0,0 +1,247 @@
+---
+title: "Connectors"
+id: connectors-api
+description: "Various connectors to integrate with external services."
+slug: "/connectors-api"
+---
+
+<a id="openapi"></a>
+
+## Module openapi
+
+<a id="openapi.OpenAPIConnector"></a>
+
+### OpenAPIConnector
+
+OpenAPIConnector enables direct invocation of REST endpoints defined in an OpenAPI specification.
+
+The OpenAPIConnector serves as a bridge between Haystack pipelines and any REST API that follows
+the OpenAPI(formerly Swagger) specification. It dynamically interprets the API specification and
+provides an interface for executing API operations. It is usually invoked by passing input
+arguments to it from a Haystack pipeline run method or by other components in a pipeline that
+pass input arguments to this component.
+
+**Example**:
+
+```python
+from haystack.utils import Secret
+from haystack.components.connectors.openapi import OpenAPIConnector
+
+connector = OpenAPIConnector(
+    openapi_spec="https://bit.ly/serperdev_openapi",
+    credentials=Secret.from_env_var("SERPERDEV_API_KEY"),
+    service_kwargs={"config_factory": my_custom_config_factory}
+)
+response = connector.run(
+    operation_id="search",
+    arguments={"q": "Who was Nikola Tesla?"}
+)
+```
+
+**Notes**:
+
+  - The `parameters` argument is required for this component.
+  - The `service_kwargs` argument is optional, it can be used to pass additional options to the OpenAPIClient.
+
+<a id="openapi.OpenAPIConnector.__init__"></a>
+
+#### OpenAPIConnector.\_\_init\_\_
+
+```python
+def __init__(openapi_spec: str,
+             credentials: Secret | None = None,
+             service_kwargs: dict[str, Any] | None = None)
+```
+
+Initialize the OpenAPIConnector with a specification and optional credentials.
+
+**Arguments**:
+
+- `openapi_spec`: URL, file path, or raw string of the OpenAPI specification
+- `credentials`: Optional API key or credentials for the service wrapped in a Secret
+- `service_kwargs`: Additional keyword arguments passed to OpenAPIClient.from_spec()
+For example, you can pass a custom config_factory or other configuration options.
+
+<a id="openapi.OpenAPIConnector.to_dict"></a>
+
+#### OpenAPIConnector.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+<a id="openapi.OpenAPIConnector.from_dict"></a>
+
+#### OpenAPIConnector.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "OpenAPIConnector"
+```
+
+Deserialize this component from a dictionary.
+
+<a id="openapi.OpenAPIConnector.run"></a>
+
+#### OpenAPIConnector.run
+
+```python
+@component.output_types(response=dict[str, Any])
+def run(operation_id: str,
+        arguments: dict[str, Any] | None = None) -> dict[str, Any]
+```
+
+Invokes a REST endpoint specified in the OpenAPI specification.
+
+**Arguments**:
+
+- `operation_id`: The operationId from the OpenAPI spec to invoke
+- `arguments`: Optional parameters for the endpoint (query, path, or body parameters)
+
+**Returns**:
+
+Dictionary containing the service response
+
+<a id="openapi_service"></a>
+
+## Module openapi\_service
+
+<a id="openapi_service.OpenAPIServiceConnector"></a>
+
+### 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 payload in messages is used to determine the method to be
+called and the parameters to be passed. The message payload should be an OpenAI JSON formatted function calling
+string consisting of the method name and the parameters to be passed to the method. 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 an `OpenAIChatGenerator` component using LLM
+with the function calling capabilities. In the example below we use the function calling payload directly, but in a
+real-world scenario, the function calling payload would usually be generated by the `OpenAIChatGenerator` component.
+
+Usage example:
+
+```python
+import json
+import requests
+
+from haystack.components.connectors import OpenAPIServiceConnector
+from haystack.dataclasses import ChatMessage
+
+
+fc_payload = [{'function': {'arguments': '{"q": "Why was Sam Altman ousted from OpenAI?"}', 'name': 'search'},
+               'id': 'call_PmEBYvZ7mGrQP5PUASA5m9wO', 'type': 'function'}]
+
+serper_token = <your_serper_dev_token>
+serperdev_openapi_spec = json.loads(requests.get("https://bit.ly/serper_dev_spec").text)
+service_connector = OpenAPIServiceConnector()
+result = service_connector.run(messages=[ChatMessage.from_assistant(json.dumps(fc_payload))],
+                               service_openapi_spec=serperdev_openapi_spec, service_credentials=serper_token)
+print(result)
+
+>> {'service_response': [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _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."...
+```
+
+<a id="openapi_service.OpenAPIServiceConnector.__init__"></a>
+
+#### OpenAPIServiceConnector.\_\_init\_\_
+
+```python
+def __init__(ssl_verify: bool | str | None = None)
+```
+
+Initializes the OpenAPIServiceConnector instance
+
+**Arguments**:
+
+- `ssl_verify`: Decide if to use SSL verification to the requests or not,
+in case a string is passed, will be used as the CA.
+
+<a id="openapi_service.OpenAPIServiceConnector.run"></a>
+
+#### OpenAPIServiceConnector.run
+
+```python
+@component.output_types(service_response=dict[str, Any])
+def 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.
+
+**Arguments**:
+
+- `messages`: A list of `ChatMessage` objects containing the messages to be processed. The last message
+should contain the tool calls.
+- `service_openapi_spec`: The OpenAPI JSON specification object of the service to be invoked. All the refs
+should already be resolved.
+- `service_credentials`: The credentials to be used for authentication with the service.
+Currently, only the http and apiKey OpenAPI security schemes are supported.
+
+**Raises**:
+
+- `ValueError`: If the last message is not from the assistant or if it does not contain tool calls.
+
+**Returns**:
+
+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.
+
+<a id="openapi_service.OpenAPIServiceConnector.to_dict"></a>
+
+#### OpenAPIServiceConnector.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="openapi_service.OpenAPIServiceConnector.from_dict"></a>
+
+#### OpenAPIServiceConnector.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "OpenAPIServiceConnector"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/document_stores_api.md

@@ -0,0 +1,381 @@
+---
+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"
+---
+
+<a id="document_store"></a>
+
+## Module document\_store
+
+<a id="document_store.BM25DocumentStats"></a>
+
+### BM25DocumentStats
+
+A dataclass for managing document statistics for BM25 retrieval.
+
+**Arguments**:
+
+- `freq_token`: A Counter of token frequencies in the document.
+- `doc_len`: Number of tokens in the document.
+
+<a id="document_store.InMemoryDocumentStore"></a>
+
+### InMemoryDocumentStore
+
+Stores data in-memory. It's ephemeral and cannot be saved to disk.
+
+<a id="document_store.InMemoryDocumentStore.__init__"></a>
+
+#### InMemoryDocumentStore.\_\_init\_\_
+
+```python
+def __init__(bm25_tokenization_regex: str = r"(?u)\b\w\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)
+```
+
+Initializes the DocumentStore.
+
+**Arguments**:
+
+- `bm25_tokenization_regex`: The regular expression used to tokenize the text for BM25 retrieval.
+- `bm25_algorithm`: The BM25 algorithm to use. One of "BM25Okapi", "BM25L", or "BM25Plus".
+- `bm25_parameters`: 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`: 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`: 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`: Optional ThreadPoolExecutor to use for async calls. If not provided, a single-threaded
+executor will be initialized and used.
+- `return_embedding`: Whether to return the embedding of the retrieved Documents. Default is True.
+
+<a id="document_store.InMemoryDocumentStore.__del__"></a>
+
+#### InMemoryDocumentStore.\_\_del\_\_
+
+```python
+def __del__()
+```
+
+Cleanup when the instance is being destroyed.
+
+<a id="document_store.InMemoryDocumentStore.shutdown"></a>
+
+#### InMemoryDocumentStore.shutdown
+
+```python
+def shutdown()
+```
+
+Explicitly shutdown the executor if we own it.
+
+<a id="document_store.InMemoryDocumentStore.storage"></a>
+
+#### InMemoryDocumentStore.storage
+
+```python
+@property
+def storage() -> dict[str, Document]
+```
+
+Utility property that returns the storage used by this instance of InMemoryDocumentStore.
+
+<a id="document_store.InMemoryDocumentStore.to_dict"></a>
+
+#### InMemoryDocumentStore.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="document_store.InMemoryDocumentStore.from_dict"></a>
+
+#### InMemoryDocumentStore.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "InMemoryDocumentStore"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="document_store.InMemoryDocumentStore.save_to_disk"></a>
+
+#### InMemoryDocumentStore.save\_to\_disk
+
+```python
+def save_to_disk(path: str) -> None
+```
+
+Write the database and its' data to disk as a JSON file.
+
+**Arguments**:
+
+- `path`: The path to the JSON file.
+
+<a id="document_store.InMemoryDocumentStore.load_from_disk"></a>
+
+#### InMemoryDocumentStore.load\_from\_disk
+
+```python
+@classmethod
+def load_from_disk(cls, path: str) -> "InMemoryDocumentStore"
+```
+
+Load the database and its' data from disk as a JSON file.
+
+**Arguments**:
+
+- `path`: The path to the JSON file.
+
+**Returns**:
+
+The loaded InMemoryDocumentStore.
+
+<a id="document_store.InMemoryDocumentStore.count_documents"></a>
+
+#### InMemoryDocumentStore.count\_documents
+
+```python
+def count_documents() -> int
+```
+
+Returns the number of how many documents are present in the DocumentStore.
+
+<a id="document_store.InMemoryDocumentStore.filter_documents"></a>
+
+#### InMemoryDocumentStore.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 DocumentStore.filter_documents() protocol
+documentation.
+
+**Arguments**:
+
+- `filters`: The filters to apply to the document list.
+
+**Returns**:
+
+A list of Documents that match the given filters.
+
+<a id="document_store.InMemoryDocumentStore.write_documents"></a>
+
+#### InMemoryDocumentStore.write\_documents
+
+```python
+def 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`.
+
+<a id="document_store.InMemoryDocumentStore.delete_documents"></a>
+
+#### InMemoryDocumentStore.delete\_documents
+
+```python
+def delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes all documents with matching document_ids from the DocumentStore.
+
+**Arguments**:
+
+- `document_ids`: The object_ids to delete.
+
+<a id="document_store.InMemoryDocumentStore.bm25_retrieval"></a>
+
+#### InMemoryDocumentStore.bm25\_retrieval
+
+```python
+def 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.
+
+**Arguments**:
+
+- `query`: The query string.
+- `filters`: A dictionary with filters to narrow down the search space.
+- `top_k`: The number of top documents to retrieve. Default is 10.
+- `scale_score`: Whether to scale the scores of the retrieved documents. Default is False.
+
+**Returns**:
+
+A list of the top_k documents most relevant to the query.
+
+<a id="document_store.InMemoryDocumentStore.embedding_retrieval"></a>
+
+#### InMemoryDocumentStore.embedding\_retrieval
+
+```python
+def 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.
+
+**Arguments**:
+
+- `query_embedding`: Embedding of the query.
+- `filters`: A dictionary with filters to narrow down the search space.
+- `top_k`: The number of top documents to retrieve. Default is 10.
+- `scale_score`: Whether to scale the scores of the retrieved Documents. Default is False.
+- `return_embedding`: 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**:
+
+A list of the top_k documents most relevant to the query.
+
+<a id="document_store.InMemoryDocumentStore.count_documents_async"></a>
+
+#### InMemoryDocumentStore.count\_documents\_async
+
+```python
+async def count_documents_async() -> int
+```
+
+Returns the number of how many documents are present in the DocumentStore.
+
+<a id="document_store.InMemoryDocumentStore.filter_documents_async"></a>
+
+#### InMemoryDocumentStore.filter\_documents\_async
+
+```python
+async def filter_documents_async(
+        filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters, refer to the DocumentStore.filter_documents() protocol
+documentation.
+
+**Arguments**:
+
+- `filters`: The filters to apply to the document list.
+
+**Returns**:
+
+A list of Documents that match the given filters.
+
+<a id="document_store.InMemoryDocumentStore.write_documents_async"></a>
+
+#### InMemoryDocumentStore.write\_documents\_async
+
+```python
+async def 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`.
+
+<a id="document_store.InMemoryDocumentStore.delete_documents_async"></a>
+
+#### InMemoryDocumentStore.delete\_documents\_async
+
+```python
+async def delete_documents_async(document_ids: list[str]) -> None
+```
+
+Deletes all documents with matching document_ids from the DocumentStore.
+
+**Arguments**:
+
+- `document_ids`: The object_ids to delete.
+
+<a id="document_store.InMemoryDocumentStore.bm25_retrieval_async"></a>
+
+#### InMemoryDocumentStore.bm25\_retrieval\_async
+
+```python
+async def 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.
+
+**Arguments**:
+
+- `query`: The query string.
+- `filters`: A dictionary with filters to narrow down the search space.
+- `top_k`: The number of top documents to retrieve. Default is 10.
+- `scale_score`: Whether to scale the scores of the retrieved documents. Default is False.
+
+**Returns**:
+
+A list of the top_k documents most relevant to the query.
+
+<a id="document_store.InMemoryDocumentStore.embedding_retrieval_async"></a>
+
+#### InMemoryDocumentStore.embedding\_retrieval\_async
+
+```python
+async def 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.
+
+**Arguments**:
+
+- `query_embedding`: Embedding of the query.
+- `filters`: A dictionary with filters to narrow down the search space.
+- `top_k`: The number of top documents to retrieve. Default is 10.
+- `scale_score`: Whether to scale the scores of the retrieved Documents. Default is False.
+- `return_embedding`: Whether to return the embedding of the retrieved Documents. Default is False.
+
+**Returns**:
+
+A list of the top_k documents most relevant to the query.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/document_writers_api.md

@@ -0,0 +1,140 @@
+---
+title: "Document Writers"
+id: document-writers-api
+description: "Writes Documents to a DocumentStore."
+slug: "/document-writers-api"
+---
+
+<a id="document_writer"></a>
+
+## Module document\_writer
+
+<a id="document_writer.DocumentWriter"></a>
+
+### 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)
+```
+
+<a id="document_writer.DocumentWriter.__init__"></a>
+
+#### DocumentWriter.\_\_init\_\_
+
+```python
+def __init__(document_store: DocumentStore,
+             policy: DuplicatePolicy = DuplicatePolicy.NONE)
+```
+
+Create a DocumentWriter component.
+
+**Arguments**:
+
+- `document_store`: The instance of the document store where you want to store your documents.
+- `policy`: 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.
+
+<a id="document_writer.DocumentWriter.to_dict"></a>
+
+#### DocumentWriter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="document_writer.DocumentWriter.from_dict"></a>
+
+#### DocumentWriter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "DocumentWriter"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Raises**:
+
+- `DeserializationError`: If the document store is not properly specified in the serialization data or its type cannot be imported.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="document_writer.DocumentWriter.run"></a>
+
+#### DocumentWriter.run
+
+```python
+@component.output_types(documents_written=int)
+def run(documents: list[Document], policy: DuplicatePolicy | None = None)
+```
+
+Run the DocumentWriter on the given input data.
+
+**Arguments**:
+
+- `documents`: A list of documents to write to the document store.
+- `policy`: The policy to use when encountering duplicate documents.
+
+**Raises**:
+
+- `ValueError`: If the specified document store is not found.
+
+**Returns**:
+
+Number of documents written to the document store.
+
+<a id="document_writer.DocumentWriter.run_async"></a>
+
+#### DocumentWriter.run\_async
+
+```python
+@component.output_types(documents_written=int)
+async def run_async(documents: list[Document],
+                    policy: DuplicatePolicy | None = None)
+```
+
+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.
+
+**Arguments**:
+
+- `documents`: A list of documents to write to the document store.
+- `policy`: The policy to use when encountering duplicate documents.
+
+**Raises**:
+
+- `ValueError`: If the specified document store is not found.
+- `TypeError`: If the specified document store does not implement `write_documents_async`.
+
+**Returns**:
+
+Number of documents written to the document store.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/evaluation_api.md

@@ -0,0 +1,110 @@
+---
+title: "Evaluation"
+id: evaluation-api
+description: "Represents the results of evaluation."
+slug: "/evaluation-api"
+---
+
+<a id="eval_run_result"></a>
+
+## Module eval\_run\_result
+
+<a id="eval_run_result.EvaluationRunResult"></a>
+
+### EvaluationRunResult
+
+Contains the inputs and the outputs of an evaluation pipeline and provides methods to inspect them.
+
+<a id="eval_run_result.EvaluationRunResult.__init__"></a>
+
+#### EvaluationRunResult.\_\_init\_\_
+
+```python
+def __init__(run_name: str, inputs: dict[str, list[Any]],
+             results: dict[str, dict[str, Any]])
+```
+
+Initialize a new evaluation run result.
+
+**Arguments**:
+
+- `run_name`: Name of the evaluation run.
+- `inputs`: 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`: 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.
+
+<a id="eval_run_result.EvaluationRunResult.aggregated_report"></a>
+
+#### EvaluationRunResult.aggregated\_report
+
+```python
+def 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.
+
+**Arguments**:
+
+- `output_format`: The output format for the report, "json", "csv", or "df", default to "json".
+- `csv_file`: Filepath to save CSV output if `output_format` is "csv", must be provided.
+
+**Returns**:
+
+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.
+
+<a id="eval_run_result.EvaluationRunResult.detailed_report"></a>
+
+#### EvaluationRunResult.detailed\_report
+
+```python
+def 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.
+
+**Arguments**:
+
+- `output_format`: The output format for the report, "json", "csv", or "df", default to "json".
+- `csv_file`: Filepath to save CSV output if `output_format` is "csv", must be provided.
+
+**Returns**:
+
+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.
+
+<a id="eval_run_result.EvaluationRunResult.comparative_detailed_report"></a>
+
+#### EvaluationRunResult.comparative\_detailed\_report
+
+```python
+def 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.
+
+**Arguments**:
+
+- `other`: Results of another evaluation run to compare with.
+- `keep_columns`: List of common column names to keep from the inputs of the evaluation runs to compare.
+- `output_format`: The output format for the report, "json", "csv", or "df", default to "json".
+- `csv_file`: Filepath to save CSV output if `output_format` is "csv", must be provided.
+
+**Returns**:
+
+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.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/extractors_api.md

@@ -0,0 +1,647 @@
+---
+title: "Extractors"
+id: extractors-api
+description: "Components to extract specific elements from textual data."
+slug: "/extractors-api"
+---
+
+<a id="image/llm_document_content_extractor"></a>
+
+## Module image/llm\_document\_content\_extractor
+
+<a id="image/llm_document_content_extractor.LLMDocumentContentExtractor"></a>
+
+### LLMDocumentContentExtractor
+
+Extracts textual content from image-based documents using a vision-enabled LLM (Large Language Model).
+
+This component converts each input document into an image using the DocumentToImageContent component,
+uses a prompt to instruct the LLM on how to extract content, and uses a ChatGenerator to extract structured
+textual content based on the provided prompt.
+
+The prompt must not contain variables; it should only include instructions for the LLM. Image data and the prompt
+are passed together to the LLM as a chat message.
+
+Documents for which the LLM fails to extract content are returned in a separate `failed_documents` list. These
+failed documents will have a `content_extraction_error` entry in their metadata. This metadata can be used for
+debugging or for reprocessing the documents later.
+
+### Usage example
+```python
+from haystack import Document
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.extractors.image import LLMDocumentContentExtractor
+chat_generator = OpenAIChatGenerator()
+extractor = LLMDocumentContentExtractor(chat_generator=chat_generator)
+documents = [
+    Document(content="", meta={"file_path": "image.jpg"}),
+    Document(content="", meta={"file_path": "document.pdf", "page_number": 1}),
+]
+updated_documents = extractor.run(documents=documents)["documents"]
+print(updated_documents)
+# [Document(content='Extracted text from image.jpg',
+#           meta={'file_path': 'image.jpg'}),
+#  ...]
+```
+
+<a id="image/llm_document_content_extractor.LLMDocumentContentExtractor.__init__"></a>
+
+#### LLMDocumentContentExtractor.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Initialize the LLMDocumentContentExtractor component.
+
+**Arguments**:
+
+- `chat_generator`: A ChatGenerator instance representing the LLM used to extract text. This generator must
+support vision-based input and return a plain text response.
+- `prompt`: Instructional text provided to the LLM. It must not contain Jinja variables.
+The prompt should only contain instructions on how to extract the content of the image-based document.
+- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF.
+- `root_path`: The root directory path where document files are located. If provided, file paths in
+document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- `detail`: Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low".
+This will be passed to chat_generator when processing the images.
+- `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while
+maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+when working with models that have resolution constraints or when transmitting images to remote services.
+- `raise_on_failure`: If True, exceptions from the LLM are raised. If False, failed documents are logged
+and returned.
+- `max_workers`: Maximum number of threads used to parallelize LLM calls across documents using a
+ThreadPoolExecutor.
+
+<a id="image/llm_document_content_extractor.LLMDocumentContentExtractor.warm_up"></a>
+
+#### LLMDocumentContentExtractor.warm\_up
+
+```python
+def warm_up()
+```
+
+Warm up the ChatGenerator if it has a warm_up method.
+
+<a id="image/llm_document_content_extractor.LLMDocumentContentExtractor.to_dict"></a>
+
+#### LLMDocumentContentExtractor.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="image/llm_document_content_extractor.LLMDocumentContentExtractor.from_dict"></a>
+
+#### LLMDocumentContentExtractor.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "LLMDocumentContentExtractor"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary with serialized data.
+
+**Returns**:
+
+An instance of the component.
+
+<a id="image/llm_document_content_extractor.LLMDocumentContentExtractor.run"></a>
+
+#### LLMDocumentContentExtractor.run
+
+```python
+@component.output_types(documents=list[Document],
+                        failed_documents=list[Document])
+def run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Run content extraction on a list of image-based documents using a vision-capable LLM.
+
+Each document is passed to the LLM along with a predefined prompt. The response is used to update the document's
+content. If the extraction fails, the document is returned in the `failed_documents` list with metadata
+describing the failure.
+
+**Arguments**:
+
+- `documents`: A list of image-based documents to process. Each must have a valid file path in its metadata.
+
+**Returns**:
+
+A dictionary with:
+- "documents": Successfully processed documents, updated with extracted content.
+- "failed_documents": Documents that failed processing, annotated with failure metadata.
+
+<a id="llm_metadata_extractor"></a>
+
+## Module llm\_metadata\_extractor
+
+<a id="llm_metadata_extractor.LLMMetadataExtractor"></a>
+
+### 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_object"},
+    },
+    max_retries=1,
+    timeout=60.0,
+)
+
+extractor = LLMMetadataExtractor(
+    prompt=NER_PROMPT,
+    chat_generator=generator,
+    expected_keys=["entities"],
+    raise_on_failure=False,
+)
+
+extractor.warm_up()
+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': []
+   }
+>>
+```
+
+<a id="llm_metadata_extractor.LLMMetadataExtractor.__init__"></a>
+
+#### LLMMetadataExtractor.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Initializes the LLMMetadataExtractor.
+
+**Arguments**:
+
+- `prompt`: The prompt to be used for the LLM.
+- `chat_generator`: 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`: The keys expected in the JSON output from the LLM.
+- `page_range`: 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`: Whether to raise an error on failure during the execution of the Generator or
+validation of the JSON output.
+- `max_workers`: The maximum number of workers to use in the thread pool executor.
+
+<a id="llm_metadata_extractor.LLMMetadataExtractor.warm_up"></a>
+
+#### LLMMetadataExtractor.warm\_up
+
+```python
+def warm_up()
+```
+
+Warm up the LLM provider component.
+
+<a id="llm_metadata_extractor.LLMMetadataExtractor.to_dict"></a>
+
+#### LLMMetadataExtractor.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="llm_metadata_extractor.LLMMetadataExtractor.from_dict"></a>
+
+#### LLMMetadataExtractor.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "LLMMetadataExtractor"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary with serialized data.
+
+**Returns**:
+
+An instance of the component.
+
+<a id="llm_metadata_extractor.LLMMetadataExtractor.run"></a>
+
+#### LLMMetadataExtractor.run
+
+```python
+@component.output_types(documents=list[Document],
+                        failed_documents=list[Document])
+def run(documents: list[Document], page_range: list[str | int] | None = None)
+```
+
+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.
+
+**Arguments**:
+
+- `documents`: List of documents to extract metadata from.
+- `page_range`: 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**:
+
+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.
+
+<a id="named_entity_extractor"></a>
+
+## Module named\_entity\_extractor
+
+<a id="named_entity_extractor.NamedEntityExtractorBackend"></a>
+
+### NamedEntityExtractorBackend
+
+NLP backend to use for Named Entity Recognition.
+
+<a id="named_entity_extractor.NamedEntityExtractorBackend.HUGGING_FACE"></a>
+
+#### HUGGING\_FACE
+
+Uses an Hugging Face model and pipeline.
+
+<a id="named_entity_extractor.NamedEntityExtractorBackend.SPACY"></a>
+
+#### SPACY
+
+Uses a spaCy model and pipeline.
+
+<a id="named_entity_extractor.NamedEntityExtractorBackend.from_str"></a>
+
+#### NamedEntityExtractorBackend.from\_str
+
+```python
+@staticmethod
+def from_str(string: str) -> "NamedEntityExtractorBackend"
+```
+
+Convert a string to a NamedEntityExtractorBackend enum.
+
+<a id="named_entity_extractor.NamedEntityAnnotation"></a>
+
+### NamedEntityAnnotation
+
+Describes a single NER annotation.
+
+**Arguments**:
+
+- `entity`: Entity label.
+- `start`: Start index of the entity in the document.
+- `end`: End index of the entity in the document.
+- `score`: Score calculated by the model.
+
+<a id="named_entity_extractor.NamedEntityExtractor"></a>
+
+### NamedEntityExtractor
+
+Annotates named entities in a collection of documents.
+
+The component supports two backends: Hugging Face and spaCy. The
+former can be used with any sequence classification model from the
+[Hugging Face model hub](https://huggingface.co/models), while the
+latter can be used with any [spaCy model](https://spacy.io/models)
+that contains an NER component. Annotations are stored as metadata
+in the documents.
+
+Usage example:
+```python
+from haystack import Document
+from haystack.components.extractors.named_entity_extractor import NamedEntityExtractor
+
+documents = [
+    Document(content="I'm Merlin, the happy pig!"),
+    Document(content="My name is Clara and I live in Berkeley, California."),
+]
+extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
+extractor.warm_up()
+results = extractor.run(documents=documents)["documents"]
+annotations = [NamedEntityExtractor.get_stored_annotations(doc) for doc in results]
+print(annotations)
+```
+
+<a id="named_entity_extractor.NamedEntityExtractor.__init__"></a>
+
+#### NamedEntityExtractor.\_\_init\_\_
+
+```python
+def __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.
+
+**Arguments**:
+
+- `backend`: Backend to use for NER.
+- `model`: Name of the model or a path to the model on
+the local disk. Dependent on the backend.
+- `pipeline_kwargs`: Keyword arguments passed to the pipeline. The
+pipeline can override these arguments. Dependent on the backend.
+- `device`: The device on which the model is loaded. If `None`,
+the default device is automatically selected. If a
+device/device map is specified in `pipeline_kwargs`,
+it overrides this parameter (only applicable to the
+HuggingFace backend).
+- `token`: The API token to download private models from Hugging Face.
+
+<a id="named_entity_extractor.NamedEntityExtractor.warm_up"></a>
+
+#### NamedEntityExtractor.warm\_up
+
+```python
+def warm_up()
+```
+
+Initialize the component.
+
+**Raises**:
+
+- `ComponentError`: If the backend fails to initialize successfully.
+
+<a id="named_entity_extractor.NamedEntityExtractor.run"></a>
+
+#### NamedEntityExtractor.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document], batch_size: int = 1) -> dict[str, Any]
+```
+
+Annotate named entities in each document and store the annotations in the document's metadata.
+
+**Arguments**:
+
+- `documents`: Documents to process.
+- `batch_size`: Batch size used for processing the documents.
+
+**Raises**:
+
+- `ComponentError`: If the backend fails to process a document.
+
+**Returns**:
+
+Processed documents.
+
+<a id="named_entity_extractor.NamedEntityExtractor.to_dict"></a>
+
+#### NamedEntityExtractor.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="named_entity_extractor.NamedEntityExtractor.from_dict"></a>
+
+#### NamedEntityExtractor.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "NamedEntityExtractor"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="named_entity_extractor.NamedEntityExtractor.initialized"></a>
+
+#### NamedEntityExtractor.initialized
+
+```python
+@property
+def initialized() -> bool
+```
+
+Returns if the extractor is ready to annotate text.
+
+<a id="named_entity_extractor.NamedEntityExtractor.get_stored_annotations"></a>
+
+#### NamedEntityExtractor.get\_stored\_annotations
+
+```python
+@classmethod
+def get_stored_annotations(
+        cls, document: Document) -> list[NamedEntityAnnotation] | None
+```
+
+Returns the document's named entity annotations stored in its metadata, if any.
+
+**Arguments**:
+
+- `document`: Document whose annotations are to be fetched.
+
+**Returns**:
+
+The stored annotations.
+
+<a id="regex_text_extractor"></a>
+
+## Module regex\_text\_extractor
+
+<a id="regex_text_extractor.RegexTextExtractor"></a>
+
+### 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"}
+```
+
+<a id="regex_text_extractor.RegexTextExtractor.__init__"></a>
+
+#### RegexTextExtractor.\_\_init\_\_
+
+```python
+def __init__(regex_pattern: str)
+```
+
+Creates an instance of the RegexTextExtractor component.
+
+**Arguments**:
+
+- `regex_pattern`: 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">'`.
+
+<a id="regex_text_extractor.RegexTextExtractor.run"></a>
+
+#### RegexTextExtractor.run
+
+```python
+@component.output_types(captured_text=str)
+def run(text_or_messages: str | list[ChatMessage]) -> dict[str, str]
+```
+
+Extracts text from input using the configured regex pattern.
+
+**Arguments**:
+
+- `text_or_messages`: Either a string or a list of ChatMessage objects to search through.
+
+**Raises**:
+
+- `None`: - ValueError: if receiving a list the last element is not a ChatMessage instance.
+
+**Returns**:
+
+- `{"captured_text": "matched text"}` if a match is found
+- `{"captured_text": ""}` if no match is found
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/fetchers_api.md

@@ -0,0 +1,144 @@
+---
+title: "Fetchers"
+id: fetchers-api
+description: "Fetches content from a list of URLs and returns a list of extracted content streams."
+slug: "/fetchers-api"
+---
+
+<a id="link_content"></a>
+
+## Module link\_content
+
+<a id="link_content.LinkContentFetcher"></a>
+
+### 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())
+```
+
+<a id="link_content.LinkContentFetcher.__init__"></a>
+
+#### LinkContentFetcher.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Initializes the component.
+
+**Arguments**:
+
+- `raise_on_failure`: 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`: [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`: The number of times to retry to fetch the URL's content.
+- `timeout`: Timeout in seconds for the request.
+- `http2`: 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`: Additional keyword arguments to pass to the httpx client.
+If `None`, default values are used.
+
+<a id="link_content.LinkContentFetcher.__del__"></a>
+
+#### LinkContentFetcher.\_\_del\_\_
+
+```python
+def __del__()
+```
+
+Clean up resources when the component is deleted.
+
+Closes both the synchronous and asynchronous HTTP clients to prevent
+resource leaks.
+
+<a id="link_content.LinkContentFetcher.run"></a>
+
+#### LinkContentFetcher.run
+
+```python
+@component.output_types(streams=list[ByteStream])
+def run(urls: list[str])
+```
+
+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".
+
+**Arguments**:
+
+- `urls`: A list of URLs to fetch content from.
+
+**Raises**:
+
+- `Exception`: If the provided list of URLs contains only a single URL, and `raise_on_failure` is set to
+`True`, an exception will be raised in case of an error during content retrieval.
+In all other scenarios, any retrieval errors are logged, and a list of successfully retrieved `ByteStream`
+ objects is returned.
+
+**Returns**:
+
+`ByteStream` objects representing the extracted content.
+
+<a id="link_content.LinkContentFetcher.run_async"></a>
+
+#### LinkContentFetcher.run\_async
+
+```python
+@component.output_types(streams=list[ByteStream])
+async def run_async(urls: list[str])
+```
+
+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.
+
+**Arguments**:
+
+- `urls`: A list of URLs to fetch content from.
+
+**Returns**:
+
+`ByteStream` objects representing the extracted content.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/image_converters_api.md

@@ -0,0 +1,374 @@
+---
+title: "Image Converters"
+id: image-converters-api
+description: "Various converters to transform image data from one format to another."
+slug: "/image-converters-api"
+---
+
+<a id="document_to_image"></a>
+
+## Module document\_to\_image
+
+<a id="document_to_image.DocumentToImageContent"></a>
+
+### DocumentToImageContent
+
+Converts documents sourced from PDF and image files into ImageContents.
+
+This component processes a list of documents and extracts visual content from supported file formats, converting
+them into ImageContents that can be used for multimodal AI tasks. It handles both direct image files and PDF
+documents by extracting specific pages as images.
+
+Documents are expected to have metadata containing:
+- The `file_path_meta_field` key with a valid file path that exists when combined with `root_path`
+- A supported image format (MIME type must be one of the supported image types)
+- For PDF files, a `page_number` key specifying which page to extract
+
+### Usage example
+    ```python
+    from haystack import Document
+    from haystack.components.converters.image.document_to_image import DocumentToImageContent
+
+    converter = DocumentToImageContent(
+        file_path_meta_field="file_path",
+        root_path="/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'}
+    #  )]
+    ```
+
+<a id="document_to_image.DocumentToImageContent.__init__"></a>
+
+#### DocumentToImageContent.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Initialize the DocumentToImageContent component.
+
+**Arguments**:
+
+- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF.
+- `root_path`: The root directory path where document files are located. If provided, file paths in
+document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
+- `detail`: 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`: 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.
+
+<a id="document_to_image.DocumentToImageContent.run"></a>
+
+#### DocumentToImageContent.run
+
+```python
+@component.output_types(image_contents=list[ImageContent | None])
+def 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.
+
+**Arguments**:
+
+- `documents`: A list of documents to process. Each document should have metadata containing at minimum
+a 'file_path_meta_field' key. PDF documents additionally require a 'page_number' key to specify which
+page to convert.
+
+**Raises**:
+
+- `ValueError`: 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.
+
+**Returns**:
+
+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.
+
+<a id="file_to_document"></a>
+
+## Module file\_to\_document
+
+<a id="file_to_document.ImageFileToDocument"></a>
+
+### 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'})]
+```
+
+<a id="file_to_document.ImageFileToDocument.__init__"></a>
+
+#### ImageFileToDocument.\_\_init\_\_
+
+```python
+def __init__(*, store_full_path: bool = False)
+```
+
+Initialize the ImageFileToDocument component.
+
+**Arguments**:
+
+- `store_full_path`: If True, the full path of the file is stored in the metadata of the document.
+If False, only the file name is stored.
+
+<a id="file_to_document.ImageFileToDocument.run"></a>
+
+#### ImageFileToDocument.run
+
+```python
+@component.output_types(documents=list[Document])
+def 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.
+
+**Arguments**:
+
+- `sources`: List of file paths or ByteStream objects to convert.
+- `meta`: 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**:
+
+A dictionary containing:
+- `documents`: A list of `Document` objects with empty content and associated metadata.
+
+<a id="file_to_image"></a>
+
+## Module file\_to\_image
+
+<a id="file_to_image.ImageFileToImageContent"></a>
+
+### 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'}),
+#  ...]
+```
+
+<a id="file_to_image.ImageFileToImageContent.__init__"></a>
+
+#### ImageFileToImageContent.\_\_init\_\_
+
+```python
+def __init__(*,
+             detail: Literal["auto", "high", "low"] | None = None,
+             size: tuple[int, int] | None = None)
+```
+
+Create the ImageFileToImageContent component.
+
+**Arguments**:
+
+- `detail`: 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`: 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.
+
+<a id="file_to_image.ImageFileToImageContent.run"></a>
+
+#### ImageFileToImageContent.run
+
+```python
+@component.output_types(image_contents=list[ImageContent])
+def 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.
+
+**Arguments**:
+
+- `sources`: List of file paths or ByteStream objects to convert.
+- `meta`: 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`: 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`: 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**:
+
+A dictionary with the following keys:
+- `image_contents`: A list of ImageContent objects.
+
+<a id="pdf_to_image"></a>
+
+## Module pdf\_to\_image
+
+<a id="pdf_to_image.PDFToImageContent"></a>
+
+### 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}),
+#  ...]
+```
+
+<a id="pdf_to_image.PDFToImageContent.__init__"></a>
+
+#### PDFToImageContent.\_\_init\_\_
+
+```python
+def __init__(*,
+             detail: Literal["auto", "high", "low"] | None = None,
+             size: tuple[int, int] | None = None,
+             page_range: list[str | int] | None = None)
+```
+
+Create the PDFToImageContent component.
+
+**Arguments**:
+
+- `detail`: 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`: If provided, resizes the image to fit within the specified dimensions (width, height) while
+maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+when working with models that have resolution constraints or when transmitting images to remote services.
+- `page_range`: List 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.
+
+<a id="pdf_to_image.PDFToImageContent.run"></a>
+
+#### PDFToImageContent.run
+
+```python
+@component.output_types(image_contents=list[ImageContent])
+def 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.
+
+**Arguments**:
+
+- `sources`: List of file paths or ByteStream objects to convert.
+- `meta`: 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`: 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`: If provided, resizes the image to fit within the specified dimensions (width, height) while
+maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
+when working with models that have resolution constraints or when transmitting images to remote services.
+If not provided, the size value will be the one set in the constructor.
+- `page_range`: List 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**:
+
+A dictionary with the following keys:
+- `image_contents`: A list of ImageContent objects.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/joiners_api.md

@@ -0,0 +1,625 @@
+---
+title: "Joiners"
+id: joiners-api
+description: "Components that join list of different objects"
+slug: "/joiners-api"
+---
+
+<a id="answer_joiner"></a>
+
+## Module answer\_joiner
+
+<a id="answer_joiner.JoinMode"></a>
+
+### JoinMode
+
+Enum for AnswerJoiner join modes.
+
+<a id="answer_joiner.JoinMode.from_str"></a>
+
+#### JoinMode.from\_str
+
+```python
+@staticmethod
+def from_str(string: str) -> "JoinMode"
+```
+
+Convert a string to a JoinMode enum.
+
+<a id="answer_joiner.AnswerJoiner"></a>
+
+### 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}})
+```
+
+<a id="answer_joiner.AnswerJoiner.__init__"></a>
+
+#### AnswerJoiner.\_\_init\_\_
+
+```python
+def __init__(join_mode: str | JoinMode = JoinMode.CONCATENATE,
+             top_k: int | None = None,
+             sort_by_score: bool = False)
+```
+
+Creates an AnswerJoiner component.
+
+**Arguments**:
+
+- `join_mode`: Specifies the join mode to use. Available modes:
+- `concatenate`: Concatenates multiple lists of Answers into a single list.
+- `top_k`: The maximum number of Answers to return.
+- `sort_by_score`: 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.
+
+<a id="answer_joiner.AnswerJoiner.run"></a>
+
+#### AnswerJoiner.run
+
+```python
+@component.output_types(answers=list[AnswerType])
+def run(answers: Variadic[list[AnswerType]], top_k: int | None = None)
+```
+
+Joins multiple lists of Answers into a single list depending on the `join_mode` parameter.
+
+**Arguments**:
+
+- `answers`: Nested list of Answers to be merged.
+- `top_k`: The maximum number of Answers to return. Overrides the instance's `top_k` if provided.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `answers`: Merged list of Answers
+
+<a id="answer_joiner.AnswerJoiner.to_dict"></a>
+
+#### AnswerJoiner.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="answer_joiner.AnswerJoiner.from_dict"></a>
+
+#### AnswerJoiner.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "AnswerJoiner"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="branch"></a>
+
+## Module branch
+
+<a id="branch.BranchJoiner"></a>
+
+### 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.converters import OutputAdapter
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.joiners import BranchJoiner
+from haystack.components.validators import JsonSchemaValidator
+from haystack.dataclasses import ChatMessage
+
+# 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())
+pipe.add_component('validator', JsonSchemaValidator(json_schema=person_schema))
+pipe.add_component('adapter', OutputAdapter("{{chat_message}}", list[ChatMessage], unsafe=True))
+
+# And connect them
+pipe.connect("adapter", "joiner")
+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"}}},
+    "adapter": {"chat_message": [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.
+
+<a id="branch.BranchJoiner.__init__"></a>
+
+#### BranchJoiner.\_\_init\_\_
+
+```python
+def __init__(type_: type)
+```
+
+Creates a `BranchJoiner` component.
+
+**Arguments**:
+
+- `type_`: The expected data type of inputs and outputs.
+
+<a id="branch.BranchJoiner.to_dict"></a>
+
+#### BranchJoiner.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component into a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="branch.BranchJoiner.from_dict"></a>
+
+#### BranchJoiner.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "BranchJoiner"
+```
+
+Deserializes a `BranchJoiner` instance from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary containing serialized component data.
+
+**Returns**:
+
+A deserialized `BranchJoiner` instance.
+
+<a id="branch.BranchJoiner.run"></a>
+
+#### BranchJoiner.run
+
+```python
+def run(**kwargs) -> dict[str, Any]
+```
+
+Executes the `BranchJoiner`, selecting the first available input value and passing it downstream.
+
+**Arguments**:
+
+- `**kwargs`: The input data. Must be of the type declared by `type_` during initialization.
+
+**Returns**:
+
+A dictionary with a single key `value`, containing the first input received.
+
+<a id="document_joiner"></a>
+
+## Module document\_joiner
+
+<a id="document_joiner.JoinMode"></a>
+
+### JoinMode
+
+Enum for join mode.
+
+<a id="document_joiner.JoinMode.from_str"></a>
+
+#### JoinMode.from\_str
+
+```python
+@staticmethod
+def from_str(string: str) -> "JoinMode"
+```
+
+Convert a string to a JoinMode enum.
+
+<a id="document_joiner.DocumentJoiner"></a>
+
+### 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")
+embedder.warm_up()
+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})
+```
+
+<a id="document_joiner.DocumentJoiner.__init__"></a>
+
+#### DocumentJoiner.\_\_init\_\_
+
+```python
+def __init__(join_mode: str | JoinMode = JoinMode.CONCATENATE,
+             weights: list[float] | None = None,
+             top_k: int | None = None,
+             sort_by_score: bool = True)
+```
+
+Creates a DocumentJoiner component.
+
+**Arguments**:
+
+- `join_mode`: 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`: 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`: The maximum number of documents to return.
+- `sort_by_score`: 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.
+
+<a id="document_joiner.DocumentJoiner.run"></a>
+
+#### DocumentJoiner.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: Variadic[list[Document]], top_k: int | None = None)
+```
+
+Joins multiple lists of Documents into a single list depending on the `join_mode` parameter.
+
+**Arguments**:
+
+- `documents`: List of list of documents to be merged.
+- `top_k`: The maximum number of documents to return. Overrides the instance's `top_k` if provided.
+
+**Returns**:
+
+A dictionary with the following keys:
+- `documents`: Merged list of Documents
+
+<a id="document_joiner.DocumentJoiner.to_dict"></a>
+
+#### DocumentJoiner.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="document_joiner.DocumentJoiner.from_dict"></a>
+
+#### DocumentJoiner.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "DocumentJoiner"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="list_joiner"></a>
+
+## Module list\_joiner
+
+<a id="list_joiner.ListJoiner"></a>
+
+### 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"])
+```
+
+<a id="list_joiner.ListJoiner.__init__"></a>
+
+#### ListJoiner.\_\_init\_\_
+
+```python
+def __init__(list_type_: type | None = None)
+```
+
+Creates a ListJoiner component.
+
+**Arguments**:
+
+- `list_type_`: 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.
+
+<a id="list_joiner.ListJoiner.to_dict"></a>
+
+#### ListJoiner.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="list_joiner.ListJoiner.from_dict"></a>
+
+#### ListJoiner.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "ListJoiner"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="list_joiner.ListJoiner.run"></a>
+
+#### ListJoiner.run
+
+```python
+def run(values: Variadic[list[Any]]) -> dict[str, list[Any]]
+```
+
+Joins multiple lists into a single flat list.
+
+**Arguments**:
+
+- `values`: The list to be joined.
+
+**Returns**:
+
+Dictionary with 'values' key containing the joined list.
+
+<a id="string_joiner"></a>
+
+## Module string\_joiner
+
+<a id="string_joiner.StringJoiner"></a>
+
+### 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?"]}}
+```
+
+<a id="string_joiner.StringJoiner.run"></a>
+
+#### StringJoiner.run
+
+```python
+@component.output_types(strings=list[str])
+def run(strings: Variadic[str])
+```
+
+Joins strings into a list of strings
+
+**Arguments**:
+
+- `strings`: strings from different components
+
+**Returns**:
+
+A dictionary with the following keys:
+- `strings`: Merged list of strings
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/preprocessors_api.md

@@ -0,0 +1,797 @@
+---
+title: "PreProcessors"
+id: preprocessors-api
+description: "Preprocess your Documents and texts. Clean, split, and more."
+slug: "/preprocessors-api"
+---
+
+<a id="csv_document_cleaner"></a>
+
+## Module csv\_document\_cleaner
+
+<a id="csv_document_cleaner.CSVDocumentCleaner"></a>
+
+### 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.
+
+<a id="csv_document_cleaner.CSVDocumentCleaner.__init__"></a>
+
+#### CSVDocumentCleaner.\_\_init\_\_
+
+```python
+def __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.
+
+**Arguments**:
+
+- `ignore_rows`: Number of rows to ignore from the top of the CSV table before processing.
+- `ignore_columns`: Number of columns to ignore from the left of the CSV table before processing.
+- `remove_empty_rows`: Whether to remove rows that are entirely empty.
+- `remove_empty_columns`: Whether to remove columns that are entirely empty.
+- `keep_id`: 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.
+
+<a id="csv_document_cleaner.CSVDocumentCleaner.run"></a>
+
+#### CSVDocumentCleaner.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Cleans CSV documents by removing empty rows and columns while preserving specified ignored rows and columns.
+
+**Arguments**:
+
+- `documents`: List of Documents containing CSV-formatted content.
+
+**Returns**:
+
+A dictionary with a list of cleaned Documents under the key "documents".
+Processing steps:
+1. Reads each document's content as a CSV table.
+2. Retains the specified number of `ignore_rows` from the top and `ignore_columns` from the left.
+3. Drops any rows and columns that are entirely empty (if enabled by `remove_empty_rows` and
+    `remove_empty_columns`).
+4. Reattaches the ignored rows and columns to maintain their original positions.
+5. Returns the cleaned CSV content as a new `Document` object, with an option to retain the original
+    document ID.
+
+<a id="csv_document_splitter"></a>
+
+## Module csv\_document\_splitter
+
+<a id="csv_document_splitter.CSVDocumentSplitter"></a>
+
+### 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.
+
+<a id="csv_document_splitter.CSVDocumentSplitter.__init__"></a>
+
+#### CSVDocumentSplitter.\_\_init\_\_
+
+```python
+def __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.
+
+**Arguments**:
+
+- `row_split_threshold`: The minimum number of consecutive empty rows required to trigger a split.
+- `column_split_threshold`: The minimum number of consecutive empty columns required to trigger a split.
+- `read_csv_kwargs`: 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`: 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.
+
+<a id="csv_document_splitter.CSVDocumentSplitter.run"></a>
+
+#### CSVDocumentSplitter.run
+
+```python
+@component.output_types(documents=list[Document])
+def 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.
+2. Applies a column-based split if `column_split_threshold` is provided.
+3. 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.
+4. Sorts the resulting sub-tables based on their original positions within the document.
+
+**Arguments**:
+
+- `documents`: 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**:
+
+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.
+
+<a id="document_cleaner"></a>
+
+## Module document\_cleaner
+
+<a id="document_cleaner.DocumentCleaner"></a>
+
+### 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 "
+```
+
+<a id="document_cleaner.DocumentCleaner.__init__"></a>
+
+#### DocumentCleaner.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Initialize DocumentCleaner.
+
+**Arguments**:
+
+- `remove_empty_lines`: If `True`, removes empty lines.
+- `remove_extra_whitespaces`: If `True`, removes extra whitespaces.
+- `remove_repeated_substrings`: If `True`, removes repeated substrings (headers and footers) from pages.
+Pages must be separated by a form feed character "\f",
+which is supported by `TextFileToDocument` and `AzureOCRDocumentConverter`.
+- `remove_substrings`: List of substrings to remove from the text.
+- `remove_regex`: Regex to match and replace substrings by "".
+- `keep_id`: If `True`, keeps the IDs of the original documents.
+- `unicode_normalization`: Unicode normalization form to apply to the text.
+Note: This will run before any other steps.
+- `ascii_only`: 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.
+
+<a id="document_cleaner.DocumentCleaner.run"></a>
+
+#### DocumentCleaner.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document])
+```
+
+Cleans up the documents.
+
+**Arguments**:
+
+- `documents`: List of Documents to clean.
+
+**Raises**:
+
+- `TypeError`: if documents is not a list of Documents.
+
+**Returns**:
+
+A dictionary with the following key:
+- `documents`: List of cleaned Documents.
+
+<a id="document_preprocessor"></a>
+
+## Module document\_preprocessor
+
+<a id="document_preprocessor.DocumentPreprocessor"></a>
+
+### 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"])
+```
+
+<a id="document_preprocessor.DocumentPreprocessor.__init__"></a>
+
+#### DocumentPreprocessor.\_\_init\_\_
+
+```python
+def __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**:
+
+**Arguments**:
+
+- `split_by`: The unit of splitting: "function", "page", "passage", "period", "word", "line", or "sentence".
+- `split_length`: The maximum number of units (words, lines, pages, and so on) in each split.
+- `split_overlap`: The number of overlapping units between consecutive splits.
+- `split_threshold`: The minimum number of units per split. If a split is smaller than this, it's merged
+with the previous split.
+- `splitting_function`: A custom function for splitting if `split_by="function"`.
+- `respect_sentence_boundary`: If `True`, splits by words but tries not to break inside a sentence.
+- `language`: Language used by the sentence tokenizer if `split_by="sentence"` or
+`respect_sentence_boundary=True`.
+- `use_split_rules`: Whether to apply additional splitting heuristics for the sentence splitter.
+- `extend_abbreviations`: Whether to extend the sentence splitter with curated abbreviations for certain
+languages.
+
+**Cleaner Parameters**:
+- `remove_empty_lines`: If `True`, removes empty lines.
+- `remove_extra_whitespaces`: If `True`, removes extra whitespaces.
+- `remove_repeated_substrings`: If `True`, removes repeated substrings like headers/footers across pages.
+- `keep_id`: If `True`, keeps the original document IDs.
+- `remove_substrings`: A list of strings to remove from the document content.
+- `remove_regex`: A regex pattern whose matches will be removed from the document content.
+- `unicode_normalization`: Unicode normalization form to apply to the text, for example `"NFC"`.
+- `ascii_only`: If `True`, converts text to ASCII only.
+
+<a id="document_preprocessor.DocumentPreprocessor.to_dict"></a>
+
+#### DocumentPreprocessor.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize SuperComponent to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="document_preprocessor.DocumentPreprocessor.from_dict"></a>
+
+#### DocumentPreprocessor.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "DocumentPreprocessor"
+```
+
+Deserializes the SuperComponent from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized SuperComponent.
+
+<a id="document_splitter"></a>
+
+## Module document\_splitter
+
+<a id="document_splitter.DocumentSplitter"></a>
+
+### 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])
+```
+
+<a id="document_splitter.DocumentSplitter.__init__"></a>
+
+#### DocumentSplitter.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Initialize DocumentSplitter.
+
+**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 NLTK 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.
+- `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.
+- `respect_sentence_boundary`: 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`: Choose the language for the NLTK tokenizer. The default is English ("en").
+- `use_split_rules`: Choose whether to use additional split rules when splitting by `sentence`.
+- `extend_abbreviations`: 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`: 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.
+
+<a id="document_splitter.DocumentSplitter.warm_up"></a>
+
+#### DocumentSplitter.warm\_up
+
+```python
+def warm_up()
+```
+
+Warm up the DocumentSplitter by loading the sentence tokenizer.
+
+<a id="document_splitter.DocumentSplitter.run"></a>
+
+#### DocumentSplitter.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: 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`.
+
+**Arguments**:
+
+- `documents`: The documents to split.
+
+**Raises**:
+
+- `TypeError`: if the input is not a list of Documents.
+- `ValueError`: if the content of a document is None.
+
+**Returns**:
+
+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.
+
+<a id="document_splitter.DocumentSplitter.to_dict"></a>
+
+#### DocumentSplitter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+<a id="document_splitter.DocumentSplitter.from_dict"></a>
+
+#### DocumentSplitter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "DocumentSplitter"
+```
+
+Deserializes the component from a dictionary.
+
+<a id="hierarchical_document_splitter"></a>
+
+## Module hierarchical\_document\_splitter
+
+<a id="hierarchical_document_splitter.HierarchicalDocumentSplitter"></a>
+
+### 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})]}
+```
+
+<a id="hierarchical_document_splitter.HierarchicalDocumentSplitter.__init__"></a>
+
+#### HierarchicalDocumentSplitter.\_\_init\_\_
+
+```python
+def __init__(block_sizes: set[int],
+             split_overlap: int = 0,
+             split_by: Literal["word", "sentence", "page",
+                               "passage"] = "word")
+```
+
+Initialize HierarchicalDocumentSplitter.
+
+**Arguments**:
+
+- `block_sizes`: Set of block sizes to split the document into. The blocks are split in descending order.
+- `split_overlap`: The number of overlapping units for each split.
+- `split_by`: The unit for splitting your documents.
+
+<a id="hierarchical_document_splitter.HierarchicalDocumentSplitter.run"></a>
+
+#### HierarchicalDocumentSplitter.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document])
+```
+
+Builds a hierarchical document structure for each document in a list of documents.
+
+**Arguments**:
+
+- `documents`: List of Documents to split into hierarchical blocks.
+
+**Returns**:
+
+List of HierarchicalDocument
+
+<a id="hierarchical_document_splitter.HierarchicalDocumentSplitter.build_hierarchy_from_doc"></a>
+
+#### HierarchicalDocumentSplitter.build\_hierarchy\_from\_doc
+
+```python
+def 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.
+
+**Arguments**:
+
+- `document`: Document to split into hierarchical blocks.
+
+**Returns**:
+
+List of HierarchicalDocument
+
+<a id="hierarchical_document_splitter.HierarchicalDocumentSplitter.to_dict"></a>
+
+#### HierarchicalDocumentSplitter.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Returns a dictionary representation of the component.
+
+**Returns**:
+
+Serialized dictionary representation of the component.
+
+<a id="hierarchical_document_splitter.HierarchicalDocumentSplitter.from_dict"></a>
+
+#### HierarchicalDocumentSplitter.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "HierarchicalDocumentSplitter"
+```
+
+Deserialize this component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize and create the component.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="recursive_splitter"></a>
+
+## Module recursive\_splitter
+
+<a id="recursive_splitter.RecursiveDocumentSplitter"></a>
+
+### 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.''')
+chunker.warm_up()
+doc = Document(content=text)
+doc_chunks = chunker.run([doc])
+print(doc_chunks["documents"])
+>[
+>Document(id=..., content: 'Artificial intelligence (AI) - Introduction\n\n', meta: {'original_id': '...', 'split_id': 0, 'split_idx_start': 0, '_split_overlap': []})
+>Document(id=..., content: 'AI, in its broadest sense, is intelligence exhibited by machines, particularly computer systems.\n', meta: {'original_id': '...', 'split_id': 1, 'split_idx_start': 45, '_split_overlap': []})
+>Document(id=..., content: 'AI technology is widely used throughout industry, government, and science.', meta: {'original_id': '...', 'split_id': 2, 'split_idx_start': 142, '_split_overlap': []})
+>Document(id=..., content: ' Some high-profile applications include advanced web search engines; recommendation systems; interac...', meta: {'original_id': '...', 'split_id': 3, 'split_idx_start': 216, '_split_overlap': []})
+>]
+```
+
+<a id="recursive_splitter.RecursiveDocumentSplitter.__init__"></a>
+
+#### RecursiveDocumentSplitter.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Initializes a RecursiveDocumentSplitter.
+
+**Arguments**:
+
+- `split_length`: The maximum length of each chunk by default in words, but can be in characters or tokens.
+See the `split_units` parameter.
+- `split_overlap`: The number of characters to overlap between consecutive chunks.
+- `split_unit`: 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`: 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`: Optional parameters to pass to the sentence tokenizer.
+See: haystack.components.preprocessors.sentence_tokenizer.SentenceSplitter for more information.
+
+**Raises**:
+
+- `ValueError`: If the overlap is greater than or equal to the chunk size or if the overlap is negative, or
+if any separator is not a string.
+
+<a id="recursive_splitter.RecursiveDocumentSplitter.warm_up"></a>
+
+#### RecursiveDocumentSplitter.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Warm up the sentence tokenizer and tiktoken tokenizer if needed.
+
+<a id="recursive_splitter.RecursiveDocumentSplitter.run"></a>
+
+#### RecursiveDocumentSplitter.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Split a list of documents into documents with smaller chunks of text.
+
+**Arguments**:
+
+- `documents`: List of Documents to split.
+
+**Returns**:
+
+A dictionary containing a key "documents" with a List of Documents with smaller chunks of text corresponding
+to the input documents.
+
+<a id="text_cleaner"></a>
+
+## Module text\_cleaner
+
+<a id="text_cleaner.TextCleaner"></a>
+
+### 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])
+```
+
+<a id="text_cleaner.TextCleaner.__init__"></a>
+
+#### TextCleaner.\_\_init\_\_
+
+```python
+def __init__(remove_regexps: list[str] | None = None,
+             convert_to_lowercase: bool = False,
+             remove_punctuation: bool = False,
+             remove_numbers: bool = False)
+```
+
+Initializes the TextCleaner component.
+
+**Arguments**:
+
+- `remove_regexps`: A list of regex patterns to remove matching substrings from the text.
+- `convert_to_lowercase`: If `True`, converts all characters to lowercase.
+- `remove_punctuation`: If `True`, removes punctuation from the text.
+- `remove_numbers`: If `True`, removes numerical digits from the text.
+
+<a id="text_cleaner.TextCleaner.run"></a>
+
+#### TextCleaner.run
+
+```python
+@component.output_types(texts=list[str])
+def run(texts: list[str]) -> dict[str, Any]
+```
+
+Cleans up the given list of strings.
+
+**Arguments**:
+
+- `texts`: List of strings to clean.
+
+**Returns**:
+
+A dictionary with the following key:
+- `texts`:  the cleaned list of strings.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/query_api.md

@@ -0,0 +1,142 @@
+---
+title: "Query"
+id: query-api
+description: "Components for query processing and expansion."
+slug: "/query-api"
+---
+
+<a id="query_expander"></a>
+
+## Module query\_expander
+
+<a id="query_expander.QueryExpander"></a>
+
+### 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:
+
+### Usage example
+
+```json
+{"queries": ["expanded query 1", "expanded query 2", "expanded query 3"]}
+```
+```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
+```
+
+<a id="query_expander.QueryExpander.__init__"></a>
+
+#### QueryExpander.\_\_init\_\_
+
+```python
+def __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.
+
+**Arguments**:
+
+- `chat_generator`: The chat generator component to use for query expansion.
+If None, a default OpenAIChatGenerator with gpt-4.1-mini model is used.
+- `prompt_template`: 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`: Number of alternative queries to generate (default: 4).
+- `include_original_query`: Whether to include the original query in the output.
+
+<a id="query_expander.QueryExpander.to_dict"></a>
+
+#### QueryExpander.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="query_expander.QueryExpander.from_dict"></a>
+
+#### QueryExpander.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "QueryExpander"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary with serialized data.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="query_expander.QueryExpander.run"></a>
+
+#### QueryExpander.run
+
+```python
+@component.output_types(queries=list[str])
+def 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.
+
+**Arguments**:
+
+- `query`: The original query to expand.
+- `n_expansions`: 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.
+
+**Raises**:
+
+- `ValueError`: If n_expansions is not positive (less than or equal to 0).
+
+**Returns**:
+
+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.
+
+<a id="query_expander.QueryExpander.warm_up"></a>
+
+#### QueryExpander.warm\_up
+
+```python
+def warm_up()
+```
+
+Warm up the LLM provider component.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/readers_api.md

@@ -0,0 +1,206 @@
+---
+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"
+---
+
+<a id="extractive"></a>
+
+## Module extractive
+
+<a id="extractive.ExtractiveReader"></a>
+
+### 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()
+reader.warm_up()
+
+question = "What is a popular programming language?"
+result = reader.run(query=question, documents=docs)
+assert "Python" in result["answers"][0].data
+```
+
+<a id="extractive.ExtractiveReader.__init__"></a>
+
+#### ExtractiveReader.\_\_init\_\_
+
+```python
+def __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.
+
+**Arguments**:
+
+- `model`: 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`: The device on which the model is loaded. If `None`, the default device is automatically selected.
+- `token`: The API token used to download private models from Hugging Face.
+- `top_k`: 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`: Returns only answers with the probability score above this threshold.
+- `max_seq_length`: Maximum number of tokens. If a sequence exceeds it, the sequence is split.
+- `stride`: Number of tokens that overlap when sequence is split because it exceeds max_seq_length.
+- `max_batch_size`: Maximum number of samples that are fed through the model at the same time.
+- `answers_per_seq`: 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`: 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`: Factor used for calibrating probabilities.
+- `overlap_threshold`: 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`: 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.
+
+<a id="extractive.ExtractiveReader.to_dict"></a>
+
+#### ExtractiveReader.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="extractive.ExtractiveReader.from_dict"></a>
+
+#### ExtractiveReader.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "ExtractiveReader"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized component.
+
+<a id="extractive.ExtractiveReader.warm_up"></a>
+
+#### ExtractiveReader.warm\_up
+
+```python
+def warm_up()
+```
+
+Initializes the component.
+
+<a id="extractive.ExtractiveReader.deduplicate_by_overlap"></a>
+
+#### ExtractiveReader.deduplicate\_by\_overlap
+
+```python
+def 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.
+
+**Arguments**:
+
+- `answers`: List of answers to be deduplicated.
+- `overlap_threshold`: If set this will remove duplicate answers if they have an overlap larger than the
+supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove
+one of these answers since the second answer has a 100% (1.0) overlap with the first answer.
+However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so
+both of these answers could be kept if this variable is set to 0.24 or lower.
+If None is provided then all answers are kept.
+
+**Returns**:
+
+List of deduplicated answers.
+
+<a id="extractive.ExtractiveReader.run"></a>
+
+#### ExtractiveReader.run
+
+```python
+@component.output_types(answers=list[ExtractedAnswer])
+def 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)
+```
+
+Locates and extracts answers from the given Documents using the given query.
+
+**Arguments**:
+
+- `query`: Query string.
+- `documents`: List of Documents in which you want to search for an answer to the query.
+- `top_k`: The maximum number of answers to return.
+An additional answer is returned if no_answer is set to True (default).
+- `score_threshold`: Returns only answers with the score above this threshold.
+- `max_seq_length`: Maximum number of tokens. If a sequence exceeds it, the sequence is split.
+- `stride`: Number of tokens that overlap when sequence is split because it exceeds max_seq_length.
+- `max_batch_size`: Maximum number of samples that are fed through the model at the same time.
+- `answers_per_seq`: 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`: Whether to return no answer scores.
+- `overlap_threshold`: If set this will remove duplicate answers if they have an overlap larger than the
+supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove
+one of these answers since the second answer has a 100% (1.0) overlap with the first answer.
+However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so
+both of these answers could be kept if this variable is set to 0.24 or lower.
+If None is provided then all answers are kept.
+
+**Returns**:
+
+List of answers sorted by (desc.) answer score.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/samplers_api.md

@@ -0,0 +1,88 @@
+---
+title: "Samplers"
+id: samplers-api
+description: "Filters documents based on their similarity scores using top-p sampling."
+slug: "/samplers-api"
+---
+
+<a id="top_p"></a>
+
+## Module top\_p
+
+<a id="top_p.TopPSampler"></a>
+
+### 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"
+```
+
+<a id="top_p.TopPSampler.__init__"></a>
+
+#### TopPSampler.\_\_init\_\_
+
+```python
+def __init__(top_p: float = 1.0,
+             score_field: str | None = None,
+             min_top_k: int | None = None)
+```
+
+Creates an instance of TopPSampler.
+
+**Arguments**:
+
+- `top_p`: 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`: 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`: 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.
+
+<a id="top_p.TopPSampler.run"></a>
+
+#### TopPSampler.run
+
+```python
+@component.output_types(documents=list[Document])
+def run(documents: list[Document], top_p: float | None = None)
+```
+
+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.
+
+**Arguments**:
+
+- `documents`: List of Document objects to be filtered.
+- `top_p`: If specified, a float to override the cumulative probability threshold set during initialization.
+
+**Raises**:
+
+- `ValueError`: If the top_p value is not within the range [0, 1].
+
+**Returns**:
+
+A dictionary with the following key:
+- `documents`: List of Document objects that have been selected based on the top-p sampling.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/tool_components_api.md

@@ -0,0 +1,323 @@
+---
+title: "Tool Components"
+id: tool-components-api
+description: "Components related to Tool Calling."
+slug: "/tool-components-api"
+---
+
+<a id="tool_invoker"></a>
+
+## Module tool\_invoker
+
+<a id="tool_invoker.ToolInvokerError"></a>
+
+### ToolInvokerError
+
+Base exception class for ToolInvoker errors.
+
+<a id="tool_invoker.ToolNotFoundException"></a>
+
+### ToolNotFoundException
+
+Exception raised when a tool is not found in the list of available tools.
+
+<a id="tool_invoker.StringConversionError"></a>
+
+### StringConversionError
+
+Exception raised when the conversion of a tool result to a string fails.
+
+<a id="tool_invoker.ToolOutputMergeError"></a>
+
+### ToolOutputMergeError
+
+Exception raised when merging tool outputs into state fails.
+
+<a id="tool_invoker.ToolOutputMergeError.from_exception"></a>
+
+#### ToolOutputMergeError.from\_exception
+
+```python
+@classmethod
+def from_exception(cls, tool_name: str,
+                   error: Exception) -> "ToolOutputMergeError"
+```
+
+Create a ToolOutputMergeError from an exception.
+
+<a id="tool_invoker.ToolInvoker"></a>
+
+### 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)
+
+<a id="tool_invoker.ToolInvoker.__init__"></a>
+
+#### ToolInvoker.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Initialize the ToolInvoker component.
+
+**Arguments**:
+
+- `tools`: A list of Tool and/or Toolset objects, or a Toolset instance that can resolve tools.
+- `raise_on_failure`: 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`: 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`: 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`: 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`: The maximum number of workers to use in the thread pool executor.
+This also decides the maximum number of concurrent tool invocations.
+
+**Raises**:
+
+- `ValueError`: If no tools are provided or if duplicate tool names are found.
+
+<a id="tool_invoker.ToolInvoker.warm_up"></a>
+
+#### ToolInvoker.warm\_up
+
+```python
+def warm_up()
+```
+
+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.
+
+<a id="tool_invoker.ToolInvoker.run"></a>
+
+#### ToolInvoker.run
+
+```python
+@component.output_types(tool_messages=list[ChatMessage], state=State)
+def 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.
+
+**Arguments**:
+
+- `messages`: A list of ChatMessage objects.
+- `state`: The runtime state that should be used by the tools.
+- `streaming_callback`: 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`: 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`: 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.
+
+**Raises**:
+
+- `ToolNotFoundException`: If the tool is not found in the list of available tools and `raise_on_failure` is True.
+- `ToolInvocationError`: If the tool invocation fails and `raise_on_failure` is True.
+- `StringConversionError`: If the conversion of the tool result to a string fails and `raise_on_failure` is True.
+- `ToolOutputMergeError`: If merging tool outputs into state fails and `raise_on_failure` is True.
+
+**Returns**:
+
+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.
+
+<a id="tool_invoker.ToolInvoker.run_async"></a>
+
+#### ToolInvoker.run\_async
+
+```python
+@component.output_types(tool_messages=list[ChatMessage], state=State)
+async def 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.
+
+**Arguments**:
+
+- `messages`: A list of ChatMessage objects.
+- `state`: The runtime state that should be used by the tools.
+- `streaming_callback`: 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`: 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`: 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.
+
+**Raises**:
+
+- `ToolNotFoundException`: If the tool is not found in the list of available tools and `raise_on_failure` is True.
+- `ToolInvocationError`: If the tool invocation fails and `raise_on_failure` is True.
+- `StringConversionError`: If the conversion of the tool result to a string fails and `raise_on_failure` is True.
+- `ToolOutputMergeError`: If merging tool outputs into state fails and `raise_on_failure` is True.
+
+**Returns**:
+
+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.
+
+<a id="tool_invoker.ToolInvoker.to_dict"></a>
+
+#### ToolInvoker.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="tool_invoker.ToolInvoker.from_dict"></a>
+
+#### ToolInvoker.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "ToolInvoker"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/tools_api.md

@@ -0,0 +1,953 @@
+---
+title: "Tools"
+id: tools-api
+description: "Unified abstractions to represent tools across the framework."
+slug: "/tools-api"
+---
+
+<a id="component_tool"></a>
+
+## Module component\_tool
+
+<a id="component_tool.ComponentTool"></a>
+
+### ComponentTool
+
+A Tool that wraps Haystack components, allowing them to be used as tools by LLMs.
+
+ComponentTool automatically generates LLM-compatible tool schemas from component input sockets,
+which are derived from the component's `run` method signature and type hints.
+
+
+Key features:
+- Automatic LLM tool calling schema generation from component input sockets
+- Type conversion and validation for component inputs
+- Support for types:
+- Dataclasses
+- Lists of dataclasses
+- Basic types (str, int, float, bool, dict)
+- Lists of basic types
+- Automatic name generation from component class name
+- Description extraction from component docstrings
+
+To use ComponentTool, you first need a Haystack component - either an existing one or a new one you create.
+You can create a ComponentTool from the component by passing the component to the ComponentTool constructor.
+Below is an example of creating a ComponentTool from an existing SerperDevWebSearch component.
+
+## Usage Example:
+
+```python
+from haystack import component, Pipeline
+from haystack.tools import ComponentTool
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.utils import Secret
+from haystack.components.tools.tool_invoker import ToolInvoker
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+# Create a SerperDev search component
+search = SerperDevWebSearch(api_key=Secret.from_env_var("SERPERDEV_API_KEY"), top_k=3)
+
+# Create a tool from the component
+tool = ComponentTool(
+    component=search,
+    name="web_search",  # Optional: defaults to "serper_dev_web_search"
+    description="Search the web for current information on any topic"  # Optional: defaults to component docstring
+)
+
+# Create pipeline with OpenAIChatGenerator and ToolInvoker
+pipeline = Pipeline()
+pipeline.add_component("llm", OpenAIChatGenerator(tools=[tool]))
+pipeline.add_component("tool_invoker", ToolInvoker(tools=[tool]))
+
+# Connect components
+pipeline.connect("llm.replies", "tool_invoker.messages")
+
+message = ChatMessage.from_user("Use the web search tool to find information about Nikola Tesla")
+
+# Run pipeline
+result = pipeline.run({"llm": {"messages": [message]}})
+
+print(result)
+```
+
+<a id="component_tool.ComponentTool.__init__"></a>
+
+#### ComponentTool.\_\_init\_\_
+
+```python
+def __init__(
+    component: Component,
+    name: str | None = None,
+    description: str | None = None,
+    parameters: dict[str, Any] | None = None,
+    *,
+    outputs_to_string: dict[str, str | Callable[[Any], str]] | None = None,
+    inputs_from_state: dict[str, str] | None = None,
+    outputs_to_state: dict[str, dict[str, str | Callable]] | None = None
+) -> None
+```
+
+Create a Tool instance from a Haystack component.
+
+**Arguments**:
+
+- `component`: The Haystack component to wrap as a tool.
+- `name`: Optional name for the tool (defaults to snake_case of component class name).
+- `description`: Optional description (defaults to component's docstring).
+- `parameters`: A JSON schema defining the parameters expected by the Tool.
+Will fall back to the parameters defined in the component's run method signature if not provided.
+- `outputs_to_string`: Optional dictionary defining how tool outputs should be converted into string(s).
+Supports two formats:
+
+1. Single output format - use "source" and/or "handler" at the root level:
+    ```python
+    {
+        "source": "docs", "handler": format_documents
+    }
+    ```
+    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.
+
+2. Multiple output format - map keys to individual configurations:
+    ```python
+    {
+        "formatted_docs": {"source": "docs", "handler": format_documents},
+        "summary": {"source": "summary_text", "handler": str.upper}
+    }
+    ```
+    Each key maps to a dictionary that can contain "source" and/or "handler".
+- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names.
+Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- `outputs_to_state`: Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
+If the source is provided only the specified output key is sent to the handler.
+Example:
+```python
+{
+    "documents": {"source": "docs", "handler": custom_handler}
+}
+```
+If the source is omitted the whole tool result is sent to the handler.
+Example:
+```python
+{
+    "documents": {"handler": custom_handler}
+}
+```
+
+**Raises**:
+
+- `ValueError`: If the component is invalid or schema generation fails.
+
+<a id="component_tool.ComponentTool.warm_up"></a>
+
+#### ComponentTool.warm\_up
+
+```python
+def warm_up()
+```
+
+Prepare the ComponentTool for use.
+
+<a id="component_tool.ComponentTool.to_dict"></a>
+
+#### ComponentTool.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the ComponentTool to a dictionary.
+
+<a id="component_tool.ComponentTool.from_dict"></a>
+
+#### ComponentTool.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "ComponentTool"
+```
+
+Deserializes the ComponentTool from a dictionary.
+
+<a id="component_tool.ComponentTool.tool_spec"></a>
+
+#### ComponentTool.tool\_spec
+
+```python
+@property
+def tool_spec() -> dict[str, Any]
+```
+
+Return the Tool specification to be used by the Language Model.
+
+<a id="component_tool.ComponentTool.invoke"></a>
+
+#### ComponentTool.invoke
+
+```python
+def invoke(**kwargs: Any) -> Any
+```
+
+Invoke the Tool with the provided keyword arguments.
+
+<a id="from_function"></a>
+
+## Module from\_function
+
+<a id="from_function.create_tool_from_function"></a>
+
+#### create\_tool\_from\_function
+
+```python
+def create_tool_from_function(
+        function: Callable,
+        name: str | None = None,
+        description: str | None = None,
+        inputs_from_state: dict[str, str] | None = None,
+        outputs_to_state: dict[str, dict[str, Any]] | None = None) -> "Tool"
+```
+
+Create a Tool instance from a function.
+
+Allows customizing the Tool name and description.
+For simpler use cases, consider using the `@tool` decorator.
+
+### Usage example
+
+```python
+from typing import Annotated, Literal
+from haystack.tools import create_tool_from_function
+
+def get_weather(
+    city: Annotated[str, "the city for which to get the weather"] = "Munich",
+    unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
+    '''A simple function to get the current weather for a location.'''
+    return f"Weather report for {city}: 20 {unit}, sunny"
+
+tool = create_tool_from_function(get_weather)
+
+print(tool)
+>>> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
+>>> parameters={
+>>> 'type': 'object',
+>>> 'properties': {
+>>>     'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
+>>>     'unit': {
+>>>         'type': 'string',
+>>>         'enum': ['Celsius', 'Fahrenheit'],
+>>>         'description': 'the unit for the temperature',
+>>>         'default': 'Celsius',
+>>>     },
+>>>     }
+>>> },
+>>> function=<function get_weather at 0x7f7b3a8a9b80>)
+```
+
+**Arguments**:
+
+- `function`: The function to be converted into a Tool.
+The function must include type hints for all parameters.
+The function is expected to have basic python input types (str, int, float, bool, list, dict, tuple).
+Other input types may work but are not guaranteed.
+If a parameter is annotated using `typing.Annotated`, its metadata will be used as parameter description.
+- `name`: The name of the Tool. If not provided, the name of the function will be used.
+- `description`: The description of the Tool. If not provided, the docstring of the function will be used.
+To intentionally leave the description empty, pass an empty string.
+- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names.
+Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- `outputs_to_state`: Optional dictionary defining how tool outputs map to state and message handling.
+Example:
+```python
+{
+    "documents": {"source": "docs", "handler": custom_handler},
+    "message": {"source": "summary", "handler": format_summary}
+}
+```
+
+**Raises**:
+
+- `ValueError`: If any parameter of the function lacks a type hint.
+- `SchemaGenerationError`: If there is an error generating the JSON schema for the Tool.
+
+**Returns**:
+
+The Tool created from the function.
+
+<a id="from_function.tool"></a>
+
+#### tool
+
+```python
+def tool(
+    function: Callable | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    inputs_from_state: dict[str, str] | None = None,
+    outputs_to_state: dict[str, dict[str, Any]] | None = None
+) -> Tool | Callable[[Callable], Tool]
+```
+
+Decorator to convert a function into a Tool.
+
+Can be used with or without parameters:
+@tool  # without parameters
+def my_function(): ...
+
+@tool(name="custom_name")  # with parameters
+def my_function(): ...
+
+### Usage example
+```python
+from typing import Annotated, Literal
+from haystack.tools import tool
+
+@tool
+def get_weather(
+    city: Annotated[str, "the city for which to get the weather"] = "Munich",
+    unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
+    '''A simple function to get the current weather for a location.'''
+    return f"Weather report for {city}: 20 {unit}, sunny"
+
+print(get_weather)
+>>> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
+>>> parameters={
+>>> 'type': 'object',
+>>> 'properties': {
+>>>     'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
+>>>     'unit': {
+>>>         'type': 'string',
+>>>         'enum': ['Celsius', 'Fahrenheit'],
+>>>         'description': 'the unit for the temperature',
+>>>         'default': 'Celsius',
+>>>     },
+>>>     }
+>>> },
+>>> function=<function get_weather at 0x7f7b3a8a9b80>)
+```
+
+**Arguments**:
+
+- `function`: The function to decorate (when used without parameters)
+- `name`: Optional custom name for the tool
+- `description`: Optional custom description
+- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names
+- `outputs_to_state`: Optional dictionary defining how tool outputs map to state and message handling
+
+**Returns**:
+
+Either a Tool instance or a decorator function that will create one
+
+<a id="tool"></a>
+
+## Module tool
+
+<a id="tool.Tool"></a>
+
+### Tool
+
+Data class representing a Tool that Language Models can prepare a call for.
+
+Accurate definitions of the textual attributes such as `name` and `description`
+are important for the Language Model to correctly prepare the call.
+
+For resource-intensive operations like establishing connections to remote services or
+loading models, override the `warm_up()` method. This method is called before the Tool
+is used and should be idempotent, as it may be called multiple times during
+pipeline/agent setup.
+
+**Arguments**:
+
+- `name`: Name of the Tool.
+- `description`: Description of the Tool.
+- `parameters`: A JSON schema defining the parameters expected by the Tool.
+- `function`: The function that will be invoked when the Tool is called.
+Must be a synchronous function; async functions are not supported.
+- `outputs_to_string`: Optional dictionary defining how tool outputs should be converted into string(s).
+Supports two formats:
+
+1. Single output format - use "source" and/or "handler" at the root level:
+   ```python
+   {
+       "source": "docs", "handler": format_documents
+   }
+   ```
+   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.
+
+2. Multiple output format - map keys to individual configurations:
+   ```python
+   {
+       "formatted_docs": {"source": "docs", "handler": format_documents},
+       "summary": {"source": "summary_text", "handler": str.upper}
+   }
+   ```
+   Each key maps to a dictionary that can contain "source" and/or "handler".
+- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names.
+Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter.
+- `outputs_to_state`: Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
+If the source is provided only the specified output key is sent to the handler.
+Example:
+```python
+{
+    "documents": {"source": "docs", "handler": custom_handler}
+}
+```
+If the source is omitted the whole tool result is sent to the handler.
+Example:
+```python
+{
+    "documents": {"handler": custom_handler}
+}
+```
+
+<a id="tool.Tool.tool_spec"></a>
+
+#### Tool.tool\_spec
+
+```python
+@property
+def tool_spec() -> dict[str, Any]
+```
+
+Return the Tool specification to be used by the Language Model.
+
+<a id="tool.Tool.warm_up"></a>
+
+#### Tool.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Prepare the Tool for use.
+
+Override this method to establish connections to remote services, load models,
+or perform other resource-intensive initialization. This method should be idempotent,
+as it may be called multiple times.
+
+<a id="tool.Tool.invoke"></a>
+
+#### Tool.invoke
+
+```python
+def invoke(**kwargs: Any) -> Any
+```
+
+Invoke the Tool with the provided keyword arguments.
+
+<a id="tool.Tool.to_dict"></a>
+
+#### Tool.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the Tool to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="tool.Tool.from_dict"></a>
+
+#### Tool.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "Tool"
+```
+
+Deserializes the Tool from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary to deserialize from.
+
+**Returns**:
+
+Deserialized Tool.
+
+<a id="toolset"></a>
+
+## Module toolset
+
+<a id="toolset.Toolset"></a>
+
+### Toolset
+
+A collection of related Tools that can be used and managed as a cohesive unit.
+
+Toolset serves two main purposes:
+
+1. Group related tools together:
+Toolset allows you to organize related tools into a single collection, making it easier
+to manage and use them as a unit in Haystack pipelines.
+
+**Example**:
+
+   ```python
+   from haystack.tools import Tool, Toolset
+   from haystack.components.tools import ToolInvoker
+
+   # Define math functions
+   def add_numbers(a: int, b: int) -> int:
+       return a + b
+
+   def subtract_numbers(a: int, b: int) -> int:
+       return a - b
+
+   # Create tools with proper schemas
+   add_tool = Tool(
+       name="add",
+       description="Add two numbers",
+       parameters={
+           "type": "object",
+           "properties": {
+               "a": {"type": "integer"},
+               "b": {"type": "integer"}
+           },
+           "required": ["a", "b"]
+       },
+       function=add_numbers
+   )
+
+   subtract_tool = Tool(
+       name="subtract",
+       description="Subtract b from a",
+       parameters={
+           "type": "object",
+           "properties": {
+               "a": {"type": "integer"},
+               "b": {"type": "integer"}
+           },
+           "required": ["a", "b"]
+       },
+       function=subtract_numbers
+   )
+
+   # Create a toolset with the math tools
+   math_toolset = Toolset([add_tool, subtract_tool])
+
+   # Use the toolset with a ToolInvoker or ChatGenerator component
+   invoker = ToolInvoker(tools=math_toolset)
+   ```
+  
+  2. Base class for dynamic tool loading:
+  By subclassing Toolset, you can create implementations that dynamically load tools
+  from external sources like OpenAPI URLs, MCP servers, or other resources.
+  
+
+**Example**:
+
+   ```python
+   from haystack.core.serialization import generate_qualified_class_name
+   from haystack.tools import Tool, Toolset
+   from haystack.components.tools import ToolInvoker
+
+   class CalculatorToolset(Toolset):
+       '''A toolset for calculator operations.'''
+
+       def __init__(self):
+           tools = self._create_tools()
+           super().__init__(tools)
+
+       def _create_tools(self):
+           # These Tool instances are obviously defined statically and for illustration purposes only.
+           # In a real-world scenario, you would dynamically load tools from an external source here.
+           tools = []
+           add_tool = Tool(
+               name="add",
+               description="Add two numbers",
+               parameters={
+                   "type": "object",
+                   "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
+                   "required": ["a", "b"],
+               },
+               function=lambda a, b: a + b,
+           )
+
+           multiply_tool = Tool(
+               name="multiply",
+               description="Multiply two numbers",
+               parameters={
+                   "type": "object",
+                   "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
+                   "required": ["a", "b"],
+               },
+               function=lambda a, b: a * b,
+           )
+
+           tools.append(add_tool)
+           tools.append(multiply_tool)
+
+           return tools
+
+       def to_dict(self):
+           return {
+               "type": generate_qualified_class_name(type(self)),
+               "data": {},  # no data to serialize as we define the tools dynamically
+           }
+
+       @classmethod
+       def from_dict(cls, data):
+           return cls()  # Recreate the tools dynamically during deserialization
+
+   # Create the dynamic toolset and use it with ToolInvoker
+   calculator_toolset = CalculatorToolset()
+   invoker = ToolInvoker(tools=calculator_toolset)
+   ```
+  
+  Toolset implements the collection interface (__iter__, __contains__, __len__, __getitem__),
+  making it behave like a list of Tools. This makes it compatible with components that expect
+  iterable tools, such as ToolInvoker or Haystack chat generators.
+  
+  When implementing a custom Toolset subclass for dynamic tool loading:
+  - Perform the dynamic loading in the __init__ method
+  - Override to_dict() and from_dict() methods if your tools are defined dynamically
+  - Serialize endpoint descriptors rather than tool instances if your tools
+  are loaded from external sources
+
+<a id="toolset.Toolset.__post_init__"></a>
+
+#### Toolset.\_\_post\_init\_\_
+
+```python
+def __post_init__()
+```
+
+Validate and set up the toolset after initialization.
+
+This handles the case when tools are provided during initialization.
+
+<a id="toolset.Toolset.__iter__"></a>
+
+#### Toolset.\_\_iter\_\_
+
+```python
+def __iter__() -> Iterator[Tool]
+```
+
+Return an iterator over the Tools in this Toolset.
+
+This allows the Toolset to be used wherever a list of Tools is expected.
+
+**Returns**:
+
+An iterator yielding Tool instances
+
+<a id="toolset.Toolset.__contains__"></a>
+
+#### Toolset.\_\_contains\_\_
+
+```python
+def __contains__(item: Any) -> bool
+```
+
+Check if a tool is in this Toolset.
+
+Supports checking by:
+- Tool instance: tool in toolset
+- Tool name: "tool_name" in toolset
+
+**Arguments**:
+
+- `item`: Tool instance or tool name string
+
+**Returns**:
+
+True if contained, False otherwise
+
+<a id="toolset.Toolset.warm_up"></a>
+
+#### Toolset.warm\_up
+
+```python
+def warm_up() -> None
+```
+
+Prepare the Toolset for use.
+
+By default, this method iterates through and warms up all tools in the Toolset.
+Subclasses can override this method to customize initialization behavior, such as:
+
+- Setting up shared resources (database connections, HTTP sessions) instead of
+  warming individual tools
+- Implementing custom initialization logic for dynamically loaded tools
+- Controlling when and how tools are initialized
+
+For example, a Toolset that manages tools from an external service (like MCPToolset)
+might override this to initialize a shared connection rather than warming up
+individual tools:
+
+```python
+class MCPToolset(Toolset):
+    def warm_up(self) -> None:
+        # Only warm up the shared MCP connection, not individual tools
+        self.mcp_connection = establish_connection(self.server_url)
+```
+
+This method should be idempotent, as it may be called multiple times.
+
+<a id="toolset.Toolset.add"></a>
+
+#### Toolset.add
+
+```python
+def add(tool: Union[Tool, "Toolset"]) -> None
+```
+
+Add a new Tool or merge another Toolset.
+
+**Arguments**:
+
+- `tool`: A Tool instance or another Toolset to add
+
+**Raises**:
+
+- `ValueError`: If adding the tool would result in duplicate tool names
+- `TypeError`: If the provided object is not a Tool or Toolset
+
+<a id="toolset.Toolset.to_dict"></a>
+
+#### Toolset.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the Toolset to a dictionary.
+
+**Returns**:
+
+A dictionary representation of the Toolset
+Note for subclass implementers:
+The default implementation is ideal for scenarios where Tool resolution is static. However, if your subclass
+of Toolset dynamically resolves Tool instances from external sources—such as an MCP server, OpenAPI URL, or
+a local OpenAPI specification—you should consider serializing the endpoint descriptor instead of the Tool
+instances themselves. This strategy preserves the dynamic nature of your Toolset and minimizes the overhead
+associated with serializing potentially large collections of Tool objects. Moreover, by serializing the
+descriptor, you ensure that the deserialization process can accurately reconstruct the Tool instances, even
+if they have been modified or removed since the last serialization. Failing to serialize the descriptor may
+lead to issues where outdated or incorrect Tool configurations are loaded, potentially causing errors or
+unexpected behavior.
+
+<a id="toolset.Toolset.from_dict"></a>
+
+#### Toolset.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "Toolset"
+```
+
+Deserialize a Toolset from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary representation of the Toolset
+
+**Returns**:
+
+A new Toolset instance
+
+<a id="toolset.Toolset.__add__"></a>
+
+#### Toolset.\_\_add\_\_
+
+```python
+def __add__(other: Union[Tool, "Toolset", list[Tool]]) -> "Toolset"
+```
+
+Concatenate this Toolset with another Tool, Toolset, or list of Tools.
+
+**Arguments**:
+
+- `other`: Another Tool, Toolset, or list of Tools to concatenate
+
+**Raises**:
+
+- `TypeError`: If the other parameter is not a Tool, Toolset, or list of Tools
+- `ValueError`: If the combination would result in duplicate tool names
+
+**Returns**:
+
+A new Toolset containing all tools
+
+<a id="toolset.Toolset.__len__"></a>
+
+#### Toolset.\_\_len\_\_
+
+```python
+def __len__() -> int
+```
+
+Return the number of Tools in this Toolset.
+
+**Returns**:
+
+Number of Tools
+
+<a id="toolset.Toolset.__getitem__"></a>
+
+#### Toolset.\_\_getitem\_\_
+
+```python
+def __getitem__(index)
+```
+
+Get a Tool by index.
+
+**Arguments**:
+
+- `index`: Index of the Tool to get
+
+**Returns**:
+
+The Tool at the specified index
+
+<a id="toolset._ToolsetWrapper"></a>
+
+### \_ToolsetWrapper
+
+A wrapper that holds multiple toolsets and provides a unified interface.
+
+This is used internally when combining different types of toolsets to preserve
+their individual configurations while still being usable with ToolInvoker.
+
+<a id="toolset._ToolsetWrapper.__iter__"></a>
+
+#### \_ToolsetWrapper.\_\_iter\_\_
+
+```python
+def __iter__()
+```
+
+Iterate over all tools from all toolsets.
+
+<a id="toolset._ToolsetWrapper.__contains__"></a>
+
+#### \_ToolsetWrapper.\_\_contains\_\_
+
+```python
+def __contains__(item)
+```
+
+Check if a tool is in any of the toolsets.
+
+<a id="toolset._ToolsetWrapper.warm_up"></a>
+
+#### \_ToolsetWrapper.warm\_up
+
+```python
+def warm_up()
+```
+
+Warm up all toolsets.
+
+<a id="toolset._ToolsetWrapper.__len__"></a>
+
+#### \_ToolsetWrapper.\_\_len\_\_
+
+```python
+def __len__()
+```
+
+Return total number of tools across all toolsets.
+
+<a id="toolset._ToolsetWrapper.__getitem__"></a>
+
+#### \_ToolsetWrapper.\_\_getitem\_\_
+
+```python
+def __getitem__(index)
+```
+
+Get a tool by index across all toolsets.
+
+<a id="toolset._ToolsetWrapper.__add__"></a>
+
+#### \_ToolsetWrapper.\_\_add\_\_
+
+```python
+def __add__(other)
+```
+
+Add another toolset or tool to this wrapper.
+
+<a id="toolset._ToolsetWrapper.__post_init__"></a>
+
+#### \_ToolsetWrapper.\_\_post\_init\_\_
+
+```python
+def __post_init__()
+```
+
+Validate and set up the toolset after initialization.
+
+This handles the case when tools are provided during initialization.
+
+<a id="toolset._ToolsetWrapper.add"></a>
+
+#### \_ToolsetWrapper.add
+
+```python
+def add(tool: Union[Tool, "Toolset"]) -> None
+```
+
+Add a new Tool or merge another Toolset.
+
+**Arguments**:
+
+- `tool`: A Tool instance or another Toolset to add
+
+**Raises**:
+
+- `ValueError`: If adding the tool would result in duplicate tool names
+- `TypeError`: If the provided object is not a Tool or Toolset
+
+<a id="toolset._ToolsetWrapper.to_dict"></a>
+
+#### \_ToolsetWrapper.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serialize the Toolset to a dictionary.
+
+**Returns**:
+
+A dictionary representation of the Toolset
+Note for subclass implementers:
+The default implementation is ideal for scenarios where Tool resolution is static. However, if your subclass
+of Toolset dynamically resolves Tool instances from external sources—such as an MCP server, OpenAPI URL, or
+a local OpenAPI specification—you should consider serializing the endpoint descriptor instead of the Tool
+instances themselves. This strategy preserves the dynamic nature of your Toolset and minimizes the overhead
+associated with serializing potentially large collections of Tool objects. Moreover, by serializing the
+descriptor, you ensure that the deserialization process can accurately reconstruct the Tool instances, even
+if they have been modified or removed since the last serialization. Failing to serialize the descriptor may
+lead to issues where outdated or incorrect Tool configurations are loaded, potentially causing errors or
+unexpected behavior.
+
+<a id="toolset._ToolsetWrapper.from_dict"></a>
+
+#### \_ToolsetWrapper.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "Toolset"
+```
+
+Deserialize a Toolset from a dictionary.
+
+**Arguments**:
+
+- `data`: Dictionary representation of the Toolset
+
+**Returns**:
+
+A new Toolset instance
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/validators_api.md

@@ -0,0 +1,145 @@
+---
+title: "Validators"
+id: validators-api
+description: "Validators validate LLM outputs"
+slug: "/validators-api"
+---
+
+<a id="json_schema"></a>
+
+## Module json\_schema
+
+<a id="json_schema.is_valid_json"></a>
+
+#### is\_valid\_json
+
+```python
+def is_valid_json(s: str) -> bool
+```
+
+Check if the provided string is a valid JSON.
+
+**Arguments**:
+
+- `s`: The string to be checked.
+
+**Returns**:
+
+`True` if the string is a valid JSON; otherwise, `False`.
+
+<a id="json_schema.JsonSchemaValidator"></a>
+
+### 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(model="gpt-4-1106-preview",
+                                           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={'model': 'gpt-4-1106-preview', 'index': 0,
+'finish_reason': 'stop', 'usage': {'completion_tokens': 17, 'prompt_tokens': 20, 'total_tokens': 37}})]}}
+```
+
+<a id="json_schema.JsonSchemaValidator.__init__"></a>
+
+#### JsonSchemaValidator.\_\_init\_\_
+
+```python
+def __init__(json_schema: dict[str, Any] | None = None,
+             error_template: str | None = None)
+```
+
+Initialize the JsonSchemaValidator component.
+
+**Arguments**:
+
+- `json_schema`: A dictionary representing the [JSON schema](https://json-schema.org/) against which
+the messages' content is validated.
+- `error_template`: A custom template string for formatting the error message in case of validation failure.
+
+<a id="json_schema.JsonSchemaValidator.run"></a>
+
+#### JsonSchemaValidator.run
+
+```python
+@component.output_types(validated=list[ChatMessage],
+                        validation_error=list[ChatMessage])
+def 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.
+
+**Arguments**:
+
+- `messages`: A list of ChatMessage instances to be validated. The last message in this list is the one
+that is validated.
+- `json_schema`: 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`: 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.
+
+**Raises**:
+
+- `ValueError`: If no JSON schema is provided or if the message content is not a dictionary or a list of
+dictionaries.
+
+**Returns**:
+
+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.
+

docs-website/reference_versioned_docs/version-2.22/haystack-api/websearch_api.md

@@ -0,0 +1,228 @@
+---
+title: "Websearch"
+id: websearch-api
+description: "Web search engine for Haystack."
+slug: "/websearch-api"
+---
+
+<a id="searchapi"></a>
+
+## Module searchapi
+
+<a id="searchapi.SearchApiWebSearch"></a>
+
+### SearchApiWebSearch
+
+Uses [SearchApi](https://www.searchapi.io/) to search the web for relevant documents.
+
+Usage example:
+```python
+from haystack.components.websearch import SearchApiWebSearch
+from haystack.utils import Secret
+
+websearch = SearchApiWebSearch(top_k=10, api_key=Secret.from_token("test-api-key"))
+results = websearch.run(query="Who is the boyfriend of Olivia Wilde?")
+
+assert results["documents"]
+assert results["links"]
+```
+
+<a id="searchapi.SearchApiWebSearch.__init__"></a>
+
+#### SearchApiWebSearch.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Initialize the SearchApiWebSearch component.
+
+**Arguments**:
+
+- `api_key`: API key for the SearchApi API
+- `top_k`: Number of documents to return.
+- `allowed_domains`: List of domains to limit the search to.
+- `search_params`: Additional parameters passed to the SearchApi API.
+For example, you can set 'num' to 100 to increase the number of search results.
+See the [SearchApi website](https://www.searchapi.io/) for more details.
+
+The default search engine is Google, however, users can change it by setting the `engine`
+parameter in the `search_params`.
+
+<a id="searchapi.SearchApiWebSearch.to_dict"></a>
+
+#### SearchApiWebSearch.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="searchapi.SearchApiWebSearch.from_dict"></a>
+
+#### SearchApiWebSearch.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "SearchApiWebSearch"
+```
+
+Deserializes the component from a dictionary.
+
+**Arguments**:
+
+- `data`: The dictionary to deserialize from.
+
+**Returns**:
+
+The deserialized component.
+
+<a id="searchapi.SearchApiWebSearch.run"></a>
+
+#### SearchApiWebSearch.run
+
+```python
+@component.output_types(documents=list[Document], links=list[str])
+def run(query: str) -> dict[str, list[Document] | list[str]]
+```
+
+Uses [SearchApi](https://www.searchapi.io/) to search the web.
+
+**Arguments**:
+
+- `query`: Search query.
+
+**Raises**:
+
+- `TimeoutError`: If the request to the SearchApi API times out.
+- `SearchApiError`: If an error occurs while querying the SearchApi API.
+
+**Returns**:
+
+A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+
+<a id="serper_dev"></a>
+
+## Module serper\_dev
+
+<a id="serper_dev.SerperDevWebSearch"></a>
+
+### SerperDevWebSearch
+
+Uses [Serper](https://serper.dev/) to search the web for relevant documents.
+
+See the [Serper Dev website](https://serper.dev/) for more details.
+
+Usage example:
+```python
+from haystack.components.websearch import SerperDevWebSearch
+from haystack.utils import Secret
+
+websearch = SerperDevWebSearch(top_k=10, api_key=Secret.from_token("test-api-key"))
+results = websearch.run(query="Who is the boyfriend of Olivia Wilde?")
+
+assert results["documents"]
+assert results["links"]
+
+# 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=Secret.from_token("test-api-key")
+)
+results_filtered = websearch_filtered.run(query="search query")
+```
+
+<a id="serper_dev.SerperDevWebSearch.__init__"></a>
+
+#### SerperDevWebSearch.\_\_init\_\_
+
+```python
+def __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)
+```
+
+Initialize the SerperDevWebSearch component.
+
+**Arguments**:
+
+- `api_key`: API key for the Serper API.
+- `top_k`: Number of documents to return.
+- `allowed_domains`: List of domains to limit the search to.
+- `exclude_subdomains`: 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`: 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.
+
+<a id="serper_dev.SerperDevWebSearch.to_dict"></a>
+
+#### SerperDevWebSearch.to\_dict
+
+```python
+def to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="serper_dev.SerperDevWebSearch.from_dict"></a>
+
+#### SerperDevWebSearch.from\_dict
+
+```python
+@classmethod
+def from_dict(cls, data: dict[str, Any]) -> "SerperDevWebSearch"
+```
+
+Serializes the component to a dictionary.
+
+**Returns**:
+
+Dictionary with serialized data.
+
+<a id="serper_dev.SerperDevWebSearch.run"></a>
+
+#### SerperDevWebSearch.run
+
+```python
+@component.output_types(documents=list[Document], links=list[str])
+def run(query: str) -> dict[str, list[Document] | list[str]]
+```
+
+Use [Serper](https://serper.dev/) to search the web.
+
+**Arguments**:
+
+- `query`: Search query.
+
+**Raises**:
+
+- `SerperDevError`: If an error occurs while querying the SerperDev API.
+- `TimeoutError`: If the request to the SerperDev API times out.
+
+**Returns**:
+
+A dictionary with the following keys:
+- "documents": List of documents returned by the search engine.
+- "links": List of links returned by the search engine.
+

docs-website/reference_versioned_docs/version-2.22/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.22/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.22/integrations-api/alloydb.md

@@ -0,0 +1,601 @@
+---
+title: "AlloyDB"
+id: integrations-alloydb
+description: "AlloyDB integration for Haystack"
+slug: "/integrations-alloydb"
+---
+
+
+## haystack_integrations.components.retrievers.alloydb.embedding_retriever
+
+### AlloyDBEmbeddingRetriever
+
+Retrieves documents from the `AlloyDBDocumentStore` by embedding similarity.
+
+Must be connected to the `AlloyDBDocumentStore`.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: AlloyDBDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    vector_function: (
+        Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+    ) = None,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create the `AlloyDBEmbeddingRetriever` component.
+
+**Parameters:**
+
+- **document_store** (<code>AlloyDBDocumentStore</code>) – An instance of `AlloyDBDocumentStore` to use as the document store.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved documents.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – The similarity function to use when searching for similar embeddings.
+  Overrides the `vector_function` set in the `AlloyDBDocumentStore`.
+  `"cosine_similarity"` and `"inner_product"` are similarity functions and
+  higher scores indicate greater similarity between the documents.
+  `"l2_distance"` returns the straight-line distance between vectors,
+  and the most similar documents are the ones with the smallest score.
+  **Important**: when using the `"hnsw"` search strategy, make sure to use the same
+  vector function as the one used when the HNSW index was created.
+  If not specified, the `vector_function` of the `AlloyDBDocumentStore` is used.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied at query time.
+  `FilterPolicy.REPLACE` (default) replaces the init filters with the run-time filters.
+  `FilterPolicy.MERGE` merges the init filters with the run-time filters.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `AlloyDBDocumentStore`.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+    vector_function: (
+        Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+    ) = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `AlloyDBDocumentStore` by embedding similarity.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – A vector representation of the query.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved documents.
+  The `filter_policy` set at initialization determines how these are combined with the init filters.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return. Overrides the `top_k` set at initialization.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – The similarity function to use when searching for similar embeddings.
+  Overrides the `vector_function` set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary containing the `documents` retrieved from the document store.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AlloyDBEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AlloyDBEmbeddingRetriever</code> – Deserialized component.
+
+## haystack_integrations.components.retrievers.alloydb.keyword_retriever
+
+### AlloyDBKeywordRetriever
+
+Retrieves documents from the `AlloyDBDocumentStore` by keyword search.
+
+Uses PostgreSQL full-text search (`to_tsvector` / `plainto_tsquery`) to find documents.
+Must be connected to the `AlloyDBDocumentStore`.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: AlloyDBDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Create the `AlloyDBKeywordRetriever` component.
+
+**Parameters:**
+
+- **document_store** (<code>AlloyDBDocumentStore</code>) – An instance of `AlloyDBDocumentStore` to use as the document store.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved documents.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied at query time.
+  `FilterPolicy.REPLACE` (default) replaces the init filters with the run-time filters.
+  `FilterPolicy.MERGE` merges the init filters with the run-time filters.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `AlloyDBDocumentStore`.
+
+#### run
+
+```python
+run(
+    query: str, filters: dict[str, Any] | None = None, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents from the `AlloyDBDocumentStore` by keyword search.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – A keyword query to search for.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved documents.
+  The `filter_policy` set at initialization determines how these are combined with the init filters.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return. Overrides the `top_k` set at initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary containing the `documents` retrieved from the document store.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AlloyDBKeywordRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AlloyDBKeywordRetriever</code> – Deserialized component.
+
+## haystack_integrations.document_stores.alloydb.document_store
+
+### AlloyDBDocumentStore
+
+Bases: <code>DocumentStore</code>
+
+A Document Store backed by [Google Cloud AlloyDB](https://cloud.google.com/alloydb).
+
+Uses the [pgvector extension](https://cloud.google.com/alloydb/docs/ai/work-with-embeddings) for vector search.
+
+AlloyDB is a fully managed, PostgreSQL-compatible database service on Google Cloud.
+Connection is handled securely via the
+[AlloyDB Python Connector](https://github.com/GoogleCloudPlatform/alloydb-python-connector),
+which provides TLS encryption and IAM-based authorization without requiring manual SSL certificate
+management, firewall rules, or IP allowlisting.
+
+**Filter limitations**: the `NOT` logical operator is not supported. Use `!=` or `not in`
+comparison operators to express negation.
+
+Usage example:
+
+```python
+import os
+from haystack_integrations.document_stores.alloydb import AlloyDBDocumentStore
+
+# Set required environment variables:
+# ALLOYDB_INSTANCE_URI = "projects/MY_PROJECT/locations/MY_REGION/clusters/MY_CLUSTER/instances/MY_INSTANCE"
+# ALLOYDB_USER = "my-db-user"
+# ALLOYDB_PASSWORD = "my-db-password"
+
+document_store = AlloyDBDocumentStore(
+    db="my-database",
+    embedding_dimension=768,
+    recreate_table=True,
+)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    instance_uri: Secret = Secret.from_env_var("ALLOYDB_INSTANCE_URI"),
+    user: Secret = Secret.from_env_var("ALLOYDB_USER"),
+    password: Secret = Secret.from_env_var("ALLOYDB_PASSWORD", strict=False),
+    db: str = "postgres",
+    enable_iam_auth: bool = False,
+    ip_type: Literal["PRIVATE", "PUBLIC", "PSC"] = "PRIVATE",
+    create_extension: bool = True,
+    schema_name: str = "public",
+    table_name: str = "haystack_documents",
+    language: str = "english",
+    embedding_dimension: int = 768,
+    vector_function: Literal[
+        "cosine_similarity", "inner_product", "l2_distance"
+    ] = "cosine_similarity",
+    recreate_table: bool = False,
+    search_strategy: Literal[
+        "exact_nearest_neighbor", "hnsw"
+    ] = "exact_nearest_neighbor",
+    hnsw_recreate_index_if_exists: bool = False,
+    hnsw_index_creation_kwargs: dict[str, int] | None = None,
+    hnsw_index_name: str = "haystack_hnsw_index",
+    hnsw_ef_search: int | None = None,
+    keyword_index_name: str = "haystack_keyword_index"
+) -> None
+```
+
+Creates a new AlloyDBDocumentStore instance.
+
+Connection to AlloyDB is established lazily on first use via the AlloyDB Python Connector.
+A specific table to store Haystack documents will be created if it doesn't exist yet.
+
+**Parameters:**
+
+- **instance_uri** (<code>Secret</code>) – The AlloyDB instance URI in the format
+  `"projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE"`.
+  Read from the `ALLOYDB_INSTANCE_URI` environment variable by default.
+- **user** (<code>Secret</code>) – The database user. Read from the `ALLOYDB_USER` environment variable by default.
+  When using IAM database authentication, use the service account email (omitting
+  `.gserviceaccount.com`) or the full IAM user email.
+- **password** (<code>Secret</code>) – The database password. Read from the `ALLOYDB_PASSWORD` environment variable by default.
+  Not required when `enable_iam_auth=True`.
+- **db** (<code>str</code>) – The name of the database to connect to. Defaults to `"postgres"`.
+- **enable_iam_auth** (<code>bool</code>) – Whether to use IAM database authentication instead of a password.
+  When `True`, `password` is ignored. The IAM principal must be granted the
+  AlloyDB Client role and have an IAM database user created.
+  See the [AlloyDB documentation](https://cloud.google.com/alloydb/docs/manage-iam-authn) for details.
+- **ip_type** (<code>Literal['PRIVATE', 'PUBLIC', 'PSC']</code>) – The IP address type to use for the connection.
+  `"PRIVATE"` (default) connects over a private VPC IP.
+  `"PUBLIC"` connects over a public IP.
+  `"PSC"` connects via Private Service Connect.
+- **create_extension** (<code>bool</code>) – Whether to create the pgvector extension if it doesn't exist.
+  Set this to `True` (default) to automatically create the extension if it is missing.
+  Creating the extension may require superuser privileges.
+  If set to `False`, ensure the extension is already installed; otherwise, an error will be raised.
+- **schema_name** (<code>str</code>) – The name of the schema the table is created in. The schema must already exist.
+- **table_name** (<code>str</code>) – The name of the table to use to store Haystack documents.
+- **language** (<code>str</code>) – The language to be used to parse query and document content in keyword retrieval.
+  To see the list of available languages, you can run the following SQL query in your PostgreSQL database:
+  `SELECT cfgname FROM pg_ts_config;`.
+- **embedding_dimension** (<code>int</code>) – The dimension of the embedding.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance']</code>) – The similarity function to use when searching for similar embeddings.
+  `"cosine_similarity"` and `"inner_product"` are similarity functions and
+  higher scores indicate greater similarity between the documents.
+  `"l2_distance"` returns the straight-line distance between vectors,
+  and the most similar documents are the ones with the smallest score.
+  **Important**: when using the `"hnsw"` search strategy, an index will be created that depends on the
+  `vector_function` passed here. Make sure subsequent queries will keep using the same
+  vector similarity function in order to take advantage of the index.
+- **recreate_table** (<code>bool</code>) – Whether to recreate the table if it already exists.
+- **search_strategy** (<code>Literal['exact_nearest_neighbor', 'hnsw']</code>) – The search strategy to use when searching for similar embeddings.
+  `"exact_nearest_neighbor"` provides perfect recall but can be slow for large numbers of documents.
+  `"hnsw"` is an approximate nearest neighbor search strategy,
+  which trades off some accuracy for speed; it is recommended for large numbers of documents.
+  **Important**: when using the `"hnsw"` search strategy, an index will be created that depends on the
+  `vector_function` passed here. Make sure subsequent queries will keep using the same
+  vector similarity function in order to take advantage of the index.
+- **hnsw_recreate_index_if_exists** (<code>bool</code>) – Whether to recreate the HNSW index if it already exists.
+  Only used if search_strategy is set to `"hnsw"`.
+- **hnsw_index_creation_kwargs** (<code>dict\[str, int\] | None</code>) – Additional keyword arguments to pass to the HNSW index creation.
+  Only used if search_strategy is set to `"hnsw"`. Valid arguments are `m` and `ef_construction`.
+  See the [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw) for details.
+- **hnsw_index_name** (<code>str</code>) – Index name for the HNSW index.
+- **hnsw_ef_search** (<code>int | None</code>) – The `ef_search` parameter to use at query time. Only used if search_strategy is set to
+  `"hnsw"`. See the [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw).
+- **keyword_index_name** (<code>str</code>) – Index name for the keyword GIN index.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AlloyDBDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AlloyDBDocumentStore</code> – Deserialized component.
+
+#### close
+
+```python
+close() -> None
+```
+
+Closes the database connection and the AlloyDB connector.
+
+Call this when you are done using the document store to release resources.
+For long-lived applications the connector runs a background refresh thread;
+calling `close()` ensures that thread is stopped cleanly.
+
+#### delete_table
+
+```python
+delete_table() -> None
+```
+
+Deletes the table used to store Haystack documents.
+
+The name of the schema (`schema_name`) and the name of the table (`table_name`)
+are defined when initializing the `AlloyDBDocumentStore`.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns how many documents are in the document store.
+
+**Returns:**
+
+- <code>int</code> – The number of documents in the document store.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns the documents that match the filters provided.
+
+For a detailed specification of the filters,
+refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Filter operator support**: comparison operators (`==`, `!=`, `>`, `>=`, `<`, `<=`, `in`,
+`not in`, `like`, `not like`) and logical operators `AND` and `OR` are fully supported.
+The `NOT` logical operator is **not** supported — use `!=` or `not in` comparison
+operators instead.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – The filters to apply to the document list.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – A list of Documents that match the given filters.
+
+**Raises:**
+
+- <code>TypeError</code> – If `filters` is not a dictionary.
+- <code>ValueError</code> – If `filters` syntax is invalid.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.FAIL
+) -> int
+```
+
+Writes documents to the document store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of Documents to write to the document store.
+- **policy** (<code>DuplicatePolicy</code>) – The duplicate policy to use when writing documents.
+
+**Returns:**
+
+- <code>int</code> – The number of documents written to the document store.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` contains objects that are not of type `Document`.
+- <code>DuplicateDocumentError</code> – If a document with the same id already exists in the document store
+  and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+- <code>DocumentStoreError</code> – If the write operation fails for any other reason.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents that match the provided `document_ids` from the document store.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – the document ids to delete
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Deletes all documents in the document store.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Deletes all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for deletion.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Updates the metadata of all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents for updating.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **meta** (<code>dict\[str, Any\]</code>) – The metadata fields to update.
+
+**Returns:**
+
+- <code>int</code> – The number of documents updated.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Returns the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to count documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>int</code> – The number of documents that match the filters.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Returns the count of unique values for each specified metadata field.
+
+Considers only documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – The filters to apply to select documents.
+  For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names to count unique values for.
+  Field names can include or omit the "meta." prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – A dictionary mapping field names to their unique value counts.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Returns information about the metadata fields in the document store.
+
+Since metadata is stored in a JSONB field, this method analyzes actual data
+to infer field types.
+
+Example return:
+
+```python
+{
+    'category': {'type': 'text'},
+    'priority': {'type': 'integer'},
+}
+```
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – A dictionary mapping field names to their type information.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(field: str) -> dict[str, Any]
+```
+
+Returns the minimum and maximum values for a metadata field.
+
+For numeric fields (integer, real), returns numeric min/max.
+For text and other non-numeric fields, returns lexicographic min/max
+using the `"C"` collation.
+
+**Parameters:**
+
+- **field** (<code>str</code>) – The metadata field name (with or without the "meta." prefix).
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with `min` and `max` keys. Returns
+  `{"min": None, "max": None}` when the field has no values or the
+  store is empty.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    field: str, filters: dict[str, Any] | None = None
+) -> list[Any]
+```
+
+Returns a list of unique values for a metadata field.
+
+**Parameters:**
+
+- **field** (<code>str</code>) – The metadata field name (with or without the "meta." prefix).
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional filters to restrict the documents considered.
+
+**Returns:**
+
+- <code>list\[Any\]</code> – A list of unique values for the given field.

docs-website/reference_versioned_docs/version-2.22/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.22/integrations-api/amazon_textract.md

@@ -0,0 +1,151 @@
+---
+title: "Amazon Textract"
+id: integrations-amazon_textract
+description: "Amazon Textract integration for Haystack"
+slug: "/integrations-amazon_textract"
+---
+
+
+## haystack_integrations.components.converters.amazon_textract.converter
+
+### AmazonTextractConverter
+
+Converts documents to Haystack Documents using AWS Textract.
+
+This component uses AWS Textract to extract text and optionally structured data
+(tables, forms) from images and single-page PDFs.
+
+When `feature_types` is not set, the component uses `DetectDocumentText` for
+plain text OCR. When `feature_types` is set (e.g. `["TABLES", "FORMS"]`), it
+uses `AnalyzeDocument` for richer structural analysis.
+
+Natural-language queries are also supported via the `queries` parameter on
+`run()`. When queries are provided, the `QUERIES` feature type is added
+automatically and Textract returns answers extracted from the document.
+
+Supported input formats: JPEG, PNG, TIFF, BMP, and single-page PDF (up to 10 MB).
+
+AWS credentials are resolved via `Secret` parameters or the default boto3
+credential chain (environment variables, AWS config files, IAM roles).
+
+### Usage example
+
+```python
+from haystack_integrations.components.converters.amazon_textract import AmazonTextractConverter
+
+converter = AmazonTextractConverter()
+results = converter.run(sources=["document.png"])
+documents = results["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    aws_access_key_id: Secret | None = Secret.from_env_var(
+        "AWS_ACCESS_KEY_ID", strict=False
+    ),
+    aws_secret_access_key: Secret | None = Secret.from_env_var(
+        "AWS_SECRET_ACCESS_KEY", strict=False
+    ),
+    aws_session_token: Secret | None = Secret.from_env_var(
+        "AWS_SESSION_TOKEN", strict=False
+    ),
+    aws_region_name: Secret | None = Secret.from_env_var(
+        "AWS_DEFAULT_REGION", strict=False
+    ),
+    aws_profile_name: Secret | None = Secret.from_env_var(
+        "AWS_PROFILE", strict=False
+    ),
+    feature_types: list[str] | None = None,
+    store_full_path: bool = False,
+    boto3_config: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an AmazonTextractConverter component.
+
+**Parameters:**
+
+- **aws_access_key_id** (<code>Secret | None</code>) – AWS access key ID.
+- **aws_secret_access_key** (<code>Secret | None</code>) – AWS secret access key.
+- **aws_session_token** (<code>Secret | None</code>) – AWS session token.
+- **aws_region_name** (<code>Secret | None</code>) – AWS region name. Must be a region that supports Textract.
+- **aws_profile_name** (<code>Secret | None</code>) – AWS profile name from the credentials file.
+- **feature_types** (<code>list\[str\] | None</code>) – List of feature types to detect when using AnalyzeDocument.
+  Valid values: "TABLES", "FORMS", "SIGNATURES", "LAYOUT".
+  If None, uses DetectDocumentText for basic text extraction.
+  The "QUERIES" feature type is managed automatically when the
+  `queries` parameter is passed to `run()`.
+- **store_full_path** (<code>bool</code>) – If True, stores the complete file path in Document metadata.
+  If False, stores only the filename (default).
+- **boto3_config** (<code>dict\[str, Any\] | None</code>) – Dictionary of configuration options for the underlying boto3 client.
+  Can be used to tune retry behavior, timeouts, and connection management.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the AWS Textract client.
+
+#### run
+
+```python
+run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+    queries: list[str] | None = None,
+) -> dict[str, Any]
+```
+
+Convert documents to Haystack Documents using AWS Textract.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths or ByteStream objects to convert.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the Documents.
+  This value can be either a list of dictionaries or a single dictionary.
+  If it's a single dictionary, its content is added to the metadata of all produced Documents.
+  If it's a list, the length of the list must match the number of sources.
+- **queries** (<code>list\[str\] | None</code>) – Optional list of natural-language questions to ask about each document.
+  When provided, the Textract `QUERIES` feature type is enabled
+  automatically and each question is sent as a query. Answers are
+  included in the raw Textract response. Example:
+  `["What is the patient name?", "What is the total due?"]`
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: List of created Documents with extracted text as content.
+- `raw_textract_response`: List of raw Textract API responses.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AmazonTextractConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AmazonTextractConverter</code> – The deserialized component.

docs-website/reference_versioned_docs/version-2.22/integrations-api/anthropic.md

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

docs-website/reference_versioned_docs/version-2.22/integrations-api/arangodb.md

@@ -0,0 +1,244 @@
+---
+title: "Arangodb"
+id: integrations-arangodb
+description: "Arangodb integration for Haystack"
+slug: "/integrations-arangodb"
+---
+
+
+## haystack_integrations.components.retrievers.arangodb.embedding_retriever
+
+### ArangoEmbeddingRetriever
+
+Retrieves documents from an `ArangoDocumentStore` using vector similarity on embeddings.
+
+The similarity function is configured on the `ArangoDocumentStore` (cosine, dot product, or L2).
+
+Example usage:
+
+```python
+from haystack_integrations.document_stores.arangodb import ArangoDocumentStore
+from haystack_integrations.components.retrievers.arangodb import ArangoEmbeddingRetriever
+
+store = ArangoDocumentStore(host="http://localhost:8529", database="haystack",
+                            username="root", collection_name="docs", embedding_dimension=768)
+retriever = ArangoEmbeddingRetriever(document_store=store, top_k=5)
+result = retriever.run(query_embedding=[0.1, 0.2, ...])
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: ArangoDocumentStore,
+    top_k: int = 10,
+    filters: dict[str, Any] | None = None
+) -> None
+```
+
+Creates a new ArangoEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>ArangoDocumentStore</code>) – The `ArangoDocumentStore` to retrieve documents from.
+- **top_k** (<code>int</code>) – Maximum number of documents to return.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional Haystack metadata filters applied at retrieval time.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    top_k: int | None = None,
+    filters: dict[str, Any] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieves documents most similar to `query_embedding`.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – The query vector.
+- **top_k** (<code>int | None</code>) – Overrides the instance-level `top_k` for this call.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Overrides the instance-level `filters` for this call.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with `documents` — a list of `Document` objects sorted by score.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ArangoEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ArangoEmbeddingRetriever</code> – Deserialized component.
+
+## haystack_integrations.document_stores.arangodb.document_store
+
+### ArangoDocumentStore
+
+A Haystack DocumentStore backed by [ArangoDB](https://www.arangodb.com/).
+
+Documents are stored in an ArangoDB collection and support vector similarity search
+via AQL vector functions (requires ArangoDB 3.12+).
+
+Example usage:
+
+```python
+from haystack_integrations.document_stores.arangodb import ArangoDocumentStore
+from haystack.utils import Secret
+
+store = ArangoDocumentStore(
+    host="http://localhost:8529",
+    database="haystack",
+    username=Secret.from_env_var("ARANGO_USERNAME", strict=False),
+    password=Secret.from_env_var("ARANGO_PASSWORD"),
+    collection_name="documents",
+    embedding_dimension=768,
+)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    host: str = "http://localhost:8529",
+    database: str = "haystack",
+    username: Secret = Secret.from_env_var("ARANGO_USERNAME", strict=False),
+    password: Secret = Secret.from_env_var("ARANGO_PASSWORD"),
+    collection_name: str = "haystack_documents",
+    embedding_dimension: int = 768,
+    recreate_collection: bool = False,
+    similarity_function: Literal["cosine", "dot_product", "l2"] = "cosine"
+) -> None
+```
+
+Creates a new ArangoDocumentStore instance.
+
+**Parameters:**
+
+- **host** (<code>str</code>) – ArangoDB server URL, e.g. `http://localhost:8529`.
+- **database** (<code>str</code>) – Name of the ArangoDB database to use. Created if it does not exist.
+- **username** (<code>Secret</code>) – ArangoDB username as a `Secret`. Defaults to `ARANGO_USERNAME` env var,
+  falling back to `root` if the variable is not set.
+- **password** (<code>Secret</code>) – ArangoDB password as a `Secret`. Defaults to `ARANGO_PASSWORD` env var.
+- **collection_name** (<code>str</code>) – Name of the collection to store documents in.
+- **embedding_dimension** (<code>int</code>) – Dimensionality of document embeddings.
+- **recreate_collection** (<code>bool</code>) – If `True`, drop and recreate the collection on startup.
+- **similarity_function** (<code>Literal['cosine', 'dot_product', 'l2']</code>) – Vector similarity function to use for embedding retrieval.
+  One of `"cosine"` (default), `"dot_product"`, or `"l2"`.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Returns the number of documents in the store.
+
+**Returns:**
+
+- <code>int</code> – Document count.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Returns documents matching the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Haystack metadata filters. If `None`, all documents are returned.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – List of matching `Document` objects.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Writes documents to the store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to write.
+- **policy** (<code>DuplicatePolicy</code>) – How to handle duplicates — `OVERWRITE`, `SKIP`, or `FAIL` (default).
+
+**Returns:**
+
+- <code>int</code> – Number of documents written.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` contains non-`Document` objects.
+- <code>DuplicateDocumentError</code> – If a duplicate is found and policy is `FAIL`.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Deletes documents by their IDs.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – List of document IDs to delete.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ArangoDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ArangoDocumentStore</code> – Deserialized component.

docs-website/reference_versioned_docs/version-2.22/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.22/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.22/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.22/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.22/integrations-api/azure_form_recognizer.md

@@ -0,0 +1,134 @@
+---
+title: "Azure Form Recognizer"
+id: integrations-azure_form_recognizer
+description: "Azure Form Recognizer integration for Haystack"
+slug: "/integrations-azure_form_recognizer"
+---
+
+
+## haystack_integrations.components.converters.azure_form_recognizer.converter
+
+### AzureOCRDocumentConverter
+
+Converts files to documents using Azure's Document Intelligence service.
+
+Supported file formats are: PDF, JPEG, PNG, BMP, TIFF, DOCX, XLSX, PPTX, and HTML.
+
+To use this component, you need an active Azure account
+and a Document Intelligence or Cognitive Services resource. For help with setting up your resource, see
+[Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/quickstarts/get-started-sdks-rest-api).
+
+### Usage example
+
+```python
+import os
+from datetime import datetime
+from haystack_integrations.components.converters.azure_form_recognizer import AzureOCRDocumentConverter
+from haystack.utils import Secret
+
+converter = AzureOCRDocumentConverter(
+    endpoint=os.environ["CORE_AZURE_CS_ENDPOINT"],
+    api_key=Secret.from_env_var("CORE_AZURE_CS_API_KEY"),
+)
+results = converter.run(
+    sources=["test/test_files/pdf/react_paper.pdf"],
+    meta={"date_added": datetime.now().isoformat()},
+)
+documents = results["documents"]
+print(documents[0].content)
+# 'This is a text from the PDF file.'
+```
+
+#### __init__
+
+```python
+__init__(
+    endpoint: str,
+    api_key: Secret = Secret.from_env_var("AZURE_AI_API_KEY"),
+    model_id: str = "prebuilt-read",
+    preceding_context_len: int = 3,
+    following_context_len: int = 3,
+    merge_multiple_column_headers: bool = True,
+    page_layout: Literal["natural", "single_column"] = "natural",
+    threshold_y: float | None = 0.05,
+    store_full_path: bool = False,
+) -> None
+```
+
+Creates an AzureOCRDocumentConverter component.
+
+**Parameters:**
+
+- **endpoint** (<code>str</code>) – The endpoint of your Azure resource.
+- **api_key** (<code>Secret</code>) – The API key of your Azure resource.
+- **model_id** (<code>str</code>) – The ID of the model you want to use. For a list of available models, see [Azure documentation]
+  (https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/choose-model-feature).
+- **preceding_context_len** (<code>int</code>) – Number of lines before a table to include as preceding context
+  (this will be added to the metadata).
+- **following_context_len** (<code>int</code>) – Number of lines after a table to include as subsequent context (
+  this will be added to the metadata).
+- **merge_multiple_column_headers** (<code>bool</code>) – If `True`, merges multiple column header rows into a single row.
+- **page_layout** (<code>Literal['natural', 'single_column']</code>) – The type reading order to follow. Possible options:
+- `natural`: Uses the natural reading order determined by Azure.
+- `single_column`: Groups all lines with the same height on the page based on a threshold
+  determined by `threshold_y`.
+- **threshold_y** (<code>float | None</code>) – Only relevant if `single_column` is set to `page_layout`.
+  The threshold, in inches, to determine if two recognized PDF elements are grouped into a
+  single line. This is crucial for section headers or numbers which may be spatially separated
+  from the remaining text on the horizontal axis.
+- **store_full_path** (<code>bool</code>) – If True, the full path of the file is stored in the metadata of the document.
+  If False, only the file name is stored.
+
+#### run
+
+```python
+run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, Any]
+```
+
+Convert a list of files to Documents using Azure's Document Intelligence service.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – List of file paths or ByteStream objects.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the Documents.
+  This value can be either a list of dictionaries or a single dictionary.
+  If it's a single dictionary, its content is added to the metadata of all produced Documents.
+  If it's a list, the length of the list must match the number of sources, because the two lists will be
+  zipped. If `sources` contains ByteStream objects, their `meta` will be added to the output Documents.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `documents`: List of created Documents
+- `raw_azure_response`: List of raw Azure responses used to create the Documents
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AzureOCRDocumentConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>AzureOCRDocumentConverter</code> – The deserialized component.

docs-website/reference_versioned_docs/version-2.22/integrations-api/brave.md

@@ -0,0 +1,96 @@
+---
+title: "Brave Search"
+id: integrations-brave
+description: "Brave Search integration for Haystack"
+slug: "/integrations-brave"
+---
+
+
+## haystack_integrations.components.websearch.brave.brave_websearch
+
+### BraveWebSearch
+
+A component that uses the Brave Search API to search the web and return results as Haystack Documents.
+
+You need a Brave Search API key from [brave.com/search/api](https://brave.com/search/api/).
+
+### Usage example
+
+```python
+from haystack_integrations.components.websearch.brave import BraveWebSearch
+from haystack.utils import Secret
+
+websearch = BraveWebSearch(
+    api_key=Secret.from_env_var("BRAVE_API_KEY"),
+    top_k=5,
+)
+result = websearch.run(query="What is Haystack by deepset?")
+documents = result["documents"]
+links = result["links"]
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("BRAVE_API_KEY"),
+    top_k: int | None = 10,
+    country: str | None = None,
+    search_lang: str | None = None,
+    extra_params: dict[str, Any] | None = None,
+    timeout: int = 10,
+    max_retries: int = 3,
+) -> None
+```
+
+Initialize the BraveWebSearch component.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – Brave Search API key. Defaults to the `BRAVE_API_KEY` environment variable.
+- **top_k** (<code>int | None</code>) – Maximum number of results to return. Maps to the `count` parameter in the Brave API.
+- **country** (<code>str | None</code>) – 2-letter country code to bias search results (e.g. `"US"`, `"DE"`).
+- **search_lang** (<code>str | None</code>) – Language code for search results (e.g. `"en"`, `"de"`).
+- **extra_params** (<code>dict\[str, Any\] | None</code>) – Additional query parameters passed directly to the Brave Search API.
+- **timeout** (<code>int</code>) – Timeout in seconds for the HTTP request. Defaults to 10.
+- **max_retries** (<code>int</code>) – Maximum number of retry attempts on transient failures. Defaults to 3.
+
+#### run
+
+```python
+run(query: str, top_k: int | None = None) -> dict[str, Any]
+```
+
+Search the web using Brave Search and return results as Documents.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Search query string.
+- **top_k** (<code>int | None</code>) – Optional per-run override of the maximum number of results.
+  If not provided, the init-time `top_k` is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with:
+- `documents`: List of Documents containing search result content.
+- `links`: List of URLs from the search results.
+
+#### run_async
+
+```python
+run_async(query: str, top_k: int | None = None) -> dict[str, Any]
+```
+
+Asynchronously search the web using Brave Search and return results as Documents.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Search query string.
+- **top_k** (<code>int | None</code>) – Optional per-run override of the maximum number of results.
+  If not provided, the init-time `top_k` is used.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with:
+- `documents`: List of Documents containing search result content.
+- `links`: List of URLs from the search results.

docs-website/reference_versioned_docs/version-2.22/integrations-api/chonkie.md

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

docs-website/reference_versioned_docs/version-2.22/integrations-api/chroma.md

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

docs-website/reference_versioned_docs/version-2.22/integrations-api/cognee.md

@@ -0,0 +1,255 @@
+---
+title: "Cognee"
+id: integrations-cognee
+description: "Cognee integration for Haystack"
+slug: "/integrations-cognee"
+---
+
+
+## haystack_integrations.components.retrievers.cognee.memory_retriever
+
+### CogneeRetriever
+
+Retrieves memories from a `CogneeMemoryStore` as `ChatMessage` instances.
+
+Configuration (`search_type`, `top_k`, `dataset_name`, `session_id`) lives on
+the store; this retriever is a thin pipeline adapter over `search_memories`.
+
+#### __init__
+
+```python
+__init__(*, memory_store: CogneeMemoryStore, top_k: int | None = None) -> None
+```
+
+Initialize the retriever.
+
+**Parameters:**
+
+- **memory_store** (<code>CogneeMemoryStore</code>) – Backing `CogneeMemoryStore` to query.
+- **top_k** (<code>int | None</code>) – Default max results; falls back to the store's `top_k` when `None`.
+
+#### run
+
+```python
+run(
+    query: str, top_k: int | None = None, user_id: str | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Search the attached store and return matching memories as ChatMessages.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – Natural-language query.
+- **top_k** (<code>int | None</code>) – Per-call override; falls back to init `top_k`, then the store's default.
+- **user_id** (<code>str | None</code>) – Cognee user UUID; scopes the search to that user.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CogneeRetriever
+```
+
+Deserialize a component from a dictionary.
+
+## haystack_integrations.components.writers.cognee.memory_writer
+
+### CogneeWriter
+
+Persists `ChatMessage`s into a `CogneeMemoryStore`.
+
+Use without `session_id` to write to the permanent graph; pass `session_id` to
+target cognee's session cache for that writer's writes. The writer's
+`session_id` overrides the store's own `session_id` per call, so one store can
+back multiple writers writing to different tiers.
+
+#### __init__
+
+```python
+__init__(
+    *, memory_store: CogneeMemoryStore, session_id: str | None = None
+) -> None
+```
+
+Initialize the writer.
+
+**Parameters:**
+
+- **memory_store** (<code>CogneeMemoryStore</code>) – Backing `CogneeMemoryStore` to write into.
+- **session_id** (<code>str | None</code>) – Overrides the store's `session_id` for this writer's writes.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage], user_id: str | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Store `messages` in Cognee memory and pass them through unchanged.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – Messages to persist.
+- **user_id** (<code>str | None</code>) – Cognee user UUID; scopes the write to that user.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CogneeWriter
+```
+
+Deserialize a component from a dictionary.
+
+## haystack_integrations.memory_stores.cognee.memory_store
+
+### CogneeMemoryStore
+
+Memory backend backed by Cognee, implementing the haystack-experimental `MemoryStore` protocol.
+
+Wraps cognee's V2 memory API: `add_memories` -> `cognee.remember`,
+`search_memories` -> `cognee.recall`, `improve` -> `cognee.improve`,
+`delete_all_memories` -> `cognee.forget`.
+
+`session_id` selects the tier — set it to use cognee's session cache (cheap,
+no LLM extraction, session-aware recall); leave `None` for the permanent
+graph.
+
+`self_improvement` is forwarded to `cognee.remember` and defaults to `True`
+(same as cognee). On the permanent tier it awaits `improve` inline; on the
+session tier it schedules `improve` as a fire-and-forget background task.
+Set to `False` when you want `improve()` to be the only improve trigger
+— otherwise an explicit `improve()` runs improve twice and produces
+near-duplicate graph nodes.
+
+`timeout` (seconds) caps how long any single cognee call may run before
+raising `concurrent.futures.TimeoutError`. The default of 300s covers
+single-message agent-memory writes comfortably; bulk ingestion of long
+documents may need a larger value.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    search_type: CogneeSearchType = "GRAPH_COMPLETION",
+    top_k: int = 5,
+    dataset_name: str = "haystack_memory",
+    session_id: str | None = None,
+    self_improvement: bool = True,
+    timeout: float = 300
+) -> None
+```
+
+Initialize the store.
+
+**Parameters:**
+
+- **search_type** (<code>CogneeSearchType</code>) – Cognee search strategy used by `search_memories`.
+- **top_k** (<code>int</code>) – Default max results for `search_memories`.
+- **dataset_name** (<code>str</code>) – Cognee dataset backing this store.
+- **session_id** (<code>str | None</code>) – When set, use the session-cache tier; otherwise the permanent graph.
+- **self_improvement** (<code>bool</code>) – Forwarded to `cognee.remember` (default `True`, matches cognee).
+  Set to `False` when `improve()` should be the only improve trigger.
+- **timeout** (<code>float</code>) – Per-call timeout in seconds for any cognee operation.
+  Raise this for bulk ingestion workloads that legitimately need >300s.
+
+#### add_memories
+
+```python
+add_memories(
+    *,
+    messages: list[ChatMessage],
+    user_id: str | None = None,
+    session_id: str | None = None
+) -> None
+```
+
+Persist messages via `cognee.remember`.
+
+Permanent tier batches all texts into one call; session tier writes one
+entry per message (matches cognee's session example). Empty messages
+are skipped.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – Messages to store.
+- **user_id** (<code>str | None</code>) – Cognee user UUID; `None` uses cognee's default user.
+- **session_id** (<code>str | None</code>) – Per-call override of the store's `session_id`.
+
+#### search_memories
+
+```python
+search_memories(
+    *,
+    query: str | None = None,
+    top_k: int | None = None,
+    user_id: str | None = None
+) -> list[ChatMessage]
+```
+
+Search via `cognee.recall` and wrap each hit in a system `ChatMessage`.
+
+**Parameters:**
+
+- **query** (<code>str | None</code>) – Natural-language query. Empty/`None` returns `[]`.
+- **top_k** (<code>int | None</code>) – Per-call override of the store's default.
+- **user_id** (<code>str | None</code>) – Cognee user UUID; `None` uses cognee's default user.
+
+#### improve
+
+```python
+improve(*, session_id: str | None = None, user_id: str | None = None) -> None
+```
+
+Promote session-cache content into the permanent graph via `cognee.improve`.
+
+Without any session_id this is a plain graph-enrichment pass.
+
+**Parameters:**
+
+- **session_id** (<code>str | None</code>) – Session to promote; defaults to the store's `session_id`.
+- **user_id** (<code>str | None</code>) – Cognee user UUID; `None` uses cognee's default user.
+
+#### delete_all_memories
+
+```python
+delete_all_memories(*, user_id: str | None = None) -> None
+```
+
+Delete this dataset via `cognee.forget(dataset=...)`.
+
+Session cache survives (sessions aren't dataset-scoped) — use
+`cognee.forget(everything=True)` for a full wipe.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this store for pipeline persistence.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> CogneeMemoryStore
+```
+
+Deserialize a store from a dict produced by `to_dict`.

docs-website/reference_versioned_docs/version-2.22/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.22/integrations-api/datadog.md

@@ -0,0 +1,190 @@
+---
+title: "Datadog"
+id: integrations-datadog
+description: "Datadog integration for Haystack"
+slug: "/integrations-datadog"
+---
+
+
+## haystack_integrations.components.connectors.datadog.datadog_connector
+
+### DatadogConnector
+
+DatadogConnector connects Haystack to [Datadog](https://www.datadoghq.com/) in order to enable the tracing of
+
+operations and data flow within the components of a pipeline.
+
+To use the DatadogConnector, add it to your pipeline without connecting it to any other component. It will
+automatically trace all pipeline operations when tracing is enabled.
+
+**Environment Configuration:**
+
+- `HAYSTACK_CONTENT_TRACING_ENABLED`: Must be set to `"true"` to trace the content (inputs and outputs) of the
+  pipeline components.
+- Datadog is configured through the standard `ddtrace` mechanisms, e.g. the `DD_SERVICE`, `DD_ENV` and
+  `DD_VERSION` environment variables or by running your application with the `ddtrace-run` command. See the
+  [ddtrace documentation](https://ddtrace.readthedocs.io/en/stable/) for more details.
+
+Here is an example of how to use the DatadogConnector in a pipeline:
+
+```python
+import os
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.connectors.datadog import DatadogConnector
+
+pipe = Pipeline()
+pipe.add_component("tracer", DatadogConnector("Chat example"))
+pipe.add_component("prompt_builder", ChatPromptBuilder())
+pipe.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+
+pipe.connect("prompt_builder.prompt", "llm.messages")
+
+messages = [
+    ChatMessage.from_system("Always respond in German even if some input data is in other languages."),
+    ChatMessage.from_user("Tell me about {{location}}"),
+]
+
+response = pipe.run(
+    data={"prompt_builder": {"template_variables": {"location": "Berlin"}, "template": messages}}
+)
+print(response["llm"]["replies"][0])
+```
+
+#### __init__
+
+```python
+__init__(name: str = 'datadog') -> None
+```
+
+Initialize the DatadogConnector component.
+
+**Parameters:**
+
+- **name** (<code>str</code>) – The name used to identify this tracing component. It is returned by the `run` method and can be
+  used to mark traces produced by this connector.
+
+#### run
+
+```python
+run() -> dict[str, str]
+```
+
+Runs the DatadogConnector component.
+
+**Returns:**
+
+- <code>dict\[str, str\]</code> – A dictionary with the following keys:
+- `name`: The name of the tracing component.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DatadogConnector
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>DatadogConnector</code> – The deserialized component instance.
+
+## haystack_integrations.tracing.datadog.tracer
+
+### DatadogSpan
+
+Bases: <code>Span</code>
+
+#### __init__
+
+```python
+__init__(span: ddSpan) -> None
+```
+
+Creates an instance of DatadogSpan.
+
+#### set_tag
+
+```python
+set_tag(key: str, value: Any) -> None
+```
+
+Set a single tag on the span.
+
+**Parameters:**
+
+- **key** (<code>str</code>) – the name of the tag.
+- **value** (<code>Any</code>) – the value of the tag.
+
+#### raw_span
+
+```python
+raw_span() -> Any
+```
+
+Provides access to the underlying span object of the tracer.
+
+**Returns:**
+
+- <code>Any</code> – The underlying span object.
+
+#### get_correlation_data_for_logs
+
+```python
+get_correlation_data_for_logs() -> dict[str, Any]
+```
+
+Return a dictionary with correlation data for logs.
+
+### DatadogTracer
+
+Bases: <code>Tracer</code>
+
+#### __init__
+
+```python
+__init__(tracer: ddTracer) -> None
+```
+
+Creates an instance of DatadogTracer.
+
+#### trace
+
+```python
+trace(
+    operation_name: str,
+    tags: dict[str, Any] | None = None,
+    parent_span: Span | None = None,
+) -> Iterator[Span]
+```
+
+Activate and return a new span that inherits from the current active span.
+
+#### current_span
+
+```python
+current_span() -> Span | None
+```
+
+Return the current active span

docs-website/reference_versioned_docs/version-2.22/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.22/integrations-api/docling.md

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

docs-website/reference_versioned_docs/version-2.22/integrations-api/docling_serve.md

@@ -0,0 +1,180 @@
+---
+title: "Docling Serve"
+id: integrations-docling_serve
+description: "Docling Serve integration for Haystack"
+slug: "/integrations-docling_serve"
+---
+
+
+## haystack_integrations.components.converters.docling_serve.converter
+
+### ExportType
+
+Bases: <code>str</code>, <code>Enum</code>
+
+Enumeration of export formats supported by DoclingServe.
+
+- `MARKDOWN`: Converts documents to Markdown format.
+- `TEXT`: Extracts plain text.
+- `JSON`: Returns the full Docling document as a JSON string.
+
+### ConversionMode
+
+Bases: <code>str</code>, <code>Enum</code>
+
+Execution mode for DoclingServe conversions.
+
+- `SYNC`: Uses DoclingServe's synchronous conversion endpoints.
+- `ASYNC`: Uses DoclingServe's async job endpoints and polls for completion.
+
+### DoclingServeConversionError
+
+Bases: <code>Exception</code>
+
+Raised when DoclingServe reports an async task or conversion failure.
+
+### DoclingServeTimeoutError
+
+Bases: <code>DoclingServeConversionError</code>
+
+Raised when a DoclingServe async task exceeds job_timeout.
+
+### DoclingServeConverter
+
+Converts documents to Haystack Documents using a DoclingServe server.
+
+See [DoclingServe](https://github.com/docling-project/docling-serve).
+
+DoclingServe hosts Docling in a scalable HTTP server, supporting PDFs, Office documents, HTML, and many other
+formats. Unlike the local `DoclingConverter`, this component has no heavy ML dependencies — all processing
+happens on the remote server.
+
+Local files and ByteStreams are uploaded via the `/v1/convert/file` endpoint. URL strings are sent to
+`/v1/convert/source`.
+
+Supports both synchronous (`run`) and asynchronous (`run_async`) execution.
+
+### Usage example
+
+```python
+from haystack_integrations.components.converters.docling_serve import DoclingServeConverter
+
+converter = DoclingServeConverter(base_url="http://localhost:5001")
+result = converter.run(sources=["https://arxiv.org/pdf/2206.01062"])
+print(result["documents"][0].content[:200])
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    base_url: str = "http://localhost:5001",
+    export_type: ExportType = ExportType.MARKDOWN,
+    convert_options: dict[str, Any] | None = None,
+    timeout: float = 120.0,
+    api_key: Secret | None = Secret.from_env_var(
+        "DOCLING_SERVE_API_KEY", strict=False
+    ),
+    mode: ConversionMode | str = ConversionMode.SYNC,
+    poll_interval: float = 2.0,
+    job_timeout: float = 600.0
+) -> None
+```
+
+Initializes the DoclingServeConverter.
+
+**Parameters:**
+
+- **base_url** (<code>str</code>) – Base URL of the DoclingServe instance. Defaults to `"http://localhost:5001"`.
+- **export_type** (<code>ExportType</code>) – The output format for converted documents. One of `ExportType.MARKDOWN` (default),
+  `ExportType.TEXT`, or `ExportType.JSON`.
+- **convert_options** (<code>dict\[str, Any\] | None</code>) – Optional dictionary of conversion options passed directly to the DoclingServe API
+  (e.g. `{"do_ocr": True, "ocr_engine": "tesseract"}`).
+  See [DoclingServe options](https://github.com/docling-project/docling-serve/blob/main/docs/usage.md).
+  Note: `to_formats` is set automatically based on `export_type` and should not be included here.
+- **timeout** (<code>float</code>) – HTTP request timeout in seconds. Defaults to `120.0`.
+- **api_key** (<code>Secret | None</code>) – API key for authenticating with a secured DoclingServe instance. Reads from the
+  `DOCLING_SERVE_API_KEY` environment variable by default. Set to `None` to disable
+  authentication.
+- **mode** (<code>ConversionMode | str</code>) – Conversion mode. `sync` uses DoclingServe's synchronous endpoints. `async` submits
+  conversion jobs to DoclingServe's async endpoints and polls until completion.
+- **poll_interval** (<code>float</code>) – Controls both the server-side long-poll wait (?wait= parameter) and the maximum local sleep between polls.
+  A higher value reduces round-trips; a lower value increases polling frequency.
+- **job_timeout** (<code>float</code>) – Maximum time in seconds to wait for each async conversion job.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary representation of the component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> DoclingServeConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary representation of the component.
+
+**Returns:**
+
+- <code>DoclingServeConverter</code> – A new `DoclingServeConverter` instance.
+
+#### run
+
+```python
+run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Converts documents by sending them to DoclingServe and returns Haystack Documents.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – List of sources to convert. Each item can be a URL string, a local file path, or a
+  `ByteStream`. URL strings are sent to `/v1/convert/source`; all other sources are
+  uploaded to `/v1/convert/file`.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the output Documents. Can be a single dict applied to
+  all documents, or a list of dicts with one entry per source.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with key `"documents"` containing the converted Haystack Documents.
+
+#### run_async
+
+```python
+run_async(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously converts documents by sending them to DoclingServe.
+
+This is the async equivalent of `run()`, useful when DoclingServe requests should not
+block the event loop.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – List of sources to convert. Each item can be a URL string, a local file path, or a
+  `ByteStream`. URL strings are sent to `/v1/convert/source`; all other sources are
+  uploaded to `/v1/convert/file`.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the output Documents.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with key `"documents"` containing the converted Haystack Documents.

docs-website/reference_versioned_docs/version-2.22/integrations-api/e2b.md

@@ -0,0 +1,418 @@
+---
+title: "E2B"
+id: integrations-e2b
+description: "E2B integration for Haystack"
+slug: "/integrations-e2b"
+---
+
+
+## haystack_integrations.tools.e2b.bash_tool
+
+### RunBashCommandTool
+
+Bases: <code>Tool</code>
+
+A :class:`~haystack.tools.Tool` that executes bash commands inside an E2B sandbox.
+
+Pass the same :class:`E2BSandbox` instance to multiple tool classes so they
+all operate in the same live sandbox environment.
+
+### Usage example
+
+```python
+from haystack_integrations.tools.e2b import E2BSandbox, RunBashCommandTool, ReadFileTool
+
+sandbox = E2BSandbox()
+agent = Agent(
+    chat_generator=...,
+    tools=[
+        RunBashCommandTool(sandbox=sandbox),
+        ReadFileTool(sandbox=sandbox),
+    ],
+)
+```
+
+#### __init__
+
+```python
+__init__(sandbox: E2BSandbox) -> None
+```
+
+Create a RunBashCommandTool.
+
+**Parameters:**
+
+- **sandbox** (<code>E2BSandbox</code>) – The :class:`E2BSandbox` instance that will execute commands.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> RunBashCommandTool
+```
+
+Deserialize a RunBashCommandTool from a dictionary.
+
+## haystack_integrations.tools.e2b.e2b_sandbox
+
+### E2BSandbox
+
+Manages the lifecycle of an E2B cloud sandbox.
+
+Instantiate this class and pass it to one or more E2B tool classes
+(`RunBashCommandTool`, `ReadFileTool`, `WriteFileTool`,
+`ListDirectoryTool`) to share a single sandbox environment across all
+tools. All tools that receive the same `E2BSandbox` instance operate
+inside the same live sandbox process.
+
+### Usage example
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.agents import Agent
+
+from haystack_integrations.tools.e2b import (
+    E2BSandbox,
+    RunBashCommandTool,
+    ReadFileTool,
+    WriteFileTool,
+    ListDirectoryTool,
+)
+
+sandbox = E2BSandbox()
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(model="gpt-4o"),
+    tools=[
+        RunBashCommandTool(sandbox=sandbox),
+        ReadFileTool(sandbox=sandbox),
+        WriteFileTool(sandbox=sandbox),
+        ListDirectoryTool(sandbox=sandbox),
+    ],
+)
+```
+
+Lifecycle is handled automatically by the Agent's pipeline. If you use the
+tools standalone, call :meth:`warm_up` before the first tool invocation:
+
+```python
+sandbox.warm_up()
+# ... use tools ...
+sandbox.close()
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("E2B_API_KEY", strict=True),
+    sandbox_template: str = "base",
+    timeout: int = 120,
+    environment_vars: dict[str, str] | None = None,
+    instance_id: str | None = None,
+) -> None
+```
+
+Create an E2BSandbox instance.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – E2B API key.
+- **sandbox_template** (<code>str</code>) – E2B sandbox template name.
+- **timeout** (<code>int</code>) – Sandbox inactivity timeout in seconds.
+- **environment_vars** (<code>dict\[str, str\] | None</code>) – Optional environment variables to inject into the sandbox.
+- **instance_id** (<code>str | None</code>) – Stable identifier preserved across `to_dict`/`from_dict`. When
+  omitted, a fresh UUID is generated. Tools that share the same `E2BSandbox`
+  instance inherit this id, which is what lets them re-share the instance after
+  a serialization round-trip. Distinct from the cloud-side sandbox id assigned
+  by E2B at warm-up.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Establish the connection to the E2B sandbox.
+
+Idempotent -- calling it multiple times has no effect if the sandbox is
+already running.
+
+**Raises:**
+
+- <code>RuntimeError</code> – If the E2B sandbox cannot be created.
+
+#### close
+
+```python
+close() -> None
+```
+
+Shut down the E2B sandbox and release all associated resources.
+
+Call this when you are done to avoid leaving idle sandboxes running.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the sandbox configuration to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary containing the serialised configuration.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> E2BSandbox
+```
+
+Deserialize an :class:`E2BSandbox` from a dictionary.
+
+Multiple tools that shared a single :class:`E2BSandbox` before serialization
+will share the same restored instance: each tool's `from_dict` consults a
+process-wide cache keyed on `instance_id`. A cache hit is only honored when
+the full serialized config (api_key, template, timeout, environment_vars)
+matches the cached entry — a crafted YAML with a guessed id but a different
+config falls through to a fresh instance and never observes the cached one.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary created by :meth:`to_dict`.
+
+**Returns:**
+
+- <code>E2BSandbox</code> – An :class:`E2BSandbox` instance ready to be warmed up. May be a
+  previously-restored instance if the id and config match.
+
+## haystack_integrations.tools.e2b.list_directory_tool
+
+### ListDirectoryTool
+
+Bases: <code>Tool</code>
+
+A :class:`~haystack.tools.Tool` that lists directory contents in an E2B sandbox.
+
+Pass the same :class:`E2BSandbox` instance to multiple tool classes so they
+all operate in the same live sandbox environment.
+
+### Usage example
+
+```python
+from haystack_integrations.tools.e2b import E2BSandbox, ListDirectoryTool
+
+sandbox = E2BSandbox()
+agent = Agent(chat_generator=..., tools=[ListDirectoryTool(sandbox=sandbox)])
+```
+
+#### __init__
+
+```python
+__init__(sandbox: E2BSandbox) -> None
+```
+
+Create a ListDirectoryTool.
+
+**Parameters:**
+
+- **sandbox** (<code>E2BSandbox</code>) – The :class:`E2BSandbox` instance to list directories from.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ListDirectoryTool
+```
+
+Deserialize a ListDirectoryTool from a dictionary.
+
+## haystack_integrations.tools.e2b.read_file_tool
+
+### ReadFileTool
+
+Bases: <code>Tool</code>
+
+A :class:`~haystack.tools.Tool` that reads files from an E2B sandbox filesystem.
+
+Pass the same :class:`E2BSandbox` instance to multiple tool classes so they
+all operate in the same live sandbox environment.
+
+### Usage example
+
+```python
+from haystack_integrations.tools.e2b import E2BSandbox, ReadFileTool
+
+sandbox = E2BSandbox()
+agent = Agent(chat_generator=..., tools=[ReadFileTool(sandbox=sandbox)])
+```
+
+#### __init__
+
+```python
+__init__(sandbox: E2BSandbox) -> None
+```
+
+Create a ReadFileTool.
+
+**Parameters:**
+
+- **sandbox** (<code>E2BSandbox</code>) – The :class:`E2BSandbox` instance to read files from.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ReadFileTool
+```
+
+Deserialize a ReadFileTool from a dictionary.
+
+## haystack_integrations.tools.e2b.sandbox_toolset
+
+### E2BToolset
+
+Bases: <code>Toolset</code>
+
+A :class:`~haystack.tools.Toolset` that bundles all E2B sandbox tools.
+
+All tools in the set share a single :class:`E2BSandbox` instance so they
+operate inside the same live sandbox process. The toolset owns the sandbox
+lifecycle: calling :meth:`warm_up` starts the sandbox, and serialisation
+round-trips preserve the shared-sandbox relationship.
+
+### Usage example
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.agents import Agent
+
+from haystack_integrations.tools.e2b import E2BToolset
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(model="gpt-4o"),
+    tools=E2BToolset(),
+)
+```
+
+#### __init__
+
+```python
+__init__(
+    api_key: Secret = Secret.from_env_var("E2B_API_KEY", strict=True),
+    sandbox_template: str = "base",
+    timeout: int = 120,
+    environment_vars: dict[str, str] | None = None,
+) -> None
+```
+
+Create an E2BToolset.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – E2B API key. Defaults to `Secret.from_env_var("E2B_API_KEY")`.
+- **sandbox_template** (<code>str</code>) – E2B sandbox template name. Defaults to `"base"`.
+- **timeout** (<code>int</code>) – Sandbox inactivity timeout in seconds. Defaults to `120`.
+- **environment_vars** (<code>dict\[str, str\] | None</code>) – Optional environment variables to inject into the sandbox.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Start the shared E2B sandbox (idempotent).
+
+#### close
+
+```python
+close() -> None
+```
+
+Shut down the shared E2B sandbox and release cloud resources.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this toolset to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> E2BToolset
+```
+
+Deserialize an E2BToolset from a dictionary.
+
+## haystack_integrations.tools.e2b.write_file_tool
+
+### WriteFileTool
+
+Bases: <code>Tool</code>
+
+A :class:`~haystack.tools.Tool` that writes files to an E2B sandbox filesystem.
+
+Pass the same :class:`E2BSandbox` instance to multiple tool classes so they
+all operate in the same live sandbox environment.
+
+### Usage example
+
+```python
+from haystack_integrations.tools.e2b import E2BSandbox, WriteFileTool
+
+sandbox = E2BSandbox()
+agent = Agent(chat_generator=..., tools=[WriteFileTool(sandbox=sandbox)])
+```
+
+#### __init__
+
+```python
+__init__(sandbox: E2BSandbox) -> None
+```
+
+Create a WriteFileTool.
+
+**Parameters:**
+
+- **sandbox** (<code>E2BSandbox</code>) – The :class:`E2BSandbox` instance to write files to.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> WriteFileTool
+```
+
+Deserialize a WriteFileTool from a dictionary.

docs-website/reference_versioned_docs/version-2.22/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.22/integrations-api/falkordb.md

@@ -0,0 +1,531 @@
+---
+title: "FalkorDB"
+id: integrations-falkordb
+description: "FalkorDB integration for Haystack"
+slug: "/integrations-falkordb"
+---
+
+
+## haystack_integrations.components.retrievers.falkordb.cypher_retriever
+
+### FalkorDBCypherRetriever
+
+A power-user retriever for executing arbitrary OpenCypher queries against FalkorDB.
+
+This retriever allows you to leverage graph traversal and multi-hop queries in
+GraphRAG pipelines. The query must return nodes or dictionaries that can be
+mapped exactly to a Haystack `Document`.
+
+**Security Warning:** Raw Cypher queries must only come from trusted sources. Do
+not use un-sanitised user input directly in query strings. Use `parameters` instead.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.falkordb import FalkorDBDocumentStore
+from haystack_integrations.components.retrievers.falkordb import FalkorDBCypherRetriever
+
+store = FalkorDBDocumentStore(host="localhost", port=6379)
+retriever = FalkorDBCypherRetriever(
+    document_store=store,
+    custom_cypher_query="MATCH (d:Document)-[:RELATES_TO]->(:Concept {name: $concept}) RETURN d"
+)
+
+res = retriever.run(parameters={"concept": "GraphRAG"})
+print(res["documents"])
+```
+
+#### __init__
+
+```python
+__init__(
+    document_store: FalkorDBDocumentStore,
+    custom_cypher_query: str | None = None,
+) -> None
+```
+
+Create a new FalkorDBCypherRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>FalkorDBDocumentStore</code>) – The FalkorDBDocumentStore instance.
+- **custom_cypher_query** (<code>str | None</code>) – A static OpenCypher query to execute. Can be
+  overridden at runtime by passing `query` to `run()`.
+
+**Raises:**
+
+- <code>ValueError</code> – If the provided `document_store` is not a `FalkorDBDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialise the retriever to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary representation of the retriever.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FalkorDBCypherRetriever
+```
+
+Deserialise a `FalkorDBCypherRetriever` produced by `to_dict`.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Serialised retriever dictionary.
+
+**Returns:**
+
+- <code>FalkorDBCypherRetriever</code> – Reconstructed `FalkorDBCypherRetriever` instance.
+
+#### run
+
+```python
+run(
+    query: str | None = None, parameters: dict[str, Any] | None = None
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by executing an OpenCypher query.
+
+If a `query` is provided here, it overrides the `custom_cypher_query`
+set during initialisation.
+
+**Parameters:**
+
+- **query** (<code>str | None</code>) – Optional OpenCypher query string.
+- **parameters** (<code>dict\[str, Any\] | None</code>) – Optional dictionary of query parameters (referenced as
+  `$param_name` in the Cypher string).
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – Dictionary containing a `"documents"` key with the retrieved documents.
+
+**Raises:**
+
+- <code>ValueError</code> – If no query string is provided (both here and at init).
+
+## haystack_integrations.components.retrievers.falkordb.embedding_retriever
+
+### FalkorDBEmbeddingRetriever
+
+A component for retrieving documents from a FalkorDBDocumentStore using vector similarity.
+
+The retriever uses FalkorDB's native vector search index to find documents whose embeddings
+are most similar to the provided query embedding.
+
+Usage example:
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.document_stores.falkordb import FalkorDBDocumentStore
+from haystack_integrations.components.retrievers.falkordb import FalkorDBEmbeddingRetriever
+
+store = FalkorDBDocumentStore(host="localhost", port=6379)
+store.write_documents([
+    Document(content="GraphRAG is powerful.", embedding=[0.1, 0.2, 0.3]),
+    Document(content="FalkorDB is fast.", embedding=[0.8, 0.9, 0.1]),
+])
+
+retriever = FalkorDBEmbeddingRetriever(document_store=store)
+res = retriever.run(query_embedding=[0.1, 0.2, 0.3])
+print(res["documents"][0].content)  # "GraphRAG is powerful."
+```
+
+#### __init__
+
+```python
+__init__(
+    document_store: FalkorDBDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: FilterPolicy = FilterPolicy.REPLACE,
+) -> None
+```
+
+Create a new FalkorDBEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>FalkorDBDocumentStore</code>) – The FalkorDBDocumentStore instance.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional Haystack filters to narrow down the search space.
+- **top_k** (<code>int</code>) – Maximum number of documents to retrieve.
+- **filter_policy** (<code>FilterPolicy</code>) – Policy to determine how runtime filters are combined with
+  initialization filters.
+
+**Raises:**
+
+- <code>ValueError</code> – If the provided `document_store` is not a `FalkorDBDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialise the retriever to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary representation of the retriever.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FalkorDBEmbeddingRetriever
+```
+
+Deserialise a `FalkorDBEmbeddingRetriever` produced by `to_dict`.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Serialised retriever dictionary.
+
+**Returns:**
+
+- <code>FalkorDBEmbeddingRetriever</code> – Reconstructed `FalkorDBEmbeddingRetriever` instance.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by vector similarity.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Query embedding vector.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional Haystack filters to be combined with the init filters based
+  on the configured filter policy.
+- **top_k** (<code>int | None</code>) – Maximum number of documents to return. If not provided, the default
+  top_k from initialization is used.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – Dictionary containing a `"documents"` key with the retrieved documents.
+
+## haystack_integrations.document_stores.falkordb.document_store
+
+### FalkorDBDocumentStore
+
+Bases: <code>DocumentStore</code>
+
+A Haystack DocumentStore backed by FalkorDB — a high-performance graph database.
+
+Optimised for GraphRAG workloads.
+
+Documents are stored as graph nodes (labelled `Document` by default) in a named
+FalkorDB graph. Document properties, including `meta` fields, are stored
+**flat** at the same level as `id` and `content` — exactly the same layout as
+the `neo4j-haystack` reference integration.
+
+Vector search is performed via FalkorDB's native vector index —
+**no APOC is required**. All bulk writes use `UNWIND` + `MERGE` for safe,
+idiomatic OpenCypher upserts.
+
+Usage example:
+
+```python
+from haystack_integrations.document_stores.falkordb import FalkorDBDocumentStore
+from haystack.dataclasses import Document
+
+store = FalkorDBDocumentStore(host="localhost", port=6379)
+store.write_documents([
+    Document(content="Hello, GraphRAG!", meta={"year": 2024}),
+])
+print(store.count_documents())  # 1
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    host: str = "localhost",
+    port: int = 6379,
+    graph_name: str = "haystack",
+    username: str | None = None,
+    password: Secret | None = None,
+    node_label: str = "Document",
+    embedding_dim: int = 768,
+    embedding_field: str = "embedding",
+    similarity: SimilarityFunction = "cosine",
+    write_batch_size: int = 100,
+    recreate_graph: bool = False,
+    verify_connectivity: bool = False
+) -> None
+```
+
+Create a new FalkorDBDocumentStore.
+
+**Parameters:**
+
+- **host** (<code>str</code>) – Hostname of the FalkorDB server.
+- **port** (<code>int</code>) – Port the FalkorDB server listens on.
+- **graph_name** (<code>str</code>) – Name of the FalkorDB graph to use. Each graph is an isolated
+  namespace.
+- **username** (<code>str | None</code>) – Optional username for FalkorDB authentication.
+- **password** (<code>Secret | None</code>) – Optional :class:`haystack.utils.Secret` holding the FalkorDB
+  password. The secret value is resolved lazily on first connection.
+- **node_label** (<code>str</code>) – Label used for document nodes in the graph.
+- **embedding_dim** (<code>int</code>) – Dimensionality of the vector embeddings. Used when
+  creating the vector index.
+- **embedding_field** (<code>str</code>) – Name of the node property that stores the embedding
+  vector.
+- **similarity** (<code>SimilarityFunction</code>) – Similarity function for the vector index. Accepted values
+  are `"cosine"` and `"euclidean"`.
+- **write_batch_size** (<code>int</code>) – Number of documents written per `UNWIND` batch.
+- **recreate_graph** (<code>bool</code>) – When `True` the existing graph (and all its data) is
+  dropped and recreated on initialisation. Useful for tests.
+- **verify_connectivity** (<code>bool</code>) – When `True` a connectivity probe is run
+  immediately in `__init__` — raises if the server is unreachable.
+
+**Raises:**
+
+- <code>ValueError</code> – If `similarity` is not `"cosine"` or `"euclidean"`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialise the store to a dictionary suitable for `from_dict`.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary representation of the store.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FalkorDBDocumentStore
+```
+
+Deserialise a `FalkorDBDocumentStore` produced by `to_dict`.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Serialised store dictionary.
+
+**Returns:**
+
+- <code>FalkorDBDocumentStore</code> – Reconstructed `FalkorDBDocumentStore` instance.
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Return the number of documents currently stored in the graph.
+
+**Returns:**
+
+- <code>int</code> – Integer count of document nodes.
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Retrieve all documents that match the provided Haystack filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional Haystack filter dict. When `None` all documents are
+  returned. For filter syntax see
+  [Metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+**Returns:**
+
+- <code>list\[Document\]</code> – List of matching :class:`haystack.dataclasses.Document` objects.
+
+**Raises:**
+
+- <code>ValueError</code> – If the filter dict is malformed.
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to the FalkorDB graph using `UNWIND` + `MERGE` for batching.
+
+Document `meta` fields are stored **flat** at the same level as `id` and
+`content` — no prefix is added. This matches the layout used by the
+`neo4j-haystack` reference integration.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of :class:`haystack.dataclasses.Document` objects.
+- **policy** (<code>DuplicatePolicy</code>) – How to handle documents whose `id` already exists.
+  Defaults to :attr:`DuplicatePolicy.NONE` (treated as FAIL).
+
+**Returns:**
+
+- <code>int</code> – Number of documents written or updated.
+
+**Raises:**
+
+- <code>ValueError</code> – If `documents` contains non-Document elements.
+- <code>DuplicateDocumentError</code> – If `policy` is FAIL / NONE and a duplicate
+  ID is encountered.
+- <code>DocumentStoreError</code> – If any other DB error occurs.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents by their IDs using a single `UNWIND`-based query.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – List of document IDs to remove from the graph.
+
+#### delete_all_documents
+
+```python
+delete_all_documents() -> None
+```
+
+Delete all documents from the graph.
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any]) -> int
+```
+
+Delete all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dict.
+
+**Returns:**
+
+- <code>int</code> – Number of documents deleted.
+
+#### update_by_filter
+
+```python
+update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int
+```
+
+Update metadata fields on all documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dict selecting which documents to update.
+- **meta** (<code>dict\[str, Any\]</code>) – Metadata fields to set. Keys may include or omit the `meta.` prefix.
+
+**Returns:**
+
+- <code>int</code> – Number of documents updated.
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any]) -> int
+```
+
+Return the number of documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dict.
+
+**Returns:**
+
+- <code>int</code> – Integer count of matching document nodes.
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any], metadata_fields: list[str]
+) -> dict[str, int]
+```
+
+Return the number of unique values for each metadata field among matching documents.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\]</code>) – Haystack filter dict. Pass an empty dict to count across all documents.
+- **metadata_fields** (<code>list\[str\]</code>) – List of metadata field names. May include or omit the `meta.` prefix.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – Dict mapping each field name (without `meta.` prefix) to its unique value count.
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, str]]
+```
+
+Return type information for each metadata field present on document nodes.
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, str\]\]</code> – Dict mapping field names to a `{"type": <typename>}` dict.
+  Type names are `"str"`, `"int"`, `"float"`, or `"bool"`.
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]
+```
+
+Return the minimum and maximum values for the given metadata field.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name. May include or omit the `meta.` prefix.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dict with keys `"min"` and `"max"`. Values are `None` when no documents
+  have a non-null value for the field.
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(
+    metadata_field: str,
+    search_term: str | None = None,
+    size: int | None = 10000,
+    after: dict[str, Any] | None = None,
+) -> tuple[list[Any], dict[str, Any] | None]
+```
+
+Return distinct values for the given metadata field with optional filtering and pagination.
+
+**Parameters:**
+
+- **metadata_field** (<code>str</code>) – Metadata field name. May include or omit the `meta.` prefix.
+- **search_term** (<code>str | None</code>) – Optional substring filter applied to string field values.
+- **size** (<code>int | None</code>) – Maximum number of values to return per page. Defaults to 10 000.
+- **after** (<code>dict\[str, Any\] | None</code>) – Pagination cursor returned by a previous call. Pass `None` for the first page.
+
+**Returns:**
+
+- <code>tuple\[list\[Any\], dict\[str, Any\] | None\]</code> – Tuple of `(values, next_cursor)`. `next_cursor` is `None` on the last page.

docs-website/reference_versioned_docs/version-2.22/integrations-api/fastembed.md

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

docs-website/reference_versioned_docs/version-2.22/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.22/integrations-api/funasr.md

@@ -0,0 +1,157 @@
+---
+title: "FunASR"
+id: integrations-funasr
+description: "FunASR speech-to-text integration for Haystack"
+slug: "/integrations-funasr"
+---
+
+
+## haystack_integrations.components.audio.funasr.transcriber
+
+### FunASRTranscriber
+
+Transcribes audio files to Documents using [FunASR](https://github.com/modelscope/FunASR).
+
+FunASR is an open-source speech recognition toolkit from Alibaba DAMO Academy.
+It supports 50+ languages, speaker diarization, and timestamp extraction, and runs
+entirely locally — no API key required.
+
+Models are downloaded from ModelScope on first use and cached in `~/.cache/modelscope`.
+
+**Usage Example:**
+
+```python
+from haystack_integrations.components.audio.funasr import FunASRTranscriber
+
+transcriber = FunASRTranscriber()
+result = transcriber.run(sources=["speech.wav", "interview.mp3"])
+documents = result["documents"]
+```
+
+**Speaker diarization and punctuation:**
+
+```python
+from haystack.utils import ComponentDevice
+
+transcriber = FunASRTranscriber(
+    model="paraformer-zh",
+    vad_model="fsmn-vad",
+    punc_model="ct-punc",
+    spk_model="cam++",
+    device=ComponentDevice.from_str("cuda"),
+)
+```
+
+**SenseVoice with inverse text normalisation:**
+
+```python
+transcriber = FunASRTranscriber(
+    model="iic/SenseVoiceSmall",
+    generation_kwargs={"use_itn": True, "merge_vad": True, "language": "auto"},
+)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    model: str = "iic/SenseVoiceSmall",
+    vad_model: str | None = "fsmn-vad",
+    punc_model: str | None = "ct-punc",
+    spk_model: str | None = None,
+    device: ComponentDevice | None = None,
+    batch_size_s: int = 300,
+    store_full_path: bool = False,
+    generation_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Create a FunASRTranscriber component.
+
+**Parameters:**
+
+- **model** (<code>str</code>) – FunASR model name or local path. Defaults to `"iic/SenseVoiceSmall"`,
+  a multilingual model supporting 50+ languages that is 5-10x faster than Whisper.
+  Alternatives include `"paraformer-zh"` (Chinese) or `"paraformer-en"` (English).
+  Browse available models at https://modelscope.github.io/FunASR/model-selection.html.
+- **vad_model** (<code>str | None</code>) – Voice activity detection model used to split long audio into segments.
+  Set to `None` to process the audio as a single stream.
+  Browse available VAD models at https://www.modelscope.cn/models.
+- **punc_model** (<code>str | None</code>) – Punctuation restoration model. Set to `None` to disable punctuation.
+  Browse available punctuation models at https://www.modelscope.cn/models.
+- **spk_model** (<code>str | None</code>) – Speaker diarization model (e.g. `"cam++"`). When set, a `"speakers"`
+  key is included in the Document metadata. Defaults to `None` (diarization disabled).
+  Browse available speaker diarization models at https://www.modelscope.cn/models.
+- **device** (<code>ComponentDevice | None</code>) – The device to run inference on. If `None`, the default device is selected
+  automatically. Use `ComponentDevice.from_str("cuda")` for GPU inference.
+- **batch_size_s** (<code>int</code>) – Batch size in seconds for VAD-segmented audio. Larger values
+  improve throughput at the cost of memory.
+- **store_full_path** (<code>bool</code>) – If `True`, store the full audio file path in Document metadata.
+  If `False` (default), store only the file name.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Extra keyword arguments forwarded to `AutoModel.generate()`.
+  Use this for model-specific options such as `use_itn=True` or `merge_vad=True`
+  for SenseVoice, or `hotword="..."` for contextual recognition.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Load the FunASR model into memory.
+
+Models are downloaded from ModelScope on first call and cached locally.
+This method is idempotent — calling it multiple times is safe.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> FunASRTranscriber
+```
+
+Deserialize the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>FunASRTranscriber</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    sources: list[str | Path | ByteStream],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Transcribe audio sources to Documents.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – Audio file paths (`str` or `Path`) or `ByteStream` objects.
+  Supported formats: WAV, MP3, FLAC, OGG, M4A, AAC, and any format that
+  FunASR's underlying audio backend (soundfile/ffmpeg) can decode.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Metadata to attach to the produced Documents. Pass a single dict
+  to apply the same metadata to all Documents, or a list aligned with `sources`.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – Dictionary with key `"documents"` — one `Document` per source whose
+  `content` holds the full transcript text.

docs-website/reference_versioned_docs/version-2.22/integrations-api/github.md

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

docs-website/reference_versioned_docs/version-2.22/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.22/integrations-api/google_drive.md

@@ -0,0 +1,350 @@
+---
+title: "Google Drive"
+id: integrations-google-drive
+description: "Google Drive integration for Haystack"
+slug: "/integrations-google-drive"
+---
+
+
+## haystack_integrations.components.fetchers.google_drive.fetcher
+
+### GoogleDriveFetcher
+
+Fetches the full content of Google Drive files via the Drive API v3.
+
+The fetcher complements `GoogleDriveRetriever`, which returns only metadata (and optionally exported text).
+Wire the retriever's `documents` (or a list of file ids / Drive URLs) into this fetcher to download the full
+content. It dispatches on each file's mime type and always returns `ByteStream`s, ready for a downstream
+converter (for example a `FileTypeRouter` in front of `PyPDFToDocument`, `DOCXToDocument`, `XLSXToDocument`,
+or `PPTXToDocument`):
+
+- **Binary files** (PDF, DOCX, images, ...) are downloaded as-is via `files.get?alt=media`.
+- **Native Google Docs/Sheets/Slides** are exported with `files.export`, by default to the Office formats
+  (DOCX/XLSX/PPTX), configurable via `export_mime_types`.
+- **Folders** and other non-downloadable Google types (Forms, Sites, ...) are skipped.
+
+Each `ByteStream`'s `meta` carries `file_id`, `web_url`, `file_name`, and `content_type`.
+
+The fetcher takes a per-user `access_token` as a run input, typically wired from an upstream `OAuthTokenResolver`.
+The token must carry a delegated Google OAuth scope that allows reading file content (for example
+`https://www.googleapis.com/auth/drive.readonly`).
+
+### Usage example
+
+```python
+from haystack_integrations.components.fetchers.google_drive import GoogleDriveFetcher
+
+fetcher = GoogleDriveFetcher()
+
+# `access_token` is a per-user delegated Google OAuth bearer token.
+result = fetcher.run(
+    access_token="my-delegated-google-token",
+    targets=["https://drive.google.com/file/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/view"],
+)
+streams = result["streams"]
+```
+
+In a pipeline, connect `GoogleDriveRetriever.documents` to the fetcher's `targets` input and an upstream
+component that emits a per-user `access_token` to the fetcher's `access_token` input.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_base_url: str = DEFAULT_API_BASE_URL,
+    timeout: float = 30.0,
+    max_retries: int = 3,
+    max_concurrent_requests: int = 5,
+    raise_on_failure: bool = True,
+    export_mime_types: dict[str, str] | None = None
+) -> None
+```
+
+Initialize the fetcher.
+
+**Parameters:**
+
+- **api_base_url** (<code>str</code>) – The Drive API base URL. Defaults to `https://www.googleapis.com/drive/v3`.
+- **timeout** (<code>float</code>) – The HTTP timeout in seconds for each request to the Drive API.
+- **max_retries** (<code>int</code>) – The maximum number of retries for throttled (HTTP 429) or transient server errors.
+- **max_concurrent_requests** (<code>int</code>) – The maximum number of files fetched concurrently by `run_async`. Bounds
+  the in-flight requests to Drive to avoid tripping its rate limits. Has no effect on the synchronous
+  `run`, which fetches files one at a time.
+- **raise_on_failure** (<code>bool</code>) – If `True`, a fetch failure raises an exception. If `False`, the failure is
+  logged and the file is skipped, so the other files are still returned.
+- **export_mime_types** (<code>dict\[str, str\] | None</code>) – Optional mapping of native Google mime type (for example
+  `application/vnd.google-apps.document`) to the mime type to export it as. Replaces the default mapping
+  (Docs/Sheets/Slides to DOCX/XLSX/PPTX). Drive caps a single export at 10 MB.
+
+**Raises:**
+
+- <code>GoogleDriveConfigError</code> – If `max_retries` is negative or `max_concurrent_requests` is not positive.
+
+#### run
+
+```python
+run(
+    access_token: str | Secret, targets: list[Document | str]
+) -> dict[str, list[ByteStream]]
+```
+
+Fetch the content of Google Drive files and return them as `ByteStream`s.
+
+**Parameters:**
+
+- **access_token** (<code>str | Secret</code>) – A delegated Google OAuth bearer token for the user whose files are fetched, typically
+  wired from an upstream `OAuthTokenResolver` (which emits a plain `str`). A `Secret` is also accepted and
+  resolved internally.
+- **targets** (<code>list\[Document | str\]</code>) – The files to fetch, as either `Document`s emitted by `GoogleDriveRetriever` or raw Google
+  Drive file ids / URLs (the two may also be mixed in one list). For a `Document`, the `file_id` in its
+  meta is fetched and `mime_type`, `file_name`, and `web_url` are reused when present. For a raw string,
+  the file id is parsed from a Drive URL (or used as-is) and the file's mime type is looked up. Folders
+  and non-downloadable Google types are skipped.
+
+**Returns:**
+
+- <code>dict\[str, list\[ByteStream\]\]</code> – A dictionary with a `streams` key holding the fetched content as `ByteStream` objects. Each
+  stream's `meta` carries `file_id`, `web_url`, `file_name`, and `content_type`.
+
+**Raises:**
+
+- <code>GoogleDriveConfigError</code> – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+  `Secret` that does not resolve to a string.
+- <code>GoogleDriveRequestError</code> – If a fetch fails and `raise_on_failure` is `True`.
+
+#### run_async
+
+```python
+run_async(
+    access_token: str | Secret, targets: list[Document | str]
+) -> dict[str, list[ByteStream]]
+```
+
+Asynchronously fetch the content of Google Drive files and return them as `ByteStream`s.
+
+**Parameters:**
+
+- **access_token** (<code>str | Secret</code>) – A delegated Google OAuth bearer token for the user whose files are fetched, typically
+  wired from an upstream `OAuthTokenResolver` (which emits a plain `str`). A `Secret` is also accepted and
+  resolved internally.
+- **targets** (<code>list\[Document | str\]</code>) – The files to fetch, as either `Document`s emitted by `GoogleDriveRetriever` or raw Google
+  Drive file ids / URLs (the two may also be mixed in one list). For a `Document`, the `file_id` in its
+  meta is fetched and `mime_type`, `file_name`, and `web_url` are reused when present. For a raw string,
+  the file id is parsed from a Drive URL (or used as-is) and the file's mime type is looked up. Folders
+  and non-downloadable Google types are skipped.
+
+**Returns:**
+
+- <code>dict\[str, list\[ByteStream\]\]</code> – A dictionary with a `streams` key holding the fetched content as `ByteStream` objects. Each
+  stream's `meta` carries `file_id`, `web_url`, `file_name`, and `content_type`.
+
+**Raises:**
+
+- <code>GoogleDriveConfigError</code> – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+  `Secret` that does not resolve to a string.
+- <code>GoogleDriveRequestError</code> – If a fetch fails and `raise_on_failure` is `True`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleDriveFetcher
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>GoogleDriveFetcher</code> – The deserialized component instance.
+
+## haystack_integrations.components.retrievers.google_drive.retriever
+
+### GoogleDriveRetriever
+
+Retrieves files from Google Drive via the Drive API v3 search (`files.list`) endpoint.
+
+Given a query, the retriever runs a full-text search over the user's Drive (and optionally shared
+drives) and maps each matching file to a Haystack `Document`. By default, each `Document` carries
+resource metadata (`file_name`, `file_id`, `web_url`, `mime_type`, `file_extension`, author, and
+timestamps) and uses the file `description` or `name` as `content`, because the Drive search API does
+not return a text snippet. Set `include_content=True` to additionally export native Google
+Docs/Sheets/Slides to text and use that as the `Document` content. Binary files (PDF, DOCX, ...) are
+never downloaded. Compose a downstream fetcher/converter on the returned `web_url`/`file_id` when full
+file content is needed.
+
+The retriever takes a per-user `access_token` as a run input, typically wired from an upstream
+`OAuthResolver`. The token must carry a delegated Google OAuth scope that allows search
+(for example `https://www.googleapis.com/auth/drive.readonly`). The metadata-only
+`drive.metadata.readonly` scope cannot search file content or export documents.
+
+### Usage example
+
+```python
+from haystack import Pipeline
+from haystack.utils import Secret
+from haystack_integrations.components.connectors.oauth import OAuthResolver
+from haystack_integrations.utils.oauth import RefreshTokenSource
+from haystack_integrations.components.retrievers.google_drive import GoogleDriveRetriever
+
+pipeline = Pipeline()
+pipeline.add_component(
+    "resolver",
+    OAuthResolver(
+        token_source=RefreshTokenSource(
+            token_url="https://oauth2.googleapis.com/token",
+            client_id="aaa-bbb-ccc",
+            refresh_token=Secret.from_env_var("GOOGLE_REFRESH_TOKEN"),
+            scopes=["https://www.googleapis.com/auth/drive.readonly"],
+        ),
+    ),
+)
+pipeline.add_component("retriever", GoogleDriveRetriever(top_k=5))
+pipeline.connect("resolver.access_token", "retriever.access_token")
+
+result = pipeline.run({"retriever": {"query": "quarterly roadmap"}})
+documents = result["retriever"]["documents"]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    include_content: bool = False,
+    top_k: int = 10,
+    query_filter: str | None = None,
+    include_shared_drives: bool = False,
+    order_by: str | None = None,
+    fields: list[str] | None = None,
+    api_base_url: str = DEFAULT_API_BASE_URL,
+    timeout: float = 30.0,
+    max_retries: int = 3
+) -> None
+```
+
+Initialize the retriever.
+
+**Parameters:**
+
+- **include_content** (<code>bool</code>) – When `True`, native Google Docs/Sheets/Slides are exported to text and the
+  result becomes the `Document` content. Binary files are never downloaded. When `False` (the
+  default), `content` is the file `description` or `name` and no export request is made.
+- **top_k** (<code>int</code>) – The maximum number of documents to return. Maps to the Drive `pageSize` and is
+  paginated when it exceeds a single page.
+- **query_filter** (<code>str | None</code>) – Optional Drive query clause AND-ed with the full-text search term, for example
+  `"mimeType != 'application/vnd.google-apps.folder'"` or `"'<folderId>' in parents"`.
+- **include_shared_drives** (<code>bool</code>) – When `True`, the search spans shared drives as well as the user's My
+  Drive (sets `includeItemsFromAllDrives`, `supportsAllDrives`, and `corpora=allDrives`).
+- **order_by** (<code>str | None</code>) – Optional Drive `orderBy` expression, for example `"modifiedTime desc"`.
+- **fields** (<code>list\[str\] | None</code>) – Optional list of file properties to request via the Drive `fields` selection.
+  Defaults to a standard set covering the returned metadata.
+- **api_base_url** (<code>str</code>) – The Drive API base URL. Defaults to `https://www.googleapis.com/drive/v3`.
+- **timeout** (<code>float</code>) – The HTTP timeout in seconds for each request to the Drive API.
+- **max_retries** (<code>int</code>) – The maximum number of retries on HTTP 429 (rate limit), 500, 502, 503,
+  or 504 responses. Set to 0 to disable retries.
+
+**Raises:**
+
+- <code>GoogleDriveConfigError</code> – If `top_k` is not positive or `max_retries` is negative.
+
+#### run
+
+```python
+run(
+    query: str, access_token: str | Secret, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Search Google Drive and return the matching documents.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The search query string, matched against the full text of files via
+  `fullText contains`.
+- **access_token** (<code>str | Secret</code>) – A delegated Google OAuth bearer token for the user whose Drive is searched,
+  typically wired from an upstream `OAuthResolver` (which emits a plain `str`). A `Secret` is also
+  accepted and resolved internally.
+- **top_k** (<code>int | None</code>) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- <code>GoogleDriveConfigError</code> – If `access_token` is a `Secret` that does not resolve to a string.
+- <code>GoogleDriveRequestError</code> – If the Drive API returns an error response.
+- <code>httpx.HTTPError</code> – If a network-level error occurs (for example a timeout or connection failure).
+
+#### run_async
+
+```python
+run_async(
+    query: str, access_token: str | Secret, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously search Google Drive and return the matching documents.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The search query string, matched against the full text of files via
+  `fullText contains`.
+- **access_token** (<code>str | Secret</code>) – A delegated Google OAuth bearer token for the user whose Drive is searched,
+  typically wired from an upstream `OAuthResolver` (which emits a plain `str`). A `Secret` is also
+  accepted and resolved internally.
+- **top_k** (<code>int | None</code>) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- <code>GoogleDriveConfigError</code> – If `access_token` is a `Secret` that does not resolve to a string.
+- <code>GoogleDriveRequestError</code> – If the Drive API returns an error response.
+- <code>httpx.HTTPError</code> – If a network-level error occurs (for example a timeout or connection failure).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> GoogleDriveRetriever
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>GoogleDriveRetriever</code> – The deserialized component instance.

docs-website/reference_versioned_docs/version-2.22/integrations-api/google_genai.md

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

docs-website/reference_versioned_docs/version-2.22/integrations-api/hanlp.md

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

docs-website/reference_versioned_docs/version-2.22/integrations-api/huggingface_api.md

@@ -0,0 +1,796 @@
+---
+title: "Hugging Face API"
+id: integrations-huggingface-api
+description: "Hugging Face API integration for Haystack"
+slug: "/integrations-huggingface-api"
+---
+
+
+## haystack_integrations.components.embedders.huggingface_api.document_embedder
+
+### HuggingFaceAPIDocumentEmbedder
+
+Embeds documents using Hugging Face APIs.
+
+Use it with the following Hugging Face APIs:
+
+- [Free Serverless Inference API](https://huggingface.co/inference-api)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+
+### Usage examples
+
+#### With free serverless inference API
+
+```python
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder
+from haystack.utils import Secret
+from haystack.dataclasses import Document
+
+doc = Document(content="I love pizza!")
+
+doc_embedder = HuggingFaceAPIDocumentEmbedder(api_type="serverless_inference_api",
+                                              api_params={"model": "BAAI/bge-small-en-v1.5"},
+                                              token=Secret.from_token("<your-api-key>"))
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### With paid inference endpoints
+
+```python
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder
+from haystack.utils import Secret
+from haystack.dataclasses import Document
+
+doc = Document(content="I love pizza!")
+
+doc_embedder = HuggingFaceAPIDocumentEmbedder(api_type="inference_endpoints",
+                                              api_params={"url": "<your-inference-endpoint-url>"},
+                                              token=Secret.from_token("<your-api-key>"))
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### With self-hosted text embeddings inference
+
+```python
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder
+from haystack.dataclasses import Document
+
+doc = Document(content="I love pizza!")
+
+doc_embedder = HuggingFaceAPIDocumentEmbedder(api_type="text_embeddings_inference",
+                                              api_params={"url": "http://localhost:8080"})
+
+result = document_embedder.run([doc])
+print(result["documents"][0].embedding)
+
+# [0.017020374536514282, -0.023255806416273117, ...]
+```
+
+#### __init__
+
+```python
+__init__(
+    api_type: HFEmbeddingAPIType | str,
+    api_params: dict[str, str],
+    token: Secret | None = Secret.from_env_var(
+        ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+    ),
+    prefix: str = "",
+    suffix: str = "",
+    truncate: bool | None = True,
+    normalize: bool | None = False,
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n",
+    concurrency_limit: int = 4,
+) -> None
+```
+
+Creates a HuggingFaceAPIDocumentEmbedder component.
+
+**Parameters:**
+
+- **api_type** (<code>HFEmbeddingAPIType | str</code>) – The type of Hugging Face API to use.
+- **api_params** (<code>dict\[str, str\]</code>) – A dictionary with the following keys:
+- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.
+- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or
+  `TEXT_EMBEDDINGS_INFERENCE`.
+- **token** (<code>Secret | None</code>) – The Hugging Face token to use as HTTP bearer authorization.
+  Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **truncate** (<code>bool | None</code>) – Truncates the input text to the maximum length supported by the model.
+  Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS`
+  if the backend uses Text Embeddings Inference.
+  If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
+- **normalize** (<code>bool | None</code>) – Normalizes the embeddings to unit length.
+  Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS`
+  if the backend uses Text Embeddings Inference.
+  If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
+- **batch_size** (<code>int</code>) – Number of documents to process at once.
+- **progress_bar** (<code>bool</code>) – If `True`, shows a progress bar when running.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of metadata fields to embed along with the document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the metadata fields to the document text.
+- **concurrency_limit** (<code>int</code>) – The maximum number of requests that should be allowed to run concurrently.
+  This parameter is only used in the `run_async` method.
+
+**Raises:**
+
+- <code>ValueError</code> – If the required `model` or `url` is missing from `api_params`, the `url` is invalid,
+  or the `api_type` is unknown.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPIDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>HuggingFaceAPIDocumentEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embeds a list of documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+
+**Raises:**
+
+- <code>TypeError</code> – If `documents` is not a list of Documents.
+- <code>ValueError</code> – If the embeddings returned by the API have an unexpected shape.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Embeds a list of documents asynchronously.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of documents with embeddings.
+
+**Raises:**
+
+- <code>TypeError</code> – If `documents` is not a list of Documents.
+- <code>ValueError</code> – If the embeddings returned by the API have an unexpected shape.
+
+## haystack_integrations.components.embedders.huggingface_api.text_embedder
+
+### HuggingFaceAPITextEmbedder
+
+Embeds strings using Hugging Face APIs.
+
+Use it with the following Hugging Face APIs:
+
+- [Free Serverless Inference API](https://huggingface.co/inference-api)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+
+### Usage examples
+
+#### With free serverless inference API
+
+```python
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder
+from haystack.utils import Secret
+
+text_embedder = HuggingFaceAPITextEmbedder(api_type="serverless_inference_api",
+                                           api_params={"model": "BAAI/bge-small-en-v1.5"},
+                                           token=Secret.from_token("<your-api-key>"))
+
+print(text_embedder.run("I love pizza!"))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+```
+
+#### With paid inference endpoints
+
+```python
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder
+from haystack.utils import Secret
+text_embedder = HuggingFaceAPITextEmbedder(api_type="inference_endpoints",
+                                           api_params={"model": "BAAI/bge-small-en-v1.5"},
+                                           token=Secret.from_token("<your-api-key>"))
+
+print(text_embedder.run("I love pizza!"))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+```
+
+#### With self-hosted text embeddings inference
+
+```python
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder
+from haystack.utils import Secret
+
+text_embedder = HuggingFaceAPITextEmbedder(api_type="text_embeddings_inference",
+                                           api_params={"url": "http://localhost:8080"})
+
+print(text_embedder.run("I love pizza!"))
+
+# {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+```
+
+#### __init__
+
+```python
+__init__(
+    api_type: HFEmbeddingAPIType | str,
+    api_params: dict[str, str],
+    token: Secret | None = Secret.from_env_var(
+        ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+    ),
+    prefix: str = "",
+    suffix: str = "",
+    truncate: bool | None = True,
+    normalize: bool | None = False,
+) -> None
+```
+
+Creates a HuggingFaceAPITextEmbedder component.
+
+**Parameters:**
+
+- **api_type** (<code>HFEmbeddingAPIType | str</code>) – The type of Hugging Face API to use.
+- **api_params** (<code>dict\[str, str\]</code>) – A dictionary with the following keys:
+- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.
+- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or
+  `TEXT_EMBEDDINGS_INFERENCE`.
+- **token** (<code>Secret | None</code>) – The Hugging Face token to use as HTTP bearer authorization.
+  Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **prefix** (<code>str</code>) – A string to add at the beginning of each text.
+- **suffix** (<code>str</code>) – A string to add at the end of each text.
+- **truncate** (<code>bool | None</code>) – Truncates the input text to the maximum length supported by the model.
+  Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS`
+  if the backend uses Text Embeddings Inference.
+  If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
+- **normalize** (<code>bool | None</code>) – Normalizes the embeddings to unit length.
+  Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS`
+  if the backend uses Text Embeddings Inference.
+  If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
+
+**Raises:**
+
+- <code>ValueError</code> – If the required `model` or `url` is missing from `api_params`, the `url` is invalid,
+  or the `api_type` is unknown.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPITextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>HuggingFaceAPITextEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embeds a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+
+**Raises:**
+
+- <code>TypeError</code> – If `text` is not a string.
+- <code>ValueError</code> – If the embedding returned by the API has an unexpected shape.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, Any]
+```
+
+Embeds a single string asynchronously.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – Text to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the following keys:
+- `embedding`: The embedding of the input text.
+
+**Raises:**
+
+- <code>TypeError</code> – If `text` is not a string.
+- <code>ValueError</code> – If the embedding returned by the API has an unexpected shape.
+
+## haystack_integrations.components.generators.huggingface_api.chat.chat_generator
+
+### HuggingFaceAPIChatGenerator
+
+Completes chats using Hugging Face APIs.
+
+HuggingFaceAPIChatGenerator uses the [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage)
+format for input and output. Use it to generate text with Hugging Face APIs:
+
+- [Serverless Inference API (Inference Providers)](https://huggingface.co/docs/inference-providers)
+- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints)
+- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference)
+
+### Usage examples
+
+#### With the serverless inference API (Inference Providers) - free tier available
+
+```python
+from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+from haystack_integrations.common.huggingface_api.utils import HFGenerationAPIType
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
+            ChatMessage.from_user("What's Natural Language Processing?")]
+
+# the api_type can be expressed using the HFGenerationAPIType enum or as a string
+api_type = HFGenerationAPIType.SERVERLESS_INFERENCE_API
+api_type = "serverless_inference_api" # this is equivalent to the above
+
+generator = HuggingFaceAPIChatGenerator(api_type=api_type,
+                                        api_params={"model": "Qwen/Qwen2.5-7B-Instruct",
+                                                    "provider": "together"},
+                                        token=Secret.from_token("<your-api-key>"))
+
+result = generator.run(messages)
+print(result)
+```
+
+#### With the serverless inference API (Inference Providers) and text+image input
+
+```python
+from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage, ImageContent
+from haystack.utils import Secret
+from haystack_integrations.common.huggingface_api.utils import HFGenerationAPIType
+
+# Create an image from file path, URL, or base64
+image = ImageContent.from_file_path("path/to/your/image.jpg")
+
+# Create a multimodal message with both text and image
+messages = [ChatMessage.from_user(content_parts=["Describe this image in detail", image])]
+
+generator = HuggingFaceAPIChatGenerator(
+    api_type=HFGenerationAPIType.SERVERLESS_INFERENCE_API,
+    api_params={
+        "model": "Qwen/Qwen2.5-VL-7B-Instruct",  # Vision Language Model
+        "provider": "hyperbolic"
+    },
+    token=Secret.from_token("<your-api-key>")
+)
+
+result = generator.run(messages)
+print(result)
+```
+
+#### With paid inference endpoints
+
+```python
+from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
+            ChatMessage.from_user("What's Natural Language Processing?")]
+
+generator = HuggingFaceAPIChatGenerator(api_type="inference_endpoints",
+                                        api_params={"url": "<your-inference-endpoint-url>"},
+                                        token=Secret.from_token("<your-api-key>"))
+
+result = generator.run(messages)
+print(result)
+```
+
+#### With self-hosted text generation inference
+
+```python
+from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"),
+            ChatMessage.from_user("What's Natural Language Processing?")]
+
+generator = HuggingFaceAPIChatGenerator(api_type="text_generation_inference",
+                                        api_params={"url": "http://localhost:8080"})
+
+result = generator.run(messages)
+print(result)
+```
+
+#### __init__
+
+```python
+__init__(
+    api_type: HFGenerationAPIType | str,
+    api_params: dict[str, str],
+    token: Secret | None = Secret.from_env_var(
+        ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+    ),
+    generation_kwargs: dict[str, Any] | None = None,
+    stop_words: list[str] | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    tools: ToolsType | None = None,
+) -> None
+```
+
+Initialize the HuggingFaceAPIChatGenerator instance.
+
+**Parameters:**
+
+- **api_type** (<code>HFGenerationAPIType | str</code>) – The type of Hugging Face API to use. Available types:
+- `text_generation_inference`: See [TGI](https://github.com/huggingface/text-generation-inference).
+- `inference_endpoints`: See [Inference Endpoints](https://huggingface.co/inference-endpoints).
+- `serverless_inference_api`: See
+  [Serverless Inference API - Inference Providers](https://huggingface.co/docs/inference-providers).
+- **api_params** (<code>dict\[str, str\]</code>) – A dictionary with the following keys:
+- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.
+- `provider`: Provider name. Recommended when `api_type` is `SERVERLESS_INFERENCE_API`.
+- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or
+  `TEXT_GENERATION_INFERENCE`.
+- Other parameters specific to the chosen API type, such as `timeout`, `headers`, etc.
+- **token** (<code>Secret | None</code>) – The Hugging Face token to use as HTTP bearer authorization.
+  Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary with keyword arguments to customize text generation.
+  Some examples: `max_tokens`, `temperature`, `top_p`.
+  For details, see [Hugging Face chat_completion documentation](https://huggingface.co/docs/huggingface_hub/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion).
+- **stop_words** (<code>list\[str\] | None</code>) – An optional list of strings representing the stop words.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – An optional callable for handling streaming responses.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  The chosen model should support tool/function calling, according to the model card.
+  Support for tools in the Hugging Face API and TGI is not yet fully refined and you may experience
+  unexpected behavior.
+
+**Raises:**
+
+- <code>ValueError</code> – If the required `model` or `url` is missing from `api_params`, the `url` is invalid, the `api_type`
+  is unknown, `tools` and `streaming_callback` are used together, or duplicate tool names are provided.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Warm up the Hugging Face API chat generator.
+
+This will warm up the tools registered in the chat generator.
+This method is idempotent and will only warm up the tools once.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary containing the serialized component.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceAPIChatGenerator
+```
+
+Deserialize this component from a dictionary.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage] | str,
+    generation_kwargs: dict[str, Any] | None = None,
+    tools: ToolsType | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Invoke the text generation inference based on the provided messages and generation parameters.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\] | str</code>) – A list of ChatMessage objects representing the input messages. If a string is provided, it is converted
+  to a list containing a ChatMessage with user role.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation.
+- **tools** (<code>ToolsType | None</code>) – A list of tools or a Toolset for which the model can prepare calls. If set, it will override
+  the `tools` parameter set during component initialization. This parameter can accept either a
+  list of `Tool` objects or a `Toolset` instance.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
+  parameter set during component initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `replies`: A list containing the generated responses as ChatMessage objects.
+
+**Raises:**
+
+- <code>ValueError</code> – If `tools` and a streaming callback are used together, or if duplicate tool names are provided.
+
+#### run_async
+
+```python
+run_async(
+    messages: list[ChatMessage] | str,
+    generation_kwargs: dict[str, Any] | None = None,
+    tools: ToolsType | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+) -> dict[str, list[ChatMessage]]
+```
+
+Asynchronously invokes the text generation inference based on the provided messages and generation parameters.
+
+This is the asynchronous version of the `run` method. It has the same parameters
+and return values but can be used with `await` in an async code.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\] | str</code>) – A list of ChatMessage objects representing the input messages. If a string is provided, it is converted
+  to a list containing a ChatMessage with user role.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation.
+- **tools** (<code>ToolsType | None</code>) – A list of tools or a Toolset for which the model can prepare calls. If set, it will override the `tools`
+  parameter set during component initialization. This parameter can accept either a list of `Tool` objects
+  or a `Toolset` instance.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
+  parameter set during component initialization.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following keys:
+- `replies`: A list containing the generated responses as ChatMessage objects.
+
+**Raises:**
+
+- <code>ValueError</code> – If `tools` and a streaming callback are used together, or if duplicate tool names are provided.
+
+## haystack_integrations.components.rankers.huggingface_api.ranker
+
+### TruncationDirection
+
+Bases: <code>str</code>, <code>Enum</code>
+
+Defines the direction to truncate text when input length exceeds the model's limit.
+
+Attributes:
+LEFT: Truncate text from the left side (start of text).
+RIGHT: Truncate text from the right side (end of text).
+
+### HuggingFaceTEIRanker
+
+Ranks documents based on their semantic similarity to the query.
+
+It can be used with a Text Embeddings Inference (TEI) API endpoint:
+
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+- [Hugging Face Inference Endpoints](https://huggingface.co/inference-endpoints)
+
+Usage example:
+
+```python
+from haystack import Document
+from haystack.utils import Secret
+
+from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker
+
+reranker = HuggingFaceTEIRanker(
+    url="http://localhost:8080",
+    top_k=5,
+    timeout=30,
+    token=Secret.from_token("my_api_token")
+)
+
+docs = [Document(content="The capital of France is Paris"), Document(content="The capital of Germany is Berlin")]
+
+result = reranker.run(query="What is the capital of France?", documents=docs)
+
+ranked_docs = result["documents"]
+print(ranked_docs)
+# >> {'documents': [Document(id=..., content: 'the capital of France is Paris', score: 0.9979767),
+# >>                Document(id=..., content: 'the capital of Germany is Berlin', score: 0.13982213)]}
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    url: str,
+    top_k: int = 10,
+    raw_scores: bool = False,
+    timeout: int | None = 30,
+    max_retries: int = 3,
+    retry_status_codes: list[int] | None = None,
+    token: Secret | None = Secret.from_env_var(
+        ["HF_API_TOKEN", "HF_TOKEN"], strict=False
+    )
+) -> None
+```
+
+Initializes the TEI reranker component.
+
+**Parameters:**
+
+- **url** (<code>str</code>) – Base URL of the TEI reranking service (for example, "https://api.example.com").
+- **top_k** (<code>int</code>) – Maximum number of top documents to return.
+- **raw_scores** (<code>bool</code>) – If True, include raw relevance scores in the API payload.
+- **timeout** (<code>int | None</code>) – Request timeout in seconds.
+- **max_retries** (<code>int</code>) – Maximum number of retry attempts for failed requests.
+- **retry_status_codes** (<code>list\[int\] | None</code>) – List of HTTP status codes that will trigger a retry.
+  When None, HTTP 408, 418, 429 and 503 will be retried (default: None).
+- **token** (<code>Secret | None</code>) – The Hugging Face token to use as HTTP bearer authorization. Not always required
+  depending on your TEI server configuration.
+  Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> HuggingFaceTEIRanker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>HuggingFaceTEIRanker</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    query: str,
+    documents: list[Document],
+    top_k: int | None = None,
+    truncation_direction: TruncationDirection | None = None,
+) -> dict[str, list[Document]]
+```
+
+Reranks the provided documents by relevance to the query using the TEI API.
+
+Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+if a score is present.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The user query string to guide reranking.
+- **documents** (<code>list\[Document\]</code>) – List of `Document` objects to rerank.
+- **top_k** (<code>int | None</code>) – Optional override for the maximum number of documents to return.
+- **truncation_direction** (<code>TruncationDirection | None</code>) – If set, enables text truncation in the specified direction.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of reranked documents.
+
+**Raises:**
+
+- <code>RuntimeError</code> – - If the API request fails.
+- <code>RuntimeError</code> – - If the API returns an error response.
+- <code>TypeError</code> – - If the API response is not in the expected list format.
+
+#### run_async
+
+```python
+run_async(
+    query: str,
+    documents: list[Document],
+    top_k: int | None = None,
+    truncation_direction: TruncationDirection | None = None,
+) -> dict[str, list[Document]]
+```
+
+Asynchronously reranks the provided documents by relevance to the query using the TEI API.
+
+Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+if a score is present.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The user query string to guide reranking.
+- **documents** (<code>list\[Document\]</code>) – List of `Document` objects to rerank.
+- **top_k** (<code>int | None</code>) – Optional override for the maximum number of documents to return.
+- **truncation_direction** (<code>TruncationDirection | None</code>) – If set, enables text truncation in the specified direction.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
+- `documents`: A list of reranked documents.
+
+**Raises:**
+
+- <code>httpx.RequestError</code> – - If the API request fails.
+- <code>RuntimeError</code> – - If the API returns an error response.
+- <code>TypeError</code> – - If the API response is not in the expected list format.

docs-website/reference_versioned_docs/version-2.22/integrations-api/ibm_db.md

@@ -0,0 +1,374 @@
+---
+title: "IBM Db2"
+id: integrations-ibm-db
+description: "IBM Db2 integration for Haystack"
+slug: "/integrations-ibm-db"
+---
+
+
+## haystack_integrations.components.retrievers.ibm_db.embedding_retriever
+
+### IBMDb2EmbeddingRetriever
+
+Retrieves documents from a IBMDb2DocumentStore using vector similarity.
+
+Use inside a Haystack pipeline after a text embedder:
+
+```python
+pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
+pipeline.add_component("retriever", IBMDb2EmbeddingRetriever(
+    document_store=store, top_k=5
+))
+pipeline.connect("embedder.embedding", "retriever.query_embedding")
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: IBMDb2DocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the IBMDb2EmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>IBMDb2DocumentStore</code>) – An instance of `IBMDb2DocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>TypeError</code> – If `document_store` is not an instance of `IBMDb2DocumentStore`.
+
+#### run
+
+```python
+run(
+    query_embedding: list[float],
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None,
+) -> dict[str, list[Document]]
+```
+
+Retrieve documents by vector similarity.
+
+**Parameters:**
+
+- **query_embedding** (<code>list\[float\]</code>) – Dense float vector from an embedder component.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Runtime filters, merged with constructor filters according to filter_policy.
+- **top_k** (<code>int | None</code>) – Override the constructor top_k for this call.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with key `documents` containing a list of matching :class:`Document` objects.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> IBMDb2EmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>IBMDb2EmbeddingRetriever</code> – Deserialized component.
+
+## haystack_integrations.document_stores.ibm_db.document_store
+
+IBM Db2 Document Store for Haystack.
+
+### IBMDb2DocumentStore
+
+IBM Db2 Document Store for Haystack using vector search capabilities.
+
+This document store uses IBM Db2's native vector search functionality
+to store and retrieve documents with embeddings.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    database: str,
+    hostname: str,
+    username: Secret = Secret.from_env_var("DB2_USERNAME"),
+    password: Secret = Secret.from_env_var("DB2_PASSWORD"),
+    port: int = 50000,
+    protocol: str = "TCPIP",
+    schema: str | None = None,
+    use_ssl: bool = False,
+    ssl_certificate: str | None = None,
+    connection_options: dict[str, Any] | None = None,
+    table_name: str = "haystack_documents",
+    embedding_dim: int = 768,
+    distance_metric: Literal["EUCLIDEAN", "COSINE", "MANHATTAN"] = "COSINE",
+    recreate_table: bool = False
+)
+```
+
+Initialize the IBM Db2 Document Store.
+
+**Parameters:**
+
+- **database** (<code>str</code>) – Database name
+- **hostname** (<code>str</code>) – Database server hostname
+- **username** (<code>Secret</code>) – Database username as a `Secret`, e.g. `Secret.from_env_var("DB2_USERNAME")`.
+- **password** (<code>Secret</code>) – Database password as a `Secret`, e.g. `Secret.from_env_var("DB2_PASSWORD")`.
+- **port** (<code>int</code>) – Database server port (default: 50000)
+- **protocol** (<code>str</code>) – Connection protocol (default: "TCPIP")
+- **schema** (<code>str | None</code>) – Database schema (optional)
+- **use_ssl** (<code>bool</code>) – Enable SSL/TLS connection (default: False)
+- **ssl_certificate** (<code>str | None</code>) – Path to SSL certificate file (optional, required if use_ssl is True)
+- **connection_options** (<code>dict\[str, Any\] | None</code>) – Additional connection options as dict (optional)
+- **table_name** (<code>str</code>) – Name of the table to store documents (default: "haystack_documents")
+- **embedding_dim** (<code>int</code>) – Dimension of embedding vectors (default: 768)
+- **distance_metric** (<code>Literal['EUCLIDEAN', 'COSINE', 'MANHATTAN']</code>) – Distance metric for similarity search (default: "COSINE")
+- **recreate_table** (<code>bool</code>) – If True, drop and recreate the table (default: False)
+
+#### count_documents
+
+```python
+count_documents() -> int
+```
+
+Count all documents in the store.
+
+**Returns:**
+
+- <code>int</code> – Number of documents
+
+#### count_documents_by_filter
+
+```python
+count_documents_by_filter(filters: dict[str, Any] | None = None) -> int
+```
+
+Count documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters to apply. See Haystack documentation for filter syntax.
+
+**Returns:**
+
+- <code>int</code> – Number of documents matching the filters
+
+#### write_documents
+
+```python
+write_documents(
+    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+) -> int
+```
+
+Write documents to the store.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – List of documents to write
+- **policy** (<code>DuplicatePolicy</code>) – Policy for handling duplicate documents
+
+**Returns:**
+
+- <code>int</code> – Number of documents written
+
+**Raises:**
+
+- <code>ValueError</code> – If documents is not a list of Document objects or has invalid embeddings
+- <code>TypeError</code> – If embeddings have invalid types
+- <code>DuplicateDocumentError</code> – If a document with the same id already exists and policy is FAIL or NONE
+
+#### filter_documents
+
+```python
+filter_documents(filters: dict[str, Any] | None = None) -> list[Document]
+```
+
+Filter documents using SQL-based metadata and field conditions.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional filter dictionary to constrain the returned documents.
+
+**Returns:**
+
+- <code>list\[Document\]</code> – List of matching documents.
+
+#### delete_documents
+
+```python
+delete_documents(document_ids: list[str]) -> None
+```
+
+Delete documents by their IDs.
+
+**Parameters:**
+
+- **document_ids** (<code>list\[str\]</code>) – List of document IDs to delete
+
+#### delete_by_filter
+
+```python
+delete_by_filter(filters: dict[str, Any] | None = None) -> int
+```
+
+Delete documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters to apply. See Haystack documentation for filter syntax.
+
+**Returns:**
+
+- <code>int</code> – Number of documents deleted
+
+#### delete_all_documents
+
+```python
+delete_all_documents(recreate_index: bool = False) -> int
+```
+
+Delete all documents from the document store.
+
+**Parameters:**
+
+- **recreate_index** (<code>bool</code>) – If True, recreate the table after deletion
+
+**Returns:**
+
+- <code>int</code> – Number of documents deleted
+
+#### update_by_filter
+
+```python
+update_by_filter(
+    filters: dict[str, Any] | None = None, meta: dict[str, Any] | None = None
+) -> int
+```
+
+Update documents that match the provided filters.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters to apply. See Haystack documentation for filter syntax.
+- **meta** (<code>dict\[str, Any\] | None</code>) – Dictionary of metadata fields to update
+
+**Returns:**
+
+- <code>int</code> – Number of documents updated
+
+#### get_metadata_field_unique_values
+
+```python
+get_metadata_field_unique_values(field: str) -> list[Any]
+```
+
+Get all unique values for a given metadata field.
+
+**Parameters:**
+
+- **field** (<code>str</code>) – The metadata field name (can include 'meta.' prefix)
+
+**Returns:**
+
+- <code>list\[Any\]</code> – List of unique values for the field
+
+#### get_metadata_field_min_max
+
+```python
+get_metadata_field_min_max(field: str) -> dict[str, Any]
+```
+
+Get the minimum and maximum values for a numeric metadata field.
+
+**Parameters:**
+
+- **field** (<code>str</code>) – The metadata field name (can include 'meta.' prefix)
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with 'min' and 'max' keys
+
+#### get_metadata_fields_info
+
+```python
+get_metadata_fields_info() -> dict[str, dict[str, Any]]
+```
+
+Get information about all metadata fields including their types.
+
+**Returns:**
+
+- <code>dict\[str, dict\[str, Any\]\]</code> – Dictionary mapping field names to their type information
+
+#### count_unique_metadata_by_filter
+
+```python
+count_unique_metadata_by_filter(
+    filters: dict[str, Any] | None = None,
+    metadata_fields: list[str] | None = None,
+) -> dict[str, int]
+```
+
+Count unique values for specified metadata fields, optionally filtered.
+
+**Parameters:**
+
+- **filters** (<code>dict\[str, Any\] | None</code>) – Optional filters to apply before counting
+- **metadata_fields** (<code>list\[str\] | None</code>) – List of metadata field names to count unique values for
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – Dictionary mapping field names to their unique value counts
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the document store to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary representation
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> IBMDb2DocumentStore
+```
+
+Deserialize the document store from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary representation
+
+**Returns:**
+
+- <code>IBMDb2DocumentStore</code> – IBMDb2DocumentStore instance

docs-website/reference_versioned_docs/version-2.22/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.22/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.22/integrations-api/langdetect.md

@@ -0,0 +1,163 @@
+---
+title: "Langdetect"
+id: integrations-langdetect
+description: "Langdetect integration for Haystack"
+slug: "/integrations-langdetect"
+---
+
+
+## haystack_integrations.components.classifiers.langdetect.document_language_classifier
+
+### DocumentLanguageClassifier
+
+Classifies the language of each document and adds it to its metadata.
+
+Provide a list of languages during initialization. If the document's text doesn't match any of the
+specified languages, the metadata value is set to "unmatched".
+To route documents based on their language, use the MetadataRouter component after DocumentLanguageClassifier.
+For routing plain text, use the TextLanguageRouter component instead.
+
+### Usage example
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.classifiers.langdetect import DocumentLanguageClassifier
+from haystack.components.routers import MetadataRouter
+from haystack.components.writers import DocumentWriter
+
+docs = [Document(id="1", content="This is an English document"),
+        Document(id="2", content="Este es un documento en español")]
+
+document_store = InMemoryDocumentStore()
+
+p = Pipeline()
+p.add_component(instance=DocumentLanguageClassifier(languages=["en"]), name="language_classifier")
+p.add_component(
+instance=MetadataRouter(rules={
+    "en": {
+        "field": "meta.language",
+        "operator": "==",
+        "value": "en"
+    }
+}),
+name="router")
+p.add_component(instance=DocumentWriter(document_store=document_store), name="writer")
+p.connect("language_classifier.documents", "router.documents")
+p.connect("router.en", "writer.documents")
+
+p.run({"language_classifier": {"documents": docs}})
+
+written_docs = document_store.filter_documents()
+assert len(written_docs) == 1
+assert written_docs[0] == Document(id="1", content="This is an English document", meta={"language": "en"})
+```
+
+#### __init__
+
+```python
+__init__(languages: list[str] | None = None) -> None
+```
+
+Initializes the DocumentLanguageClassifier component.
+
+**Parameters:**
+
+- **languages** (<code>list\[str\] | None</code>) – A list of ISO language codes.
+  See the supported languages in [`langdetect` documentation](https://github.com/Mimino666/langdetect#languages).
+  If not specified, defaults to ["en"].
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, list[Document]]
+```
+
+Classifies the language of each document and adds it to its metadata.
+
+If the document's text doesn't match any of the languages specified at initialization,
+sets the metadata value to "unmatched".
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – A list of documents for language classification.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following key:
+- `documents`: A list of documents with an added `language` metadata field.
+
+**Raises:**
+
+- <code>TypeError</code> – if the input is not a list of Documents.
+
+## haystack_integrations.components.routers.langdetect.text_language_router
+
+### TextLanguageRouter
+
+Routes text strings to different output connections based on their language.
+
+Provide a list of languages during initialization. If the document's text doesn't match any of the
+specified languages, the metadata value is set to "unmatched".
+For routing documents based on their language, use the DocumentLanguageClassifier component,
+followed by the MetaDataRouter.
+
+### Usage example
+
+```python
+from haystack import Pipeline, Document
+from haystack_integrations.components.routers.langdetect import TextLanguageRouter
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+
+document_store = InMemoryDocumentStore()
+document_store.write_documents([Document(content="Elvis Presley was an American singer and actor.")])
+
+p = Pipeline()
+p.add_component(instance=TextLanguageRouter(languages=["en"]), name="text_language_router")
+p.add_component(instance=InMemoryBM25Retriever(document_store=document_store), name="retriever")
+p.connect("text_language_router.en", "retriever.query")
+
+result = p.run({"text_language_router": {"text": "Who was Elvis Presley?"}})
+assert result["retriever"]["documents"][0].content == "Elvis Presley was an American singer and actor."
+
+result = p.run({"text_language_router": {"text": "ένα ελληνικό κείμενο"}})
+assert result["text_language_router"]["unmatched"] == "ένα ελληνικό κείμενο"
+```
+
+#### __init__
+
+```python
+__init__(languages: list[str] | None = None) -> None
+```
+
+Initialize the TextLanguageRouter component.
+
+**Parameters:**
+
+- **languages** (<code>list\[str\] | None</code>) – A list of ISO language codes.
+  See the supported languages in [`langdetect` documentation](https://github.com/Mimino666/langdetect#languages).
+  If not specified, defaults to ["en"].
+
+#### run
+
+```python
+run(text: str) -> dict[str, str]
+```
+
+Routes the text strings to different output connections based on their language.
+
+If the document's text doesn't match any of the specified languages, the metadata value is set to "unmatched".
+
+**Parameters:**
+
+- **text** (<code>str</code>) – A text string to route.
+
+**Returns:**
+
+- <code>dict\[str, str\]</code> – A dictionary in which the key is the language (or `"unmatched"`),
+  and the value is the text.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.

docs-website/reference_versioned_docs/version-2.22/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.22/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.22/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.22/integrations-api/litellm.md

@@ -0,0 +1,138 @@
+---
+title: "LiteLLM"
+id: integrations-litellm
+description: "LiteLLM integration for Haystack"
+slug: "/integrations-litellm"
+---
+
+
+## haystack_integrations.components.generators.litellm.chat.chat_generator
+
+### LiteLLMChatGenerator
+
+Completes chats using any of 100+ LLM providers via LiteLLM.
+
+LiteLLM routes to OpenAI, Anthropic, Google, AWS Bedrock, Azure, Cohere,
+Mistral, Groq, and many more through a single unified interface.
+
+Model names use LiteLLM format: `provider/model-name`, e.g.
+`anthropic/claude-sonnet-4-20250514`, `openai/gpt-4o`,
+`bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0`.
+
+See https://docs.litellm.ai/docs/providers for the full list.
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.litellm import LiteLLMChatGenerator
+from haystack.dataclasses import ChatMessage
+
+generator = LiteLLMChatGenerator(
+    model="anthropic/claude-sonnet-4-20250514",
+    generation_kwargs={"max_tokens": 1024, "temperature": 0.7},
+)
+
+messages = [
+    ChatMessage.from_system("You are a helpful assistant"),
+    ChatMessage.from_user("What's Natural Language Processing?"),
+]
+result = generator.run(messages=messages)
+print(result["replies"][0].text)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret | None = None,
+    model: str = "openai/gpt-4o",
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: str | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    tools: ToolsType | None = None
+) -> None
+```
+
+Create a LiteLLMChatGenerator instance.
+
+**Parameters:**
+
+- **api_key** (<code>Secret | None</code>) – The API key for the provider. Optional: when not set, LiteLLM resolves
+  credentials itself from the provider's standard environment variable
+  (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`). Pass a `Secret` only
+  when you want Haystack to manage and serialize the key explicitly.
+- **model** (<code>str</code>) – The model name in LiteLLM format (provider/model-name).
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function invoked with each new StreamingChunk.
+- **api_base_url** (<code>str | None</code>) – Custom API base URL (e.g. for a self-hosted LiteLLM proxy).
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional parameters passed to litellm.completion().
+  See https://docs.litellm.ai/docs/completion/input for details.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool / Toolset objects the model can prepare calls for.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage] | str,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Invoke chat completion via LiteLLM.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\] | str</code>) – Input messages as ChatMessage instances.
+  If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – Override the streaming callback for this call.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Override generation parameters for this call.
+- **tools** (<code>ToolsType | None</code>) – Override tools for this call.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dict with key `replies` containing ChatMessage instances.
+
+#### run_async
+
+```python
+run_async(
+    messages: list[ChatMessage] | str,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    tools: ToolsType | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Async version of run(). Invoke chat completion via LiteLLM.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\] | str</code>) – Input messages as ChatMessage instances.
+  If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – Override the streaming callback for this call.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Override generation parameters for this call.
+- **tools** (<code>ToolsType | None</code>) – Override tools for this call.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dict with key `replies` containing ChatMessage instances.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> LiteLLMChatGenerator
+```
+
+Deserialize a component from a dictionary.

docs-website/reference_versioned_docs/version-2.22/integrations-api/llama_cpp.md

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

docs-website/reference_versioned_docs/version-2.22/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.22/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.22/integrations-api/mcp.md

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

docs-website/reference_versioned_docs/version-2.22/integrations-api/mem0.md

@@ -0,0 +1,589 @@
+---
+title: "Mem0"
+id: integrations-mem0
+description: "Mem0 integration for Haystack"
+slug: "/integrations-mem0"
+---
+
+
+## haystack_integrations.components.retrievers.mem0.retriever
+
+### Mem0MemoryRetriever
+
+Retrieves memories from a Mem0MemoryStore as a list of ChatMessage objects.
+
+Use this component in a Haystack Pipeline to fetch relevant memories before passing
+context to a language model or Agent. The returned memories are system messages.
+
+Provide either `filters` or at least one Mem0 entity ID (`user_id`, `run_id`, `agent_id`, or `app_id`)
+when running the component. If both are provided, the filters and entity IDs are combined.
+
+### Usage example
+
+```python
+from haystack_integrations.components.retrievers.mem0 import Mem0MemoryRetriever
+from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+
+store = Mem0MemoryStore()
+retriever = Mem0MemoryRetriever(memory_store=store, top_k=3)
+
+result = retriever.run(query="What does Alice like?", user_id="alice")
+memories = result["memories"]
+print([message.text for message in memories])
+
+# Pass query=None to retrieve all memories in scope.
+all_memories = retriever.run(query=None, user_id="alice")["memories"]
+```
+
+#### __init__
+
+```python
+__init__(*, memory_store: Mem0MemoryStore, top_k: int = 5) -> None
+```
+
+Initialize the Mem0MemoryRetriever.
+
+**Parameters:**
+
+- **memory_store** (<code>Mem0MemoryStore</code>) – The Mem0MemoryStore instance to retrieve memories from.
+- **top_k** (<code>int</code>) – Default maximum number of memories to return per query.
+
+#### run
+
+```python
+run(
+    query: str | None,
+    *,
+    user_id: str | None = None,
+    run_id: str | None = None,
+    agent_id: str | None = None,
+    app_id: str | None = None,
+    filters: dict[str, Any] | None = None,
+    top_k: int | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Retrieve memories matching the query from Mem0.
+
+**Parameters:**
+
+- **query** (<code>str | None</code>) – Text query used to search for relevant memories. Pass `None` to retrieve all memories matching
+  the scope.
+- **user_id** (<code>str | None</code>) – User ID to scope the search.
+- **run_id** (<code>str | None</code>) – Run ID to scope the search.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope the search.
+- **app_id** (<code>str | None</code>) – App ID to scope the search.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Haystack-style filters to apply. When provided with ID parameters, they are combined.
+  Mem0 requires entity IDs inside filters and supports a fixed set of native fields and operators:
+  [Search Memories API](https://docs.mem0.ai/api-reference/memory/search-memories) and
+  [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters). Fields that are not native
+  Mem0 filter fields are treated as Mem0 metadata fields.
+- **top_k** (<code>int | None</code>) – Maximum number of memories to return. Overrides the init-time default.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – Dictionary with key `memories` containing a list of ChatMessage objects. User-provided
+  Mem0 metadata is included in each message's meta. Mem0 retrieval fields such as `memory_id`, `user_id`,
+  `score`, and timestamps are included under `meta["mem0"]`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Mem0MemoryRetriever
+```
+
+Deserialize this component from a dictionary.
+
+## haystack_integrations.components.writers.mem0.writer
+
+### Mem0MemoryWriter
+
+Writes ChatMessage objects as memories to a Mem0MemoryStore.
+
+Use this component in a Haystack Pipeline to persist conversation messages.
+Scoping IDs (`user_id`, `run_id`, `agent_id`, `app_id`) are runtime parameters so the
+same pipeline instance can serve multiple users or agents. The `infer` setting controls whether
+Mem0 extracts memories from messages or stores message text as-is.
+
+### Usage example
+
+```python
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.writers.mem0 import Mem0MemoryWriter
+from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+
+store = Mem0MemoryStore()
+writer = Mem0MemoryWriter(memory_store=store, infer=False)
+
+result = writer.run(
+    messages=[ChatMessage.from_user("Alice prefers concise Python examples.")],
+    user_id="alice",
+)
+print(result["memories_written"])
+```
+
+#### __init__
+
+```python
+__init__(*, memory_store: Mem0MemoryStore, infer: bool = True) -> None
+```
+
+Initialize the Mem0MemoryWriter.
+
+**Parameters:**
+
+- **memory_store** (<code>Mem0MemoryStore</code>) – The Mem0MemoryStore instance to write memories to.
+- **infer** (<code>bool</code>) – If True, Mem0 extracts memories from messages. If False, Mem0 stores message text as-is.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage],
+    *,
+    user_id: str | None = None,
+    run_id: str | None = None,
+    agent_id: str | None = None,
+    app_id: str | None = None
+) -> dict[str, int]
+```
+
+Write messages as memories to the Mem0 store.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – List of ChatMessage objects to store.
+- **user_id** (<code>str | None</code>) – User ID to scope the stored memories.
+- **run_id** (<code>str | None</code>) – Run ID to scope the stored memories.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope the stored memories.
+- **app_id** (<code>str | None</code>) – App ID to scope the stored memories.
+
+**Returns:**
+
+- <code>dict\[str, int\]</code> – Dictionary with key `memories_written` containing the count of stored memory items.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Mem0MemoryWriter
+```
+
+Deserialize this component from a dictionary.
+
+## haystack_integrations.memory_stores.mem0.errors
+
+### Mem0MemoryStoreError
+
+Bases: <code>RuntimeError</code>
+
+Raised when a Mem0 API operation fails.
+
+## haystack_integrations.memory_stores.mem0.memory_store
+
+### Mem0MemoryStore
+
+A memory store backed by the Mem0 cloud API.
+
+Stores and retrieves ChatMessage-based memories scoped by user_id, run_id, agent_id, or app_id.
+The Mem0 client is created lazily on first use (or explicitly via warm_up()).
+Requires a Mem0 API key set via the MEM0_API_KEY environment variable or passed explicitly.
+
+#### __init__
+
+```python
+__init__(*, api_key: Secret = Secret.from_env_var('MEM0_API_KEY')) -> None
+```
+
+Initialize the Mem0 memory store.
+
+The Mem0 client is not created until warm_up() is called (or the first method that
+needs the client is invoked).
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The Mem0 API key. Defaults to the MEM0_API_KEY environment variable.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Create the Mem0 client. Called automatically on first use if not called explicitly.
+
+Calling this method explicitly is useful when you want to validate the API key
+or pre-connect before the first pipeline run.
+
+#### client
+
+```python
+client: MemoryClient
+```
+
+Return the initialized client, calling warm_up() if necessary.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the store configuration to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Mem0MemoryStore
+```
+
+Deserialize the store from a dictionary.
+
+#### add_memories
+
+```python
+add_memories(
+    *,
+    messages: list[ChatMessage],
+    user_id: str | None = None,
+    run_id: str | None = None,
+    agent_id: str | None = None,
+    app_id: str | None = None,
+    infer: bool = True,
+    **kwargs: Any
+) -> list[dict[str, Any]]
+```
+
+Add ChatMessage memories to Mem0.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – List of ChatMessage objects to store as memories.
+- **user_id** (<code>str | None</code>) – User ID to scope these memories.
+- **run_id** (<code>str | None</code>) – Run ID to scope these memories.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope these memories. Required for Mem0 to store assistant messages.
+- **app_id** (<code>str | None</code>) – App ID to scope these memories.
+- **infer** (<code>bool</code>) – If True, Mem0 extracts memories from messages. If False, Mem0 stores message text as-is.
+- **kwargs** (<code>Any</code>) – Additional keyword arguments forwarded to the Mem0 client add method.
+  Note: ChatMessage.meta is ignored because Mem0 doesn't support per-message metadata.
+  Pass `metadata` as a kwarg to attach metadata to the whole batch instead.
+
+**Returns:**
+
+- <code>list\[dict\[str, Any\]\]</code> – List of objects with `memory_id` and `memory` text for each stored memory.
+
+**Raises:**
+
+- <code>Mem0MemoryStoreError</code> – If the Mem0 API call fails.
+
+#### search_memories
+
+```python
+search_memories(
+    *,
+    query: str | None = None,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 5,
+    user_id: str | None = None,
+    run_id: str | None = None,
+    agent_id: str | None = None,
+    app_id: str | None = None,
+    **kwargs: Any
+) -> list[ChatMessage]
+```
+
+Search for memories in Mem0.
+
+Either `filters` or at least one of `user_id`, `run_id`, `agent_id`, or `app_id` must be provided.
+When both `filters` and IDs are provided, they are combined with an `AND` condition.
+
+**Parameters:**
+
+- **query** (<code>str | None</code>) – Text query to search. If omitted, returns all memories matching the scope.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Haystack-style filters to apply. See
+  [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+  Mem0 requires entity IDs inside filters and supports a fixed set of native fields and operators:
+  [Search Memories API](https://docs.mem0.ai/api-reference/memory/search-memories) and
+  [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters).
+  Fields that are not native Mem0 filter fields are treated as Mem0 metadata fields.
+- **top_k** (<code>int</code>) – Maximum number of results to return.
+- **user_id** (<code>str | None</code>) – User ID to scope the search.
+- **run_id** (<code>str | None</code>) – Run ID to scope the search.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope the search.
+- **app_id** (<code>str | None</code>) – App ID to scope the search.
+- **kwargs** (<code>Any</code>) – Additional keyword arguments forwarded to the Mem0 client.
+
+**Returns:**
+
+- <code>list\[ChatMessage\]</code> – List of ChatMessage (system role) objects containing the retrieved memories. User-provided
+  Mem0 metadata is included in each message's meta. Mem0 retrieval fields such as `memory_id`, `user_id`,
+  `score`, and timestamps are included under `meta["mem0"]`.
+
+**Raises:**
+
+- <code>Mem0MemoryStoreError</code> – If the Mem0 API call fails.
+
+## haystack_integrations.tools.mem0.retriever_tool
+
+### Mem0MemoryRetrieverTool
+
+Bases: <code>Tool</code>
+
+A tool that searches a Mem0MemoryStore for memories.
+
+The `user_id` is injected at runtime from Agent State via `inputs_from_state`,
+so a single tool instance can serve many users. The LLM only sees `query` and `top_k` by default.
+If the LLM omits `query` or passes `None`, Mem0 returns all memories matching the injected scope.
+Pass a custom `inputs_from_state` mapping to inject other supported Mem0 entity IDs such as
+`run_id`, `agent_id`, or `app_id`. The mapping keys are Agent State keys and the values are this
+tool's parameter names. For example, use
+`inputs_from_state={"user_id": "user_id", "session_id": "run_id"}` to pass `state["session_id"]`
+to the tool's `run_id` parameter at runtime.
+
+### Usage example
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+from haystack_integrations.tools.mem0 import Mem0MemoryRetrieverTool
+
+store = Mem0MemoryStore()
+retrieve_memories = Mem0MemoryRetrieverTool(memory_store=store, top_k=5)
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+    tools=[retrieve_memories],
+    state_schema={"user_id": {"type": str}, "session_id": {"type": str}},
+)
+
+# The Agent can call retrieve_memories with a query for targeted recall,
+# or without a query when it needs all scoped memories.
+result = agent.run(
+    messages=[ChatMessage.from_user("What do you remember about me?")],
+    user_id="alice",
+    session_id="chat-42",
+)
+print(result["last_message"].text)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    memory_store: Mem0MemoryStore,
+    top_k: int = 5,
+    name: str = "retrieve_memories",
+    description: str = _DEFAULT_DESCRIPTION,
+    parameters: dict[str, Any] = _PARAMETERS,
+    inputs_from_state: dict[str, str] = _DEFAULT_INPUTS_FROM_STATE
+) -> None
+```
+
+Initialize the Mem0MemoryRetrieverTool.
+
+**Parameters:**
+
+- **memory_store** (<code>Mem0MemoryStore</code>) – The Mem0MemoryStore instance to query.
+- **top_k** (<code>int</code>) – Default maximum number of memories to return. The LLM may override this.
+- **name** (<code>str</code>) – Tool name exposed to the LLM.
+- **description** (<code>str</code>) – Tool description exposed to the LLM.
+- **parameters** (<code>dict\[str, Any\]</code>) – JSON schema for the parameters exposed to the LLM. Defaults to optional `query` and `top_k`.
+- **inputs_from_state** (<code>dict\[str, str\]</code>) – Mapping from Agent State keys to this tool's parameter names.
+  Defaults to `{"user_id": "user_id"}`, which injects `state["user_id"]` into the `user_id`
+  parameter. To pass more Mem0 IDs at runtime, add the state fields to the Agent's
+  `state_schema` and map them to the corresponding tool parameters, for example
+  `{"user_id": "user_id", "session_id": "run_id", "agent_name": "agent_id", "app_name": "app_id"}`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Mem0 client. Subsequent calls are no-ops.
+
+#### retrieve
+
+```python
+retrieve(
+    query: str | None = None,
+    *,
+    top_k: int | None = None,
+    user_id: str | None = None,
+    run_id: str | None = None,
+    agent_id: str | None = None,
+    app_id: str | None = None
+) -> str
+```
+
+Retrieve memories relevant to a query, or all memories when no query is provided.
+
+**Parameters:**
+
+- **query** (<code>str | None</code>) – Text query used to search for relevant memories. If omitted or `None`, all memories matching
+  the scope are returned.
+- **top_k** (<code>int | None</code>) – Maximum number of memories to return for query searches. Overrides the tool default.
+- **user_id** (<code>str | None</code>) – User ID to scope the search. Injected from Agent State by default.
+- **run_id** (<code>str | None</code>) – Run ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+- **app_id** (<code>str | None</code>) – App ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+
+**Returns:**
+
+- <code>str</code> – Retrieved memories formatted for the Agent, or a message when no memories were found.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Mem0MemoryRetrieverTool
+```
+
+Deserialize this tool from a dictionary.
+
+## haystack_integrations.tools.mem0.writer_tool
+
+### Mem0MemoryWriterTool
+
+Bases: <code>Tool</code>
+
+A tool that writes a memory to a Mem0MemoryStore.
+
+The `user_id` is injected at runtime from Agent State via `inputs_from_state`,
+so a single tool instance can serve many users. The LLM only sees `text` and `infer`.
+Pass a custom `inputs_from_state` mapping to inject other supported Mem0 entity IDs such as
+`run_id`, `agent_id`, or `app_id`. The mapping keys are Agent State keys and the values are this
+tool's parameter names. For example, use
+`inputs_from_state={"user_id": "user_id", "session_id": "run_id"}` to pass `state["session_id"]`
+to the tool's `run_id` parameter at runtime.
+
+### Usage example
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+from haystack_integrations.tools.mem0 import Mem0MemoryWriterTool
+
+store = Mem0MemoryStore()
+store_memory = Mem0MemoryWriterTool(memory_store=store)
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+    tools=[store_memory],
+    state_schema={"user_id": {"type": str}, "session_id": {"type": str}},
+)
+
+result = agent.run(
+    messages=[ChatMessage.from_user("Remember that I prefer concise Python examples.")],
+    user_id="alice",
+    session_id="chat-42",
+)
+print(result["last_message"].text)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    memory_store: Mem0MemoryStore,
+    name: str = "store_memory",
+    description: str = _DEFAULT_DESCRIPTION,
+    parameters: dict[str, Any] = _PARAMETERS,
+    inputs_from_state: dict[str, str] = _DEFAULT_INPUTS_FROM_STATE
+) -> None
+```
+
+Initialize the Mem0MemoryWriterTool.
+
+**Parameters:**
+
+- **memory_store** (<code>Mem0MemoryStore</code>) – The Mem0MemoryStore instance to write to.
+- **name** (<code>str</code>) – Tool name exposed to the LLM.
+- **description** (<code>str</code>) – Tool description exposed to the LLM.
+- **parameters** (<code>dict\[str, Any\]</code>) – JSON schema for the parameters exposed to the LLM. Defaults to `text` and `infer`.
+- **inputs_from_state** (<code>dict\[str, str\]</code>) – Mapping from Agent State keys to this tool's parameter names.
+  Defaults to `{"user_id": "user_id"}`, which injects `state["user_id"]` into the `user_id`
+  parameter. To pass more Mem0 IDs at runtime, add the state fields to the Agent's
+  `state_schema` and map them to the corresponding tool parameters, for example
+  `{"user_id": "user_id", "session_id": "run_id", "agent_name": "agent_id", "app_name": "app_id"}`.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initialize the Mem0 client. Subsequent calls are no-ops.
+
+#### store
+
+```python
+store(
+    text: str,
+    *,
+    infer: bool = False,
+    user_id: str | None = None,
+    run_id: str | None = None,
+    agent_id: str | None = None,
+    app_id: str | None = None
+) -> str
+```
+
+Store text as a memory.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – The information to store as a memory.
+- **infer** (<code>bool</code>) – If True, Mem0 extracts memories from the text. If False, Mem0 stores the text as-is.
+- **user_id** (<code>str | None</code>) – User ID to scope the stored memory. Injected from Agent State by default.
+- **run_id** (<code>str | None</code>) – Run ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+- **agent_id** (<code>str | None</code>) – Agent ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+- **app_id** (<code>str | None</code>) – App ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+
+**Returns:**
+
+- <code>str</code> – A string indicating how many memory items were stored.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this tool to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> Mem0MemoryWriterTool
+```
+
+Deserialize this tool from a dictionary.

docs-website/reference_versioned_docs/version-2.22/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.22/integrations-api/microsoft_sharepoint.md

@@ -0,0 +1,341 @@
+---
+title: "Microsoft SharePoint"
+id: integrations-microsoft-sharepoint
+description: "Microsoft SharePoint integration for Haystack"
+slug: "/integrations-microsoft-sharepoint"
+---
+
+
+## haystack_integrations.components.fetchers.microsoft_sharepoint.fetcher
+
+### MSSharePointFetcher
+
+Fetches the full content of Microsoft SharePoint and OneDrive items via the Microsoft Graph API.
+
+The fetcher complements `MSSharePointRetriever`, which only returns Search snippets and metadata. Wire the
+retriever's `documents` (or a list of `web_url`s) into this fetcher to download the full content. It
+dispatches on the entity type of each hit and always returns `ByteStream`s, ready for a downstream converter
+(for example a `FileTypeRouter` in front of `PyPDFToDocument`, `DOCXToDocument`, `HTMLToDocument`, or a JSON
+converter):
+
+- **Files** (`driveItem`) are downloaded as their raw bytes (PDF, DOCX, ...).
+- **List items** (`listItem`) are returned as a JSON `ByteStream` of the item's column values (`fields`).
+- **SharePoint pages** (`sitePage`) are returned as an HTML `ByteStream` built from the page's web parts.
+
+Each `ByteStream`'s `meta` carries `url`, `file_name`, `content_type`, and a normalized `entity_type`
+(`driveItem`, `listItem`, or `sitePage`).
+
+Everything is resolved through the Microsoft Graph `shares` endpoint (plus the Pages API for pages), so only
+the `web_url` already exposed by the retriever is needed. The fetcher takes a per-user `access_token` as a run
+input, typically wired from an upstream `OAuthTokenResolver`. The token must carry delegated Microsoft Graph
+permissions (for example `Files.Read.All` for files and `Sites.Read.All` for list items and pages).
+
+### Usage example
+
+```python
+from haystack_integrations.components.fetchers.microsoft_sharepoint import MSSharePointFetcher
+
+fetcher = MSSharePointFetcher()
+
+# `access_token` is a per-user delegated Microsoft Graph bearer token.
+result = fetcher.run(
+    access_token="my-delegated-graph-token",
+    targets=["https://contoso.sharepoint.com/sites/contoso-team/contoso-designs.docx"],
+)
+streams = result["streams"]
+```
+
+In a pipeline, connect `MSSharePointRetriever.documents` to the fetcher's `targets` input and an upstream
+component that emits a per-user `access_token` to the fetcher's `access_token` input.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    graph_url: str = DEFAULT_GRAPH_URL,
+    timeout: float = 30.0,
+    max_retries: int = 3,
+    max_concurrent_requests: int = 5,
+    raise_on_failure: bool = True
+) -> None
+```
+
+Initialize the fetcher.
+
+**Parameters:**
+
+- **graph_url** (<code>str</code>) – The Microsoft Graph base URL. Defaults to `https://graph.microsoft.com/v1.0`.
+  Override for sovereign clouds.
+- **timeout** (<code>float</code>) – The HTTP timeout in seconds for each request to Microsoft Graph.
+- **max_retries** (<code>int</code>) – The maximum number of retries for throttled (HTTP 429) or transient server errors.
+- **max_concurrent_requests** (<code>int</code>) – The maximum number of items fetched concurrently by `run_async`. Bounds
+  the in-flight requests to Microsoft Graph to avoid tripping its rate limits. Has no effect on the
+  synchronous `run`, which fetches items one at a time.
+- **raise_on_failure** (<code>bool</code>) – If `True`, a fetch failure raises an exception. If `False`, the failure is
+  logged and the item is skipped, so the other items are still returned.
+
+**Raises:**
+
+- <code>SharePointConfigError</code> – If `max_retries` is negative or `max_concurrent_requests` is not positive.
+
+#### run
+
+```python
+run(
+    access_token: str | Secret, targets: list[Document | str]
+) -> dict[str, list[ByteStream]]
+```
+
+Fetch the content of SharePoint and OneDrive items and return them as `ByteStream`s.
+
+**Parameters:**
+
+- **access_token** (<code>str | Secret</code>) – A delegated Microsoft Graph bearer token for the user whose content is fetched,
+  typically wired from an upstream `OAuthTokenResolver` (which emits a plain `str`). A `Secret` is also
+  accepted and resolved internally.
+- **targets** (<code>list\[Document | str\]</code>) – The items to fetch, as either `Document`s emitted by `MSSharePointRetriever` or raw
+  SharePoint/OneDrive `web_url` strings (the two may also be mixed in one list). For a `Document`, the
+  `web_url` in its meta is fetched and `file_name`, `mime_type`, `entity_type`, and the SharePoint IDs
+  are reused when present; container hits with no extractable content (for example `site` or `list`) are
+  skipped. For a raw URL, the item is probed as a file and falls back to a list item.
+
+**Returns:**
+
+- <code>dict\[str, list\[ByteStream\]\]</code> – A dictionary with a `streams` key holding the fetched content as `ByteStream` objects. Each
+  stream's `meta` carries `url`, `file_name`, `content_type`, and `entity_type`.
+
+**Raises:**
+
+- <code>SharePointConfigError</code> – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+  `Secret` that does not resolve to a string.
+- <code>SharePointRequestError</code> – If a fetch fails and `raise_on_failure` is `True`.
+
+#### run_async
+
+```python
+run_async(
+    access_token: str | Secret, targets: list[Document | str]
+) -> dict[str, list[ByteStream]]
+```
+
+Asynchronously fetch the content of SharePoint and OneDrive items and return them as `ByteStream`s.
+
+**Parameters:**
+
+- **access_token** (<code>str | Secret</code>) – A delegated Microsoft Graph bearer token for the user whose content is fetched,
+  typically wired from an upstream `OAuthTokenResolver` (which emits a plain `str`). A `Secret` is also
+  accepted and resolved internally.
+- **targets** (<code>list\[Document | str\]</code>) – The items to fetch, as either `Document`s emitted by `MSSharePointRetriever` or raw
+  SharePoint/OneDrive `web_url` strings (the two may also be mixed in one list). For a `Document`, the
+  `web_url` in its meta is fetched and `file_name`, `mime_type`, `entity_type`, and the SharePoint IDs
+  are reused when present; container hits with no extractable content (for example `site` or `list`) are
+  skipped. For a raw URL, the item is probed as a file and falls back to a list item.
+
+**Returns:**
+
+- <code>dict\[str, list\[ByteStream\]\]</code> – A dictionary with a `streams` key holding the fetched content as `ByteStream` objects. Each
+  stream's `meta` carries `url`, `file_name`, `content_type`, and `entity_type`.
+
+**Raises:**
+
+- <code>SharePointConfigError</code> – If an item is neither a `Document` nor a `str`, or if `access_token` is a
+  `Secret` that does not resolve to a string.
+- <code>SharePointRequestError</code> – If a fetch fails and `raise_on_failure` is `True`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MSSharePointFetcher
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>MSSharePointFetcher</code> – The deserialized component instance.
+
+## haystack_integrations.components.retrievers.microsoft_sharepoint.retriever
+
+### MSSharePointRetriever
+
+Retrieves content from Microsoft SharePoint and OneDrive via the Microsoft Search (Graph) API.
+
+Given a query, the retriever calls `POST /search/query` and maps each hit to a Haystack `Document`
+whose `content` is the search snippet and whose `meta` carries the resource metadata (`file_name`,
+`web_url`, `entity_type`, `created_date_time`, `last_modified_date_time`, `created_by`, `last_modified_by`,
+`mime_type`, and `file_extension`), plus the SharePoint identifiers a downstream fetcher needs to read
+list items and pages by ID (`site_id`, `list_id`, `list_item_id`, `list_item_unique_id`). It does not
+download or convert the underlying files. Compose a downstream fetcher/converter (such as
+`MSSharePointFetcher`) when full content is needed.
+
+The retriever takes a per-user `access_token` as a run input, typically wired
+from an upstream `OAuthResolver`. The token must carry delegated Microsoft Graph permissions
+(for example `Files.Read.All` and, for site/list scoping, `Sites.Read.All`). The Search API supports
+delegated permissions only.
+
+### Usage example
+
+```python
+from haystack_integrations.components.retrievers.microsoft_sharepoint import (
+    MSSharePointRetriever,
+)
+
+retriever = MSSharePointRetriever(top_k=5)
+
+# `access_token` is a per-user delegated Microsoft Graph bearer token.
+result = retriever.run(
+    query="quarterly roadmap", access_token="my-delegated-graph-token"
+)
+documents = result["documents"]
+```
+
+In a pipeline, connect an upstream component that emits a per-user `access_token` to the retriever's
+`access_token` input. See the integration documentation for a full example that obtains the token from
+an OAuth provider.
+
+#### __init__
+
+```python
+__init__(
+    *,
+    entity_types: list[str] | None = None,
+    top_k: int = 10,
+    fields: list[str] | None = None,
+    query_template: str | None = None,
+    graph_url: str = DEFAULT_GRAPH_URL,
+    timeout: float = 30.0,
+    max_retries: int = 3
+) -> None
+```
+
+Initialize the retriever.
+
+**Parameters:**
+
+- **entity_types** (<code>list\[str\] | None</code>) – The Microsoft Search entity types to query. Defaults to `["driveItem", "listItem"]`,
+  which covers files, folders, SharePoint pages and news, and list items. Other valid values are
+  `"list"` and `"site"`. See the supported values and combinations in the
+  [Microsoft docs](https://learn.microsoft.com/en-us/graph/api/resources/searchrequest).
+- **top_k** (<code>int</code>) – The maximum number of documents to return. Maps to the Search API `size` and is paginated
+  when it exceeds a single page.
+- **fields** (<code>list\[str\] | None</code>) – Optional list of resource properties to request via the Search API `fields` selection
+  (only honored for `listItem` and `driveItem` entity types). See
+  [Get selected properties](https://learn.microsoft.com/en-us/graph/api/resources/search-api-overview#get-selected-properties).
+- **query_template** (<code>str | None</code>) – Optional query template used to scope the search, for example
+  `'{searchTerms} path:"https://contoso.sharepoint.com/sites/Team"'`. The literal `{searchTerms}`
+  placeholder is replaced by the run-time query. The template uses
+  [Keyword Query Language (KQL)](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference).
+- **graph_url** (<code>str</code>) – The Microsoft Graph base URL. Defaults to `https://graph.microsoft.com/v1.0`.
+  Override for sovereign clouds.
+- **timeout** (<code>float</code>) – The HTTP timeout in seconds for each request to Microsoft Graph.
+- **max_retries** (<code>int</code>) – The maximum number of retries for throttled (HTTP 429) or transient server errors.
+
+**Raises:**
+
+- <code>SharePointConfigError</code> – If `entity_types` is empty, `top_k` is not positive, or `max_retries` is
+  negative.
+
+#### run
+
+```python
+run(
+    query: str, access_token: str | Secret, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Search SharePoint and OneDrive and return the matching documents.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The search query string. Filter results by embedding Keyword Query Language (KQL)
+  operators directly in the query, for example `filetype:docx`, `author:"Jane Doe"`, or
+  `path:"https://contoso.sharepoint.com/sites/Team"`. See the
+  [KQL syntax reference](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference).
+- **access_token** (<code>str | Secret</code>) – A delegated Microsoft Graph bearer token for the user whose content is searched,
+  typically wired from an upstream `OAuthResolver` (which emits a plain `str`). A `Secret` is also
+  accepted and resolved internally.
+- **top_k** (<code>int | None</code>) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- <code>SharePointConfigError</code> – If `access_token` is a `Secret` that does not resolve to a string.
+- <code>SharePointRequestError</code> – If Microsoft Graph returns an error response.
+
+#### run_async
+
+```python
+run_async(
+    query: str, access_token: str | Secret, top_k: int | None = None
+) -> dict[str, list[Document]]
+```
+
+Asynchronously search SharePoint and OneDrive and return the matching documents.
+
+**Parameters:**
+
+- **query** (<code>str</code>) – The search query string. Filter results by embedding Keyword Query Language (KQL)
+  operators directly in the query, for example `filetype:docx`, `author:"Jane Doe"`, or
+  `path:"https://contoso.sharepoint.com/sites/Team"`. See the
+  [KQL syntax reference](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference).
+- **access_token** (<code>str | Secret</code>) – A delegated Microsoft Graph bearer token for the user whose content is searched,
+  typically wired from an upstream `OAuthResolver` (which emits a plain `str`). A `Secret` is also
+  accepted and resolved internally.
+- **top_k** (<code>int | None</code>) – Overrides the `top_k` configured at initialization for this run.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with a `documents` key holding the list of retrieved `Document` objects.
+
+**Raises:**
+
+- <code>SharePointConfigError</code> – If `access_token` is a `Secret` that does not resolve to a string.
+- <code>SharePointRequestError</code> – If Microsoft Graph returns an error response.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MSSharePointRetriever
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>MSSharePointRetriever</code> – The deserialized component instance.

docs-website/reference_versioned_docs/version-2.22/integrations-api/mirage.md

@@ -0,0 +1,288 @@
+---
+title: "Mirage"
+id: integrations-mirage
+description: "Mirage integration for Haystack"
+slug: "/integrations-mirage"
+---
+
+
+## haystack_integrations.tools.mirage.shell_tool
+
+### MirageShellTool
+
+Bases: <code>Tool</code>
+
+A Haystack `Tool` that lets an `Agent` run bash commands across a Mirage virtual filesystem.
+
+Mirage mounts heterogeneous backends (object storage, databases, SaaS apps, local disk) as one
+filesystem; this tool exposes Mirage's single `execute` surface to an Agent as one well-described
+tool with a `command` parameter. Output is normalized to text and truncated before it reaches the
+model.
+
+### Security model
+
+Mirage never shells out to the host: every command runs inside Mirage's own virtual-filesystem
+interpreter, so the blast radius is confined to the mounts you attach. Two controls shape what an
+Agent can do:
+
+- **Per-mount read-only mode** (`MirageMount(..., read_only=True)`) is the authoritative write
+  boundary. Mirage refuses any write to a read-only mount regardless of the command used, so this
+  -- not the allowlist -- is how you prevent modification or deletion. Mount anything the Agent
+  should not change as read-only.
+- **The command allowlist** (`allowed_commands`) restricts *which* commands may run. It is
+  enforced against every command Mirage would execute, including commands nested inside
+  `$(...)`, backticks, `<(...)` and subshells, so `ls "$(rm x)"` is rejected unless `rm`
+  is also allowed. Treat it as a best-effort filter to steer the Agent, not a sandbox: allowing a
+  command that itself runs other commands (`eval`, `bash`, `sh`, `source`, `xargs`,
+  `timeout`) effectively allows anything, so do not list those for untrusted/hosted use.
+- **`denied_paths`** rejects any command whose text references one of the given path substrings.
+
+### Usage example
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.tools.mirage import MirageWorkspace, MirageMount, MirageShellTool
+
+workspace = MirageWorkspace([
+    MirageMount(path="/data", resource="ram"),
+    MirageMount(path="/s3", resource="s3", config={"bucket": "my-bucket"}, read_only=True),
+])
+tool = MirageShellTool(workspace, allowed_commands=["ls", "cat", "grep", "head", "wc", "cp"])
+
+agent = Agent(chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"), tools=[tool])
+result = agent.run(messages=[ChatMessage.from_user("How many lines in /s3/log.txt mention 'alert'?")])
+print(result["messages"][-1].text)
+```
+
+#### __init__
+
+```python
+__init__(
+    workspace: MirageWorkspace,
+    *,
+    name: str = "mirage_shell",
+    description: str | None = None,
+    invocation_timeout: float = 60.0,
+    max_output_chars: int = 20000,
+    allowed_commands: list[str] | None = None,
+    denied_paths: list[str] | None = None
+) -> None
+```
+
+Initialize the Mirage shell tool.
+
+**Parameters:**
+
+- **workspace** (<code>MirageWorkspace</code>) – The :class:`MirageWorkspace` describing the mount tree.
+- **name** (<code>str</code>) – Tool name exposed to the LLM.
+- **description** (<code>str | None</code>) – Custom description. If None, one is generated from the mount tree.
+- **invocation_timeout** (<code>float</code>) – Maximum seconds to wait for a command to finish.
+- **max_output_chars** (<code>int</code>) – Truncate command output to this many characters before returning it.
+- **allowed_commands** (<code>list\[str\] | None</code>) – If set, only these command names may run, e.g.
+  `["ls", "cat", "grep", "head", "wc"]`. The allowlist is enforced against *every* command
+  Mirage would execute -- including commands nested in substitutions/subshells -- so
+  `ls "$(rm x)"` is rejected unless `rm` is also allowed. It is a filter over Mirage's
+  virtual commands to steer the Agent, not a security sandbox; the write boundary is
+  per-mount `read_only` (see the class "Security model" section). If None, any command is
+  allowed (not recommended for untrusted/hosted use).
+- **denied_paths** (<code>list\[str\] | None</code>) – If set, any command referencing one of these path substrings is rejected.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Build the underlying live workspace eagerly. Called by `Agent.warm_up()`/`Pipeline.warm_up()`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the tool to a dictionary in the `{"type": ..., "data": ...}` format.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MirageShellTool
+```
+
+Deserialize the tool from a dictionary.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the underlying workspace.
+
+## haystack_integrations.tools.mirage.workspace
+
+### MirageMount
+
+Declarative description of a single backend mounted into a :class:`MirageWorkspace`.
+
+A mount is the serializable unit of a Mirage workspace: it names *where* a backend is mounted
+(`path`), *which* backend it is (`resource`, a Mirage registry name such as `"s3"` or `"gdrive"`),
+and *how* to configure it (`config`).
+
+`config` values may be plain values, Haystack `Secret` objects for credentials, or an OAuth token
+source (e.g. `OAuthRefreshTokenSource`) for backends whose config accepts a token-provider callable
+(such as Mirage's OneDrive `access_token`). Secrets and token sources are resolved only when the
+live workspace is built.
+
+Every backend is created the same way. Use the Mirage registry name and the config keys that backend expects
+(discover names with `MirageMount.available_resources()`; config keys come from the backend's Mirage config class):
+
+```python
+from haystack.utils import Secret
+
+MirageMount(path="/data", resource="ram")                                  # in-memory scratch
+MirageMount(path="/local", resource="disk", config={"root": "/srv/data"})  # local disk
+MirageMount(path="/s3", resource="s3", config={"bucket": "my-bucket"}, read_only=True)
+MirageMount(
+    path="/drive",
+    resource="gdrive",
+    config={"client_id": "...", "refresh_token": Secret.from_env_var("GDRIVE_REFRESH_TOKEN")},
+    read_only=True,
+)
+```
+
+**Parameters:**
+
+- **path** (<code>str</code>) – Mount point in the virtual filesystem, e.g. `"/s3"`.
+- **resource** (<code>str</code>) – Mirage registry name of the backend, e.g. `"ram"`, `"disk"`, `"s3"`, `"gdrive"`.
+  See `mirage.resource.registry.REGISTRY` or `MirageMount.available_resources()` for the full list.
+- **config** (<code>dict\[str, Any\]</code>) – Keyword arguments passed to the backend's Mirage config. Values may be `Secret`s, or
+  an OAuth token source that is turned into a token-provider callable when the workspace is built.
+- **read_only** (<code>bool</code>) – If True, the mount is mounted in Mirage's READ mode and writes are rejected by
+  Mirage itself.
+
+#### available_resources
+
+```python
+available_resources() -> list[str]
+```
+
+Return the Mirage registry names usable as `resource`.
+
+These are short backend names such as `"s3"`, `"gdrive"`, `"postgres"`. Pass one to
+`MirageMount(resource=...)`; the config keys each backend expects come from its Mirage
+config class.
+
+### MirageWorkspace
+
+A description of a Mirage mount tree that lazily builds a live `mirage.Workspace`.
+
+`MirageWorkspace` is the shared backend behind the Mirage tools and components: it holds the list of
+:class:`MirageMount`s and the cache configuration, serializes cleanly (resolving `Secret`s only at
+build time), and constructs the live workspace on first use via Mirage's resource registry.
+
+### Usage example
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.tools.mirage import MirageWorkspace, MirageMount
+
+ws = MirageWorkspace(
+    mounts=[
+        MirageMount(path="/data", resource="ram"),
+        MirageMount(path="/s3", resource="s3", config={"bucket": "my-bucket"}, read_only=True),
+    ]
+)
+print(ws.run("ls /s3"))
+```
+
+#### __init__
+
+```python
+__init__(
+    mounts: list[MirageMount], *, cache_limit: str | int = "512MB"
+) -> None
+```
+
+Initialize the workspace description.
+
+**Parameters:**
+
+- **mounts** (<code>list\[MirageMount\]</code>) – The backends to mount, as a list of :class:`MirageMount`.
+- **cache_limit** (<code>str | int</code>) – Mirage file-cache size limit (e.g. `"512MB"` or an int byte count).
+
+**Raises:**
+
+- <code>MirageConfigError</code> – If no mounts are provided or mount paths are not unique.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Build the live `mirage.Workspace` eagerly. Idempotent.
+
+#### close
+
+```python
+close() -> None
+```
+
+Close the live workspace and release its resources, if it was built. Thread-safe.
+
+#### run
+
+```python
+run(
+    command: str, *, timeout: float = 60.0, max_chars: int | None = None
+) -> str
+```
+
+Run a bash `command` against the mount tree from a synchronous context and return its output.
+
+**Parameters:**
+
+- **command** (<code>str</code>) – A bash command line, e.g. `"grep -r alert /s3/logs | wc -l"`.
+- **timeout** (<code>float</code>) – Maximum seconds to wait for the command.
+- **max_chars** (<code>int | None</code>) – If set, truncate the returned text to this many characters.
+
+**Returns:**
+
+- <code>str</code> – Combined stdout (plus a trailing error note on non-zero exit) as a string.
+
+#### run_async
+
+```python
+run_async(
+    command: str, *, timeout: float = 60.0, max_chars: int | None = None
+) -> str
+```
+
+Async counterpart of :meth:`run`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the workspace description to a dictionary (Secret-safe).
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> MirageWorkspace
+```
+
+Deserialize a workspace description from a dictionary.
+
+#### describe
+
+```python
+describe() -> str
+```
+
+Return a human/LLM-readable summary of the mount tree (used in tool descriptions).

docs-website/reference_versioned_docs/version-2.22/integrations-api/mistral.md

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

docs-website/reference_versioned_docs/version-2.22/integrations-api/mongodb_atlas.md

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

docs-website/reference_versioned_docs/version-2.22/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.22/integrations-api/oauth.md

@@ -0,0 +1,500 @@
+---
+title: "OAuth"
+id: integrations-oauth
+description: "OAuth integration for Haystack"
+slug: "/integrations-oauth"
+---
+
+
+## haystack_integrations.components.connectors.oauth.resolver
+
+### OAuthTokenResolver
+
+Resolves an OAuth access token at pipeline runtime and emits it on the `access_token` output socket.
+
+The resolver component is a thin wrapper over a pluggable token source that decides *where* the token comes from:
+a standalone OAuth refresh grant (`OAuthRefreshTokenSource`), a per-request token exchange
+(`OAuthTokenExchangeSource`), a static long-lived token (`OAuthStaticTokenSource`), or a custom source you
+provide. A downstream component (for
+example a SharePoint or Google Drive retriever) consumes the token via a normal connection and never knows how
+it was resolved.
+
+The run input depends on the token source. A source that needs a per-request credential (it sets
+`requires_subject_token = True`, like `OAuthTokenExchangeSource`) makes the resolver declare a **mandatory**
+`subject_token` input — a controller-injected per-request credential (for example an incoming user assertion),
+not chosen by an end user. A config-only source declares no run input, so the resolver is a source node.
+
+### Usage example
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.components.connectors.oauth import OAuthTokenResolver
+from haystack_integrations.utils.oauth import OAuthRefreshTokenSource
+
+resolver = OAuthTokenResolver(
+    token_source=OAuthRefreshTokenSource(
+        token_url="https://login.microsoftonline.com/common/oauth2/v2.0/token",
+        client_id="aaa-bbb-ccc",
+        refresh_token=Secret.from_env_var("MS_REFRESH_TOKEN"),
+        scopes=["https://graph.microsoft.com/Files.Read.All", "offline_access"],
+    ),
+)
+access_token = resolver.run()["access_token"]
+```
+
+#### __init__
+
+```python
+__init__(token_source: TokenSource | SubjectTokenSource) -> None
+```
+
+Initialize the resolver.
+
+**Parameters:**
+
+- **token_source** (<code>TokenSource | SubjectTokenSource</code>) – The strategy that resolves the access token. If it sets `requires_subject_token = True`
+  (for example `OAuthTokenExchangeSource`), the resolver declares a mandatory `subject_token` run input;
+  otherwise the resolver takes no run input.
+
+**Raises:**
+
+- <code>OAuthConfigError</code> – If `token_source` does not implement a token-source protocol.
+
+#### run
+
+```python
+run(**kwargs: Any) -> dict[str, str]
+```
+
+Resolve an access token and emit it.
+
+**Parameters:**
+
+- **kwargs** (<code>Any</code>) – Carries `subject_token` when the configured source requires it (declared as a mandatory
+  input in that case, injected by the application/controller per request). For config-only sources no
+  input is declared and `kwargs` is empty.
+
+**Returns:**
+
+- <code>dict\[str, str\]</code> – A dictionary with a single `access_token` key containing a bearer token string.
+
+**Raises:**
+
+- <code>OAuthConfigError</code> – If the source requires a `subject_token` but it is missing or empty.
+
+#### run_async
+
+```python
+run_async(**kwargs: Any) -> dict[str, str]
+```
+
+Asynchronously resolve an access token and emit it.
+
+**Parameters:**
+
+- **kwargs** (<code>Any</code>) – Carries `subject_token` when the configured source requires it.
+
+**Returns:**
+
+- <code>dict\[str, str\]</code> – A dictionary with a single `access_token` key containing a bearer token string.
+
+**Raises:**
+
+- <code>OAuthConfigError</code> – If the source requires a `subject_token` but it is missing or empty.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OAuthTokenResolver
+```
+
+Deserialize this component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of this component.
+
+**Returns:**
+
+- <code>OAuthTokenResolver</code> – The deserialized component instance.
+
+**Raises:**
+
+- <code>ImportError</code> – If the serialized `token_source` type cannot be imported.
+
+## haystack_integrations.utils.oauth.errors
+
+### OAuthError
+
+Bases: <code>Exception</code>
+
+Base class for errors raised by the OAuth integration.
+
+### OAuthConfigError
+
+Bases: <code>OAuthError</code>
+
+Raised when an OAuth component or token source is misconfigured.
+
+### TokenRefreshError
+
+Bases: <code>OAuthError</code>
+
+Raised when a token cannot be resolved or refreshed at the identity provider.
+
+## haystack_integrations.utils.oauth.protocols
+
+### TokenSource
+
+Bases: <code>Protocol</code>
+
+A token source that resolves an access token with no per-request input (a config-only source).
+
+Implemented by sources whose credential is fixed at construction time — e.g. `OAuthRefreshTokenSource` and
+`OAuthStaticTokenSource`. Such sources set the class attribute `requires_subject_token = False`, and
+`OAuthTokenResolver` runs them as source nodes (no run input).
+
+#### resolve
+
+```python
+resolve() -> str
+```
+
+Return a valid access token.
+
+#### resolve_async
+
+```python
+resolve_async() -> str
+```
+
+Asynchronous counterpart of `resolve`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the source to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TokenSource
+```
+
+Deserialize the source from a dictionary.
+
+### SubjectTokenSource
+
+Bases: <code>Protocol</code>
+
+A token source that resolves an access token by exchanging a per-request subject token.
+
+The `subject_token` is a controller-injected per-request credential (for example an incoming user assertion),
+not chosen by an end user. Implemented by `OAuthTokenExchangeSource`. Such sources set the class attribute
+`requires_subject_token = True`, which makes `OAuthTokenResolver` declare a mandatory `subject_token` run input.
+
+#### resolve
+
+```python
+resolve(subject_token: str) -> str
+```
+
+Return a valid access token for the per-request `subject_token`.
+
+#### resolve_async
+
+```python
+resolve_async(subject_token: str) -> str
+```
+
+Asynchronous counterpart of `resolve`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the source to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SubjectTokenSource
+```
+
+Deserialize the source from a dictionary.
+
+## haystack_integrations.utils.oauth.sources
+
+### OAuthRefreshTokenSource
+
+Resolves access tokens by running the RFC 6749 refresh-token grant against an OAuth token endpoint.
+
+Given a stored refresh token plus client credentials, it exchanges them for an access token and caches it in
+process until shortly before expiry. If the identity provider rotates the refresh token on exchange, the new value
+is kept for the lifetime of the process and surfaced through the optional `on_rotate` callback so it can be
+persisted.
+
+This source is **single-identity**: one refresh token per instance, and its in-process cache is not shared across
+processes. In a multi-replica deployment each replica keeps its own cache, so for providers that rotate (issue
+single-use) refresh tokens the replicas can invalidate one another's token unless rotations are persisted to a
+shared store via `on_rotate` and a single owner drives the refresh.
+
+Choose this source for a single fixed identity backed by a refresh grant. For a long-lived, non-expiring token
+use `OAuthStaticTokenSource`; for multi-replica or multi-user backends use `OAuthTokenExchangeSource`.
+
+#### __init__
+
+```python
+__init__(
+    token_url: str,
+    client_id: str,
+    *,
+    refresh_token: Secret = Secret.from_env_var("OAUTH_REFRESH_TOKEN"),
+    client_secret: Secret | None = None,
+    scopes: list[str] | None = None,
+    scope_delimiter: str = " ",
+    expiry_buffer_seconds: int = DEFAULT_EXPIRY_BUFFER_SECONDS,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    on_rotate: Callable[[str], None] | None = None
+) -> None
+```
+
+Initialize the source.
+
+**Parameters:**
+
+- **token_url** (<code>str</code>) – The OAuth 2.0 token endpoint.
+- **client_id** (<code>str</code>) – The OAuth client identifier.
+- **refresh_token** (<code>Secret</code>) – The refresh token to exchange. Defaults to the value of the `OAUTH_REFRESH_TOKEN`
+  environment variable.
+- **client_secret** (<code>Secret | None</code>) – The client secret for confidential clients. Omit it for public clients.
+- **scopes** (<code>list\[str\] | None</code>) – The OAuth scopes to request, joined with `scope_delimiter`. Scope *values* are
+  provider-specific (consult your identity provider's documentation).
+- **scope_delimiter** (<code>str</code>) – The delimiter used to join scopes. Defaults to a space (some providers use a comma).
+- **expiry_buffer_seconds** (<code>int</code>) – Refresh the cached access token this many seconds before its declared expiry.
+- **timeout** (<code>float</code>) – The timeout, in seconds, for the request to the token endpoint.
+- **on_rotate** (<code>Callable\\[[str\], None\] | None</code>) – An optional callback invoked with the new refresh token whenever the provider rotates it.
+  Use it to persist the rotated token durably (the source itself only keeps it in process).
+
+**Raises:**
+
+- <code>OAuthConfigError</code> – If the configuration is invalid.
+
+#### resolve
+
+```python
+resolve() -> str
+```
+
+Return a cached access token, or run the refresh-token grant to obtain a fresh one.
+
+**Returns:**
+
+- <code>str</code> – A valid bearer access token.
+
+#### resolve_async
+
+```python
+resolve_async() -> str
+```
+
+Asynchronous counterpart of `resolve`. Use a single instance in either sync or async mode, not both.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the source to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OAuthRefreshTokenSource
+```
+
+Deserialize the source from a dictionary.
+
+### OAuthTokenExchangeSource
+
+Resolves access tokens by exchanging a per-request subject token at an OAuth token endpoint.
+
+This implements RFC 8693 token exchange (and, via configuration, Microsoft's on-behalf-of flow). Unlike
+`OAuthRefreshTokenSource`, it is **multi-user without any persistent storage**: the per-request `subject_token` (the
+incoming user assertion) *is* the user identity and is exchanged fresh for a downstream token. Resolved tokens
+are cached in memory per subject token (bounded, LRU) until shortly before expiry. Because no per-instance state
+is persisted, it is also the right choice for multi-replica deployments.
+
+Provider differences are expressed as configuration: `grant_type`, `subject_token_param` (for example
+`assertion` for Microsoft), `scopes`, and `extra_token_params` (for example
+`{"requested_token_use": "on_behalf_of"}`).
+
+#### __init__
+
+```python
+__init__(
+    token_url: str,
+    client_id: str,
+    *,
+    client_secret: Secret | None = None,
+    grant_type: str = DEFAULT_TOKEN_EXCHANGE_GRANT,
+    subject_token_param: str = "subject_token",
+    subject_token_type: str | None = None,
+    requested_token_type: str | None = None,
+    scopes: list[str] | None = None,
+    scope_delimiter: str = " ",
+    extra_token_params: dict[str, str] | None = None,
+    expiry_buffer_seconds: int = DEFAULT_EXPIRY_BUFFER_SECONDS,
+    cache_max_size: int = DEFAULT_CACHE_MAX_SIZE,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS
+) -> None
+```
+
+Initialize the source.
+
+**Parameters:**
+
+- **token_url** (<code>str</code>) – The OAuth 2.0 token endpoint.
+- **client_id** (<code>str</code>) – The OAuth client identifier.
+- **client_secret** (<code>Secret | None</code>) – The client secret for confidential clients. Omit it for public clients.
+- **grant_type** (<code>str</code>) – The grant type sent as the `grant_type` form parameter. Defaults to the RFC 8693
+  token-exchange grant. Set it to the value your provider expects (for example the
+  `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for Microsoft on-behalf-of).
+- **subject_token_param** (<code>str</code>) – The name of the form parameter carrying the per-request subject token. Defaults
+  to `subject_token` (RFC 8693). Some providers expect a different name, such as `assertion`.
+- **subject_token_type** (<code>str | None</code>) – The RFC 8693 identifier for the type of the supplied subject token, sent as the
+  `subject_token_type` form parameter (omitted when not set). Required by RFC 8693 token exchange
+  (e.g. `urn:ietf:params:oauth:token-type:access_token`); not used by Microsoft's on-behalf-of flow.
+- **requested_token_type** (<code>str | None</code>) – The RFC 8693 identifier for the token to return, sent as the
+  `requested_token_type` form parameter (omitted when not set). Optional.
+- **scopes** (<code>list\[str\] | None</code>) – The OAuth scopes to request, joined with `scope_delimiter`. Scope *values* are
+  provider-specific (consult your identity provider's documentation); only the wire format is standardized
+  (RFC 6749 §3.3).
+- **scope_delimiter** (<code>str</code>) – The delimiter used to join scopes. Defaults to a space.
+- **extra_token_params** (<code>dict\[str, str\] | None</code>) – Additional form parameters included verbatim in every request (for example
+  `{"requested_token_use": "on_behalf_of"}`). Applied last, so any key here overrides the corresponding
+  form parameter derived from the other arguments (for example `grant_type`, `subject_token_type`,
+  `requested_token_type`, `scope`, or `client_secret`).
+- **expiry_buffer_seconds** (<code>int</code>) – Refresh a cached access token this many seconds before its declared expiry.
+- **cache_max_size** (<code>int</code>) – The maximum number of per-user tokens to keep in the in-memory cache. The
+  least-recently-used entry is evicted when the cache is full.
+- **timeout** (<code>float</code>) – The timeout, in seconds, for the request to the token endpoint.
+
+**Raises:**
+
+- <code>OAuthConfigError</code> – If the configuration is invalid.
+
+#### resolve
+
+```python
+resolve(subject_token: str) -> str
+```
+
+Exchange the per-request `subject_token` for an access token (cached per subject token).
+
+**Parameters:**
+
+- **subject_token** (<code>str</code>) – The controller-injected per-request subject token (for example an incoming user
+  assertion) to exchange for a downstream access token.
+
+**Returns:**
+
+- <code>str</code> – A valid bearer access token for the given `subject_token`.
+
+#### resolve_async
+
+```python
+resolve_async(subject_token: str) -> str
+```
+
+Asynchronous counterpart of `resolve`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the source to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OAuthTokenExchangeSource
+```
+
+Deserialize the source from a dictionary.
+
+### OAuthStaticTokenSource
+
+Returns a configured long-lived access token as-is.
+
+Suitable for providers that issue non-expiring tokens (for example Slack or Notion), where no refresh flow is
+needed and the token is managed out of band. If the provider issues short-lived tokens that must be refreshed,
+use `OAuthRefreshTokenSource` instead. It takes no per-request input.
+
+#### __init__
+
+```python
+__init__(token: Secret) -> None
+```
+
+Initialize the source.
+
+**Parameters:**
+
+- **token** (<code>Secret</code>) – The long-lived access token to return.
+
+#### resolve
+
+```python
+resolve() -> str
+```
+
+Return the configured token.
+
+**Returns:**
+
+- <code>str</code> – The configured long-lived access token.
+
+#### resolve_async
+
+```python
+resolve_async() -> str
+```
+
+Asynchronous counterpart of `resolve`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize the source to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OAuthStaticTokenSource
+```
+
+Deserialize the source from a dictionary.

docs-website/reference_versioned_docs/version-2.22/integrations-api/ollama.md

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

docs-website/reference_versioned_docs/version-2.22/integrations-api/openapi.md

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

docs-website/reference_versioned_docs/version-2.22/integrations-api/openrouter.md

@@ -0,0 +1,189 @@
+---
+title: "OpenRouter"
+id: integrations-openrouter
+description: "OpenRouter integration for Haystack"
+slug: "/integrations-openrouter"
+---
+
+
+## haystack_integrations.components.generators.openrouter.chat.chat_generator
+
+### OpenRouterChatGenerator
+
+Bases: <code>OpenAIChatGenerator</code>
+
+Enables text generation using OpenRouter generative models.
+
+For supported models, see [OpenRouter docs](https://openrouter.ai/models).
+
+Users can pass any text generation parameters valid for the OpenRouter chat completion API
+directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs`
+parameter in `run` method.
+
+Key Features and Compatibility:
+
+- **Primary Compatibility**: Compatible with the OpenRouter chat completion endpoint.
+- **Streaming Support**: Supports streaming responses from the OpenRouter chat completion endpoint.
+- **Customizability**: Supports all parameters supported by the OpenRouter chat completion endpoint.
+- **Reasoning Support**: Extracts reasoning/thinking content from models that support it
+  (e.g., DeepSeek R1, Claude with extended thinking) and stores it in the `ReasoningContent`
+  field on `ChatMessage`. Reasoning content is only captured for non-streaming requests.
+
+This component uses the ChatMessage format for structuring both input and output,
+ensuring coherent and contextually relevant responses in chat-based text generation scenarios.
+Details on the ChatMessage format can be found in the
+[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage)
+
+For more details on the parameters supported by the OpenRouter API, refer to the
+[OpenRouter API Docs](https://openrouter.ai/docs/quickstart).
+
+Usage example:
+
+```python
+from haystack_integrations.components.generators.openrouter import (
+    OpenRouterChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+
+messages = [ChatMessage.from_user("What's Natural Language Processing?")]
+
+client = OpenRouterChatGenerator(
+    model="deepseek/deepseek-r1",
+    generation_kwargs={"reasoning": {"effort": "high"}},
+)
+response = client.run(messages)
+print(response["replies"][0].reasoning)  # Access reasoning content
+print(response["replies"][0].text)  # Access final answer
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("OPENROUTER_API_KEY"),
+    model: str = "openai/gpt-5-mini",
+    streaming_callback: StreamingCallbackT | None = None,
+    api_base_url: str | None = "https://openrouter.ai/api/v1",
+    generation_kwargs: dict[str, Any] | None = None,
+    tools: ToolsType | None = None,
+    timeout: float | None = None,
+    extra_headers: dict[str, Any] | None = None,
+    max_retries: int | None = None,
+    http_client_kwargs: dict[str, Any] | None = None
+) -> None
+```
+
+Creates an instance of OpenRouterChatGenerator.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The OpenRouter API key.
+- **model** (<code>str</code>) – The name of the OpenRouter chat completion model to use.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  The callback function accepts StreamingChunk as an argument.
+- **api_base_url** (<code>str | None</code>) – The OpenRouter API Base url.
+  For more details, see OpenRouter [docs](https://openrouter.ai/docs/quickstart).
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Other parameters to use for the model. These parameters are all sent directly to
+  the OpenRouter endpoint. See [OpenRouter API docs](https://openrouter.ai/docs/quickstart) for more details.
+  Some of the supported parameters:
+- `max_tokens`: The maximum number of tokens the output text can have.
+- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks.
+  Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.
+- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model
+  considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+  comprising the top 10% probability mass are considered.
+- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
+  events as they become available, with the stream terminated by a data: [DONE] message.
+- `safe_prompt`: Whether to inject a safety prompt before all conversations.
+- `random_seed`: The seed to use for random sampling.
+- `reasoning`: A dict to configure reasoning/thinking tokens for models that support it.
+  Example: `{"effort": "high"}` or `{"max_tokens": 2000}`.
+  Reasoning content is only captured for non-streaming requests.
+  See [OpenRouter reasoning docs](https://openrouter.ai/docs/use-cases/reasoning-tokens).
+- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response.
+- **tools** (<code>ToolsType | None</code>) – A list of tools or a Toolset for which the model can prepare calls. This parameter can accept either a
+  list of `Tool` objects or a `Toolset` instance.
+- **timeout** (<code>float | None</code>) – The timeout for the OpenRouter API call.
+- **extra_headers** (<code>dict\[str, Any\] | None</code>) – Additional HTTP headers to include in requests to the OpenRouter API.
+  This can be useful for adding site URL or title for rankings on openrouter.ai
+  For more details, see OpenRouter [docs](https://openrouter.ai/docs/quickstart).
+- **max_retries** (<code>int | None</code>) – Maximum number of retries to contact OpenAI after an internal error.
+  If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5.
+- **http_client_kwargs** (<code>dict\[str, Any\] | None</code>) – A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
+  For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized component as a dictionary.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage] | str,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    tools: ToolsType | None = None,
+    tools_strict: bool | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Invokes chat completion on the OpenRouter API.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\] | str</code>) – A list of ChatMessage instances representing the input messages.
+  If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation. These parameters will
+  override the parameters passed during component initialization.
+  For details on OpenRouter API parameters, see
+  [OpenRouter docs](https://openrouter.ai/docs/quickstart).
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter provided during initialization.
+- **tools_strict** (<code>bool | None</code>) – Whether to enable strict schema adherence for tool calls.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.
+
+#### run_async
+
+```python
+run_async(
+    messages: list[ChatMessage] | str,
+    streaming_callback: StreamingCallbackT | None = None,
+    generation_kwargs: dict[str, Any] | None = None,
+    *,
+    tools: ToolsType | None = None,
+    tools_strict: bool | None = None
+) -> dict[str, list[ChatMessage]]
+```
+
+Asynchronously invokes chat completion on the OpenRouter API.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\] | str</code>) – A list of ChatMessage instances representing the input messages.
+  If a string is provided, it is converted to a list containing a ChatMessage with user role.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that is called when a new token is received from the stream.
+  Must be a coroutine.
+- **generation_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments for text generation.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset.
+- **tools_strict** (<code>bool | None</code>) – Whether to enable strict schema adherence for tool calls.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – A dictionary with the following key:
+- `replies`: A list containing the generated responses as ChatMessage instances.