Haystack experimental package

The haystack-experimental package provides Haystack users with access to experimental features without immediately committing to their official release. The main goal is to gather user feedback and iterate on new features quickly.

Installation

For simplicity, every release of haystack-experimental will ship all the available experiments at that time. To install the latest experimental features, run:

sh $ pip install -U haystack-experimental

Install from the main branch to try the newest features: sh pip install git+https://github.com/deepset-ai/haystack-experimental.git@main

[!IMPORTANT] The latest version of the experimental package is only tested against the latest version of Haystack. Compatibility with older versions of Haystack is not guaranteed.

Experiments lifecycle

Each experimental feature has a default lifespan of 3 months starting from the date of the first non-pre-release build that includes it. Once it reaches the end of its lifespan, the experiment will be either:

• Merged into Haystack core and published in the next minor release, or
• Released as a Core Integration, or
• Dropped.

Experiments catalog

Active experiments

| Name | Type | Expected End Date | Dependencies | Cookbook | Discussion | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|-------------------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| | InMemoryChatMessageStore | Memory Store | December 2024 | None | | Discuss | | ChatMessageRetriever | Memory Component | December 2024 | None | | Discuss | | ChatMessageWriter | Memory Component | December 2024 | None | | Discuss | | QueryExpander | Query Expansion Component | October 2025 | None | None | Discuss | | EmbeddingBasedDocumentSplitter | EmbeddingBasedDocumentSplitter | August 2025 | None | None | Discuss | | MultiQueryEmbeddingRetriever | MultiQueryEmbeddingRetriever | November 2025 | None | None | Discuss | | MultiQueryTextRetriever | MultiQueryTextRetriever | November 2025 | None | None | Discuss | | OpenAIChatGenerator | Chat Generator Component | November 2025 | None | | Discuss | | MarkdownHeaderLevelInferrer | Preprocessor | January 2025 | None | None | Discuss | | Agent; Confirmation Policies; ConfirmationUIs; ConfirmationStrategies; ConfirmationUIResult and ToolExecutionDecision HITLBreakpointException | Human in the Loop | December 2025 | rich | None | Discuss | | RegexTextExtractor | Text Extractor Component | January 2025 | None | None | Discuss |

Adopted experiments

| Name | Type | Final release | |----------------------------------------------------------------------------------------|------------------------------------------|---------------| | ChatMessage refactoring; Tool class; tool support in ChatGenerators; ToolInvoker | Tool Calling support | 0.4.0 | | AsyncPipeline; Pipeline bug fixes and refactoring | AsyncPipeline execution | 0.7.0 | | LLMMetadataExtractor | Metadata extraction with LLM | 0.7.0 | | Auto-Merging Retriever & HierarchicalDocumentSplitter | Document Splitting & Retrieval Technique | 0.8.0 | | Agent | Simplify Agent development | 0.8.0 | | SuperComponent | Simplify Pipeline development | 0.8.0 | | Pipeline | Pipeline breakpoints for debugging | 0.12.0 | | ImageContent; Image Converters; multimodal support in OpenAIChatGenerator and AmazonBedrockChatGenerator; ChatPromptBuilder refactoring; SentenceTransformersDocumentImageEmbedder; LLMDocumentContentExtractor; new Routers | Multimodality | 0.12.0 |

Discontinued experiments

| Name | Type | Final release | Cookbook | |------------------------|----------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------| | OpenAIFunctionCaller | Function Calling Component | 0.3.0 | None | | OpenAPITool | OpenAPITool component | 0.3.0 | Notebook | | EvaluationHarness | Evaluation orchestrator | 0.7.0 | None |

Usage

Experimental new features can be imported like any other Haystack integration package:

```python from haystack.dataclasses import ChatMessage from haystack_experimental.components.generators import FoobarGenerator

c = FoobarGenerator() c.run([ChatMessage.from_user("What's an experiment? Be brief.")]) ```

Experiments can also override existing Haystack features. For example, users can opt into an experimental type of Pipeline by just changing the usual import:

```python

from haystack import Pipeline

from haystack_experimental import Pipeline

pipe = Pipeline()

...

pipe.run(...) ```

Some experimental features come with example notebooks that can be found in the Haystack Cookbook.

Documentation

Documentation for haystack-experimental can be found here.

Implementation

Experiments should replicate the namespace of the core package. For example, a new generator:

```python

in haystack_experimental/components/generators/foobar.py

from haystack import component

@component class FoobarGenerator: ...

```

When the experiment overrides an existing feature, the new symbol should be created at the same path in the experimental package. This new symbol will override the original in haystack-ai: for classes, with a subclass and for bare functions, with a wrapper. For example:

```python

in haystackexperiment/src/haystackexperiment/core/pipeline/pipeline.py

from haystack.core.pipeline import Pipeline as HaystackPipeline

class Pipeline(HaystackPipeline): # Any new experimental method that doesn't exist in the original class def run_async(self, inputs) -> Dict[str, Dict[str, Any]]: ...

# Existing methods with breaking changes to their signature, like adding a new mandatory param
def to_dict(self, new_param: str) -> Dict[str, Any]:
    # do something with the new parameter
    print(new_param)
    # call the original method
    return super().to_dict()

```

Contributing

Direct contributions to haystack-experimental are not expected, but Haystack maintainers might ask contributors to move pull requests that target the core repository to this repository.

Telemetry

As with the Haystack core package, we rely on anonymous usage statistics to determine the impact and usefulness of the experimental features. For more information on what we collect and how we use the data, as well as instructions to opt-out, please refer to our documentation.