chore: enable ANN ruff ruleset for type annotation enforcement (#10856)

julian-risch · claude · web-flow · commit 6c7348023b3c · 2026-03-18T11:28:33.000Z
* chore: enable ANN ruff ruleset, exclude components and testing dirs

- Add ANN (flake8-annotations) to ruff select in pyproject.toml
- Globally ignore ANN401 (Any) for legitimate dynamic types
- Exclude haystack/components/** and haystack/testing/** from ANN checks
  (mirrors existing mypy disallow_incomplete_defs=false overrides)
- Fix all 43 ANN violations in the remaining modules:
  - Add -&gt; None to __post_init__ in breakpoints, file_content,
    image_content, sparse_embedding, streaming_chunk, tool, toolset, auth
  - Add -&gt; str to __str__ in filter_policy, auth, hf (2x)
  - Add *args: Any, **kwargs: Any + return types to metaclass __call__
    in component.py and document.py, and __new__ in chat_message.py
  - Add -&gt; None to async _runner() in async_pipeline.py
  - Type _check_callable_compatibility args and return bool
  - Add Callable return type to _dispatch_bm25
  - Type send_telemetry decorator params and return
  - Type __init_track__ and __setattr_warn__ wrapper functions
  - Type _parse_date, _parse_generic_args, async run()

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* chore: fix ANN violations in .github/utils and docs-website scripts

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* chore: fix mypy errors introduced by ANN annotations

- async_pipeline.py: _runner() returns Mapping[str, Any], not None
- dataclasses.py: extend type: ignore to cover arg-type in addition to call-arg

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* alphabetical order of ruff rules

* fix: add ANN type annotations to haystack/components and remove per-file-ignore

Fix all ANN (flake8-annotations) violations in haystack/components/ so
the per-file-ignore for that directory can be removed entirely.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* chore: remove haystack.components.* from mypy disallow_incomplete_defs override

All ANN type annotations have been added to haystack/components/, so the
mypy override is no longer needed for that module.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.github/utils/check_imports.py b/.github/utils/check_imports.py
@@ -46,7 +46,7 @@ def validate_module_imports(root_dir: str, exclude_subdirs: list[str] | None = N
     return imported, failed
 
 
-def main():
+def main() -> None:
     """
     This script checks that all Haystack modules can be imported successfully.
 
diff --git a/.github/utils/docstrings_checksum.py b/.github/utils/docstrings_checksum.py
@@ -4,7 +4,7 @@
 from pathlib import Path
 
 
-def docstrings_checksum(python_files: Iterator[Path]):
+def docstrings_checksum(python_files: Iterator[Path]) -> str:
     """
     Calculate the checksum of the docstrings in the given Python files.
     """
diff --git a/.github/utils/pyproject_to_requirements.py b/.github/utils/pyproject_to_requirements.py
@@ -13,7 +13,7 @@
 parser.add_argument("--extra", default="")
 
 
-def resolve(target: str, extras: dict, results: set):
+def resolve(target: str, extras: dict, results: set) -> None:
     """
     Resolve the dependencies for a given target.
     """
@@ -30,7 +30,7 @@ def resolve(target: str, extras: dict, results: set):
             resolve(t, extras, results)
 
 
-def main(pyproject_path: Path, extra: str = ""):
+def main(pyproject_path: Path, extra: str = "") -> None:
     """
     Convert a pyproject.toml file to a requirements.txt file.
     """
diff --git a/docs-website/scripts/generate_requirements.py b/docs-website/scripts/generate_requirements.py
@@ -30,7 +30,7 @@ def _package_name(dep: str) -> str:
     return candidate.strip()
 
 
-def fetch_haystack_deps(version="main"):
+def fetch_haystack_deps(version: str = "main") -> list[str]:
     """
     Fetch and parse Haystack's pyproject.toml to extract dependencies.
 
@@ -110,7 +110,7 @@ def fetch_haystack_deps(version="main"):
     return filtered_deps
 
 
-def main():
+def main() -> None:
     """Entry point for generating requirements for docs snippet tests."""
     parser = argparse.ArgumentParser(
         description="Generate requirements.txt from Haystack's pyproject.toml for docs snippet testing"
diff --git a/haystack/components/agents/agent.py b/haystack/components/agents/agent.py
@@ -511,7 +511,7 @@ def _initialize_fresh_execution(
         generation_kwargs: dict[str, Any] | None = None,
         tools: ToolsType | list[str] | None = None,
         confirmation_strategy_context: dict[str, Any] | None = None,
-        **kwargs,
+        **kwargs: Any,
     ) -> _ExecutionContext:
         """
         Initialize execution context for a fresh run of the agent.
diff --git a/haystack/components/audio/whisper_local.py b/haystack/components/audio/whisper_local.py
@@ -133,7 +133,7 @@ def run(
         documents = self.transcribe(sources, **whisper_params)
         return {"documents": documents}
 
-    def transcribe(self, sources: list[str | Path | ByteStream], **kwargs) -> list[Document]:
+    def transcribe(self, sources: list[str | Path | ByteStream], **kwargs: Any) -> list[Document]:
         """
         Transcribes the audio files into a list of Documents, one for each input file.
 
@@ -166,7 +166,7 @@ def _get_path(self, source: str | Path | ByteStream) -> Path:
             source.to_file(path)
         return path
 
-    def _raw_transcribe(self, sources: list[str | Path | ByteStream], **kwargs) -> dict[Path, Any]:
+    def _raw_transcribe(self, sources: list[str | Path | ByteStream], **kwargs: Any) -> dict[Path, Any]:
         """
         Transcribes the given audio files. Returns the output of the model, a dictionary, for each input file.
 
diff --git a/haystack/components/builders/chat_prompt_builder.py b/haystack/components/builders/chat_prompt_builder.py
@@ -213,7 +213,7 @@ def run(
         self,
         template: list[ChatMessage] | str | None = None,
         template_variables: dict[str, Any] | None = None,
-        **kwargs,
+        **kwargs: Any,
     ) -> dict[str, list[ChatMessage]]:
         """
         Renders the prompt template with the provided variables.
diff --git a/haystack/components/connectors/openapi_service.py b/haystack/components/connectors/openapi_service.py
@@ -21,7 +21,7 @@
     # If you see that https://github.com/Dorthu/openapi3/pull/124/
     # is merged, we can remove this patch - notify authors of this code
     def patch_request(
-        self,
+        self: "Operation",
         base_url: str,
         *,
         data: Any | None = None,
diff --git a/haystack/components/embedders/backends/sentence_transformers_sparse_backend.py b/haystack/components/embedders/backends/sentence_transformers_sparse_backend.py
@@ -103,7 +103,7 @@ def __init__(
             backend=backend,
         )
 
-    def embed(self, *, data: list[str], **kwargs) -> list[SparseEmbedding]:
+    def embed(self, *, data: list[str], **kwargs: Any) -> list[SparseEmbedding]:
         embeddings_list = self.model.encode(
             data,
             convert_to_tensor=False,  # output is a list of individual tensors
diff --git a/haystack/components/evaluators/context_relevance.py b/haystack/components/evaluators/context_relevance.py
@@ -157,7 +157,7 @@ def __init__(
         )
 
     @component.output_types(score=float, results=list[dict[str, Any]])
-    def run(self, **inputs) -> dict[str, Any]:
+    def run(self, **inputs: Any) -> dict[str, Any]:
         """
         Run the LLM evaluator.
 
diff --git a/haystack/components/evaluators/faithfulness.py b/haystack/components/evaluators/faithfulness.py
@@ -147,7 +147,7 @@ def __init__(
         )
 
     @component.output_types(individual_scores=list[int], score=float, results=list[dict[str, Any]])
-    def run(self, **inputs) -> dict[str, Any]:
+    def run(self, **inputs: Any) -> dict[str, Any]:
         """
         Run the LLM evaluator.
 
diff --git a/haystack/components/evaluators/llm_evaluator.py b/haystack/components/evaluators/llm_evaluator.py
@@ -176,7 +176,7 @@ def validate_init_parameters(
                 raise ValueError(msg)
 
     @component.output_types(results=list[dict[str, Any]])
-    def run(self, **inputs) -> dict[str, Any]:
+    def run(self, **inputs: Any) -> dict[str, Any]:
         """
         Run the LLM evaluator.
 
diff --git a/haystack/components/generators/chat/azure.py b/haystack/components/generators/chat/azure.py
@@ -89,7 +89,7 @@ def __init__(
         *,
         azure_ad_token_provider: AzureADTokenProvider | AsyncAzureADTokenProvider | None = None,
         http_client_kwargs: dict[str, Any] | None = None,
-    ):
+    ) -> None:
         """
         Initialize the Azure OpenAI Chat Generator component.
 
diff --git a/haystack/components/generators/chat/hugging_face_api.py b/haystack/components/generators/chat/hugging_face_api.py
@@ -594,7 +594,7 @@ def _run_streaming(
         messages: list[dict[str, str]],
         generation_kwargs: dict[str, Any],
         streaming_callback: SyncStreamingCallbackT,
-    ):
+    ) -> dict[str, list[ChatMessage]]:
         api_output: Iterable[ChatCompletionStreamOutput] = self._client.chat_completion(
             messages,
             stream=True,
@@ -665,7 +665,7 @@ async def _run_streaming_async(
         messages: list[dict[str, str]],
         generation_kwargs: dict[str, Any],
         streaming_callback: AsyncStreamingCallbackT,
-    ):
+    ) -> dict[str, list[ChatMessage]]:
         api_output: AsyncIterable[ChatCompletionStreamOutput] = await self._async_client.chat_completion(
             messages,
             stream=True,
diff --git a/haystack/components/generators/chat/hugging_face_local.py b/haystack/components/generators/chat/hugging_face_local.py
@@ -6,7 +6,7 @@
 import json
 import re
 import sys
-from collections.abc import Callable
+from collections.abc import AsyncIterator, Callable
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import asynccontextmanager, suppress
 from typing import Any, Literal, Union
@@ -523,7 +523,9 @@ async def run_async(
         return {"replies": chat_messages}
 
     @asynccontextmanager
-    async def _manage_queue_processor(self, async_handler: "AsyncHFTokenStreamingHandler"):
+    async def _manage_queue_processor(
+        self, async_handler: "AsyncHFTokenStreamingHandler"
+    ) -> AsyncIterator["asyncio.Task[None]"]:
         """Context manager for proper queue processor lifecycle management."""
         queue_processor = asyncio.create_task(async_handler.process_queue())
         try:
diff --git a/haystack/components/joiners/branch.py b/haystack/components/joiners/branch.py
@@ -116,7 +116,7 @@ def from_dict(cls, data: dict[str, Any]) -> "BranchJoiner":
         data["init_parameters"]["type_"] = deserialize_type(data["init_parameters"]["type_"])
         return default_from_dict(cls, data)
 
-    def run(self, **kwargs) -> dict[str, Any]:
+    def run(self, **kwargs: Any) -> dict[str, Any]:
         """
         Executes the `BranchJoiner`, selecting the first available input value and passing it downstream.
 
diff --git a/haystack/components/preprocessors/document_splitter.py b/haystack/components/preprocessors/document_splitter.py
@@ -240,9 +240,9 @@ def _split_by_nltk_sentence(self, doc: Document) -> list[Document]:
 
         return split_docs
 
-    def _split_by_character(self, doc) -> list[Document]:
+    def _split_by_character(self, doc: Document) -> list[Document]:
         split_at = _CHARACTER_SPLIT_BY_MAPPING[self.split_by]
-        units = doc.content.split(split_at)
+        units = doc.content.split(split_at)  # type: ignore[union-attr]
         # Add the delimiter back to all units except the last one
         for i in range(len(units) - 1):
             units[i] += split_at
@@ -255,7 +255,7 @@ def _split_by_character(self, doc) -> list[Document]:
             text_splits=text_splits, splits_pages=splits_pages, splits_start_idxs=splits_start_idxs, meta=metadata
         )
 
-    def _split_by_function(self, doc) -> list[Document]:
+    def _split_by_function(self, doc: Document) -> list[Document]:
         # the check for None is done already in the run method
         splits = self.splitting_function(doc.content)  # type: ignore
         docs: list[Document] = []
@@ -344,7 +344,7 @@ def _create_docs_from_splits(
     @staticmethod
     def _add_split_overlap_information(
         current_doc: Document, current_doc_start_idx: int, previous_doc: Document, previous_doc_start_idx: int
-    ):
+    ) -> None:
         """
         Adds split overlap information to the current and previous Document's meta.
 
diff --git a/haystack/components/preprocessors/hierarchical_document_splitter.py b/haystack/components/preprocessors/hierarchical_document_splitter.py
@@ -67,14 +67,14 @@ def run(self, documents: list[Document]) -> dict[str, list[Document]]:
             hierarchical_docs.extend(self.build_hierarchy_from_doc(doc))
         return {"documents": hierarchical_docs}
 
-    def _build_block_sizes(self):
+    def _build_block_sizes(self) -> None:
         for block_size in self.block_sizes:
             self.splitters[block_size] = DocumentSplitter(
                 split_length=block_size, split_overlap=self.split_overlap, split_by=self.split_by
             )
 
     @staticmethod
-    def _add_meta_data(document: Document):
+    def _add_meta_data(document: Document) -> Document:
         document.meta["__block_size"] = 0
         document.meta["__parent_id"] = None
         document.meta["__children_ids"] = []
diff --git a/haystack/components/rankers/sentence_transformers_diversity.py b/haystack/components/rankers/sentence_transformers_diversity.py
@@ -319,7 +319,7 @@ def _greedy_diversity_order(self, query: str, documents: list[Document]) -> list
 
         return ranked_docs
 
-    def _embed_and_normalize(self, query, texts_to_embed):
+    def _embed_and_normalize(self, query: str, texts_to_embed: list[str]) -> tuple[Any, Any]:
         assert self.model is not None  # verified in run but mypy doesn't see it
 
         # Calculate embeddings
@@ -381,7 +381,7 @@ def _maximum_margin_relevance(
         return [documents[i] for i in selected]
 
     @staticmethod
-    def _check_lambda_threshold(lambda_threshold: float, strategy: DiversityRankingStrategy):
+    def _check_lambda_threshold(lambda_threshold: float, strategy: DiversityRankingStrategy) -> None:
         if (strategy == DiversityRankingStrategy.MAXIMUM_MARGIN_RELEVANCE) and not 0 <= lambda_threshold <= 1:
             raise ValueError(f"lambda_threshold must be between 0 and 1, but got {lambda_threshold}.")
 
diff --git a/haystack/components/retrievers/auto_merging_retriever.py b/haystack/components/retrievers/auto_merging_retriever.py
@@ -99,7 +99,7 @@ def from_dict(cls, data: dict[str, Any]) -> "AutoMergingRetriever":
         return default_from_dict(cls, data)
 
     @staticmethod
-    def _check_valid_documents(matched_leaf_documents: list[Document]):
+    def _check_valid_documents(matched_leaf_documents: list[Document]) -> None:
         # check if the matched leaf documents have the required meta fields
         if not all(doc.meta.get("__parent_id") for doc in matched_leaf_documents):
             raise ValueError("The matched leaf documents do not have the required meta field '__parent_id'")
diff --git a/haystack/components/routers/conditional_router.py b/haystack/components/routers/conditional_router.py
@@ -374,7 +374,7 @@ def run(self, **kwargs: Any) -> dict[str, Any]:
 
         raise NoRouteSelectedException(f"No route fired. Routes: {self.routes}")
 
-    def _validate_routes(self, routes: list[Route]):
+    def _validate_routes(self, routes: list[Route]) -> None:
         """
         Validates a list of routes.
 
@@ -440,7 +440,7 @@ def _extract_variables(env: Environment, templates: list[str]) -> set[str]:
             variables.update(template_variables - assigned_variables)
         return variables
 
-    def _validate_template(self, env: Environment, template_text: str):
+    def _validate_template(self, env: Environment, template_text: str) -> bool:
         """
         Validates a template string by parsing it with Jinja.
 
@@ -457,7 +457,7 @@ def _validate_template(self, env: Environment, template_text: str):
         except TemplateSyntaxError:
             return False
 
-    def _output_matches_type(self, value: Any, expected_type: type):  # noqa: PLR0911
+    def _output_matches_type(self, value: Any, expected_type: type) -> bool:  # noqa: PLR0911
         """
         Checks whether `value` type matches the `expected_type`.
         """
diff --git a/haystack/core/component/component.py b/haystack/core/component/component.py
@@ -291,7 +291,7 @@ def inner(method: Callable[..., Any], sockets: Sockets) -> inspect.Signature:
                     f"Parameters of 'run' and 'run_async' methods must be the same.\nDifferences found:\n{sig_diff}"
                 )
 
-    def __call__(cls, *args, **kwargs):
+    def __call__(cls, *args: Any, **kwargs: Any) -> Any:
         """
         This method is called when clients instantiate a Component and runs before __new__ and __init__.
         """
diff --git a/haystack/core/pipeline/async_pipeline.py b/haystack/core/pipeline/async_pipeline.py
@@ -320,7 +320,7 @@ async def _schedule_task(component_name: str) -> None:
                 component_inputs = self._consume_component_inputs(component_name, comp_dict, inputs_state)
                 component_inputs = self._add_missing_input_defaults(component_inputs, comp_dict["input_sockets"])
 
-                async def _runner():
+                async def _runner() -> Mapping[str, Any]:
                     async with ready_sem:
                         component_pipeline_outputs = await self._run_component_async(
                             component_name=component_name,
diff --git a/haystack/core/type_utils.py b/haystack/core/type_utils.py
@@ -146,7 +146,7 @@ def _strict_types_are_compatible(sender: Any, receiver: Any) -> bool:  # noqa: P
     )
 
 
-def _check_callable_compatibility(sender_args, receiver_args):
+def _check_callable_compatibility(sender_args: tuple[Any, ...], receiver_args: tuple[Any, ...]) -> bool:
     """Helper function to check compatibility of Callable types"""
     if not receiver_args:
         return True
diff --git a/haystack/dataclasses/breakpoints.py b/haystack/dataclasses/breakpoints.py
@@ -81,7 +81,7 @@ class AgentBreakpoint:
     agent_name: str
     break_point: Breakpoint | ToolBreakpoint
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if (
             isinstance(self.break_point, Breakpoint) and not isinstance(self.break_point, ToolBreakpoint)
         ) and self.break_point.component_name != "chat_generator":
@@ -215,7 +215,7 @@ class PipelineSnapshot:
     timestamp: datetime | None = None
     include_outputs_from: set[str] = field(default_factory=set)
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         # Validate consistency between component_visits and ordered_component_names
         components_in_state = set(self.pipeline_state.component_visits.keys())
         components_in_order = set(self.ordered_component_names)
diff --git a/haystack/dataclasses/chat_message.py b/haystack/dataclasses/chat_message.py
@@ -282,7 +282,7 @@ class ChatMessage:
     _name: str | None = None
     _meta: dict[str, Any] = field(default_factory=dict, hash=False)
 
-    def __new__(cls, *args, **kwargs):  # noqa: ARG004
+    def __new__(cls, *args: Any, **kwargs: Any) -> "ChatMessage":  # noqa: ARG004
         """
         This method is reimplemented to make the changes to the `ChatMessage` dataclass more visible.
 
diff --git a/haystack/dataclasses/document.py b/haystack/dataclasses/document.py
@@ -20,7 +20,7 @@ class _BackwardCompatible(type):
     Metaclass that handles Document backward compatibility.
     """
 
-    def __call__(cls, *args, **kwargs):
+    def __call__(cls, *args: Any, **kwargs: Any) -> Any:
         """
         Called before Document.__init__, handles legacy fields.
 
diff --git a/haystack/dataclasses/file_content.py b/haystack/dataclasses/file_content.py
@@ -43,7 +43,7 @@ class FileContent:
     extra: dict[str, Any] = field(default_factory=dict)
     validation: bool = True
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.validation:
             return
 
diff --git a/haystack/dataclasses/image_content.py b/haystack/dataclasses/image_content.py
@@ -82,7 +82,7 @@ class ImageContent:
     meta: dict[str, Any] = field(default_factory=dict)
     validation: bool = True
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.validation:
             return
 
diff --git a/haystack/dataclasses/sparse_embedding.py b/haystack/dataclasses/sparse_embedding.py
@@ -21,7 +21,7 @@ class SparseEmbedding:
     indices: list[int]
     values: list[float]
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         """
         Checks if the indices and values lists are of the same length.
 
diff --git a/haystack/dataclasses/streaming_chunk.py b/haystack/dataclasses/streaming_chunk.py
@@ -136,7 +136,7 @@ class StreamingChunk:
     finish_reason: FinishReason | None = field(default=None)
     reasoning: ReasoningContent | None = field(default=None)
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         fields_set = sum(bool(x) for x in (self.content, self.tool_calls, self.tool_call_result, self.reasoning))
         if fields_set > 1:
             raise ValueError(
diff --git a/haystack/document_stores/in_memory/document_store.py b/haystack/document_stores/in_memory/document_store.py
diff --git a/haystack/document_stores/types/filter_policy.py b/haystack/document_stores/types/filter_policy.py
diff --git a/haystack/telemetry/_telemetry.py b/haystack/telemetry/_telemetry.py
diff --git a/haystack/tools/tool.py b/haystack/tools/tool.py
diff --git a/haystack/tools/toolset.py b/haystack/tools/toolset.py
diff --git a/haystack/utils/auth.py b/haystack/utils/auth.py
diff --git a/haystack/utils/dataclasses.py b/haystack/utils/dataclasses.py
diff --git a/haystack/utils/filters.py b/haystack/utils/filters.py
diff --git a/haystack/utils/hf.py b/haystack/utils/hf.py
diff --git a/haystack/utils/requests_utils.py b/haystack/utils/requests_utils.py
diff --git a/haystack/utils/type_serialization.py b/haystack/utils/type_serialization.py
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -103,7 +103,7 @@ def __init__(`
`103`	`103`	`backend=backend,`
`104`	`104`	`)`
`105`	`105`
`106`		`- def embed(self, , data: list[str], *kwargs) -> list[SparseEmbedding]:`
	`106`	`+ def embed(self, , data: list[str], *kwargs: Any) -> list[SparseEmbedding]:`
`107`	`107`	`embeddings_list = self.model.encode(`
`108`	`108`	`data,`
`109`	`109`	`convert_to_tensor=False, # output is a list of individual tensors`
Original file line number	Diff line number	Diff line change
`@@ -157,7 +157,7 @@ def __init__(`
`157`	`157`	`)`
`158`	`158`
`159`	`159`	`@component.output_types(score=float, results=list[dict[str, Any]])`
`160`		`- def run(self, **inputs) -> dict[str, Any]:`
	`160`	`+ def run(self, **inputs: Any) -> dict[str, Any]:`
`161`	`161`	`"""`
`162`	`162`	`Run the LLM evaluator.`
`163`	`163`