refactor: support PEP604 typing syntax (X|Y and X|None)

[anakin87]

Related Issues

• related to Drop Python 3.9 support because of Python 3.9 EOL #9854

We want to use X | Y instead of Union[X, Y] and X | None instead of Optional[X] across the codebase.
Since the old syntax is still valid, we also want to ensure it continues to work correctly.

Proposed Changes:

• update the codebase to use PEP604 typing syntax
• enforce these rules with Ruff
• make sure that typing utilities across the codebase handle both new and old syntax correctly

Most relevant files

Since this PR is quite large, I'm reporting here the list of files with the most relevant changes. Most of the other changes have been automatically applied using Ruff.

pyproject.toml

haystack/utils/type_serialization.py
haystack/core/type_utils.py
haystack/core/super_component/utils.py
haystack/components/agents/state/state_utils.py
haystack/tools/parameters_schema_utils.py

test/core/pipeline/test_type_syntax_compatibility.py (new)
test/utils/test_type_serialization.py
test/core/test_type_utils.py
test/core/super_component/test_utils.py
test/components/agents/test_state_class.py
test/tools/test_parameters_schema_utils.py
test/components/routers/test_conditional_router.py

How did you test it?

• CI, new tests
• Also opened a draft PR in core integrations to test that all the integrations components (no PEP604 typing) still work correctly with this PR: test pep604 haystack branch haystack-core-integrations#2619

Notes for the reviewer

In case this PR introduces bugs that we are not able to spot immediately, I hope that testing the future Release Candidate on Platform can help surface them.

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
haystack-docs	Ignored	Preview	Dec 19, 2025 2:33pm

[coveralls]

Pull Request Test Coverage Report for Build 20373119300

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 144 unchanged lines in 26 files lost coverage.
• Overall coverage increased (+0.08%) to 92.261%

---

Files with Coverage Reduction	New Missed Lines	%
components/converters/docx.py	1	99.43%
components/converters/image/file_to_document.py	1	96.3%
components/extractors/regex_text_extractor.py	1	95.56%
components/preprocessors/sentence_tokenizer.py	1	94.12%
dataclasses/streaming_chunk.py	1	95.77%
components/converters/pypdf.py	2	96.0%
components/converters/txt.py	2	91.18%
components/joiners/answer_joiner.py	2	95.83%
components/converters/json.py	3	87.36%
components/converters/msg.py	3	93.33%

Totals
Change from base Build 20371470877:	0.08%
Covered Lines:	14186
Relevant Lines:	15376

---

💛 - Coveralls

[sjrl]

Looks good! Let's make sure to give platform plenty of heads up about this change as well. Unsure if it effects the visual builder in any way.