NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #5335 most downloaded on PyPI
LLM framework to build customizable, production-ready LLM applications. Connect components (models, vector DBs, file converters) to pipelines or agents that can interact with your data.
Latest stable
3.5.0
Last release 11 days ago
11 Nov 2026
Ships on a steady schedule
a new release about every 8 days
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
3 years old
277 releases · first in 2023
Drag across the ruler to compare, or tap a release to open it.
Nothing published for this version
Nothing published for this version
Three new components use the OpenAI Decisions API to choose how to handle your data without instructions. `OpenAIDecisionsTextRouter` sends text to a
Three new components use the OpenAI Decisions API to choose how to handle your data without instructions. OpenAIDecisionsTextRouter sends text to a named output per label, OpenAIDecisionsImageRouter does the same for images and can send low-confidence decisions to a fallback branch, and OpenAIDecisionsDocumentClassifier answers choice, score, and yes/no questions about documents and stores the answers in their metadata.
from haystack.components.routers import OpenAIDecisionsTextRouter
router = OpenAIDecisionsTextRouter(
labels={
"billing": "Payments, invoices, refunds and charges",
"technical": "Bugs, crashes and errors in the product",
},
instructions="Which team should handle this support request?",
min_confidence=0.6,
)
print(router.run(text="I was charged twice for my subscription."))
# >> {'billing': 'I was charged twice for my subscription.'}
The new StructuredOutputHook validates the Agent's final reply against a Pydantic model or JSON schema and returns it as a dict in result["structured_output"]. If the reply doesn't validate, the hook sends the error back to the model and lets it try again, up to max_retries times.
from pydantic import BaseModel
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.hooks.structured_output import StructuredOutputHook
class CityInfo(BaseModel):
city: str
country: str
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(generation_kwargs={"text_format": CityInfo}),
state_schema={"structured_output": {"type": dict}},
hooks={"on_exit": [StructuredOutputHook(schema=CityInfo)]},
)
result = agent.run(messages=[ChatMessage.from_user("Which city is the Eiffel Tower in?")])
print(result["structured_output"])
# >> {'city': 'Paris', 'country': 'France'}
Also new for Agents: the experimental StepBudgetReminderHook tells the model how many steps it has left as it approaches max_agent_steps, so it wraps up with an answer instead of being cut off.
Document has a new multivector_embedding field for late-interaction models such as ColBERT, and the new MaxSimRanker reranks candidates by comparing each query vector to the document vectors and summing the best matches. DocumentJoiner(join_mode="merge_embeddings") can also combine dense, sparse, and multivector embeddings computed in parallel for the same documents.
This is the first step toward multivector retrieval in Haystack (#13257). Embedders that produce multivector embeddings are in progress in Haystack Core Integrations: Sentence Transformers and vLLM.
from haystack import Document
from haystack.components.rankers import MaxSimRanker
# Representative multivector embedding for "How do solar panels work?"
query_multivector_embedding = [[1.0, 0.0], [0.0, 1.0]]
documents = [
Document(content="Wind turbines generate electricity.", multivector_embedding=[[1.0, 0.0], [0.0, 0.2]]),
Document(content="Solar panels turn sunlight into power.", multivector_embedding=[[0.95, 0.05], [0.15, 0.9]]),
Document(content="Solar cells absorb light.", multivector_embedding=[[0.9, 0.1], [0.1, 0.9]]),
]
ranker = MaxSimRanker(top_k=2)
result = ranker.run(query_multivector_embedding=query_multivector_embedding, documents=documents)
for document in result["documents"]:
print(f"{document.score:.2f}: {document.content}")
# >> 1.85: Solar panels turn sunlight into power.
# >> 1.80: Solar cells absorb light.
OpenAIChatGenerator, OpenAIResponsesChatGenerator, and the LLM-based evaluators now default to gpt-5.6-terra, the replacement OpenAI recommends for gpt-5-mini. OpenAI shuts down gpt-5-mini on December 11, 2026. Pipelines saved with model: gpt-5-mini keep using it, so update their YAML before then.
Raise the minimum supported openai SDK version from 2.6.0 to 3.26.0 to support the Decisions API.
Declared pydantic>=2.12 (>=2.14 on Python 3.15) as the minimum supported version. pydantic releases before 2.11 generate different JSON schemas for tool parameters in create_tool_from_function/@tool, ComponentTool, and PipelineTool.
If you don't set keep_default_na or na_values in read_excel_kwargs, XLSXToDocument now keeps cell text such as "NA", "N/A", "NULL", and "None" instead of treating it as missing. A numeric column that contains such text is therefore no longer converted to floats, so in CSV output its whole numbers render as 1 instead of 1.0. To restore the previous behavior, pass read_excel_kwargs={"keep_default_na": True}.
Components with a Variadic input, or a list input connected to several senders, now receive the values in the order the senders were connected with Pipeline.connect(). Before, Pipeline.run() passed them in the order the senders ran, so the results of order-dependent components such as DocumentJoiner with weights can change: connect the senders in the order you want the values to arrive.
If you load pipelines from YAML, check the order of your connections entries. Pipelines saved before this release list connections grouped by sender, not in the order they were made, and the order of the entries now decides the order in which a socket receives its values. For example, if embedding_retriever is listed before bm25_retriever in connections, DocumentJoiner now applies weights[0] to the embedding retriever, where before it could apply it to the BM25 retriever. Reorder the entries that feed a Variadic or multi-sender list socket so the senders come in the order you expect.
The default model of OpenAIChatGenerator and OpenAIResponsesChatGenerator changed from gpt-5-mini to gpt-5.6-terra, the replacement OpenAI recommends. OpenAI shuts down gpt-5-mini on December 11, 2026. LLMEvaluator, ContextRelevanceEvaluator, and FaithfulnessEvaluator use the new default too.
Pipelines serialized before this change store model: gpt-5-mini and keep using it. Update the model value in their YAML before December 11, 2026. To keep gpt-5-mini until then, pass it explicitly: OpenAIChatGenerator(model="gpt-5-mini").
If you read id, encrypted_content, or status directly from reply.reasoning.extra in OpenAIResponsesChatGenerator replies, read them from entries in reply.reasoning.extra["reasoning_items"] instead. For example, replace reply.reasoning.extra["id"] with reply.reasoning.extra["reasoning_items"][0]["id"] for the first item, or iterate over the list to handle all reasoning items.
OpenAIChatGenerator and AzureOpenAIChatGenerator now request token usage metadata by default when streaming. To restore the previous behavior, pass generation_kwargs={"stream_options": {"include_usage": False}}.
max_agent_steps is now a reserved state key on Agent. If you defined a custom state_schema key named max_agent_steps, rename it (e.g. my_max_agent_steps): the Agent now raises a ValueError at initialization when a reserved key is redefined.
Add the optional multivector_embedding field to Document to store multi-vector representation such as those generated by late-interaction models like ColBERT. This is a first step toward supporting multivector embedders, retrievers, and rankers.
Add MaxSimRanker to rank documents by their similarity to a query using precomputed multivector embeddings. In two-stage retrieval, an embedding retriever can quickly select candidates using dense similarity, then MaxSimRanker performs a more fine-grained comparison of the query and each candidate's content to return the most relevant documents.
Add OpenAIDecisionsDocumentClassifier to answer choice, score, and predicate questions about documents using the OpenAI Decisions API. Answers are stored in document metadata.
Add OpenAIDecisionsImageRouter to route images to different pipeline branches based on their content, with optional text context. Images with low-confidence decisions can be sent to a fallback branch.
Add OpenAIDecisionsTextRouter to route text to named categories using the OpenAI Decisions API.
Added StructuredOutputHook to haystack.hooks.structured_output. Registered under on_exit, it parses the Agent's final reply as JSON, validates it against a Pydantic model or a JSON schema, and stores the result as a dict under the structured_output key by default. The key must be declared in the Agent's state_schema, otherwise the hook raises an error at runtime.
When a reply can't be parsed, the hook sends the validation error back to the model and keeps the Agent running so it can correct its reply, up to max_retries times (2 by default). When the reply still can't be parsed, or the Agent stops on another exit condition, None is stored.
from pydantic import BaseModel
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.hooks.structured_output import StructuredOutputHook
class CityInfo(BaseModel):
city: str
country: str
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(generation_kwargs={"text_format": CityInfo}),
state_schema={"structured_output": {"type": dict}},
hooks={"on_exit": [StructuredOutputHook(schema=CityInfo)]},
)
result = agent.run(messages=[ChatMessage.from_user("Which city is the Eiffel Tower in?")])
print(result["structured_output"])
# {'city': 'Paris', 'country': 'France'}
DocumentJoiner now supports join_mode="merge_embeddings" to combine the embedding and sparse_embedding fields of documents with the same ID. This allows dense and sparse document embedders to run in parallel and their outputs to be combined before passing them to DocumentWriter.
Added StepBudgetReminderHook (experimental), a before_llm hook that tells the model how many steps it has left once an Agent run gets close to max_agent_steps. Before each of the last remind_within_steps LLM calls, it adds a user message wrapped in <system-reminder> tags, such as "You have 2 of 10 steps remaining", and on the last step asks for the final answer. This lets the Agent wrap up instead of being cut off mid-investigation.
from haystack.hooks.budget import StepBudgetReminderHook
agent = Agent(
chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
tools=[search],
max_agent_steps=20,
hooks={"before_llm": [StepBudgetReminderHook(remind_within_steps=3)]},
)
Reminder messages are marked with meta={"system_reminder": True}. Context compaction recognizes the marker and never treats a reminder as the user's task.
delete_by_filter_async() method to InMemoryDocumentStore. Previously, only the sync delete_by_filter() was available, unlike the other methods of the store, which all have an async counterpart. The new method runs delete_by_filter() in the store's thread-pool executor and returns the number of deleted documents.modify_template of BlockingConfirmationStrategy now tells the LLM that the user wants the result of the modified tool call used and that it should not call the tool again with the original arguments. With the previous wording, models often repeated the original tool call after a user modified its parameters. Pass modify_template explicitly to keep the previous message.DocumentJoiner(join_mode="merge_embeddings") now supports multivector embeddings in addition to dense and sparse embeddings when combining documents with the same ID.OpenAIChatGenerator now includes several methods to make it easier for subclasses to customize the component's behavior while reducing code duplication.Document objects and pipeline inputs are now faster, with the same results as before. Document now implements __deepcopy__, which copies the embedding list in one step instead of element by element. Pipeline also returns immutable values such as strings and numbers unchanged when copying component inputs, without running the more expensive checks meant for other objects. Pipelines that pass embeddings or many embedded documents between components benefit most.EvaluationRunResult.comparative_detailed_report has a new align_on parameter to match the rows of the two runs by an input column, such as a question ID or the question itself, instead of by position. This compares runs correctly even if they evaluated the same questions in a different order, or not all of the same questions. Rows without a match are kept with None for the other run.HierarchicalDocumentSplitter now supports split_by="token" (requires pip install tiktoken), with the encoding set by the new tokenizer_encoding parameter (default "o200k_base"). A new warm_up() method loads the tokenizer up front instead of on the first run().PPTXToDocument now extracts text from grouped shapes and tables, which were previously skipped. Tables are included in the document content as CSV.OpenAIChatGenerator and OpenAIResponsesChatGenerator now preserve OpenAI API refusals in ChatMessage.meta["refusal"]. Applications can inspect this metadata to detect and handle refusals.OpenAIResponsesChatGenerator now preserves text annotations in reply.meta["annotations"], with aligned annotation_offsets for locating citations in the concatenated reply text.tokenizer_encoding parameter to RecursiveDocumentSplitter to choose the tiktoken encoding used when split_unit="token", as in DocumentSplitter. It defaults to "o200k_base", the encoding used until now. Set it to match your model, for example "cl100k_base" for OpenAI's text-embedding-3 models, so that chunks fit the model's token limit.RecursiveDocumentSplitter now validates split_unit at initialization, raising a ValueError for values other than "word", "char", or "token" instead of failing later during run().max_agent_steps state key, for example with state.get("max_agent_steps"). It is not returned as an Agent output.Fixed Agent losing token counts in token_usage when a later LLM call reports a usage field as null, for example prompt_tokens_details reported on one call and null on the next. A null value now counts as not reported, so the totals no longer depend on the order of the calls.
FilterRetriever, AutoMergingRetriever, SentenceWindowRetriever, CacheChecker and DocumentWriter now work with document stores that implement only the synchronous API. Their run_async methods use the store's async method when it exists and otherwise run the synchronous one in a worker thread, instead of failing on the missing async method.
Fix AutoMergingRetriever.run() and run_async() when retrieved leaves from HierarchicalDocumentSplitter have different depths. Shallower leaves now merge together with siblings promoted from deeper branches, preventing missed parent merges and duplicate parent documents in the retrieved context.
ComponentTool now skips unknown invocation arguments with a warning instead of raising KeyError, including extra properties in custom schemas and arguments added by the LLM. Custom schemas with unknown properties also produce a warning during construction. A ValueError is raised when a custom schema omits mandatory component inputs not provided through inputs_from_state. Automatically injected State inputs are excluded. This also applies to AgentTool when a custom parameters schema omits messages and it is not provided through inputs_from_state. Previously, construction succeeded but invocation failed because the required input was missing.
ImageContent.from_dict, FileContent.from_dict and TextContent.from_dict now build the calling class instead of the base class, so a subclass survives a to_dict / from_dict round trip. This matches the behaviour of ByteStream.from_dict.
Fixed DocumentCleaner removing indentation and newlines at the start and end of every page when remove_regex was set, even on pages where the regex matched nothing. Pages without a match are now left unchanged, which preserves Markdown and code content when remove_extra_whitespaces, remove_empty_lines and strip_whitespaces are disabled. Pages where the regex matches are still stripped as before.
DocumentJoiner now raises a ValueError when weights contains NaN or infinite values. Previously, these values were accepted and turned the document scores into NaN in the merge and reciprocal_rank_fusion join modes.
DOCXToDocument now reads text that a paragraph keeps inside a tracked insertion, moved text, a smart tag, custom XML, a simple field or a filled-in inline content control. Previously only a paragraph's direct runs and hyperlinks were read, so a document with unaccepted tracked changes lost every inserted word, and a filled form field lost its value. Deleted text, the old place of moved text and content controls that still show their placeholder prompt are left out, as the document does not show them.
DocumentRecallEvaluator and DocumentNDCGEvaluator now support list and dictionary metadata values in document_comparison_field instead of raising TypeError. Nested values are supported, and duplicate documents retain the existing recall and relevance scoring behavior.
FileTypeRouter no longer loses the detected MIME type when meta is passed alongside file paths.
Fix AutoMergingRetriever incorrectly counting duplicate child documents when evaluating merge thresholds. Documents are now deduplicated by ID before merging, retaining the highest-scoring copy in both synchronous and asynchronous retrieval.
EvaluationRunResult.comparative_detailed_report no longer drops the first run's scores when both runs have the same run_name. Their columns are named with _first and _second again, as they were before the report stopped using pandas. When align_on isn't set and the two runs have a different number of rows, it logs a warning and pads the shorter run with None instead of returning columns of different lengths.
DocumentToImageContent now skips an image file that cannot be decoded instead of failing the whole run() call. The skipped document gets None in image_contents and a warning is logged.
ImageFileToImageContent now skips a source that is not a valid image instead of failing the whole run() call. A non-image file in a mixed batch, such as a .txt file, is logged and omitted from image_contents, while the other sources are still converted.
Fixed ListJoiner.from_dict mutating the caller's data in place: the serialized list_type_ string was replaced with the deserialized type, so a second from_dict call on the same dictionary failed and the dictionary could no longer be dumped to JSON or YAML. from_dict now works on a copy and the caller's data is left untouched.
TiktokenCounter no longer raises ValueError when message or tool content contains literal special-token strings such as <|endoftext|>. They are now encoded as ordinary text and counted, consistent with DocumentSplitter and RecursiveDocumentSplitter.
Fix LLMEvaluator input validation to reject malformed tuples and non-list types with ValueError.
LLMRanker now skips response indices that do not represent valid integers.
Fixed MetadataRouter.from_dict mutating the caller's serialized dictionary in place, which made a second from_dict call on the same dictionary fail.
Fix MSGToDocument incorrectly including Cc and Bcc recipients in the To line. To, Cc and Bcc now use transport headers when available, falling back to Outlook recipients when headers are missing or blank.
ChatMessage.from_openai_dict_format now accepts an empty string as content for user, system, developer, and tool messages instead of raising ValueError. Messages such as ChatMessage.from_tool(tool_result="", ...) or ChatMessage.from_user(text="") now round-trip through to_openai_dict_format.
Ensures PythonCodeSplitter emits syntactically valid chunks when strip_docstrings=True is used on a function or class whose docstring is its only statement.
Fixed an issue in PythonCodeSplitter where form feed characters (\f) and certain Unicode separators could cause functions to be split incorrectly across chunks. Chunk boundaries and the start_line / end_line metadata now remain correct when these characters appear in the source.
DocumentMRREvaluator, DocumentMAPEvaluator and DocumentNDCGEvaluator no longer count an empty comparison value as a match. Previously, when the document_comparison_field was an empty string on both a ground truth and a retrieved Document, for example meta.file_id="", unrelated Documents were scored as relevant and could get a perfect score. DocumentRecallEvaluator already ignored empty values. With the default content field, this also means a ground truth Document with content="" is now excluded. DocumentMRREvaluator and DocumentMAPEvaluator now log a warning when none of the ground truth Documents for a question has a valid comparison value, like DocumentRecallEvaluator does.
RecursiveDocumentSplitter with split_unit="word" no longer counts a whitespace-only piece, such as a page break (\f) or a tab between two spaces, as a word when measuring chunks against split_length. The word-mode fixed-size fallback already skipped them, so it produced chunks that the rest of the splitter measured as longer than split_length, and chunks split at separators held fewer real words than split_length whenever they contained a page break. With split_overlap, such a piece could also be taken as the overlapping word.
This changes the chunk boundaries for text containing page breaks or other whitespace surrounded by spaces. Re-split and re-index documents if you rely on stable chunk boundaries.
OpenAIResponsesChatGenerator and AzureOpenAIResponsesChatGenerator now accept chat histories with assistant messages produced by other providers, for example when FallbackChatGenerator switches from AmazonBedrockChatGenerator. Reasoning without a Responses API reasoning item id is dropped instead of being sent as an invalid input item, and tool calls without a call_id in extra use the tool call id as call_id. Previously, the API rejected these requests with a 400 error.
SASEvaluator now normalizes Cross Encoder scores based on the model instead of the scores in the batch. Previously, raw logits were only passed through a sigmoid if at least one score in the batch was above 1, so the same answer could get a different score depending on the other answers in the batch, and batches of only wrong answers returned negative scores. This affected models that return raw logits, such as cross-encoder/ms-marco-MiniLM-L-6-v2.
Fixed DocumentSplitter sentence-boundary overlap keeping one extra sentence when a sentence already contained exactly split_overlap words. The next chunk now stops at that word count instead of pulling in the sentence before it.
SlidingWindowCompactor no longer always removes the summary a SummarizationCompactor leaves in the current task. The summary is now kept or removed together with the Agent step after it. A summary at the start of history is now treated as the oldest historical turn.
Fixed StructuredOutputHook failing to parse JSON wrapped in Markdown code fences using CRLF line endings. Fenced replies using either LF or CRLF line endings are now stripped before structured-output parsing.
Fixed an issue where XLSXToDocument dropped literal text values such as "NA" and "N/A", converting them into empty cells. When neither keep_default_na nor na_values is supplied in read_excel_kwargs, the converter uses keep_default_na=False and na_values=[""] to preserve literal text while still recognizing empty cells as missing.
Fixed XLSXToDocument attaching hyperlinks to the wrong cells when read_excel_kwargs includes skiprows, usecols, or names.
HierarchicalDocumentSplitter now sets page_number and split_idx_start relative to the original document for documents below the first level. Previously they were counted from the start of the parent block, so deeper leaves reported the wrong page.
InMemoryDocumentStore.bm25_retrieval() and embedding_retrieval(), and their async variants, now raise a ValueError for a negative top_k. Previously, a negative value silently dropped documents from the end of the results, for example top_k=-1 returned 9 of 10 matches.
In JSONConverter, reject an extra_meta_fields value that is a string other than the literal '*' at component creation. Previously such a string was silently iterated character by character, producing meaningless metadata keys and dropping the intended fields from the converted documents.
PythonCodeSplitter with strip_docstrings=True no longer drops code that follows a docstring on the same line, such as """Docs."""; return 5. Previously the whole line was removed, silently deleting the statement and possibly leaving a chunk that fails to parse. In this case the docstring is now kept in the chunk content.
Pipeline.run_async() passed the values of a Variadic input, or a list input connected to several senders, in the order the senders finished, which could change between runs, so DocumentJoiner could apply its weights to the wrong retriever. Values now arrive in connection order, as in Pipeline.run(), with pipeline inputs passed directly to such a socket first. Pipeline.to_dict() now saves connections in the order they were made, so a pipeline loaded with Pipeline.from_dict() keeps the same order.
LinkContentFetcher no longer adds a text/plain entry to its handlers dictionary when it fetches content whose type matches no registered pattern (for example font/woff or multipart/form-data). Such content is still handled as text, as before.
LLM now declares exit_reason as an output, so it can be connected to other components in a Pipeline. It is one of "text" (a complete reply), "length" (the reply was cut off by the token limit) or "content_filter" (the reply was cut off by the provider's content filter), taken from the chat generator's finish_reason. For example, you can route a truncated reply to a retry with a higher max_tokens.
ConfirmationHook now marks the user message it adds when the user modifies a tool call's arguments with meta={"system_reminder": True}. SlidingWindowCompactor and SummarizationCompactor took that message for the user's task, so compaction could remove the real request. They now skip it when finding the task. StructuredOutputHook marks its correction messages the same way.
MarkdownHeaderSplitter no longer includes the optional closing sequence of an ATX header in the header and parent_headers metadata. For example, ## Install ## now produces the header Install instead of Install ##. The chunk content is unchanged.
MarkdownHeaderSplitter now follows the CommonMark rules for fenced code blocks, so # lines inside them are no longer split off as headers. A block can now close with a longer fence than the one that opened it, fences may be indented by up to three spaces, and a block that is never closed runs to the end of the document. A line that starts with inline code, where more backticks follow the opening ones on the same line, is not treated as a fence.
MarkdownHeaderSplitter now recognizes ATX headers with up to three leading spaces, preserving section boundaries and header hierarchy metadata for indented Markdown headers. Lines indented by four or more spaces remain ordinary content.
MarkdownToDocument with table_to_single_line=True now separates table cells with spaces and tables from surrounding content with newlines. Previously, cell contents and consecutive tables were concatenated without separators, losing word boundaries.
MetaFieldRanker now rejects a NaN weight in its constructor and in run() with a ValueError instead of returning documents with NaN scores.
MultiRetriever now raises a ValueError at initialization if join_mode is not "concatenate" or "reciprocal_rank_fusion". Previously, unsupported values such as "rrf" were silently treated as "concatenate" when top_k was not set.
OpenAIChatGenerator now works with tools on gpt-5.6 models, gpt-6-sol, and gpt-6-luna. Over the Chat Completions API, these models accept tools only with reasoning_effort="none" and returned HTTP 400 when tools were sent without it. When a request to one of these models includes tools and generation_kwargs doesn't set reasoning_effort, OpenAIChatGenerator now sends reasoning_effort="none", so these requests run without reasoning. To combine reasoning with tools, use OpenAIResponsesChatGenerator.
OpenAIResponsesChatGenerator and AzureOpenAIResponsesChatGenerator now raise a RuntimeError when a streamed response fails, that is when the stream ends with a response.failed event or contains an error event. Previously these events were ignored and the generator returned an empty reply without a finish reason, so the failure went unnoticed.
ByteStream.from_dict() now preserves subclasses when deserializing a dictionary, instead of always returning a ByteStream instance.
MockChatGenerator.from_dict() now preserves the supplied serialized configuration, so the same dictionary can be loaded more than once when using predefined responses, a response function, or a streaming callback.
Pipeline.run() no longer changes the visit counts stored in a PipelineSnapshot when resuming it. Replaying the same snapshot or retrying after a downstream failure now preserves the saved state and does not incorrectly exhaust max_runs_per_component.
Preserve field text, such as slide numbers, in PPTXToDocument when link_format is "markdown" or "plain". Field values in text boxes and table cells are kept in their original position alongside text and links.
Preserve all reasoning items returned by OpenAIResponsesChatGenerator in both streaming and non-streaming responses, including each item's ID and encrypted content. Individual items are stored in a single ReasoningContent.extra["reasoning_items"] list. Reasoning items and function calls retain their original relative order when replayed in a multi-turn conversation. Previously serialized single-item reasoning metadata remains supported.
PythonCodeSplitter now keeps decorators with the methods or classes they belong to, without copying them to other chunks. This also works with multiline decorators.
MetaFieldRanker now treats a NaN relevance score as out of range in linear_score mode. It logs the existing warning and defaults the score to 0 instead of sorting the document by a NaN score.
create_tool_from_function and the @tool decorator now raise ValueError when a required parameter name starts with an underscore, such as _tenant, and that parameter is not listed in inputs_from_state. Those names are not exposed to the LLM, so a tool created without the value could not be called. Provide the parameter through inputs_from_state or give it a default. Underscore-prefixed parameters that already have a default stay omitted from the schema.
Fix MultiQueryEmbeddingRetriever, MultiQueryTextRetriever, and TextEmbeddingRetriever sorting so documents without a score are placed after all scored documents, including documents with negative scores.
Runtime streaming callbacks now correctly override initialization callbacks, avoiding errors and warnings caused by unused callbacks. Callback selection also correctly handles callable objects that evaluate to false.
SearchableToolset now rejects catalog tools that share the bootstrap search tool name when the catalog has at least search_threshold tools. Previously, discovering such a tool produced duplicate names and failed the Agent run. Set search_tool_name to a different name to use that catalog.
create_tool_from_function and ComponentTool now exclude callback parameters wrapped in typing.Annotated from their tool schemas, including optional callbacks. Annotating a callback no longer causes tool construction to fail with SchemaGenerationError; the callback's default remains available when the tool is invoked.
ImageContent.from_file_path() now raises a ValueError naming the file when it cannot be converted to an image, for example because it does not exist or is not an image. Previously it raised an unhelpful IndexError: list index out of range.
SlidingWindowCompactor no longer removes system reminders from the current task, such as the ones StepBudgetReminderHook adds. Before, every compaction removed them, including a reminder added for the LLM call about to happen, which the model then never saw. Now a reminder is kept or removed together with the next assistant message and its tool results, and reminders after the last assistant message are always kept.
Fix StructuredOutputHook for list-typed state keys, such as {"type": list[str]}. The hook now replaces the state value with the validated result, or None on failure, instead of appending to it. Previously, a failed attempt followed by a successful retry returned [None, "Paris"] instead of ["Paris"].
StructuredOutputHook now honors max_retries when StepBudgetReminderHook (or another hook adding system_reminder messages) is registered. The hook counts its corrections since the last user message, and it treated each reminder as a new user turn, so the count reset every step: the Agent kept asking for corrections until max_agent_steps and stopped with exit_reason="max_agent_steps". Reminders are now skipped when counting.
create_tool_from_function and the @tool decorator now leave *args and **kwargs out of the Tool's parameters schema. Before, they were added as required parameters under their own names, such as args and kwargs, and the LLM was asked to fill them. A value the LLM sent for *args made the tool call fail with ToolInvocationError, and a value for **kwargs reached the function nested under the parameter's name. An untyped *args or **kwargs no longer raises a missing type hint ValueError.
Tool now rejects non-empty inputs_from_state mappings for tools that take no inputs. The error is raised when the tool is created instead of when it is invoked. If the callable's signature cannot be inspected, parameter names in inputs_from_state are not checked at construction time.
Fix FileSystemToolResultStore altering line endings in text results on Windows.
Pipeline.connect now accepts a Union output connected to a Union input when each member of the output fits a member of the input, in any order. For example, str | None connects to str | int | None, and list[Path | ByteStream] connects to the list[str | Path | ByteStream] input of converters such as TextFileToDocument. Before, the members were compared by position, and these connections raised PipelineConnectError. Literal types are matched the same way: Literal["b", "c"] now connects to Literal["a", "b", "c"].
OpenAIDocumentEmbedder and AzureOpenAIDocumentEmbedder now check batch_size when the component is created and raise a ValueError if it is not a positive integer, such as 0, -1, or 0.5 (for example ValueError: batch_size must be a positive integer, but got 0). Before this fix, an invalid batch_size was accepted without any error. The problem only appeared later, when run or run_async was called, with errors such as ValueError: n must be at least one that do not mention batch_size.
MultiRetriever, MultiQueryTextRetriever, MultiQueryEmbeddingRetriever, LLMMetadataExtractor and LLMDocumentContentExtractor now raise a ValueError at initialization when max_workers is smaller than 1. Previously the invalid value was accepted, run failed later inside ThreadPoolExecutor, and run_async silently treated it as 1.
@Aditya17-bot, @Afloat16, @amarthya-14, @anakin87, @anh-nguyenn, @aryamangodara, @Aurantium-47, @bogdankostic, @BugBuster18, @chrikrah, @D1822787566, @davidsbatista, @desty, @Dhruv-Patil-1720, @Elias-Sun, @Elonon901001, @emme1t, @erdogan-deniz, @Eryx-Z, @gauravch-code, @geyazheng, @Guo-Yixin, @Harbor404, @HareeshDaxton, @HarshitR2004, @hazelxue, @hermanrous, @hessamhzDS, @its-amann, @JackyHsu-X, @jaeminbird, @jeevan1098, @JimmyWang0417, @julian-risch, @kerthans, @kun654, @L4XB, @lalith0407, @lester076, @linhongyu510, @MALLADISARMA, @mengchen-atx, @mittalpk, @Naeemeh146, @nik13, @NotZhu, @pcbeingused333, @pei711, @porkedchop, @priy-anshugupta, @Quantum-Enigma-dot, @Revinand, @senthurapandi2000, @shivsin25, @shuaiyafei, @simin-yuan, @sjrl, @Smilewithoutfalling, @solitarybear, @Starchaser1024, @SuhrudhC, @sunhouy, @Tanishq-Choudhary, @TemitopeKadri, @Vedant-Agarwal, @Winoren, @wozhenbang2004, @Ytq1115, @yuv009
Your coding agent can read these notes before it upgrades. Set up the MCP server →
🧭 Classify and Route with the OpenAI Decisions API
Three new components use the OpenAI Decisions API to make choices about your data without writing a prompt. OpenAIDecisionsTextRouter sends text to a named output per label, OpenAIDecisionsImageRouter does the same for images and can send low-confidence decisions to a fallback branch, and OpenAIDecisionsDocumentClassifier answers choice, score, and yes/no questions about documents and stores the answers in their metadata.
from haystack.components.routers import OpenAIDecisionsTextRouter
router = OpenAIDecisionsTextRouter(
labels={
"billing": "Payments, invoices, refunds and charges",
"technical": "Bugs, crashes and errors in the product",
},
instructions="Which team should handle this support request?",
min_confidence=0.6,
)
print(router.run(text="I was charged twice for my subscription."))
# >> {'billing': 'I was charged twice for my subscription.'}The new StructuredOutputHook validates the Agent's final reply against a Pydantic model or JSON schema and returns it as a dict in result["structured_output"]. If the reply doesn't validate, the hook sends the error back to the model and lets it try again, up to max_retries times.
from pydantic import BaseModel
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.hooks.structured_output import StructuredOutputHook
class CityInfo(BaseModel):
city: str
country: str
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(generation_kwargs={"text_format": CityInfo}),
state_schema={"structured_output": {"type": dict}},
hooks={"on_exit": [StructuredOutputHook(schema=CityInfo)]},
)
result = agent.run(messages=[ChatMessage.from_user("Which city is the Eiffel Tower in?")])
print(result["structured_output"])
# >> {'city': 'Paris', 'country': 'France'}Also new for Agents: the experimental StepBudgetReminderHook tells the model how many steps it has left as it approaches max_agent_steps, so it wraps up with an answer instead of being cut off.
Document has a new multivector_embedding field for late-interaction models such as ColBERT, and the new MaxSimRanker reranks candidates by comparing each query vector to the document vectors and summing the best matches. DocumentJoiner(join_mode="merge_embeddings") can also combine dense, sparse, and multivector embeddings computed in parallel for the same documents.
This is the first step toward multivector retrieval in Haystack (#13257). Embedders that produce multivector embeddings are in progress in Haystack Core Integrations: Sentence Transformers and vLLM.
from haystack import Document
from haystack.components.rankers import MaxSimRanker
# Representative multivector embedding for "How do solar panels work?"
query_multivector_embedding = [[1.0, 0.0], [0.0, 1.0]]
documents = [
Document(content="Wind turbines generate electricity.", multivector_embedding=[[1.0, 0.0], [0.0, 0.2]]),
Document(content="Solar panels turn sunlight into power.", multivector_embedding=[[0.95, 0.05], [0.15, 0.9]]),
Document(content="Solar cells absorb light.", multivector_embedding=[[0.9, 0.1], [0.1, 0.9]]),
]
ranker = MaxSimRanker(top_k=2)
result = ranker.run(query_multivector_embedding=query_multivector_embedding, documents=documents)
for document in result["documents"]:
print(f"{document.score:.2f}: {document.content}")
# >> 1.85: Solar panels turn sunlight into power.
# >> 1.80: Solar cells absorb light.OpenAIChatGenerator, OpenAIResponsesChatGenerator, and the LLM-based evaluators now default to gpt-5.6-terra, the replacement OpenAI recommends for gpt-5-mini. OpenAI shuts down gpt-5-mini on December 11, 2026. Pipelines saved with model: gpt-5-mini keep using it, so update their YAML before then.
Raise the minimum supported openai SDK version from 2.6.0 to 3.26.0 to support the Decisions API.
Declared pydantic>=2.12 (>=2.14 on Python 3.15) as the minimum supported version. pydantic releases before 2.11 generate different JSON schemas for tool parameters in create_tool_from_function/@tool, ComponentTool, and PipelineTool.
If you don't set keep_default_na or na_values in read_excel_kwargs, XLSXToDocument now keeps cell text such as "NA", "N/A", "NULL", and "None" instead of treating it as missing. A numeric column that contains such text is therefore no longer converted to floats, so in CSV output its whole numbers render as 1 instead of 1.0. To restore the previous behavior, pass read_excel_kwargs={"keep_default_na": True}.
Components with a Variadic input, or a list input connected to several senders, now receive the values in the order the senders were connected with Pipeline.connect(). Before, Pipeline.run() passed them in the order the senders ran, so the results of order-dependent components such as DocumentJoiner with weights can change: connect the senders in the order you want the values to arrive.
If you load pipelines from YAML, check the order of your connections entries. Pipelines saved before this release list connections grouped by sender, not in the order they were made, and the order of the entries now decides the order in which a socket receives its values. For example, if embedding_retriever is listed before bm25_retriever in connections, DocumentJoiner now applies weights[0] to the embedding retriever, where before it could apply it to the BM25 retriever. Reorder the entries that feed a Variadic or multi-sender list socket so the senders come in the order you expect.
The default model of OpenAIChatGenerator and OpenAIResponsesChatGenerator changed from gpt-5-mini to gpt-5.6-terra, the replacement OpenAI recommends. OpenAI shuts down gpt-5-mini on December 11, 2026. LLMEvaluator, ContextRelevanceEvaluator, and FaithfulnessEvaluator use the new default too.
Pipelines serialized before this change store model: gpt-5-mini and keep using it. Update the model value in their YAML before December 11, 2026. To keep gpt-5-mini until then, pass it explicitly: OpenAIChatGenerator(model="gpt-5-mini").
If you read id, encrypted_content, or status directly from reply.reasoning.extra in OpenAIResponsesChatGenerator replies, read them from entries in reply.reasoning.extra["reasoning_items"] instead. For example, replace reply.reasoning.extra["id"] with reply.reasoning.extra["reasoning_items"][0]["id"] for the first item, or iterate over the list to handle all reasoning items.
OpenAIChatGenerator and AzureOpenAIChatGenerator now request token usage metadata by default when streaming. To restore the previous behavior, pass generation_kwargs={"stream_options": {"include_usage": False}}.
max_agent_steps is now a reserved state key on Agent. If you defined a custom state_schema key named max_agent_steps, rename it (e.g. my_max_agent_steps): the Agent now raises a ValueError at initialization when a reserved key is redefined.
Add the optional multivector_embedding field to Document to store multi-vector representation such as those generated by late-interaction models like ColBERT. This is a first step toward supporting multivector embedders, retrievers, and rankers.
Add MaxSimRanker to rank documents by their similarity to a query using precomputed multivector embeddings. In two-stage retrieval, an embedding retriever can quickly select candidates using dense similarity, then MaxSimRanker performs a more fine-grained comparison of the query and each candidate's content to return the most relevant documents.
Add OpenAIDecisionsDocumentClassifier to answer choice, score, and predicate questions about documents using the OpenAI Decisions API. Answers are stored in document metadata.
Add OpenAIDecisionsImageRouter to route images to different pipeline branches based on their content, with optional text context. Images with low-confidence decisions can be sent to a fallback branch.
Add OpenAIDecisionsTextRouter to route text to named categories using the OpenAI Decisions API.
Added StructuredOutputHook to haystack.hooks.structured_output. Registered under on_exit, it parses the Agent's final reply as JSON, validates it against a Pydantic model or a JSON schema, and stores the result as a dict under the structured_output key by default. The key must be declared in the Agent's state_schema, otherwise the hook raises an error at runtime.
When a reply can't be parsed, the hook sends the validation error back to the model and keeps the Agent running so it can correct its reply, up to max_retries times (2 by default). When the reply still can't be parsed, or the Agent stops on another exit condition, None is stored.
from pydantic import BaseModel
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.hooks.structured_output import StructuredOutputHook
class CityInfo(BaseModel):
city: str
country: str
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(generation_kwargs={"text_format": CityInfo}),
state_schema={"structured_output": {"type": dict}},
hooks={"on_exit": [StructuredOutputHook(schema=CityInfo)]},
)
result = agent.run(messages=[ChatMessage.from_user("Which city is the Eiffel Tower in?")])
print(result["structured_output"])
# {'city': 'Paris', 'country': 'France'}DocumentJoiner now supports join_mode="merge_embeddings" to combine the embedding and sparse_embedding fields of documents with the same ID. This allows dense and sparse document embedders to run in parallel and their outputs to be combined before passing them to DocumentWriter.
Added StepBudgetReminderHook (experimental), a before_llm hook that tells the model how many steps it has left once an Agent run gets close to max_agent_steps. Before each of the last remind_within_steps LLM calls, it adds a user message wrapped in <system-reminder> tags, such as "You have 2 of 10 steps remaining", and on the last step asks for the final answer. This lets the Agent wrap up instead of being cut off mid-investigation.
from haystack.hooks.budget import StepBudgetReminderHook
agent = Agent(
chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
tools=[search],
max_agent_steps=20,
hooks={"before_llm": [StepBudgetReminderHook(remind_within_steps=3)]},
)Reminder messages are marked with meta={"system_reminder": True}. Context compaction recognizes the marker and never treats a reminder as the user's task.
delete_by_filter_async() method to InMemoryDocumentStore. Previously, only the sync delete_by_filter() was available, unlike the other methods of the store, which all have an async counterpart. The new method runs delete_by_filter() in the store's thread-pool executor and returns the number of deleted documents.modify_template of BlockingConfirmationStrategy now tells the LLM that the user wants the result of the modified tool call used and that it should not call the tool again with the original arguments. With the previous wording, models often repeated the original tool call after a user modified its parameters. Pass modify_template explicitly to keep the previous message.DocumentJoiner(join_mode="merge_embeddings") now supports multivector embeddings in addition to dense and sparse embeddings when combining documents with the same ID.OpenAIChatGenerator now includes several methods to make it easier for subclasses to customize the component's behavior while reducing code duplication.Document objects and pipeline inputs are now faster, with the same results as before. Document now implements __deepcopy__, which copies the embedding list in one step instead of element by element. Pipeline also returns immutable values such as strings and numbers unchanged when copying component inputs, without running the more expensive checks meant for other objects. Pipelines that pass embeddings or many embedded documents between components benefit most.EvaluationRunResult.comparative_detailed_report has a new align_on parameter to match the rows of the two runs by an input column, such as a question ID or the question itself, instead of by position. This compares runs correctly even if they evaluated the same questions in a different order, or not all of the same questions. Rows without a match are kept with None for the other run.HierarchicalDocumentSplitter now supports split_by="token" (requires pip install tiktoken), with the encoding set by the new tokenizer_encoding parameter (default "o200k_base"). A new warm_up() method loads the tokenizer up front instead of on the first run().PPTXToDocument now extracts text from grouped shapes and tables, which were previously skipped. Tables are included in the document content as CSV.OpenAIChatGenerator and OpenAIResponsesChatGenerator now preserve OpenAI API refusals in ChatMessage.meta["refusal"]. Applications can inspect this metadata to detect and handle refusals.OpenAIResponsesChatGenerator now preserves text annotations in reply.meta["annotations"], with aligned annotation_offsets for locating citations in the concatenated reply text.tokenizer_encoding parameter to RecursiveDocumentSplitter to choose the tiktoken encoding used when split_unit="token", as in DocumentSplitter. It defaults to "o200k_base", the encoding used until now. Set it to match your model, for example "cl100k_base" for OpenAI's text-embedding-3 models, so that chunks fit the model's token limit.RecursiveDocumentSplitter now validates split_unit at initialization, raising a ValueError for values other than "word", "char", or "token" instead of failing later during run().max_agent_steps state key, for example with state.get("max_agent_steps"). It is not returned as an Agent output.Fixed Agent losing token counts in token_usage when a later LLM call reports a usage field as null, for example prompt_tokens_details reported on one call and null on the next. A null value now counts as not reported, so the totals no longer depend on the order of the calls.
FilterRetriever, AutoMergingRetriever, SentenceWindowRetriever, CacheChecker and DocumentWriter now work with document stores that implement only the synchronous API. Their run_async methods use the store's async method when it exists and otherwise run the synchronous one in a worker thread, instead of failing on the missing async method.
Fix AutoMergingRetriever.run() and run_async() when retrieved leaves from HierarchicalDocumentSplitter have different depths. Shallower leaves now merge together with siblings promoted from deeper branches, preventing missed parent merges and duplicate parent documents in the retrieved context.
ComponentTool now skips unknown invocation arguments with a warning instead of raising KeyError, including extra properties in custom schemas and arguments added by the LLM. Custom schemas with unknown properties also produce a warning during construction. A ValueError is raised when a custom schema omits mandatory component inputs not provided through inputs_from_state. Automatically injected State inputs are excluded. This also applies to AgentTool when a custom parameters schema omits messages and it is not provided through inputs_from_state. Previously, construction succeeded but invocation failed because the required input was missing.
ImageContent.from_dict, FileContent.from_dict and TextContent.from_dict now build the calling class instead of the base class, so a subclass survives a to_dict / from_dict round trip. This matches the behaviour of ByteStream.from_dict.
Fixed DocumentCleaner removing indentation and newlines at the start and end of every page when remove_regex was set, even on pages where the regex matched nothing. Pages without a match are now left unchanged, which preserves Markdown and code content when remove_extra_whitespaces, remove_empty_lines and strip_whitespaces are disabled. Pages where the regex matches are still stripped as before.
DocumentJoiner now raises a ValueError when weights contains NaN or infinite values. Previously, these values were accepted and turned the document scores into NaN in the merge and reciprocal_rank_fusion join modes.
DOCXToDocument now reads text that a paragraph keeps inside a tracked insertion, moved text, a smart tag, custom XML, a simple field or a filled-in inline content control. Previously only a paragraph's direct runs and hyperlinks were read, so a document with unaccepted tracked changes lost every inserted word, and a filled form field lost its value. Deleted text, the old place of moved text and content controls that still show their placeholder prompt are left out, as the document does not show them.
DocumentRecallEvaluator and DocumentNDCGEvaluator now support list and dictionary metadata values in document_comparison_field instead of raising TypeError. Nested values are supported, and duplicate documents retain the existing recall and relevance scoring behavior.
FileTypeRouter no longer loses the detected MIME type when meta is passed alongside file paths.
Fix AutoMergingRetriever incorrectly counting duplicate child documents when evaluating merge thresholds. Documents are now deduplicated by ID before merging, retaining the highest-scoring copy in both synchronous and asynchronous retrieval.
EvaluationRunResult.comparative_detailed_report no longer drops the first run's scores when both runs have the same run_name. Their columns are named with _first and _second again, as they were before the report stopped using pandas. When align_on isn't set and the two runs have a different number of rows, it logs a warning and pads the shorter run with None instead of returning columns of different lengths.
DocumentToImageContent now skips an image file that cannot be decoded instead of failing the whole run() call. The skipped document gets None in image_contents and a warning is logged.
ImageFileToImageContent now skips a source that is not a valid image instead of failing the whole run() call. A non-image file in a mixed batch, such as a .txt file, is logged and omitted from image_contents, while the other sources are still converted.
Fixed ListJoiner.from_dict mutating the caller's data in place: the serialized list_type_ string was replaced with the deserialized type, so a second from_dict call on the same dictionary failed and the dictionary could no longer be dumped to JSON or YAML. from_dict now works on a copy and the caller's data is left untouched.
TiktokenCounter no longer raises ValueError when message or tool content contains literal special-token strings such as <|endoftext|>. They are now encoded as ordinary text and counted, consistent with DocumentSplitter and RecursiveDocumentSplitter.
Fix LLMEvaluator input validation to reject malformed tuples and non-list types with ValueError.
LLMRanker now skips response indices that do not represent valid integers.
Fixed MetadataRouter.from_dict mutating the caller's serialized dictionary in place, which made a second from_dict call on the same dictionary fail.
Fix MSGToDocument incorrectly including Cc and Bcc recipients in the To line. To, Cc and Bcc now use transport headers when available, falling back to Outlook recipients when headers are missing or blank.
ChatMessage.from_openai_dict_format now accepts an empty string as content for user, system, developer, and tool messages instead of raising ValueError. Messages such as ChatMessage.from_tool(tool_result="", ...) or ChatMessage.from_user(text="") now round-trip through to_openai_dict_format.
Ensures PythonCodeSplitter emits syntactically valid chunks when strip_docstrings=True is used on a function or class whose docstring is its only statement.
Fixed an issue in PythonCodeSplitter where form feed characters (\f) and certain Unicode separators could cause functions to be split incorrectly across chunks. Chunk boundaries and the start_line / end_line metadata now remain correct when these characters appear in the source.
DocumentMRREvaluator, DocumentMAPEvaluator and DocumentNDCGEvaluator no longer count an empty comparison value as a match. Previously, when the document_comparison_field was an empty string on both a ground truth and a retrieved Document, for example meta.file_id="", unrelated Documents were scored as relevant and could get a perfect score. DocumentRecallEvaluator already ignored empty values. With the default content field, this also means a ground truth Document with content="" is now excluded. DocumentMRREvaluator and DocumentMAPEvaluator now log a warning when none of the ground truth Documents for a question has a valid comparison value, like DocumentRecallEvaluator does.
RecursiveDocumentSplitter with split_unit="word" no longer counts a whitespace-only piece, such as a page break (\f) or a tab between two spaces, as a word when measuring chunks against split_length. The word-mode fixed-size fallback already skipped them, so it produced chunks that the rest of the splitter measured as longer than split_length, and chunks split at separators held fewer real words than split_length whenever they contained a page break. With split_overlap, such a piece could also be taken as the overlapping word.
This changes the chunk boundaries for text containing page breaks or other whitespace surrounded by spaces. Re-split and re-index documents if you rely on stable chunk boundaries.
OpenAIResponsesChatGenerator and AzureOpenAIResponsesChatGenerator now accept chat histories with assistant messages produced by other providers, for example when FallbackChatGenerator switches from AmazonBedrockChatGenerator. Reasoning without a Responses API reasoning item id is dropped instead of being sent as an invalid input item, and tool calls without a call_id in extra use the tool call id as call_id. Previously, the API rejected these requests with a 400 error.
SASEvaluator now normalizes Cross Encoder scores based on the model instead of the scores in the batch. Previously, raw logits were only passed through a sigmoid if at least one score in the batch was above 1, so the same answer could get a different score depending on the other answers in the batch, and batches of only wrong answers returned negative scores. This affected models that return raw logits, such as cross-encoder/ms-marco-MiniLM-L-6-v2.
Fixed DocumentSplitter sentence-boundary overlap keeping one extra sentence when a sentence already contained exactly split_overlap words. The next chunk now stops at that word count instead of pulling in the sentence before it.
SlidingWindowCompactor no longer always removes the summary a SummarizationCompactor leaves in the current task. The summary is now kept or removed together with the Agent step after it. A summary at the start of history is now treated as the oldest historical turn.
Fixed StructuredOutputHook failing to parse JSON wrapped in Markdown code fences using CRLF line endings. Fenced replies using either LF or CRLF line endings are now stripped before structured-output parsing.
Fixed an issue where XLSXToDocument dropped literal text values such as "NA" and "N/A", converting them into empty cells. When neither keep_default_na nor na_values is supplied in read_excel_kwargs, the converter uses keep_default_na=False and na_values=[""] to preserve literal text while still recognizing empty cells as missing.
Fixed XLSXToDocument attaching hyperlinks to the wrong cells when read_excel_kwargs includes skiprows, usecols, or names.
HierarchicalDocumentSplitter now sets page_number and split_idx_start relative to the original document for documents below the first level. Previously they were counted from the start of the parent block, so deeper leaves reported the wrong page.
InMemoryDocumentStore.bm25_retrieval() and embedding_retrieval(), and their async variants, now raise a ValueError for a negative top_k. Previously, a negative value silently dropped documents from the end of the results, for example top_k=-1 returned 9 of 10 matches.
In JSONConverter, reject an extra_meta_fields value that is a string other than the literal '*' at component creation. Previously such a string was silently iterated character by character, producing meaningless metadata keys and dropping the intended fields from the converted documents.
PythonCodeSplitter with strip_docstrings=True no longer drops code that follows a docstring on the same line, such as """Docs."""; return 5. Previously the whole line was removed, silently deleting the statement and possibly leaving a chunk that fails to parse. In this case the docstring is now kept in the chunk content.
Pipeline.run_async() passed the values of a Variadic input, or a list input connected to several senders, in the order the senders finished, which could change between runs, so DocumentJoiner could apply its weights to the wrong retriever. Values now arrive in connection order, as in Pipeline.run(), with pipeline inputs passed directly to such a socket first. Pipeline.to_dict() now saves connections in the order they were made, so a pipeline loaded with Pipeline.from_dict() keeps the same order.
LinkContentFetcher no longer adds a text/plain entry to its handlers dictionary when it fetches content whose type matches no registered pattern (for example font/woff or multipart/form-data). Such content is still handled as text, as before.
LLM now declares exit_reason as an output, so it can be connected to other components in a Pipeline. It is one of "text" (a complete reply), "length" (the reply was cut off by the token limit) or "content_filter" (the reply was cut off by the provider's content filter), taken from the chat generator's finish_reason. For example, you can route a truncated reply to a retry with a higher max_tokens.
ConfirmationHook now marks the user message it adds when the user modifies a tool call's arguments with meta={"system_reminder": True}. SlidingWindowCompactor and SummarizationCompactor took that message for the user's task, so compaction could remove the real request. They now skip it when finding the task. StructuredOutputHook marks its correction messages the same way.
MarkdownHeaderSplitter no longer includes the optional closing sequence of an ATX header in the header and parent_headers metadata. For example, ## Install ## now produces the header Install instead of Install ##. The chunk content is unchanged.
MarkdownHeaderSplitter now follows the CommonMark rules for fenced code blocks, so # lines inside them are no longer split off as headers. A block can now close with a longer fence than the one that opened it, fences may be indented by up to three spaces, and a block that is never closed runs to the end of the document. A line that starts with inline code, where more backticks follow the opening ones on the same line, is not treated as a fence.
MarkdownHeaderSplitter now recognizes ATX headers with up to three leading spaces, preserving section boundaries and header hierarchy metadata for indented Markdown headers. Lines indented by four or more spaces remain ordinary content.
MarkdownToDocument with table_to_single_line=True now separates table cells with spaces and tables from surrounding content with newlines. Previously, cell contents and consecutive tables were concatenated without separators, losing word boundaries.
MetaFieldRanker now rejects a NaN weight in its constructor and in run() with a ValueError instead of returning documents with NaN scores.
MultiRetriever now raises a ValueError at initialization if join_mode is not "concatenate" or "reciprocal_rank_fusion". Previously, unsupported values such as "rrf" were silently treated as "concatenate" when top_k was not set.
OpenAIChatGenerator now works with tools on gpt-5.6 models, gpt-6-sol, and gpt-6-luna. Over the Chat Completions API, these models accept tools only with reasoning_effort="none" and returned HTTP 400 when tools were sent without it. When a request to one of these models includes tools and generation_kwargs doesn't set reasoning_effort, OpenAIChatGenerator now sends reasoning_effort="none", so these requests run without reasoning. To combine reasoning with tools, use OpenAIResponsesChatGenerator.
OpenAIResponsesChatGenerator and AzureOpenAIResponsesChatGenerator now raise a RuntimeError when a streamed response fails, that is when the stream ends with a response.failed event or contains an error event. Previously these events were ignored and the generator returned an empty reply without a finish reason, so the failure went unnoticed.
ByteStream.from_dict() now preserves subclasses when deserializing a dictionary, instead of always returning a ByteStream instance.
MockChatGenerator.from_dict() now preserves the supplied serialized configuration, so the same dictionary can be loaded more than once when using predefined responses, a response function, or a streaming callback.
Pipeline.run() no longer changes the visit counts stored in a PipelineSnapshot when resuming it. Replaying the same snapshot or retrying after a downstream failure now preserves the saved state and does not incorrectly exhaust max_runs_per_component.
Preserve field text, such as slide numbers, in PPTXToDocument when link_format is "markdown" or "plain". Field values in text boxes and table cells are kept in their original position alongside text and links.
Preserve all reasoning items returned by OpenAIResponsesChatGenerator in both streaming and non-streaming responses, including each item's ID and encrypted content. Individual items are stored in a single ReasoningContent.extra["reasoning_items"] list. Reasoning items and function calls retain their original relative order when replayed in a multi-turn conversation. Previously serialized single-item reasoning metadata remains supported.
PythonCodeSplitter now keeps decorators with the methods or classes they belong to, without copying them to other chunks. This also works with multiline decorators.
MetaFieldRanker now treats a NaN relevance score as out of range in linear_score mode. It logs the existing warning and defaults the score to 0 instead of sorting the document by a NaN score.
create_tool_from_function and the @tool decorator now raise ValueError when a required parameter name starts with an underscore, such as _tenant, and that parameter is not listed in inputs_from_state. Those names are not exposed to the LLM, so a tool created without the value could not be called. Provide the parameter through inputs_from_state or give it a default. Underscore-prefixed parameters that already have a default stay omitted from the schema.
Fix MultiQueryEmbeddingRetriever, MultiQueryTextRetriever, and TextEmbeddingRetriever sorting so documents without a score are placed after all scored documents, including documents with negative scores.
Runtime streaming callbacks now correctly override initialization callbacks, avoiding errors and warnings caused by unused callbacks. Callback selection also correctly handles callable objects that evaluate to false.
SearchableToolset now rejects catalog tools that share the bootstrap search tool name when the catalog has at least search_threshold tools. Previously, discovering such a tool produced duplicate names and failed the Agent run. Set search_tool_name to a different name to use that catalog.
create_tool_from_function and ComponentTool now exclude callback parameters wrapped in typing.Annotated from their tool schemas, including optional callbacks. Annotating a callback no longer causes tool construction to fail with SchemaGenerationError; the callback's default remains available when the tool is invoked.
ImageContent.from_file_path() now raises a ValueError naming the file when it cannot be converted to an image, for example because it does not exist or is not an image. Previously it raised an unhelpful IndexError: list index out of range.
SlidingWindowCompactor no longer removes system reminders from the current task, such as the ones StepBudgetReminderHook adds. Before, every compaction removed them, including a reminder added for the LLM call about to happen, which the model then never saw. Now a reminder is kept or removed together with the next assistant message and its tool results, and reminders after the last assistant message are always kept.
Fix StructuredOutputHook for list-typed state keys, such as {"type": list[str]}. The hook now replaces the state value with the validated result, or None on failure, instead of appending to it. Previously, a failed attempt followed by a successful retry returned [None, "Paris"] instead of ["Paris"].
StructuredOutputHook now honors max_retries when StepBudgetReminderHook (or another hook adding system_reminder messages) is registered. The hook counts its corrections since the last user message, and it treated each reminder as a new user turn, so the count reset every step: the Agent kept asking for corrections until max_agent_steps and stopped with exit_reason="max_agent_steps". Reminders are now skipped when counting.
create_tool_from_function and the @tool decorator now leave *args and **kwargs out of the Tool's parameters schema. Before, they were added as required parameters under their own names, such as args and kwargs, and the LLM was asked to fill them. A value the LLM sent for *args made the tool call fail with ToolInvocationError, and a value for **kwargs reached the function nested under the parameter's name. An untyped *args or **kwargs no longer raises a missing type hint ValueError.
Tool now rejects non-empty inputs_from_state mappings for tools that take no inputs. The error is raised when the tool is created instead of when it is invoked. If the callable's signature cannot be inspected, parameter names in inputs_from_state are not checked at construction time.
Fix FileSystemToolResultStore altering line endings in text results on Windows.
Pipeline.connect now accepts a Union output connected to a Union input when each member of the output fits a member of the input, in any order. For example, str | None connects to str | int | None, and list[Path | ByteStream] connects to the list[str | Path | ByteStream] input of converters such as TextFileToDocument. Before, the members were compared by position, and these connections raised PipelineConnectError. Literal types are matched the same way: Literal["b", "c"] now connects to Literal["a", "b", "c"].
OpenAIDocumentEmbedder and AzureOpenAIDocumentEmbedder now check batch_size when the component is created and raise a ValueError if it is not a positive integer, such as 0, -1, or 0.5 (for example ValueError: batch_size must be a positive integer, but got 0). Before this fix, an invalid batch_size was accepted without any error. The problem only appeared later, when run or run_async was called, with errors such as ValueError: n must be at least one that do not mention batch_size.
MultiRetriever, MultiQueryTextRetriever, MultiQueryEmbeddingRetriever, LLMMetadataExtractor and LLMDocumentContentExtractor now raise a ValueError at initialization when max_workers is smaller than 1. Previously the invalid value was accepted, run failed later inside ThreadPoolExecutor, and run_async silently treated it as 1.
@Aditya17-bot, @Afloat16, @amarthya-14, @anakin87, @anh-nguyenn, @aryamangodara, @Aurantium-47, @bogdankostic, @BugBuster18, @chrikrah, @D1822787566, @davidsbatista, @desty, @Dhruv-Patil-1720, @Elias-Sun, @Elonon901001, @emme1t, @erdogan-deniz, @Eryx-Z, @gauravch-code, @geyazheng, @Guo-Yixin, @Harbor404, @HareeshDaxton, @HarshitR2004, @hazelxue, @hermanrous, @hessamhzDS, @its-amann, @JackyHsu-X, @jaeminbird, @jeevan1098, @JimmyWang0417, @julian-risch, @kerthans, @kun654, @L4XB, @lalith0407, @lester076, @linhongyu510, @MALLADISARMA, @mengchen-atx, @mittalpk, @Naeemeh146, @nik13, @NotZhu, @pcbeingused333, @pei711, @porkedchop, @priy-anshugupta, @Quantum-Enigma-dot, @Revinand, @senthurapandi2000, @shivsin25, @shuaiyafei, @simin-yuan, @sjrl, @Smilewithoutfalling, @solitarybear, @Starchaser1024, @SuhrudhC, @sunhouy, @Tanishq-Choudhary, @TemitopeKadri, @Vedant-Agarwal, @Winoren, @wozhenbang2004, @Ytq1115, @yuv009
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Haystack now requires certifi>=2026.10.19. certifi is installed transitively through httpx and posthog; earlier versions trust eMudhra/emSign certific
certifi>=2026.10.19. certifi is installed transitively through httpx and posthog; earlier versions trust eMudhra/emSign certificate authorities whose private keys were compromised (GHSA-6q48-6c7w-9gw2). If you pin certifi, raise the pin to at least 2026.10.19.Nothing published for this version
Nothing published for this version
Haystack now officially supports Python 3.15. Python 3.10 reaches end of life in October 2026, so the minimum supported version is now 3.11. ⚠️
Haystack now officially supports Python 3.15. Python 3.10 reaches end of life in October 2026, so the minimum supported version is now 3.11. ⚠️
The experimental ToolResultOffloadCompactor is a new compaction strategy for CompactionHook. When compaction is triggered, it doesn't drop or summarize older tool results. It writes them to a ToolResultStore and leaves a reference in their place. The Agent can read the full output back on demand with a read tool scoped to the same store. Fresh results stay in context until compaction kicks in, so short runs pay nothing extra.
from typing import Annotated
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, ToolResultOffloadCompactor
from haystack.hooks.tool_result_offloading import FileSystemToolResultStore
from haystack.tools import tool
store = FileSystemToolResultStore(root="tool_results")
@tool
def read_offloaded_result(path: Annotated[str, "Path of an offloaded tool result"]) -> str:
"""Read back the full content of an offloaded tool result."""
content = store.read(path)
if isinstance(content, bytes):
return f"'{path}' holds {len(content)} bytes of binary content and cannot be read as text."
return content
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
tools=[web_search, read_offloaded_result],
hooks={"before_llm": [CompactionHook(compactor=ToolResultOffloadCompactor(store=store), context_window=400_000)]},
)
The page_number metadata field now means the same thing in every splitter: the page the chunk's text starts on. Two cases change:
RecursiveDocumentSplitter reported the page a chunk ended on. A chunk spanning a page break now reports the page it starts on, matching DocumentSplitter and MarkdownHeaderSplitter.DocumentSplitter, MarkdownHeaderSplitter and EmbeddingBasedDocumentSplitter reported the previous page for a chunk that began with one or more form feeds (\f), even though all of the chunk's text was on the following page. Such chunks now report the page their text is on. A chunk made up entirely of page breaks is an empty page and keeps the page it starts on, so blank pages emitted by split_by="page" still get their own number.If you display page_number to users or store it alongside embeddings, re-index documents that contain form feeds to pick up the corrected values.
RecursiveDocumentSplitter with split_unit="word" and split_overlap greater than 0 now returns chunks copied from the document as they are. Previously it rebuilt them from their words joined by single spaces, which added spaces the document does not have, collapsed line breaks and repeated spaces, and could drop form feeds (\f). The overlap also counts words the way split_length does, as text separated by spaces, so where words are separated only by line or page breaks, chunks can end at different words than before. Re-index documents split this way if you need their chunks to match the source text.
RecursiveDocumentSplitter now keeps the whitespace between sentences when sentence_splitter_params sets keep_white_spaces to False. That is the sentence tokenizer's default, so this applies whenever sentence_splitter_params is passed without "keep_white_spaces": True. The tokenizer leaves that whitespace out, and the chunks used to glue their sentences together, as in "One two.Three four.": the glued words counted as one toward split_length, page breaks (\f) between sentences were lost, and split_idx_start and page_number fell behind the chunk's real start. Chunks are now copied from the document whatever keep_white_spaces is set to; it only changes the rules the tokenizer uses to decide where a sentence ends. Re-index documents split with this setting to pick up the corrected chunks.
Dropped support for Python 3.10 since it reaches End of Life (EOL) in October 2026. The minimum supported Python version is now 3.11. If you are on Python 3.10, upgrade your Python version before upgrading Haystack.
FilterPolicy.MERGE now intersects initialization and runtime logical filters when both use OR or NOT. Callers that relied on the previous broader result should construct a single explicit OR filter containing all alternatives and pass it with FilterPolicy.REPLACE instead.
ChatMessage.from_openai_dict_format now raises a ValueError for content parts it can't convert: images referenced by a URL such as https://example.com/image.png (only images embedded as base64 data URLs, like data:image/png;base64,..., are supported), files referenced by file_id, and other part types such as input_audio. Previously, such messages were accepted because the whole list was stored as a single text, and ChatMessage.to_openai_dict_format sent that list back unchanged, so forwarding them to OpenAI worked by accident. You're affected if the OpenAI messages you convert contain any of these parts. To keep sending images by URL, download them and build the message yourself, for example ChatMessage.from_user(content_parts=["Describe this image", ImageContent.from_url(url)]). Send files inline as base64 file_data instead of referencing them by file_id. Extra keys on content parts, such as cache_control, are no longer passed through, so prompt caching through OpenRouter or LiteLLM stops for these messages.
HTMLToDocument now defaults to encoding=None, delegating HTML encoding detection to Trafilatura. Set encoding="utf-8" to retain explicit UTF-8 decoding.
Previously, HTMLToDocument used the encoding value in a source ByteStream's metadata to decode its content, overriding the converter's encoding setting. This metadata no longer affects decoding. If you relied on it, pass the encoding to the converter instead, for example HTMLToDocument(encoding="latin-1").
The default model for OpenAITextEmbedder, OpenAIDocumentEmbedder, AzureOpenAITextEmbedder, and AzureOpenAIDocumentEmbedder has been changed from text-embedding-ada-002 to text-embedding-3-small.
text-embedding-3-small is roughly 5x cheaper per token than the previous generation text-embedding-ada-002 and scores higher on the MTEB benchmark (see OpenAI's announcement).
To preserve previous behavior, pass model="text-embedding-ada-002" explicitly (or, for the Azure variants, azure_deployment="text-embedding-ada-002").
Note for Azure users: azure_deployment refers to the deployment name in your Azure OpenAI resource, not a model identifier. If you do not already have a text-embedding-3-small deployment in Azure, you will need to create one or pass the name of an existing deployment explicitly.
Embeddings generated with the new default model are not compatible with embeddings produced by text-embedding-ada-002. If you have a document store populated with previously-generated embeddings, either keep using the old model explicitly or re-embed your corpus.
The base Tool.warm_up() and Toolset.warm_up() methods were removed. OpenAI/Azure Chat Generators no longer warm up tools.
If you use tools through an Agent, no changes are needed. For manual preparation, use warm_up_tools or warm_up_tools_async. Lazy toolsets such as MCPToolset must be warmed up before passing them to a Chat Generator.
Added the experimental ToolResultOffloadCompactor for CompactionHook. Once compaction is triggered, it writes older tool results to a ToolResultStore and leaves a reference in their place, so the Agent can read the full output back with a read tool you scope to the same store. Fresh results stay in context until then.
from typing import Annotated
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, ToolResultOffloadCompactor
from haystack.hooks.tool_result_offloading import FileSystemToolResultStore
from haystack.tools import tool
store = FileSystemToolResultStore(root="tool_results")
@tool
def read_offloaded_result(path: Annotated[str, "Path of an offloaded tool result"]) -> str:
"""Read back the full content of an offloaded tool result."""
content = store.read(path)
if isinstance(content, bytes):
return f"'{path}' holds {len(content)} bytes of binary content and cannot be read as text."
return content
# web_search stands in for your own tool that returns long results.
hook = CompactionHook(compactor=ToolResultOffloadCompactor(store=store), context_window=400_000)
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
tools=[web_search, read_offloaded_result],
hooks={"before_llm": [hook]},
)
When an Agent runs inside a Pipeline, the anonymous pipeline telemetry event now also reports the chat generator class and its tools: the number of tools, the class and name of each tool, the component wrapped by each ComponentTool, and the classes of any Toolset objects.
Haystack now officially supports Python 3.15.
Removed the Sockets.__getattribute__ override. It looked up a _sockets attribute that no instance has, so on every attribute access it raised and caught AttributeError and never returned a socket; socket access has always gone through the copies __init__ and __setitem__ put in __dict__. Without the override, accessing a socket attribute such as component.__haystack_input__.query is about 14x faster.
HTMLToDocument now uses Trafilatura's encoding detection instead of assuming UTF-8, allowing non-UTF-8 sources to be converted without manually specifying their encoding. If conversion produces incorrect characters, install trafilatura[all] for additional encoding detection support, or set the converter's encoding explicitly.
LLMEvaluator fallback warnings now name the component class, for example FaithfulnessEvaluator, and say that the result for a failed input is set to None. A response that isn't valid JSON or is missing the expected keys now gets its own warning with the response and the parsing error.
LLMRanker fallback warnings for an empty query, a chat generation failure and a response parsing failure now consistently say the deduplicated input documents are returned unranked, so the fallback order isn't mistaken for a ranking.
QueryExpander fallback warnings now say what is returned: only the original query, or no queries when include_original_query is False. QueryExpander now also warns when the ChatGenerator response isn't valid JSON, including the response and the parsing error, and when the response contains no valid queries.
When no chat_generator is passed, LLMRanker and QueryExpander now use OpenAIResponsesChatGenerator instead of OpenAIChatGenerator, with the same model and temperature. The default generator sets "store": False so OpenAI does not keep the requests and responses.
Agent now uses its close()/close_async() methods to release its configured tools and supports asynchronous tool preparation using warm_up_async(). Invoking a tool directly through tool.invoke() or tool.invoke_async() automatically calls its warm-up methods when available.
This enables tools to manage synchronous and asynchronous resources separately. We'll update tools in Haystack Core Integrations to take advantage of this support.
When a tool call made by Agent fails, its haystack.agent.step.tool tracing span now carries the tag haystack.tool.error set to True. Tracers can use it to mark the span as failed, so a failed call is no longer indistinguishable from a tool that returns an {"error": ...} dict. The tag is set even when content tracing is disabled.
DOCXToDocument dropping the fragment of an external link when Word stores it separately in the w:anchor attribute instead of the hyperlink address. For example, a link to https://example.org/manual#refund-policy was converted to https://example.org/manual with both the markdown and the plain link_format option. The complete link target, including the fragment, is now preserved.RecursiveDocumentSplitter assigning page_number values that drifted upwards, and could exceed the number of pages in the document, when split_overlap was greater than 0. A page break repeated in an overlapping tail was counted once per chunk it appeared in. page_number is now derived from the chunk's offset in the source document instead of a running counter, so a repeated page break cannot be counted twice.RecursiveDocumentSplitter reporting split_idx_start values past the chunk's real start when split_unit="word" and split_overlap was greater than 0, which also pushed page_number onto pages the chunk had not reached yet. split_idx_start now points at the chunk's start in the source document, and the _split_overlap ranges cover exactly the text the two chunks share.RecursiveDocumentSplitter dropping the whitespace after the last sentence of each piece of text it split into sentences, such as the "\n\n" ending a paragraph longer than split_length. This lost text, and moved the split_idx_start of every later chunk before its real start, which could put a chunk on the page before the one it starts on. The whitespace is now kept at the end of the chunk it follows, so with no overlap the chunks add up to the document again. Such a chunk can exceed split_length by that trailing whitespace.bound_event_dict_values now also bounds log values nested inside list, tuple and dict fields. Exceptions in a container are rendered with str instead of repr, so a UnicodeDecodeError no longer writes the whole buffer it failed to decode into the log line, and containers are cut short in place with [container budget exhausted], [recursive container] or [maximum depth reached] markers when they reach the traversal limits.PDFToImageContent and DocumentToImageContent do, now closes the pypdfium2 document even when rendering a page raises an error. Before, the document was only closed after all pages rendered successfully, so a failing page left it open until garbage collection.DOCXToDocument now extracts text and tables inside text boxes. Previously this content was silently dropped.from haystack.tools import tool now returns the tool decorator. Before, lazy from haystack.tools import tool and imports under PYTHON_LAZY_IMPORTS=all returned the haystack.tools.tool module instead.AnswerExactMatchEvaluator, DocumentMAPEvaluator, DocumentMRREvaluator and DocumentRecallEvaluator now raise a descriptive ValueError when called with empty input lists, instead of failing with an opaque ZeroDivisionError. This matches the existing behavior of DocumentNDCGEvaluator.FilterPolicy.MERGE returning documents that the initialization filters exclude. When the initialization and runtime filters were both logical filters sharing an OR or NOT operator, their conditions were concatenated, which unions the two filters rather than applying both. They are now combined under an AND so each filter still restricts the result. Merging two AND filters is unchanged.SentenceSplitter now reads its curated abbreviation lists as UTF-8 regardless of the system locale. Previously, on Windows, the German list was decoded with the ANSI code page (for example cp1252), so abbreviations containing umlauts or ß, such as ggü. or außenpol., were garbled and did not prevent sentence splits when extend_abbreviations=True.SchemaGenerationError when using @tool, create_tool_from_function, or ComponentTool with a parameter typed as Annotated[State, ...], including optional variants. These parameters are now excluded from the schema sent to the language model and receive the Agent's live State object when the tool runs, just like parameters typed as State.InMemoryDocumentStore no longer counts Documents without content, such as image Documents that only have an embedding, in its BM25 statistics. Previously they increased the document count and lowered the average document length, which changed the BM25 scores and ranking of text Documents even though BM25 retrieval never returns Documents without content.ChatMessage.from_openai_dict_format now converts messages whose content is a list of content parts. Previously, the whole list was stored in a single TextContent, so ChatMessage.text returned a list instead of a string. In user messages, text parts now become TextContent, image_url parts with base64 data URLs become ImageContent, and file parts with inline file_data become FileContent. In system, developer, and assistant messages, text parts are joined with a newline into a single text. An assistant's refusal, given as a refusal part or as the refusal field, is stored in ChatMessage.meta["refusal"] instead of the text, and ChatMessage.to_openai_dict_format sends it back. content that is neither a string nor a list now raises a ValueError instead of being stored as text.EvaluationRunResult.aggregated_report, detailed_report and comparative_detailed_report with output_format="csv" now write the CSV file as UTF-8. Previously the file used the locale encoding, so on Windows a report with text outside the ANSI code page (e.g. Japanese or Cyrillic questions) was left half-written and an error message was returned instead, and accented characters were written as cp1252.expand_page_range silently dropping pages when a reversed range (e.g. "7-5") appeared alongside valid entries. Mixed inputs like ["1-3", "7-5", "8"] previously returned [1, 2, 3, 8] with no warning, losing pages 5-7. A reversed range now raises ValueError with a descriptive message identifying the offending range.logger.exception() on loggers from haystack.logging.getLogger now logs the active traceback, as the standard library does. Previously it logged only the message, without the stack trace, in both JSON and console output. Passing exc_info explicitly still works.MetaFieldRanker now applies missing_meta when the meta values can't be sorted together, for example 1 and "x". In this case the Documents keep their original order, but Documents missing the meta field are dropped with "drop", placed first with "top", and placed last with "bottom". Previously, all Documents were returned in their original order and missing_meta was ignored.OpenAIChatGenerator and OpenAIResponsesChatGenerator no longer drop a tool call whose arguments are an empty string, and no longer raise TypeError when they are null, in non-streaming responses. OpenAI-compatible servers such as vLLM send these for a tool with no parameters. Both now become empty arguments, as they already did in streaming responses and in ChatMessage.from_openai_dict_format.QueryExpander now states that its examples show the output for 3 requested queries and that exactly n_expansions queries must be returned. The trailing JSON format example, which always showed three queries, is removed. Before, the examples showed three or four queries without saying so, which contradicted the instruction for any other n_expansions value.SentenceWindowRetriever returning context_windows with the chunks in the wrong order when the documents have no split_idx_start meta field, for example chunks produced by MarkdownHeaderSplitter. The chunks were concatenated in the order returned by the Document Store instead of by split_id, so the context passed to an LLM could be scrambled while context_documents was correctly sorted. The chunks are now sorted by split_id before being merged, in both run and run_async.JsonSchemaValidator.run() now raises a ValueError saying the message list is empty when it receives no messages, instead of an IndexError from reading the last message.ToolResultOffloadHook and ToolResultOffloadCompactor no longer stop the Agent run when a ToolResultStore write fails, for example when FileSystemToolResultStore rejects a key containing .. or the disk is full. The result stays in the conversation, a warning naming the tool and the store is logged, and the remaining results are still offloaded. If one part of a result with several content blocks fails to write, the whole result stays in the conversation.LLMDocumentContentExtractor messages. The failure warning said "Skipping metadata extraction", and a document that couldn't be converted to an image got extraction_error set to "Document has no content". The docstring also named the wrong metadata field (content_extraction_error instead of extraction_error). Warnings now say the document is returned in failed_documents, and a response that isn't a JSON object is now logged too.LLMEvaluator warning that summarizes failed inputs. It logged the raw template LLM evaluator failed for {errors} out of {len(list_of_input_names_to_values)} inputs. instead of the counts. This also affects FaithfulnessEvaluator and ContextRelevanceEvaluator.LostInTheMiddleRanker now validates all input documents before deduplication and top_k selection, raising ValueError if any document is non-textual. Previously, single-document selections and documents excluded by top_k could bypass the text-only validation.Pipeline.connect() silently skipping a new socket-to-socket connection when other connections already link the same sender and receiver components. Repeating an existing connection remains a no-op, and invalid additional connections now raise the expected error.error.pipeline_snapshot_file_path is now None. Before, it held the path of the snapshot file that was never written.CSVToDocument in row mode now preserves values from a CSV column named row_number as csv_row_number in metadata (with a suffix on collision), instead of overwriting them with the generated row index.ImageContent and FileContent) nested inside ToolCallResult when tracing is enabled. Replaces raw base64 data with placeholder strings (such as "Base64 string (N characters)"), preventing multi-megabyte payloads from leaking into pipeline tracing spans.FilterError instead of leaking a Python TypeError when an ordering metadata filter compares a datetime with a non-datetime value.OpenAIResponsesChatGenerator and AzureOpenAIResponsesChatGenerator now map the raw reasoning text that the Responses API returns as reasoning_text content to ReasoningContent.reasoning_text, both when streaming (response.reasoning_text.delta events) and when not streaming. Previously, this text was dropped while streaming and only kept in ReasoningContent.extra["content"] otherwise. OpenAI models only return reasoning summaries, which still take precedence, but other providers such as OpenRouter return the raw reasoning. When such a reply is sent back to the model in a later turn, the raw reasoning is no longer duplicated as a summary.@Aditya17-bot, @agnieszka-m, @amengnew, @anakin87, @ArzelaAscoIi, @Ayushdevo, @basilalshukaili, @Ben160804, @bhaskargurram-ai, @bilgeyucel, @bogdankostic, @camgrimsec, @chrikrah, @davidsbatista, @Evihut, @hardness1020, @Harsh23Kashyap, @julian-risch, @kacperlukawski, @L4XB, @LimbC-C, @LindseyZ1205, @Marcuswang0824, @Morningstar202604, @otiscuilei, @rautaditya2606, @rxchitrx, @ShousenZHANG, @sjrl, @Timotty, @TimurRakhmatullin86, @Vedant-Agarwal, @yuv009
🐍 Python 3.15 Support, Python 3.10 Dropped
Haystack now officially supports Python 3.15. Python 3.10 reaches end of life in October 2026, so the minimum supported version is now 3.11. ⚠️
The experimental ToolResultOffloadCompactor is a new compaction strategy for CompactionHook. When compaction is triggered, it doesn't drop or summarize older tool results. It writes them to a ToolResultStore and leaves a reference in their place. The Agent can read the full output back on demand with a read tool scoped to the same store. Fresh results stay in context until compaction kicks in, so short runs pay nothing extra.
from typing import Annotated
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, ToolResultOffloadCompactor
from haystack.hooks.tool_result_offloading import FileSystemToolResultStore
from haystack.tools import tool
store = FileSystemToolResultStore(root="tool_results")
@tool
def read_offloaded_result(path: Annotated[str, "Path of an offloaded tool result"]) -> str:
"""Read back the full content of an offloaded tool result."""
content = store.read(path)
if isinstance(content, bytes):
return f"'{path}' holds {len(content)} bytes of binary content and cannot be read as text."
return content
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
tools=[web_search, read_offloaded_result],
hooks={"before_llm": [CompactionHook(compactor=ToolResultOffloadCompactor(store=store), context_window=400_000)]},
)The page_number metadata field now means the same thing in every splitter: the page the chunk's text starts on. Two cases change:
RecursiveDocumentSplitter reported the page a chunk ended on. A chunk spanning a page break now reports the page it starts on, matching DocumentSplitter and MarkdownHeaderSplitter.DocumentSplitter, MarkdownHeaderSplitter and EmbeddingBasedDocumentSplitter reported the previous page for a chunk that began with one or more form feeds (\f), even though all of the chunk's text was on the following page. Such chunks now report the page their text is on. A chunk made up entirely of page breaks is an empty page and keeps the page it starts on, so blank pages emitted by split_by="page" still get their own number.If you display page_number to users or store it alongside embeddings, re-index documents that contain form feeds to pick up the corrected values.
RecursiveDocumentSplitter with split_unit="word" and split_overlap greater than 0 now returns chunks copied from the document as they are. Previously it rebuilt them from their words joined by single spaces, which added spaces the document does not have, collapsed line breaks and repeated spaces, and could drop form feeds (\f). The overlap also counts words the way split_length does, as text separated by spaces, so where words are separated only by line or page breaks, chunks can end at different words than before. Re-index documents split this way if you need their chunks to match the source text.
RecursiveDocumentSplitter now keeps the whitespace between sentences when sentence_splitter_params sets keep_white_spaces to False. That is the sentence tokenizer's default, so this applies whenever sentence_splitter_params is passed without "keep_white_spaces": True. The tokenizer leaves that whitespace out, and the chunks used to glue their sentences together, as in "One two.Three four.": the glued words counted as one toward split_length, page breaks (\f) between sentences were lost, and split_idx_start and page_number fell behind the chunk's real start. Chunks are now copied from the document whatever keep_white_spaces is set to; it only changes the rules the tokenizer uses to decide where a sentence ends. Re-index documents split with this setting to pick up the corrected chunks.
Dropped support for Python 3.10 since it reaches End of Life (EOL) in October 2026. The minimum supported Python version is now 3.11. If you are on Python 3.10, upgrade your Python version before upgrading Haystack.
FilterPolicy.MERGE now intersects initialization and runtime logical filters when both use OR or NOT. Callers that relied on the previous broader result should construct a single explicit OR filter containing all alternatives and pass it with FilterPolicy.REPLACE instead.
ChatMessage.from_openai_dict_format now raises a ValueError for content parts it can't convert: images referenced by a URL such as https://example.com/image.png (only images embedded as base64 data URLs, like data:image/png;base64,..., are supported), files referenced by file_id, and other part types such as input_audio. Previously, such messages were accepted because the whole list was stored as a single text, and ChatMessage.to_openai_dict_format sent that list back unchanged, so forwarding them to OpenAI worked by accident. You're affected if the OpenAI messages you convert contain any of these parts. To keep sending images by URL, download them and build the message yourself, for example ChatMessage.from_user(content_parts=["Describe this image", ImageContent.from_url(url)]). Send files inline as base64 file_data instead of referencing them by file_id. Extra keys on content parts, such as cache_control, are no longer passed through, so prompt caching through OpenRouter or LiteLLM stops for these messages.
HTMLToDocument now defaults to encoding=None, delegating HTML encoding detection to Trafilatura. Set encoding="utf-8" to retain explicit UTF-8 decoding.
Previously, HTMLToDocument used the encoding value in a source ByteStream's metadata to decode its content, overriding the converter's encoding setting. This metadata no longer affects decoding. If you relied on it, pass the encoding to the converter instead, for example HTMLToDocument(encoding="latin-1").
The default model for OpenAITextEmbedder, OpenAIDocumentEmbedder, AzureOpenAITextEmbedder, and AzureOpenAIDocumentEmbedder has been changed from text-embedding-ada-002 to text-embedding-3-small.
text-embedding-3-small is roughly 5x cheaper per token than the previous generation text-embedding-ada-002 and scores higher on the MTEB benchmark (see OpenAI's announcement).
To preserve previous behavior, pass model="text-embedding-ada-002" explicitly (or, for the Azure variants, azure_deployment="text-embedding-ada-002").
Note for Azure users: azure_deployment refers to the deployment name in your Azure OpenAI resource, not a model identifier. If you do not already have a text-embedding-3-small deployment in Azure, you will need to create one or pass the name of an existing deployment explicitly.
Embeddings generated with the new default model are not compatible with embeddings produced by text-embedding-ada-002. If you have a document store populated with previously-generated embeddings, either keep using the old model explicitly or re-embed your corpus.
The base Tool.warm_up() and Toolset.warm_up() methods were removed. OpenAI/Azure Chat Generators no longer warm up tools.
If you use tools through an Agent, no changes are needed. For manual preparation, use warm_up_tools or warm_up_tools_async. Lazy toolsets such as MCPToolset must be warmed up before passing them to a Chat Generator.
Added the experimental ToolResultOffloadCompactor for CompactionHook. Once compaction is triggered, it writes older tool results to a ToolResultStore and leaves a reference in their place, so the Agent can read the full output back with a read tool you scope to the same store. Fresh results stay in context until then.
from typing import Annotated
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, ToolResultOffloadCompactor
from haystack.hooks.tool_result_offloading import FileSystemToolResultStore
from haystack.tools import tool
store = FileSystemToolResultStore(root="tool_results")
@tool
def read_offloaded_result(path: Annotated[str, "Path of an offloaded tool result"]) -> str:
"""Read back the full content of an offloaded tool result."""
content = store.read(path)
if isinstance(content, bytes):
return f"'{path}' holds {len(content)} bytes of binary content and cannot be read as text."
return content
# web_search stands in for your own tool that returns long results.
hook = CompactionHook(compactor=ToolResultOffloadCompactor(store=store), context_window=400_000)
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
tools=[web_search, read_offloaded_result],
hooks={"before_llm": [hook]},
)When an Agent runs inside a Pipeline, the anonymous pipeline telemetry event now also reports the chat generator class and its tools: the number of tools, the class and name of each tool, the component wrapped by each ComponentTool, and the classes of any Toolset objects.
Haystack now officially supports Python 3.15.
Removed the Sockets.__getattribute__ override. It looked up a _sockets attribute that no instance has, so on every attribute access it raised and caught AttributeError and never returned a socket; socket access has always gone through the copies __init__ and __setitem__ put in __dict__. Without the override, accessing a socket attribute such as component.__haystack_input__.query is about 14x faster.
HTMLToDocument now uses Trafilatura's encoding detection instead of assuming UTF-8, allowing non-UTF-8 sources to be converted without manually specifying their encoding. If conversion produces incorrect characters, install trafilatura[all] for additional encoding detection support, or set the converter's encoding explicitly.
LLMEvaluator fallback warnings now name the component class, for example FaithfulnessEvaluator, and say that the result for a failed input is set to None. A response that isn't valid JSON or is missing the expected keys now gets its own warning with the response and the parsing error.
LLMRanker fallback warnings for an empty query, a chat generation failure and a response parsing failure now consistently say the deduplicated input documents are returned unranked, so the fallback order isn't mistaken for a ranking.
QueryExpander fallback warnings now say what is returned: only the original query, or no queries when include_original_query is False. QueryExpander now also warns when the ChatGenerator response isn't valid JSON, including the response and the parsing error, and when the response contains no valid queries.
When no chat_generator is passed, LLMRanker and QueryExpander now use OpenAIResponsesChatGenerator instead of OpenAIChatGenerator, with the same model and temperature. The default generator sets "store": False so OpenAI does not keep the requests and responses.
Agent now uses its close()/close_async() methods to release its configured tools and supports asynchronous tool preparation using warm_up_async(). Invoking a tool directly through tool.invoke() or tool.invoke_async() automatically calls its warm-up methods when available.
This enables tools to manage synchronous and asynchronous resources separately. We'll update tools in Haystack Core Integrations to take advantage of this support.
When a tool call made by Agent fails, its haystack.agent.step.tool tracing span now carries the tag haystack.tool.error set to True. Tracers can use it to mark the span as failed, so a failed call is no longer indistinguishable from a tool that returns an {"error": ...} dict. The tag is set even when content tracing is disabled.
DOCXToDocument dropping the fragment of an external link when Word stores it separately in the w:anchor attribute instead of the hyperlink address. For example, a link to https://example.org/manual#refund-policy was converted to https://example.org/manual with both the markdown and the plain link_format option. The complete link target, including the fragment, is now preserved.RecursiveDocumentSplitter assigning page_number values that drifted upwards, and could exceed the number of pages in the document, when split_overlap was greater than 0. A page break repeated in an overlapping tail was counted once per chunk it appeared in. page_number is now derived from the chunk's offset in the source document instead of a running counter, so a repeated page break cannot be counted twice.RecursiveDocumentSplitter reporting split_idx_start values past the chunk's real start when split_unit="word" and split_overlap was greater than 0, which also pushed page_number onto pages the chunk had not reached yet. split_idx_start now points at the chunk's start in the source document, and the _split_overlap ranges cover exactly the text the two chunks share.RecursiveDocumentSplitter dropping the whitespace after the last sentence of each piece of text it split into sentences, such as the "\n\n" ending a paragraph longer than split_length. This lost text, and moved the split_idx_start of every later chunk before its real start, which could put a chunk on the page before the one it starts on. The whitespace is now kept at the end of the chunk it follows, so with no overlap the chunks add up to the document again. Such a chunk can exceed split_length by that trailing whitespace.bound_event_dict_values now also bounds log values nested inside list, tuple and dict fields. Exceptions in a container are rendered with str instead of repr, so a UnicodeDecodeError no longer writes the whole buffer it failed to decode into the log line, and containers are cut short in place with [container budget exhausted], [recursive container] or [maximum depth reached] markers when they reach the traversal limits.PDFToImageContent and DocumentToImageContent do, now closes the pypdfium2 document even when rendering a page raises an error. Before, the document was only closed after all pages rendered successfully, so a failing page left it open until garbage collection.DOCXToDocument now extracts text and tables inside text boxes. Previously this content was silently dropped.from haystack.tools import tool now returns the tool decorator. Before, lazy from haystack.tools import tool and imports under PYTHON_LAZY_IMPORTS=all returned the haystack.tools.tool module instead.AnswerExactMatchEvaluator, DocumentMAPEvaluator, DocumentMRREvaluator and DocumentRecallEvaluator now raise a descriptive ValueError when called with empty input lists, instead of failing with an opaque ZeroDivisionError. This matches the existing behavior of DocumentNDCGEvaluator.FilterPolicy.MERGE returning documents that the initialization filters exclude. When the initialization and runtime filters were both logical filters sharing an OR or NOT operator, their conditions were concatenated, which unions the two filters rather than applying both. They are now combined under an AND so each filter still restricts the result. Merging two AND filters is unchanged.SentenceSplitter now reads its curated abbreviation lists as UTF-8 regardless of the system locale. Previously, on Windows, the German list was decoded with the ANSI code page (for example cp1252), so abbreviations containing umlauts or ß, such as ggü. or außenpol., were garbled and did not prevent sentence splits when extend_abbreviations=True.SchemaGenerationError when using @tool, create_tool_from_function, or ComponentTool with a parameter typed as Annotated[State, ...], including optional variants. These parameters are now excluded from the schema sent to the language model and receive the Agent's live State object when the tool runs, just like parameters typed as State.InMemoryDocumentStore no longer counts Documents without content, such as image Documents that only have an embedding, in its BM25 statistics. Previously they increased the document count and lowered the average document length, which changed the BM25 scores and ranking of text Documents even though BM25 retrieval never returns Documents without content.ChatMessage.from_openai_dict_format now converts messages whose content is a list of content parts. Previously, the whole list was stored in a single TextContent, so ChatMessage.text returned a list instead of a string. In user messages, text parts now become TextContent, image_url parts with base64 data URLs become ImageContent, and file parts with inline file_data become FileContent. In system, developer, and assistant messages, text parts are joined with a newline into a single text. An assistant's refusal, given as a refusal part or as the refusal field, is stored in ChatMessage.meta["refusal"] instead of the text, and ChatMessage.to_openai_dict_format sends it back. content that is neither a string nor a list now raises a ValueError instead of being stored as text.EvaluationRunResult.aggregated_report, detailed_report and comparative_detailed_report with output_format="csv" now write the CSV file as UTF-8. Previously the file used the locale encoding, so on Windows a report with text outside the ANSI code page (e.g. Japanese or Cyrillic questions) was left half-written and an error message was returned instead, and accented characters were written as cp1252.expand_page_range silently dropping pages when a reversed range (e.g. "7-5") appeared alongside valid entries. Mixed inputs like ["1-3", "7-5", "8"] previously returned [1, 2, 3, 8] with no warning, losing pages 5-7. A reversed range now raises ValueError with a descriptive message identifying the offending range.logger.exception() on loggers from haystack.logging.getLogger now logs the active traceback, as the standard library does. Previously it logged only the message, without the stack trace, in both JSON and console output. Passing exc_info explicitly still works.MetaFieldRanker now applies missing_meta when the meta values can't be sorted together, for example 1 and "x". In this case the Documents keep their original order, but Documents missing the meta field are dropped with "drop", placed first with "top", and placed last with "bottom". Previously, all Documents were returned in their original order and missing_meta was ignored.OpenAIChatGenerator and OpenAIResponsesChatGenerator no longer drop a tool call whose arguments are an empty string, and no longer raise TypeError when they are null, in non-streaming responses. OpenAI-compatible servers such as vLLM send these for a tool with no parameters. Both now become empty arguments, as they already did in streaming responses and in ChatMessage.from_openai_dict_format.QueryExpander now states that its examples show the output for 3 requested queries and that exactly n_expansions queries must be returned. The trailing JSON format example, which always showed three queries, is removed. Before, the examples showed three or four queries without saying so, which contradicted the instruction for any other n_expansions value.SentenceWindowRetriever returning context_windows with the chunks in the wrong order when the documents have no split_idx_start meta field, for example chunks produced by MarkdownHeaderSplitter. The chunks were concatenated in the order returned by the Document Store instead of by split_id, so the context passed to an LLM could be scrambled while context_documents was correctly sorted. The chunks are now sorted by split_id before being merged, in both run and run_async.JsonSchemaValidator.run() now raises a ValueError saying the message list is empty when it receives no messages, instead of an IndexError from reading the last message.ToolResultOffloadHook and ToolResultOffloadCompactor no longer stop the Agent run when a ToolResultStore write fails, for example when FileSystemToolResultStore rejects a key containing .. or the disk is full. The result stays in the conversation, a warning naming the tool and the store is logged, and the remaining results are still offloaded. If one part of a result with several content blocks fails to write, the whole result stays in the conversation.LLMDocumentContentExtractor messages. The failure warning said "Skipping metadata extraction", and a document that couldn't be converted to an image got extraction_error set to "Document has no content". The docstring also named the wrong metadata field (content_extraction_error instead of extraction_error). Warnings now say the document is returned in failed_documents, and a response that isn't a JSON object is now logged too.LLMEvaluator warning that summarizes failed inputs. It logged the raw template LLM evaluator failed for {errors} out of {len(list_of_input_names_to_values)} inputs. instead of the counts. This also affects FaithfulnessEvaluator and ContextRelevanceEvaluator.LostInTheMiddleRanker now validates all input documents before deduplication and top_k selection, raising ValueError if any document is non-textual. Previously, single-document selections and documents excluded by top_k could bypass the text-only validation.Pipeline.connect() silently skipping a new socket-to-socket connection when other connections already link the same sender and receiver components. Repeating an existing connection remains a no-op, and invalid additional connections now raise the expected error.error.pipeline_snapshot_file_path is now None. Before, it held the path of the snapshot file that was never written.CSVToDocument in row mode now preserves values from a CSV column named row_number as csv_row_number in metadata (with a suffix on collision), instead of overwriting them with the generated row index.ImageContent and FileContent) nested inside ToolCallResult when tracing is enabled. Replaces raw base64 data with placeholder strings (such as "Base64 string (N characters)"), preventing multi-megabyte payloads from leaking into pipeline tracing spans.FilterError instead of leaking a Python TypeError when an ordering metadata filter compares a datetime with a non-datetime value.OpenAIResponsesChatGenerator and AzureOpenAIResponsesChatGenerator now map the raw reasoning text that the Responses API returns as reasoning_text content to ReasoningContent.reasoning_text, both when streaming (response.reasoning_text.delta events) and when not streaming. Previously, this text was dropped while streaming and only kept in ReasoningContent.extra["content"] otherwise. OpenAI models only return reasoning summaries, which still take precedence, but other providers such as OpenRouter return the raw reasoning. When such a reply is sent back to the model in a later turn, the raw reasoning is no longer duplicated as a summary.@Aditya17-bot, @agnieszka-m, @amengnew, @anakin87, @ArzelaAscoIi, @Ayushdevo, @basilalshukaili, @Ben160804, @bhaskargurram-ai, @bilgeyucel, @bogdankostic, @camgrimsec, @chrikrah, @davidsbatista, @Evihut, @hardness1020, @Harsh23Kashyap, @julian-risch, @kacperlukawski, @L4XB, @LimbC-C, @LindseyZ1205, @Marcuswang0824, @Morningstar202604, @otiscuilei, @rautaditya2606, @rxchitrx, @ShousenZHANG, @sjrl, @Timotty, @TimurRakhmatullin86, @Vedant-Agarwal, @yuv009
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
anyio is installed transitively through httpx and openai; versions before 4.14.2 are affected by CVE-2026-63374 (GHSA-82r6-8w77-94w6).
SentenceWindowRetriever now queries the Document Store once per run or run_async call instead of once per retrieved document. Fewer calls mean lower latency and less load on the Document Store and outputs have not changed, so existing pipelines get faster without code changes.
InMemoryDocumentStore.bm25_retrieval and InMemoryBM25Retriever with BM25L (the default) or BM25Plus now return only documents that contain at least one query term, with or without scale_score. Previously, documents without any query term were returned with a positive score and filled up top_k. As a result, retrieval can now return fewer than top_k documents, or none at all. The delta lower bound now applies only to query terms that occur in the document, as in the original BM25L/BM25+ definitions. So scores of matching documents are lower than before whenever the query has terms that a document does not contain. If you filter results with a fixed score threshold, re-check the threshold. BM25Okapi is not affected.TextCleaner.run now raises a clear TypeError when texts is not a list or any element is not a str, instead of failing later or producing unexpected results.anyio>=4.14.2. anyio is installed transitively through httpx and openai; versions before 4.14.2 are affected by CVE-2026-63374 (GHSA-82r6-8w77-94w6).Fixed BM25 tokenization in InMemoryDocumentStore for Chinese, Japanese and Korean text. The default bm25_tokenization_regex now splits CJK characters into one token each, so bare-term queries can match words inside longer unspaced runs. Text is also NFC-normalized before tokenization, so composed and decomposed spellings produce the same tokens.
Fix Pipeline.connect() raising TypeError: object of type 'ellipsis' has no len() when one of the sockets is annotated with Callable[..., T]. A Callable[..., T] now matches callables with any parameters, in both directions, as long as the return types are compatible.
Fixed ChatPromptBuilder dropping content parts when the template is a list of ChatMessage objects. Only the first TextContent part was rendered, and every other part - additional texts, images, files -was removed from the rendered prompt without a warning. Template variables used in those dropped parts were not detected either, so they were not exposed as inputs. Now all TextContent parts are rendered and the remaining content parts are passed through unchanged.
Fixed CompactionHook.close() and close_async() to release the token counter's resources as well as the compactor's. Previously, resources such as OpenAITokenCounter's HTTP client remained open after the hook or Agent was closed.
ConfirmationHook no longer drops the messages that come after the last user or tool message when it rewrites the conversation, such as a system message added by another hook or an assistant answer followed by an on_exit reminder. Before, those messages were removed from the history the Agent sends to the model.
DocumentToImageContent no longer raises a KeyError for the whole batch when a document points to a PDF page that cannot be converted, because the page is out of range or the PDF cannot be read. That document now gets None in image_contents, like other invalid documents, and the rest of the batch is still converted. The logged warnings now include the path of the PDF file.
Fixed DOCXToDocument breaking a Markdown table when a cell contains a pipe or spans several paragraphs. A pipe was emitted as a column separator, and a cell's line break ended the row in the middle of it. Pipes are now escaped and line breaks inside a cell are collapsed to a space. The csv table format is unchanged: it already kept such cells intact by quoting them.
Fixed DOCXToDocument dropping hyperlink addresses inside tables. With link_format set to markdown or plain, links in table cells were written as their display text only, while links in body paragraphs kept their address. Links in table cells are now formatted the same way, in both the markdown and csv table formats. The default link_format="none" output is unchanged.
Fixed ConditionalRouter.from_dict mutating the caller's routes data in place: serialized output_type strings were deserialized directly inside the caller's dictionaries, so reusing the same serialized pipeline dict afterwards yielded already-deserialized type objects. from_dict now works on a copy and the caller's data is left untouched. BranchJoiner.from_dict received the same treatment.
LinkContentFetcher no longer adds its timeout and follow_redirects defaults to the client_kwargs dictionary passed by the caller. The dictionary is now copied before the defaults are applied, so reusing one HTTP client configuration across components no longer leaks these defaults.
Fix MetaFieldRanker to return no documents when missing_meta="drop" and all documents lack the ranking field or have a None value.
MetaFieldRanker now treats a Document whose meta_field value is None the same as a Document that is missing the field, applying the missing_meta setting to it. Previously a single None value made sorting fail, so the ranker logged a warning and returned all Documents in their original order, ignoring missing_meta="drop" as well.
MockTextEmbedder and MockDocumentEmbedder now accept non-positive dimension values when embedding or embedding_fn is provided, matching the documented behavior. The default deterministic embedding mode still requires a positive dimension.
ChatMessage.from_openai_dict_format now accepts tool-call arguments that are already a dictionary instead of raising a TypeError. Some OpenAI-compatible servers send a parsed object rather than a JSON string.
MetaFieldGroupingRanker now treats a group_by or subgroup_by value of None as missing, the same way it already treats sort_docs_by. Documents with None go to the end with the other ungrouped documents, instead of forming a group named "None" that also absorbed documents whose value was the string "None".
Fixed JSONConverter failing with ValueError when content_key contains numeric or boolean scalar values. These values are now converted to strings before creating the Document, while null values remain unchanged.
Fixed SentenceSplitter losing the whitespace between two sentences when the first one ends with a closing quote, as in He said "Hi." Bye.. Those characters were missing from the chunk text and shifted the split_idx_start offset of every following chunk, so chunks could no longer be mapped back onto the original text. This affects all components that split on sentences, such as DocumentSplitter, RecursiveDocumentSplitter, MarkdownHeaderSplitter and EmbeddingBasedDocumentSplitter. Chunk boundaries change for text that contains quoted sentences, so re-indexing an existing corpus produces different chunks than before.
Fixed LLMMetadataExtractor incorrectly treating a chat generator output that carries its own error field as a failed LLM call, which sent every document to failed_documents with metadata_extraction_error set to None. Such documents are now processed normally.
Retrievers now handle top_k consistently. A negative top_k passed at runtime to InMemoryBM25Retriever, InMemoryEmbeddingRetriever or MultiRetriever (top_k and top_k_per_retriever) now raises a ValueError. Previously it was applied as a negative slice, silently dropping the last documents. A runtime top_k=0 returns no documents.
MultiRetriever now also validates top_k and top_k_per_retriever at initialization, raising a ValueError when they are set and not greater than 0, matching the in-memory retrievers. None still means no limit.
Fixed Pipeline.run(), Pipeline.run_async(), and Pipeline.stream() treating a flat input with a dictionary value as a component name. For example, {"payload": {"x": 1}} now reaches components with a payload input without requiring the component name in the input data.
Pipeline.run_async now lets a BreakpointException or PipelineRuntimeError raised by a nested component propagate unchanged, instead of wrapping it in another PipelineRuntimeError. This matches the synchronous Pipeline.run and preserves the original error context (for example an agent snapshot) when a component internally runs a pipeline.
XLSXToDocument now escapes pipe characters and replaces in-cell line breaks with spaces in the default Markdown pipe table output. This keeps cell content from being interpreted as additional table columns or rows.
@alanhuangyoo, @anakin87, @bilgeyucel, @carey-bk, @Cha-Imaa, @chrikrah, @dakjdakd, @gauravch-code, @Harsh23Kashyap, @Jayanth-reflex, @JbravoI, @julian-risch, @L4XB, @Lesereingrape, @lets-order-some-fries, @mnm-matin, @MohammadHijjawi97, @nanhanq1, @pcbeingused333, @PeterSmith0127-lcm, @Rainmemery, @sclfcz, @serhiizghama, @shivsin25, @ShousenZHANG, @simpleqt, @winklemad
anyio is installed transitively through httpx and openai ; versions before 4.14.2 are affected by CVE-2026-63374 ( GHSA-82r6-8w77-94w6 ).
SentenceWindowRetriever now queries the Document Store once per run or run_async call instead of once per retrieved document. Fewer calls mean lower latency and less load on the Document Store and outputs have not changed, so existing pipelines get faster without code changes.
InMemoryDocumentStore.bm25_retrieval and InMemoryBM25Retriever with BM25L (the default) or BM25Plus now return only documents that contain at least one query term, with or without scale_score. Previously, documents without any query term were returned with a positive score and filled up top_k. As a result, retrieval can now return fewer than top_k documents, or none at all. The delta lower bound now applies only to query terms that occur in the document, as in the original BM25L/BM25+ definitions. So scores of matching documents are lower than before whenever the query has terms that a document does not contain. If you filter results with a fixed score threshold, re-check the threshold. BM25Okapi is not affected.TextCleaner.run now raises a clear TypeError when texts is not a list or any element is not a str, instead of failing later or producing unexpected results.anyio>=4.14.2. anyio is installed transitively through httpx and openai; versions before 4.14.2 are affected by CVE-2026-63374 (GHSA-82r6-8w77-94w6).Fixed BM25 tokenization in InMemoryDocumentStore for Chinese, Japanese and Korean text. The default bm25_tokenization_regex now splits CJK characters into one token each, so bare-term queries can match words inside longer unspaced runs. Text is also NFC-normalized before tokenization, so composed and decomposed spellings produce the same tokens.
Fix Pipeline.connect() raising TypeError: object of type 'ellipsis' has no len() when one of the sockets is annotated with Callable[..., T]. A Callable[..., T] now matches callables with any parameters, in both directions, as long as the return types are compatible.
Fixed ChatPromptBuilder dropping content parts when the template is a list of ChatMessage objects. Only the first TextContent part was rendered, and every other part - additional texts, images, files -was removed from the rendered prompt without a warning. Template variables used in those dropped parts were not detected either, so they were not exposed as inputs. Now all TextContent parts are rendered and the remaining content parts are passed through unchanged.
Fixed CompactionHook.close() and close_async() to release the token counter's resources as well as the compactor's. Previously, resources such as OpenAITokenCounter's HTTP client remained open after the hook or Agent was closed.
ConfirmationHook no longer drops the messages that come after the last user or tool message when it rewrites the conversation, such as a system message added by another hook or an assistant answer followed by an on_exit reminder. Before, those messages were removed from the history the Agent sends to the model.
DocumentToImageContent no longer raises a KeyError for the whole batch when a document points to a PDF page that cannot be converted, because the page is out of range or the PDF cannot be read. That document now gets None in image_contents, like other invalid documents, and the rest of the batch is still converted. The logged warnings now include the path of the PDF file.
Fixed DOCXToDocument breaking a Markdown table when a cell contains a pipe or spans several paragraphs. A pipe was emitted as a column separator, and a cell's line break ended the row in the middle of it. Pipes are now escaped and line breaks inside a cell are collapsed to a space. The csv table format is unchanged: it already kept such cells intact by quoting them.
Fixed DOCXToDocument dropping hyperlink addresses inside tables. With link_format set to markdown or plain, links in table cells were written as their display text only, while links in body paragraphs kept their address. Links in table cells are now formatted the same way, in both the markdown and csv table formats. The default link_format="none" output is unchanged.
Fixed ConditionalRouter.from_dict mutating the caller's routes data in place: serialized output_type strings were deserialized directly inside the caller's dictionaries, so reusing the same serialized pipeline dict afterwards yielded already-deserialized type objects. from_dict now works on a copy and the caller's data is left untouched. BranchJoiner.from_dict received the same treatment.
LinkContentFetcher no longer adds its timeout and follow_redirects defaults to the client_kwargs dictionary passed by the caller. The dictionary is now copied before the defaults are applied, so reusing one HTTP client configuration across components no longer leaks these defaults.
Fix MetaFieldRanker to return no documents when missing_meta="drop" and all documents lack the ranking field or have a None value.
MetaFieldRanker now treats a Document whose meta_field value is None the same as a Document that is missing the field, applying the missing_meta setting to it. Previously a single None value made sorting fail, so the ranker logged a warning and returned all Documents in their original order, ignoring missing_meta="drop" as well.
MockTextEmbedder and MockDocumentEmbedder now accept non-positive dimension values when embedding or embedding_fn is provided, matching the documented behavior. The default deterministic embedding mode still requires a positive dimension.
ChatMessage.from_openai_dict_format now accepts tool-call arguments that are already a dictionary instead of raising a TypeError. Some OpenAI-compatible servers send a parsed object rather than a JSON string.
MetaFieldGroupingRanker now treats a group_by or subgroup_by value of None as missing, the same way it already treats sort_docs_by. Documents with None go to the end with the other ungrouped documents, instead of forming a group named "None" that also absorbed documents whose value was the string "None".
Fixed JSONConverter failing with ValueError when content_key contains numeric or boolean scalar values. These values are now converted to strings before creating the Document, while null values remain unchanged.
Fixed SentenceSplitter losing the whitespace between two sentences when the first one ends with a closing quote, as in He said "Hi." Bye.. Those characters were missing from the chunk text and shifted the split_idx_start offset of every following chunk, so chunks could no longer be mapped back onto the original text. This affects all components that split on sentences, such as DocumentSplitter, RecursiveDocumentSplitter, MarkdownHeaderSplitter and EmbeddingBasedDocumentSplitter. Chunk boundaries change for text that contains quoted sentences, so re-indexing an existing corpus produces different chunks than before.
Fixed LLMMetadataExtractor incorrectly treating a chat generator output that carries its own error field as a failed LLM call, which sent every document to failed_documents with metadata_extraction_error set to None. Such documents are now processed normally.
Retrievers now handle top_k consistently. A negative top_k passed at runtime to InMemoryBM25Retriever, InMemoryEmbeddingRetriever or MultiRetriever (top_k and top_k_per_retriever) now raises a ValueError. Previously it was applied as a negative slice, silently dropping the last documents. A runtime top_k=0 returns no documents.
MultiRetriever now also validates top_k and top_k_per_retriever at initialization, raising a ValueError when they are set and not greater than 0, matching the in-memory retrievers. None still means no limit.
Fixed Pipeline.run(), Pipeline.run_async(), and Pipeline.stream() treating a flat input with a dictionary value as a component name. For example, {"payload": {"x": 1}} now reaches components with a payload input without requiring the component name in the input data.
Pipeline.run_async now lets a BreakpointException or PipelineRuntimeError raised by a nested component propagate unchanged, instead of wrapping it in another PipelineRuntimeError. This matches the synchronous Pipeline.run and preserves the original error context (for example an agent snapshot) when a component internally runs a pipeline.
XLSXToDocument now escapes pipe characters and replaces in-cell line breaks with spaces in the default Markdown pipe table output. This keeps cell content from being interpreted as additional table columns or rows.
@alanhuangyoo, @anakin87, @bilgeyucel, @carey-bk, @Cha-Imaa, @chrikrah, @dakjdakd, @gauravch-code, @Harsh23Kashyap, @Jayanth-reflex, @JbravoI, @julian-risch, @L4XB, @Lesereingrape, @lets-order-some-fries, @mnm-matin, @MohammadHijjawi97, @nanhanq1, @pcbeingused333, @PeterSmith0127-lcm, @Rainmemery, @sclfcz, @serhiizghama, @shivsin25, @ShousenZHANG, @simpleqt, @winklemad
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
The experimental `SummarizationCompactor` is a new compaction strategy for `CompactionHook`. It replaces older turns and Agent steps with LLM-generate
The experimental SummarizationCompactor is a new compaction strategy for CompactionHook. It replaces older turns and Agent steps with LLM-generated summaries. Long-running Agents keep a condensed record of earlier goals, decisions, and open work. It summarizes as little as needed to reach the target size, starting with the oldest historical turns and only then moving to the current task's older steps. The min_keep_steps newest steps always stay as they are. You can use a small, cheap model to write the summaries.
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, SummarizationCompactor
compaction_hook = CompactionHook(
compactor=SummarizationCompactor(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
min_keep_steps=2,
),
context_window=400_000,
compact_at=0.7,
compact_to=0.4,
)
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4"),
tools=[web_search],
hooks={"before_llm": [compaction_hook]},
)
The experimental TokenBudgetHook caps how many tokens an Agent run can spend. Once the budget is used up, the Agent stops before its next LLM call, sets exit_reason to "token_budget_exceeded", and returns the messages collected so far. Set add_final_message=True to add an assistant message explaining why the run ended.
The hook is built on the new stop_run state key, which any hook can set to end a run cleanly with a custom reason instead of raising an error. For example, you can stop after too many calls to one tool:
from haystack.hooks import hook
from haystack.hooks.budget import TokenBudgetHook
@hook
def limit_searches(state):
if state.get("tool_call_counts", {}).get("web_search", 0) >= 5:
state.set("stop_run", "search_limit_reached")
agent = Agent(
chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
tools=[web_search],
hooks={"before_llm": [TokenBudgetHook(max_total_tokens=100_000), limit_searches]},
)
result = agent.run(messages)
print(result["exit_reason"]) # "text", "token_budget_exceeded", or "search_limit_reached"
Building a pipeline takes less code with Haystack version 3.2: Pipeline.add_components() adds several components in one call and Pipeline.connect_many() creates several connections in one call. Both add_component() and add_components() now return the pipeline, so you can chain the calls.
from haystack import Pipeline
pipeline = (
Pipeline()
.add_components({"retriever": retriever, "prompt_builder": prompt_builder, "llm": llm})
.connect_many([("retriever", "prompt_builder.documents"), ("prompt_builder", "llm")])
)
Serialized OutputAdapter and ConditionalRouter components containing Jinja custom_filters must now be loaded with Pipeline.load(..., unsafe=True) (or the equivalent Pipeline.loads / Pipeline.from_dict option).
The tool_result_offloaded meta key that the hook sets on an offloaded message now always holds a list of store references rather than a single reference string, since a result can span several entries. Code reading that key (for example to re-read an offloaded result) should index into the list.
ToolResultStore.write and read are typed str | bytes. Nothing changes at runtime for a text-only store, but one that subclasses the protocol and annotates content: str may need a type-checker fix.
The + operator for combining Toolsets has been removed. Pass Toolsets as a list wherever tools are accepted instead: Agent(..., tools=[toolset_a, toolset_b]). Pipelines serialized with a +-combined Toolset cannot be loaded anymore (their YAML references the removed internal _ToolsetWrapper class): recreate them with the list form and serialize them again.
Toolset.add() now only accepts a single Tool, not another Toolset. To combine Toolsets, pass them as a list: Agent(..., tools=[toolset_a, toolset_b]).
Add Pipeline.add_components() to add a mapping of component names to component instances in one call. Re-adding the same component instance under the same name with Pipeline.add_component() or Pipeline.add_components() is now a no-op.
pipeline.add_components(
{
"retriever": retriever,
"prompt_builder": prompt_builder,
"llm": llm,
}
)
Added the experimental SummarizationCompactor (use with CompactionHook), which progressively summarizes a conversation until it fits a target token budget, preserving useful context from long-running Agents instead of dropping older messages.
It uses four summarization tiers in order until the target token budget is reached:
historical_turns: Starting with the oldest, summarize as few complete historical turns as needed.historical_summaries: When no complete historical turns remain, combine as few of the oldest historical summaries as needed.current_task_steps: Summarize the fewest oldest steps needed to reach the target while preserving the min_keep_steps newest steps.current_task_summaries: When no more steps can be summarized, combine as few of the current task's oldest summaries as needed to reach the target.from typing import Annotated
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, SummarizationCompactor
from haystack.tools import tool
@tool
def web_search(query: Annotated[str, "The search query"]) -> str:
"""Search the web for current information."""
return f"Search results for: {query}"
agent_generator = OpenAIResponsesChatGenerator(model="gpt-5.4")
summary_generator = OpenAIResponsesChatGenerator(model="gpt-5.4-nano")
compaction_hook = CompactionHook(
compactor=SummarizationCompactor(
chat_generator=summary_generator,
min_keep_steps=2,
approximate_summary_tokens=1_024,
),
context_window=400_000,
compact_at=0.7,
compact_to=0.4,
)
agent = Agent(
chat_generator=agent_generator,
tools=[web_search],
hooks={"before_llm": [compaction_hook]},
)
Added stop_run, a control flag that lets an Agent hook end a run cleanly instead of raising an error. The hook sets it to a reason of your choice (state.set("stop_run", "my_reason")), and the Agent stops without another model call and reports that reason in exit_reason.
Added TokenBudgetHook (experimental), a ready-made hook that caps how many tokens an Agent run may spend. The run ends with exit_reason set to "token_budget_exceeded", keeping the messages collected so far.
from haystack.hooks.budget import TokenBudgetHook
agent = Agent(
chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
tools=[search],
hooks={"before_llm": [TokenBudgetHook(max_total_tokens=100_000)]},
)
Add Pipeline.connect_many() to connect multiple (sender, receiver) pairs in one call. Pipeline.add_component() and Pipeline.add_components() now return the pipeline, allowing pipeline-building methods to be chained.
pipeline = (
Pipeline()
.add_components(
{
"retriever": retriever,
"prompt_builder": prompt_builder,
"llm": llm,
}
)
.connect_many(
[
("retriever", "prompt_builder.documents"),
("prompt_builder", "llm"),
]
)
)
Added the HAYSTACK_UNSAFE_DESERIALIZATION environment variable as a process-wide equivalent of loading with unsafe=True. When set to a truthy value (1 or true), every Pipeline.load / Pipeline.loads / Pipeline.from_dict call skips all deserialization safety checks — the module allowlist, the builtin/import-primitive and control-plane denylists, the object-internals traversal guard, and the refusal to honor a component's own unsafe: true flag. This is intended for deployments that only ever load fully trusted pipelines and cannot pass unsafe=True at every call site. A warning is logged the first time it takes effect. Only enable it when every pipeline the process loads is trusted: a single untrusted pipeline then leads to arbitrary code execution.
The switch is not limited to pipeline loading: it disables the same checks for every deserialization path in the process, including ones that take no unsafe argument of their own — Tool.from_dict, State.from_dict (agent snapshot resume), and the ConditionalRouter and OutputAdapter Jinja sandbox flags. A deployment that loads trusted pipelines at startup but accepts serialized tools or agent state at request time is therefore exposed on the request path as well, not only at load time.
The variable is read once, on the first deserialization in the process, and the result is then frozen for the process lifetime: writes to it afterwards are ignored, in either direction. Set it before the first pipeline is loaded. Freezing keeps the safety mode of a process from changing under a caller's feet and, because the first read happens before any deserialized data can run, stops a hostile pipeline from switching the checks off while it is being loaded.
FileSystemSkillStore's skills_dir now also accepts a Secret, so the skills directory path can be sourced from an environment variable (e.g. Secret.from_env_var("SKILLS_DIR")) instead of being hard-coded in pipeline configuration.
AnswerJoiner now logs an informational message when sort_by_score is enabled and some answers have no score, matching the existing behaviour of DocumentJoiner. Such answers are still sorted as if their score were -infinity, but the demotion is no longer silent. This is common when joining GeneratedAnswer objects, which carry no score at all.
Add the min_content_length parameter to DocumentCleaner. After the configured cleaning steps run, text documents shorter than the threshold (ignoring leading and trailing whitespace) are omitted from the output.
Add split_by="token" to DocumentSplitter and DocumentPreprocessor. Splits text by LLM token count using tiktoken. The encoding defaults to "o200k_base" (current OpenAI models) and can be changed via the new tokenizer_encoding parameter. split_length, split_overlap, and split_threshold all work as usual. Requires pip install tiktoken.
ToolResultOffloadHook now offloads tool results carrying ImageContent or FileContent, not just text.
Each part of a result gets its own store entry, with images and files decoded from base64 to raw bytes, under the extension of its filename when it has one and of its mime_type otherwise (falling back to .bin). For example:
Tool result offloaded to 3 files:
1. text (412 characters) at '/abs/path/tool_results/2_fetch_call-123_0.txt'. Preview: Quarterly report...
2. image/png (48210 bytes) at '/abs/path/tool_results/2_fetch_call-123_1.png'
3. application/pdf named 'q3.pdf' (1048576 bytes) at '/abs/path/tool_results/2_fetch_call-123_2.pdf'
Binary content is opt-in, via a new supports_binary_content attribute on the ToolResultStore protocol, which FileSystemToolResultStore sets to True. A store leaving it at its False default never receives bytes: images and files stay in context with a warning, as before, so existing custom stores keep working unchanged.
An offload policy receives the result as a single string: the text and base64 payloads of all its parts concatenated.
FallbackChatGenerator now wraps every internal ChatGenerator attempt in a haystack.chat_generator.run tracing span for both synchronous and asynchronous execution. With content tracing enabled, each internal span records the forwarded inputs. The successful output remains on the enclosing FallbackChatGenerator component span so tracing backends do not count its token usage twice.
TopPSampler now rejects negative, boolean, and non-integer min_top_k values during initialization with a clear ValueError.
Pipeline component outputs typed as list[T] to connect to inputs typed as Iterable[T]. Lists already satisfy the iterable input contract and are passed through without conversion.AnswerJoiner.run docstring: it did not mention that the sort_by_score init parameter affects the order of the returned answers. The docstring now documents that when sort_by_score=True the merged answers are sorted by score in descending order (answers without a score are handled as if their score were -infinity) before top_k is applied, and that the input order is preserved otherwise.Agent.clone() and Agent.to_dict()/from_dict() raising TypeError for an Agent built on a chat generator that does not accept a tools parameter. tools is normalized to an empty list at init, and both round-trip paths passed that empty list back to the constructor, where it was treated as "tools were provided". An empty list now carries no tools, matching the equivalent check already applied in Agent.run(). Passing tools=[] explicitly to such an Agent is accepted for the same reason. A non-empty tools value still raises, and a Toolset is still never tested for truthiness at init.Agent from retrying an empty response when a chat generator reports finish_reason="length". This can happen when reasoning tokens exhaust the maximum output token budget. OpenAIResponsesChatGenerator now maps terminal Responses API events to Haystack FinishReason values and attaches finish_reason to the returned ChatMessage.Agent now reports exit_reason="length" or "content_filter" when a tool-call-free model reply ends for either reason, including replies containing partial text. These incomplete generations stop by default but can be recovered with an on_exit hook. AgentTool also warns the calling model that such results may be incomplete.JsonSchemaValidator now accepts an empty JSON Schema ({}) and honors it when passed to run(). Empty schemas are valid JSON Schema and match every JSON value.AutoMergingRetriever rejecting documents whose hierarchy metadata uses __level=0 or __block_size=0. HierarchicalDocumentSplitter stores those values on the root node, so validation now checks for key presence instead of truthiness.str instead of repr, because some carry their whole input in their repr - UnicodeDecodeError keeps the entire buffer it failed to decode, so logging one raised while decoding a large file would emit that whole file as a single log line. Any remaining value longer than 4096 characters is truncated.LLMMetadataExtractor now removes the metadata_extraction_error and metadata_extraction_response keys from a document's metadata on every successful extraction, in both run and run_async. Previously, when a document from failed_documents was re-run and the LLM returned an empty JSON object {}, the document ended up in documents still carrying both keys from the earlier failed attempt.TextFileToDocument, CSVToDocument, MarkdownToDocument and MultiFileConverter now default to utf-8-sig instead of utf-8, so a UTF-8 byte order mark (BOM) is stripped rather than leaking into Document.content as a zero-width character. utf-8-sig decodes plain UTF-8 identically, so files without a BOM are unaffected.JSONConverter no longer silently skips UTF-8 files that start with a byte order mark. The file content is now decoded with utf-8-sig. Previously the UnicodeError was caught and logged as a warning, so a BOM file was dropped from the pipeline without raising - three input files could produce two documents with no error.DocumentJoiner now raises a ValueError when any value in weights is negative. Previously negative weights were normalized by their -- possibly negative -- sum, which flipped their sign and could produce negative document scores in merge mode. For example weights=[1, -2] was normalized to [-1.0, 2.0]. The existing error for weights that sum to zero is unchanged.DocumentJoiner distribution-based rank fusion when an input list contains a single document or has zero score variance.DocumentSplitter now adds split_id, split_idx_start and page_number to the metadata of the chunks it creates when split_by="function", like it already did for all other split modes. Without this metadata, components that rely on it, such as SentenceWindowRetriever, could not be used with chunks produced by a custom splitting function. Empty chunks returned by the splitting function are now also skipped, unless skip_empty_documents=False.DocumentSplitter with split_by="token" generating redundant trailing chunks containing only overlap. The splitter now stops creating chunks after reaching the end of the document.DocumentToImageContent no longer raises a ValueError for the whole batch when one document is missing the file path or page_number metadata, has an invalid file path, or has an unsupported MIME type. That document now gets None in image_contents and a warning with the reason is logged, while the other documents are still converted. This lets LLMDocumentContentExtractor return such documents in failed_documents instead of failing the entire run.ToolResultOffloadHook offloading empty tool results. An empty string, or a result made up of nothing but empty text blocks, was written to the ToolResultStore as a zero-byte entry and replaced in the conversation by a pointer ending in a dangling Preview: - growing the context the hook exists to shrink, and inviting the model to read back an empty file. Such results are now left in context, as empty-list results already were.FilterRetriever so that an empty runtime filters dictionary clears filters provided at initialization during synchronous and asynchronous execution.document_matches_filter raising AttributeError for dotted filter fields whose root is not a Document attribute (for example {"field": "typo.x", ...}). Such fields are now treated as missing, consistent with non-dotted unknown fields and the documented behavior. This affected InMemoryDocumentStore.filter_documents and MetadataRouter.CompactionHook mis-estimating the context size when compaction leaves a conversation with no assistant message, for example when a compactor summarizes every Agent step away. The hook now records the whole compacted conversation as accounted for, and the estimate reads that count back unchanged, so a second compaction hook running right after sees the true size instead of counting the conversation twice.AzureOpenAIChatGenerator.to_dict() when response_format is passed as a dictionary.ComponentDevice.first_device raising a ValueError when the first entry of a device map is a disk device. Disk devices are only valid as part of a device map (for example when HuggingFace offloads weights with device_map='auto'), so first_device now skips disk entries and returns the first usable device instead of crashing. If the device map is empty or contains only disk devices, a ValueError is raised.deserialize_secrets_inplace with recursive=True: serialized secrets were left as plain dicts instead of being converted back to Secret, and nested dictionaries deeper than one level were never visited.FileTypeRouter.run() writing the meta passed to it into the meta dict of the input ByteStream objects. The metadata is now added to a copy, so ByteStream sources are left untouched, matching the behaviour already in place for file path sources.FilterPolicy.MERGE from mutating initialization or runtime filters when combining logical filters. Reusing a retriever for multiple runs now applies each runtime filter independently.InMemoryDocumentStore.count_unique_metadata_by_filter and count_unique_metadata_by_filter_async raising TypeError when metadata values are JSON-serializable lists or dictionaries, and make composite metadata deduplication consistent with get_metadata_field_unique_values.JsonSchemaValidator no longer raises ValueError when the message content is a top-level JSON scalar like "hello", 42, true or null. The same crash happened for JSON arrays of scalars. Those values now reach the schema validator, which either accepts them or returns the usual validation_error output.LinkContentFetcher.run_async() omitting default headers configured through client_kwargs. Asynchronous and synchronous fetches now apply the same client-default headers.DocumentSplitter and RecursiveDocumentSplitter failing on documents containing strings such as <|endoftext|>. These strings are now preserved and counted as ordinary text, including when splitting with overlap.LLMDocumentContentExtractor.run_async converting documents to images on the event loop. DocumentToImageContent reads every file and renders the requested PDF pages, and it has no run_async, so calling it directly blocked the loop for the whole batch before any LLM call started. It now runs through _execute_component_async, which hands the synchronous work to a thread.parent_headers metadata in MarkdownHeaderSplitter when keep_headers=False and secondary splitting is enabled. Editing one chunk's parent headers no longer changes its siblings' metadata.MetaFieldGroupingRanker no longer partially reorders a group before falling back on a TypeError. When sort_docs_by values are mutually non-comparable (e.g. int and str), the group's original insertion order is now guaranteed, as the sorting happens on a copy instead of in place.AssertionError crash when comparing a Pipeline to any non-Pipeline object (such as pipeline == object() or pipeline in [object(), ...]) caused by an inverted isinstance check in PipelineBase.__eq__.QueryExpander now returns an empty query list when query is None or not a string, instead of raising AttributeError on str.strip.RecursiveDocumentSplitter applied the overlap at every recursion level when chunking text with multiple separators, producing chunks that were not substrings of the source text. The overlap is now applied exactly once, on the final chunk list.Tool subclasses such as ComponentTool in OpenAIResponsesChatGenerator.from_dict() and AzureOpenAIResponsesChatGenerator.from_dict().FileSystemSkillStore.load_skill including symlinks that resolve outside the skill directory in its bundled-file manifest. Escaping symlinks are now excluded, matching read_skill_file traversal protection.split_overlap validation message in RecursiveDocumentSplitter (0 is the default and only negative values are rejected) and clarify that overlap is measured in split_units. Also fix stale docstrings in AnswerJoiner (documented parameters the methods do not take, and claimed sorting that only happens for answers) and the meta_field ranker (referenced a nonexistent score mode).create_tool_from_function, the @tool decorator, and ComponentTool stripping title keys inside OpenAPI 3.0 singular example values when building a tool's JSON schema. example is now treated as instance data alongside default, const, enum and examples, so a title key carried via Pydantic json_schema_extra stays part of the tool contract.MetaFieldRanker raising a TypeError when meta_value_type is set and a document contains an unhashable metadata value, such as a list or dictionary. These values now follow the existing warning and original-document fallback behavior.XLSXToDocument skipping workbooks with hyperlinks in numeric or boolean columns when using pandas 3. Hyperlink text is now inserted without a dtype error, while columns without hyperlinks retain their original types and formatting.LinkContentFetcher now performs the configured number of retries in synchronous runs. Previously, retry_attempts counted the initial request as an attempt, so synchronous runs performed one fewer retry than configured and behaved differently from asynchronous runs.LLMDocumentContentExtractor incorrectly treating a chat generator output that carries its own error field as a failed LLM call. Such documents are now processed normally.LLMMessagesRouter now raises a ValueError when output_names contains "chat_generator_text" or "unmatched". Those two outputs are always created by the router, so reusing either name used to be accepted and then silently broke the component: "chat_generator_text" had its socket retyped to list[ChatMessage] and lost the LLM reply at run time, while "unmatched" made a matched decision indistinguishable from an unmatched one.LLMMetadataExtractor incorrectly treating an extracted error metadata field as an extraction failure. error can now be used in expected_keys like any other metadata key.LLMRanker no longer crashes with AttributeError when query is None (or another non-string) coming from an upstream pipeline component. Both run and run_async now return the documents unranked, matching the existing empty-query fallback.MarkdownHeaderSplitter silently dropping a document's leading header line when secondary_split is used with keep_headers=False. This happened for any chunk that wasn't the result of an actual header split, for example when a document has no headers, only headers without body content, a header at a level excluded from header_split_levels, or input metadata that already contained a header key. The header line is now only stripped from chunks that truly came from a header split.MarkdownHeaderSplitter no longer drops the text that precedes the first header it splits on. A document's opening paragraph, title block, or front matter was silently lost, and so was any content above the first matching header when header_split_levels excluded the levels above it. A document whose headers all had empty bodies lost that text too, because it was treated as header-only. That text is now emitted as a leading chunk with empty header and parent_headers metadata, so every chunk still carries the documented metadata fields. Leading text that is only whitespace joins the first chunk instead of becoming a chunk of its own, which keeps the chunks a byte-exact partition of the input without adding an empty chunk.page_number metadata from MarkdownHeaderSplitter when secondary splitting uses overlap. Page breaks in overlapping content are no longer counted multiple times, and custom page_break_character values are respected.EmbeddingBasedDocumentSplitter emitting a final split shorter than min_length. Small splits were only merged forward, so the last one had nothing left to absorb and was returned as its own document. It is now merged into the preceding split, unless doing so would reach max_length, the same limit that already governs forward merges.MultiQueryTextRetriever, MultiQueryEmbeddingRetriever and MultiRetriever now honour max_workers in their run_async methods. Previously only the synchronous run bounded fan-out (via a ThreadPoolExecutor); run_async launched every sub-query / sub-retriever call at once, ignoring max_workers and risking rate limits or connection exhaustion against the underlying retriever or embedder. run_async now bounds concurrency with an asyncio.Semaphore, matching the behaviour of the LLM extractors.ChatMessage.from_openai_dict_format accepts the same empty content, so such a message round-trips.OpenAIDocumentEmbedder.run_async (and AzureOpenAIDocumentEmbedder) now request encoding_format="float" from the embeddings endpoint, matching the synchronous run. The async batch path was missed when this was added in #9655, so run_async let the OpenAI SDK negotiate the base64 wire format, which some OpenAI-compatible endpoints do not support.OpenAIChatGenerator and OpenAIResponsesChatGenerator so that an empty runtime tools list overrides tools configured at initialization.timeout and max_retries to the to_dict method of OpenAIImageGenerator. They were dropped on serialization, so a pipeline saved and reloaded silently fell back to the OPENAI_TIMEOUT/OPENAI_MAX_RETRIES defaults instead of the configured values. This matches OpenAIChatGenerator, OpenAITextEmbedder and OpenAIDocumentEmbedder, which already serialize both.OutputAdapter and ConditionalRouter no longer coerce string outputs to other Python types when output_type=str. Previously the rendered template was always passed through ast.literal_eval in safe mode, so a string that happened to be a valid Python literal was silently converted (for example "1,000" became the tuple (1, 0) and "42" became the integer 42), producing a value that did not match the declared str output type. Literal evaluation is now skipped when output_type is str, so string outputs are returned unchanged. Other output types still reconstruct structured literals as before.PythonCodeSplitter now deep-copies the metadata of the document it splits, matching the other splitters. Previously it copied it shallowly, so nested values such as a list under meta["tags"] were shared between every chunk and with the input document, and editing one chunk's metadata changed all the others. The secondary line-based split of oversized units had the same problem.RecursiveDocumentSplitter and TextCleaner now keep their init parameters when serialized, for example in a pipeline saved with Pipeline.dumps(). Before, RecursiveDocumentSplitter wrote split_unit: word whatever unit it was created with, so a reloaded splitter configured for characters or tokens counted words instead. A reloaded TextCleaner lost all of its options and returned the texts unchanged.DocumentSplitter with split_by="word", "period", "page", "passage", "line" or "sentence" generating redundant trailing chunks containing only overlap. Segments that add no new text beyond the already covered units are now skipped, mirroring the split_by="token" fix.IndexError: list index out of range when a chat generator's stream completes without emitting any chunks. _convert_streaming_chunks_to_chat_message now returns an assistant message with empty content and None metadata instead.SuperComponent.run_async now returns outputs mapped from components that are not leaves of the wrapped pipeline, like run does. Before, an output that was also consumed inside the pipeline, such as retriever.documents feeding a prompt builder, was silently missing from the async result. This also affected a PipelineTool run by Agent.run_async, whose outputs_to_state got nothing for such outputs.create_tool_from_function and the @tool decorator now work with functions defined in a module that uses from __future__ import annotations. Before, the parameter annotations were plain strings, and creating the tool raised a SchemaGenerationError for any parameter typed with something other than a builtin, such as Annotated, Literal, Optional, Document or State. The annotations are now resolved first, and Annotated descriptions are kept.MetadataRouter now raises a clear ValueError when a rule uses the reserved output name unmatched, instead of failing with an internal duplicate-keyword TypeError during output registration.FileTypeRouter and DocumentTypeRouter now raise a clear ValueError when a MIME type uses a reserved output name (unclassified, or failed on FileTypeRouter), instead of failing with an internal duplicate-keyword TypeError during output registration.XLSXToDocument writing the string nan into an empty cell when table_format="markdown". The same cell is written as an empty field by table_format="csv", so an empty cell now reads as empty in both formats. A different placeholder can be set with table_format_kwargs={"missingval": "N/A"}.@abhati27, @abo3losh1, @Aftabbs, @AjayShivran, @alanhuangyoo, @anakin87, @Anurag-M1, @Arman-Beykmohammadi, @ArzelaAscoIi, @atikulmunna, @Awshesh12, @bilgeyucel, @bogdankostic, @businessarshgoyal, @coder058, @CoralGarden52, @davidsbatista, @dfedoryshchev, @dingpuyu, @Diwak4r, @Dxfory, @eatLaoJun, @ege-arhan, @feiiiiii5, @fng713, @Goodnight77, @Gout999, @gyanu2507, @Harsh23Kashyap, @iridescentWen, @JbravoI, @JimmyWang0417, @jliounis, @julian-risch, @kacperlukawski, @Koushik890, @Kuang-xianxin, @L4XB, @Lesereingrape, @lets-order-some-fries, @LHMQ878, @linhongyu510, @mfurkanakinci, @mikemikimike, @MohammadHijjawi97, @mrchtr, @Nikhi00718, @otiscuilei, @PattonBrown, @pcbeingused333, @PeterSmith0127-lcm, @Rainmemery, @rautaditya2606, @Ricky-7-Yan, @sainikhiljuluri, @samrusani, @seanxuu, @ShousenZHANG, @simpleqt, @sjrl, @spacesheepinternet, @SyedShahmeerAli12, @teachershuang, @tstadel, @uczltw6, @Vedant-Agarwal, @vercel[bot], @winter-street, @xblwh, @yavuz-yilmaz
Serialized OutputAdapter and ConditionalRouter components containing Jinja custom_filters must now be loaded with Pipeline.load(..., unsafe=True) (or
Serialized OutputAdapter and ConditionalRouter components containing Jinja custom_filters must now be loaded with Pipeline.load(..., unsafe=True) (or the equivalent Pipeline.loads / Pipeline.from_dict option).
The tool_result_offloaded meta key that the hook sets on an offloaded message now always holds a list of store references rather than a single reference string, since a result can span several entries. Code reading that key (for example to re-read an offloaded result) should index into the list.
ToolResultStore.write and read are typed str | bytes. Nothing changes at runtime for a text-only store, but one that subclasses the protocol and annotates content: str may need a type-checker fix.
The + operator for combining Toolsets has been removed. Pass Toolsets as a list wherever tools are accepted instead: Agent(..., tools=[toolset_a, toolset_b]). Pipelines serialized with a +-combined Toolset cannot be loaded anymore (their YAML references the removed internal _ToolsetWrapper class): recreate them with the list form and serialize them again.
Toolset.add() now only accepts a single Tool, not another Toolset. To combine Toolsets, pass them as a list: Agent(..., tools=[toolset_a, toolset_b]).
Add Pipeline.add_components() to add a mapping of component names to component instances in one call. Re-adding the same component instance under the same name with Pipeline.add_component() or Pipeline.add_components() is now a no-op.
pipeline.add_components(
{
"retriever": retriever,
"prompt_builder": prompt_builder,
"llm": llm,
}
)Added the experimental SummarizationCompactor (use with CompactionHook), which progressively summarizes a conversation until it fits a target token budget, preserving useful context from long-running Agents instead of dropping older messages.
It uses four summarization tiers in order until the target token budget is reached:
historical_turns: Starting with the oldest, summarize as few complete historical turns as needed.historical_summaries: When no complete historical turns remain, combine as few of the oldest historical summaries as needed.current_task_steps: Summarize the fewest oldest steps needed to reach the target while preserving the min_keep_steps newest steps.current_task_summaries: When no more steps can be summarized, combine as few of the current task's oldest summaries as needed to reach the target.from typing import Annotated
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, SummarizationCompactor
from haystack.tools import tool
@tool
def web_search(query: Annotated[str, "The search query"]) -> str:
"""Search the web for current information."""
return f"Search results for: {query}"
agent_generator = OpenAIResponsesChatGenerator(model="gpt-5.4")
summary_generator = OpenAIResponsesChatGenerator(model="gpt-5.4-nano")
compaction_hook = CompactionHook(
compactor=SummarizationCompactor(
chat_generator=summary_generator,
min_keep_steps=2,
approximate_summary_tokens=1_024,
),
context_window=400_000,
compact_at=0.7,
compact_to=0.4,
)
agent = Agent(
chat_generator=agent_generator,
tools=[web_search],
hooks={"before_llm": [compaction_hook]},
)Added stop_run, a control flag that lets an Agent hook end a run cleanly instead of raising an error. The hook sets it to a reason of your choice (state.set("stop_run", "my_reason")), and the Agent stops without another model call and reports that reason in exit_reason.
Added TokenBudgetHook (experimental), a ready-made hook that caps how many tokens an Agent run may spend. The run ends with exit_reason set to "token_budget_exceeded", keeping the messages collected so far.
from haystack.hooks.budget import TokenBudgetHook
agent = Agent(
chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
tools=[search],
hooks={"before_llm": [TokenBudgetHook(max_total_tokens=100_000)]},
)Add Pipeline.connect_many() to connect multiple (sender, receiver) pairs in one call. Pipeline.add_component() and Pipeline.add_components() now return the pipeline, allowing pipeline-building methods to be chained.
pipeline = (
Pipeline()
.add_components(
{
"retriever": retriever,
"prompt_builder": prompt_builder,
"llm": llm,
}
)
.connect_many(
[
("retriever", "prompt_builder.documents"),
("prompt_builder", "llm"),
]
)
)Added the HAYSTACK_UNSAFE_DESERIALIZATION environment variable as a process-wide equivalent of loading with unsafe=True. When set to a truthy value (1 or true), every Pipeline.load / Pipeline.loads / Pipeline.from_dict call skips all deserialization safety checks — the module allowlist, the builtin/import-primitive and control-plane denylists, the object-internals traversal guard, and the refusal to honor a component's own unsafe: true flag. This is intended for deployments that only ever load fully trusted pipelines and cannot pass unsafe=True at every call site. A warning is logged the first time it takes effect. Only enable it when every pipeline the process loads is trusted: a single untrusted pipeline then leads to arbitrary code execution.
The switch is not limited to pipeline loading: it disables the same checks for every deserialization path in the process, including ones that take no unsafe argument of their own — Tool.from_dict, State.from_dict (agent snapshot resume), and the ConditionalRouter and OutputAdapter Jinja sandbox flags. A deployment that loads trusted pipelines at startup but accepts serialized tools or agent state at request time is therefore exposed on the request path as well, not only at load time.
The variable is read once, on the first deserialization in the process, and the result is then frozen for the process lifetime: writes to it afterwards are ignored, in either direction. Set it before the first pipeline is loaded. Freezing keeps the safety mode of a process from changing under a caller's feet and, because the first read happens before any deserialized data can run, stops a hostile pipeline from switching the checks off while it is being loaded.
FileSystemSkillStore's skills_dir now also accepts a Secret, so the skills directory path can be sourced from an environment variable (e.g. Secret.from_env_var("SKILLS_DIR")) instead of being hard-coded in pipeline configuration.
AnswerJoiner now logs an informational message when sort_by_score is enabled and some answers have no score, matching the existing behaviour of DocumentJoiner. Such answers are still sorted as if their score were -infinity, but the demotion is no longer silent. This is common when joining GeneratedAnswer objects, which carry no score at all.
Add the min_content_length parameter to DocumentCleaner. After the configured cleaning steps run, text documents shorter than the threshold (ignoring leading and trailing whitespace) are omitted from the output.
Add split_by="token" to DocumentSplitter and DocumentPreprocessor. Splits text by LLM token count using tiktoken. The encoding defaults to "o200k_base" (current OpenAI models) and can be changed via the new tokenizer_encoding parameter. split_length, split_overlap, and split_threshold all work as usual. Requires pip install tiktoken.
ToolResultOffloadHook now offloads tool results carrying ImageContent or FileContent, not just text.
Each part of a result gets its own store entry, with images and files decoded from base64 to raw bytes, under the extension of its filename when it has one and of its mime_type otherwise (falling back to .bin). For example:
Tool result offloaded to 3 files:
1. text (412 characters) at '/abs/path/tool_results/2_fetch_call-123_0.txt'. Preview: Quarterly report...
2. image/png (48210 bytes) at '/abs/path/tool_results/2_fetch_call-123_1.png'
3. application/pdf named 'q3.pdf' (1048576 bytes) at '/abs/path/tool_results/2_fetch_call-123_2.pdf'
Binary content is opt-in, via a new supports_binary_content attribute on the ToolResultStore protocol, which FileSystemToolResultStore sets to True. A store leaving it at its False default never receives bytes: images and files stay in context with a warning, as before, so existing custom stores keep working unchanged.
An offload policy receives the result as a single string: the text and base64 payloads of all its parts concatenated.
FallbackChatGenerator now wraps every internal ChatGenerator attempt in a haystack.chat_generator.run tracing span for both synchronous and asynchronous execution. With content tracing enabled, each internal span records the forwarded inputs. The successful output remains on the enclosing FallbackChatGenerator component span so tracing backends do not count its token usage twice.
TopPSampler now rejects negative, boolean, and non-integer min_top_k values during initialization with a clear ValueError.
Pipeline component outputs typed as list[T] to connect to inputs typed as Iterable[T]. Lists already satisfy the iterable input contract and are passed through without conversion.AnswerJoiner.run docstring: it did not mention that the sort_by_score init parameter affects the order of the returned answers. The docstring now documents that when sort_by_score=True the merged answers are sorted by score in descending order (answers without a score are handled as if their score were -infinity) before top_k is applied, and that the input order is preserved otherwise.Agent.clone() and Agent.to_dict()/from_dict() raising TypeError for an Agent built on a chat generator that does not accept a tools parameter. tools is normalized to an empty list at init, and both round-trip paths passed that empty list back to the constructor, where it was treated as "tools were provided". An empty list now carries no tools, matching the equivalent check already applied in Agent.run(). Passing tools=[] explicitly to such an Agent is accepted for the same reason. A non-empty tools value still raises, and a Toolset is still never tested for truthiness at init.Agent from retrying an empty response when a chat generator reports finish_reason="length". This can happen when reasoning tokens exhaust the maximum output token budget. OpenAIResponsesChatGenerator now maps terminal Responses API events to Haystack FinishReason values and attaches finish_reason to the returned ChatMessage.Agent now reports exit_reason="length" or "content_filter" when a tool-call-free model reply ends for either reason, including replies containing partial text. These incomplete generations stop by default but can be recovered with an on_exit hook. AgentTool also warns the calling model that such results may be incomplete.JsonSchemaValidator now accepts an empty JSON Schema ({}) and honors it when passed to run(). Empty schemas are valid JSON Schema and match every JSON value.AutoMergingRetriever rejecting documents whose hierarchy metadata uses __level=0 or __block_size=0. HierarchicalDocumentSplitter stores those values on the root node, so validation now checks for key presence instead of truthiness.str instead of repr, because some carry their whole input in their repr - UnicodeDecodeError keeps the entire buffer it failed to decode, so logging one raised while decoding a large file would emit that whole file as a single log line. Any remaining value longer than 4096 characters is truncated.LLMMetadataExtractor now removes the metadata_extraction_error and metadata_extraction_response keys from a document's metadata on every successful extraction, in both run and run_async. Previously, when a document from failed_documents was re-run and the LLM returned an empty JSON object {}, the document ended up in documents still carrying both keys from the earlier failed attempt.TextFileToDocument, CSVToDocument, MarkdownToDocument and MultiFileConverter now default to utf-8-sig instead of utf-8, so a UTF-8 byte order mark (BOM) is stripped rather than leaking into Document.content as a zero-width character. utf-8-sig decodes plain UTF-8 identically, so files without a BOM are unaffected.JSONConverter no longer silently skips UTF-8 files that start with a byte order mark. The file content is now decoded with utf-8-sig. Previously the UnicodeError was caught and logged as a warning, so a BOM file was dropped from the pipeline without raising - three input files could produce two documents with no error.DocumentJoiner now raises a ValueError when any value in weights is negative. Previously negative weights were normalized by their -- possibly negative -- sum, which flipped their sign and could produce negative document scores in merge mode. For example weights=[1, -2] was normalized to [-1.0, 2.0]. The existing error for weights that sum to zero is unchanged.DocumentJoiner distribution-based rank fusion when an input list contains a single document or has zero score variance.DocumentSplitter now adds split_id, split_idx_start and page_number to the metadata of the chunks it creates when split_by="function", like it already did for all other split modes. Without this metadata, components that rely on it, such as SentenceWindowRetriever, could not be used with chunks produced by a custom splitting function. Empty chunks returned by the splitting function are now also skipped, unless skip_empty_documents=False.DocumentSplitter with split_by="token" generating redundant trailing chunks containing only overlap. The splitter now stops creating chunks after reaching the end of the document.DocumentToImageContent no longer raises a ValueError for the whole batch when one document is missing the file path or page_number metadata, has an invalid file path, or has an unsupported MIME type. That document now gets None in image_contents and a warning with the reason is logged, while the other documents are still converted. This lets LLMDocumentContentExtractor return such documents in failed_documents instead of failing the entire run.ToolResultOffloadHook offloading empty tool results. An empty string, or a result made up of nothing but empty text blocks, was written to the ToolResultStore as a zero-byte entry and replaced in the conversation by a pointer ending in a dangling Preview: - growing the context the hook exists to shrink, and inviting the model to read back an empty file. Such results are now left in context, as empty-list results already were.FilterRetriever so that an empty runtime filters dictionary clears filters provided at initialization during synchronous and asynchronous execution.document_matches_filter raising AttributeError for dotted filter fields whose root is not a Document attribute (for example {"field": "typo.x", ...}). Such fields are now treated as missing, consistent with non-dotted unknown fields and the documented behavior. This affected InMemoryDocumentStore.filter_documents and MetadataRouter.CompactionHook mis-estimating the context size when compaction leaves a conversation with no assistant message, for example when a compactor summarizes every Agent step away. The hook now records the whole compacted conversation as accounted for, and the estimate reads that count back unchanged, so a second compaction hook running right after sees the true size instead of counting the conversation twice.AzureOpenAIChatGenerator.to_dict() when response_format is passed as a dictionary.ComponentDevice.first_device raising a ValueError when the first entry of a device map is a disk device. Disk devices are only valid as part of a device map (for example when HuggingFace offloads weights with device_map='auto'), so first_device now skips disk entries and returns the first usable device instead of crashing. If the device map is empty or contains only disk devices, a ValueError is raised.deserialize_secrets_inplace with recursive=True: serialized secrets were left as plain dicts instead of being converted back to Secret, and nested dictionaries deeper than one level were never visited.FileTypeRouter.run() writing the meta passed to it into the meta dict of the input ByteStream objects. The metadata is now added to a copy, so ByteStream sources are left untouched, matching the behaviour already in place for file path sources.FilterPolicy.MERGE from mutating initialization or runtime filters when combining logical filters. Reusing a retriever for multiple runs now applies each runtime filter independently.InMemoryDocumentStore.count_unique_metadata_by_filter and count_unique_metadata_by_filter_async raising TypeError when metadata values are JSON-serializable lists or dictionaries, and make composite metadata deduplication consistent with get_metadata_field_unique_values.JsonSchemaValidator no longer raises ValueError when the message content is a top-level JSON scalar like "hello", 42, true or null. The same crash happened for JSON arrays of scalars. Those values now reach the schema validator, which either accepts them or returns the usual validation_error output.LinkContentFetcher.run_async() omitting default headers configured through client_kwargs. Asynchronous and synchronous fetches now apply the same client-default headers.DocumentSplitter and RecursiveDocumentSplitter failing on documents containing strings such as <|endoftext|>. These strings are now preserved and counted as ordinary text, including when splitting with overlap.LLMDocumentContentExtractor.run_async converting documents to images on the event loop. DocumentToImageContent reads every file and renders the requested PDF pages, and it has no run_async, so calling it directly blocked the loop for the whole batch before any LLM call started. It now runs through _execute_component_async, which hands the synchronous work to a thread.parent_headers metadata in MarkdownHeaderSplitter when keep_headers=False and secondary splitting is enabled. Editing one chunk's parent headers no longer changes its siblings' metadata.MetaFieldGroupingRanker no longer partially reorders a group before falling back on a TypeError. When sort_docs_by values are mutually non-comparable (e.g. int and str), the group's original insertion order is now guaranteed, as the sorting happens on a copy instead of in place.AssertionError crash when comparing a Pipeline to any non-Pipeline object (such as pipeline == object() or pipeline in [object(), ...]) caused by an inverted isinstance check in PipelineBase.__eq__.QueryExpander now returns an empty query list when query is None or not a string, instead of raising AttributeError on str.strip.RecursiveDocumentSplitter applied the overlap at every recursion level when chunking text with multiple separators, producing chunks that were not substrings of the source text. The overlap is now applied exactly once, on the final chunk list.Tool subclasses such as ComponentTool in OpenAIResponsesChatGenerator.from_dict() and AzureOpenAIResponsesChatGenerator.from_dict().FileSystemSkillStore.load_skill including symlinks that resolve outside the skill directory in its bundled-file manifest. Escaping symlinks are now excluded, matching read_skill_file traversal protection.split_overlap validation message in RecursiveDocumentSplitter (0 is the default and only negative values are rejected) and clarify that overlap is measured in split_units. Also fix stale docstrings in AnswerJoiner (documented parameters the methods do not take, and claimed sorting that only happens for answers) and the meta_field ranker (referenced a nonexistent score mode).create_tool_from_function, the @tool decorator, and ComponentTool stripping title keys inside OpenAPI 3.0 singular example values when building a tool's JSON schema. example is now treated as instance data alongside default, const, enum and examples, so a title key carried via Pydantic json_schema_extra stays part of the tool contract.MetaFieldRanker raising a TypeError when meta_value_type is set and a document contains an unhashable metadata value, such as a list or dictionary. These values now follow the existing warning and original-document fallback behavior.XLSXToDocument skipping workbooks with hyperlinks in numeric or boolean columns when using pandas 3. Hyperlink text is now inserted without a dtype error, while columns without hyperlinks retain their original types and formatting.LinkContentFetcher now performs the configured number of retries in synchronous runs. Previously, retry_attempts counted the initial request as an attempt, so synchronous runs performed one fewer retry than configured and behaved differently from asynchronous runs.LLMDocumentContentExtractor incorrectly treating a chat generator output that carries its own error field as a failed LLM call. Such documents are now processed normally.LLMMessagesRouter now raises a ValueError when output_names contains "chat_generator_text" or "unmatched". Those two outputs are always created by the router, so reusing either name used to be accepted and then silently broke the component: "chat_generator_text" had its socket retyped to list[ChatMessage] and lost the LLM reply at run time, while "unmatched" made a matched decision indistinguishable from an unmatched one.LLMMetadataExtractor incorrectly treating an extracted error metadata field as an extraction failure. error can now be used in expected_keys like any other metadata key.LLMRanker no longer crashes with AttributeError when query is None (or another non-string) coming from an upstream pipeline component. Both run and run_async now return the documents unranked, matching the existing empty-query fallback.MarkdownHeaderSplitter silently dropping a document's leading header line when secondary_split is used with keep_headers=False. This happened for any chunk that wasn't the result of an actual header split, for example when a document has no headers, only headers without body content, a header at a level excluded from header_split_levels, or input metadata that already contained a header key. The header line is now only stripped from chunks that truly came from a header split.MarkdownHeaderSplitter no longer drops the text that precedes the first header it splits on. A document's opening paragraph, title block, or front matter was silently lost, and so was any content above the first matching header when header_split_levels excluded the levels above it. A document whose headers all had empty bodies lost that text too, because it was treated as header-only. That text is now emitted as a leading chunk with empty header and parent_headers metadata, so every chunk still carries the documented metadata fields. Leading text that is only whitespace joins the first chunk instead of becoming a chunk of its own, which keeps the chunks a byte-exact partition of the input without adding an empty chunk.page_number metadata from MarkdownHeaderSplitter when secondary splitting uses overlap. Page breaks in overlapping content are no longer counted multiple times, and custom page_break_character values are respected.EmbeddingBasedDocumentSplitter emitting a final split shorter than min_length. Small splits were only merged forward, so the last one had nothing left to absorb and was returned as its own document. It is now merged into the preceding split, unless doing so would reach max_length, the same limit that already governs forward merges.MultiQueryTextRetriever, MultiQueryEmbeddingRetriever and MultiRetriever now honour max_workers in their run_async methods. Previously only the synchronous run bounded fan-out (via a ThreadPoolExecutor); run_async launched every sub-query / sub-retriever call at once, ignoring max_workers and risking rate limits or connection exhaustion against the underlying retriever or embedder. run_async now bounds concurrency with an asyncio.Semaphore, matching the behaviour of the LLM extractors.ChatMessage.from_openai_dict_format accepts the same empty content, so such a message round-trips.OpenAIDocumentEmbedder.run_async (and AzureOpenAIDocumentEmbedder) now request encoding_format="float" from the embeddings endpoint, matching the synchronous run. The async batch path was missed when this was added in #9655, so run_async let the OpenAI SDK negotiate the base64 wire format, which some OpenAI-compatible endpoints do not support.OpenAIChatGenerator and OpenAIResponsesChatGenerator so that an empty runtime tools list overrides tools configured at initialization.timeout and max_retries to the to_dict method of OpenAIImageGenerator. They were dropped on serialization, so a pipeline saved and reloaded silently fell back to the OPENAI_TIMEOUT/OPENAI_MAX_RETRIES defaults instead of the configured values. This matches OpenAIChatGenerator, OpenAITextEmbedder and OpenAIDocumentEmbedder, which already serialize both.OutputAdapter and ConditionalRouter no longer coerce string outputs to other Python types when output_type=str. Previously the rendered template was always passed through ast.literal_eval in safe mode, so a string that happened to be a valid Python literal was silently converted (for example "1,000" became the tuple (1, 0) and "42" became the integer 42), producing a value that did not match the declared str output type. Literal evaluation is now skipped when output_type is str, so string outputs are returned unchanged. Other output types still reconstruct structured literals as before.PythonCodeSplitter now deep-copies the metadata of the document it splits, matching the other splitters. Previously it copied it shallowly, so nested values such as a list under meta["tags"] were shared between every chunk and with the input document, and editing one chunk's metadata changed all the others. The secondary line-based split of oversized units had the same problem.RecursiveDocumentSplitter and TextCleaner now keep their init parameters when serialized, for example in a pipeline saved with Pipeline.dumps(). Before, RecursiveDocumentSplitter wrote split_unit: word whatever unit it was created with, so a reloaded splitter configured for characters or tokens counted words instead. A reloaded TextCleaner lost all of its options and returned the texts unchanged.DocumentSplitter with split_by="word", "period", "page", "passage", "line" or "sentence" generating redundant trailing chunks containing only overlap. Segments that add no new text beyond the already covered units are now skipped, mirroring the split_by="token" fix.IndexError: list index out of range when a chat generator's stream completes without emitting any chunks. _convert_streaming_chunks_to_chat_message now returns an assistant message with empty content and None metadata instead.SuperComponent.run_async now returns outputs mapped from components that are not leaves of the wrapped pipeline, like run does. Before, an output that was also consumed inside the pipeline, such as retriever.documents feeding a prompt builder, was silently missing from the async result. This also affected a PipelineTool run by Agent.run_async, whose outputs_to_state got nothing for such outputs.create_tool_from_function and the @tool decorator now work with functions defined in a module that uses from __future__ import annotations. Before, the parameter annotations were plain strings, and creating the tool raised a SchemaGenerationError for any parameter typed with something other than a builtin, such as Annotated, Literal, Optional, Document or State. The annotations are now resolved first, and Annotated descriptions are kept.MetadataRouter now raises a clear ValueError when a rule uses the reserved output name unmatched, instead of failing with an internal duplicate-keyword TypeError during output registration.FileTypeRouter and DocumentTypeRouter now raise a clear ValueError when a MIME type uses a reserved output name (unclassified, or failed on FileTypeRouter), instead of failing with an internal duplicate-keyword TypeError during output registration.XLSXToDocument writing the string nan into an empty cell when table_format="markdown". The same cell is written as an empty field by table_format="csv", so an empty cell now reads as empty in both formats. A different placeholder can be set with table_format_kwargs={"missingval": "N/A"}.@abhati27, @abo3losh1, @AjayShivran, @alanhuangyoo, @anakin87, @Anurag-M1, @Arman-Beykmohammadi, @ArzelaAscoIi, @Awshesh12, @bilgeyucel, @bogdankostic, @businessarshgoyal, @coder058, @CoralGarden52, @davidsbatista, @dfedoryshchev, @dingpuyu, @Diwak4r, @Dxfory, @eatLaoJun, @ege-arhan, @feiiiiii5, @fng713, @Goodnight77, @gyanu2507, @Harsh23Kashyap, @iridescentWen, @JbravoI, @JimmyWang0417, @jliounis, @julian-risch, @kacperlukawski, @Koushik890, @Kuang-xianxin, @L4XB, @Lesereingrape, @lets-order-some-fries, @linhongyu510, @mfurkanakinci, @mikemikimike, @MohammadHijjawi97, @mrchtr, @Nikhi00718, @otiscuilei, @PattonBrown, @pcbeingused333, @PeterSmith0127-lcm, @Rainmemery, @rautaditya2606, @Ricky-7-Yan, @sainikhiljuluri, @samrusani, @seanxuu, @ShousenZHANG, @simpleqt, @sjrl, @spacesheepinternet, @teachershuang, @tstadel, @Vedant-Agarwal, @vercel[bot], @winter-street, @xblwh, @yavuz-yilmaz
One column per quarter.