chore: add ANN ruff ruleset to llama_cpp, llama_stack, mcp, meta_llama, mistral, mongodb_atlas, nvidia, ollama, openrouter, opensearch (#2991)

Adds the flake8-annotations (ANN) ruleset to enforce return type annotations,
while excluding ANN401 (Any) globally and ANN from test and example files.
Fixes all ANN violations by adding missing return type annotations to __init__,
warm_up, close, __del__, __post_init__, and other public/private methods.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: julian-risch

integrations/llama_cpp/pyproject.toml

@@ -94,6 +94,7 @@ line-length = 120
 [tool.ruff.lint]
 select = [
     "A",
+    "ANN",
     "ARG",
     "B",
     "C",
@@ -131,14 +132,16 @@ ignore = [
     "PLR0912",
     "PLR0913",
     "PLR0915",
+  # Allow `Any` - used legitimately for dynamic types and SDK boundaries
+  "ANN401",
 ]
 
 [tool.ruff.lint.flake8-tidy-imports]
 ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252"]
+"tests/**/*" = ["PLR2004", "S101", "TID252", "ANN"]
 # Examples can print their output
 "examples/**" = ["T201"]
 "tests/**" = ["T201"]

integrations/llama_stack/examples/llama-stack-with-tools.py

@@ -41,9 +41,9 @@ def weather(city: str):
 
 response = client.run(messages=messages, tools=[weather_tool])["replies"]
 
-print(f"assistant messages: {response[0]}\n")  # noqa: T201
+print(f"assistant messages: {response[0]}\n")
 
 # If the assistant message contains a tool call, run the tool invoker
 if response[0].tool_calls:
     tool_messages = tool_invoker.run(messages=response)["tool_messages"]
-    print(f"tool messages: {tool_messages}")  # noqa: T201
+    print(f"tool messages: {tool_messages}")

integrations/llama_stack/pyproject.toml

@@ -79,6 +79,7 @@ line-length = 120
 [tool.ruff.lint]
 select = [
   "A",
+  "ANN",
   "ARG",
   "B",
   "C",
@@ -119,6 +120,8 @@ ignore = [
   # Misc
   "B008",
   "S101",
+  # Allow `Any` - used legitimately for dynamic types and SDK boundaries
+  "ANN401",
 ]
 unfixable = [
   # Don't touch unused imports
@@ -133,7 +136,9 @@ ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252", "E501", "F841"]
+"tests/**/*" = ["PLR2004", "S101", "TID252", "ANN", "E501", "F841"]
+# Examples can print their output and don't need type annotations
+"examples/**/*" = ["T201", "ANN"]
 
 [tool.coverage.run]
 source = ["haystack_integrations"]

integrations/llama_stack/src/haystack_integrations/components/generators/llama_stack/chat/chat_generator.py

@@ -68,7 +68,7 @@ def __init__(
         tools_strict: bool = False,
         max_retries: int | None = None,
         http_client_kwargs: dict[str, Any] | None = None,
-    ):
+    ) -> None:
         """
         Creates an instance of LlamaStackChatGenerator. To use this chat generator,
         you need to setup Llama Stack Server with an inference provider and have a model available.

integrations/mcp/pyproject.toml

@@ -94,6 +94,7 @@ line-length = 120
 [tool.ruff.lint]
 select = [
     "A",
+    "ANN",
     "ARG",
     "B",
     "C",
@@ -135,6 +136,8 @@ ignore = [
     "RUF005",
     "S603",
     "S607",
+    # Allow `Any` - used legitimately for dynamic types and SDK boundaries
+    "ANN401",
 ]
 unfixable = [
     # Don't touch unused imports
@@ -149,8 +152,8 @@ ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252"]
-"examples/**/*" = ["T201", "E501"] 
+"tests/**/*" = ["PLR2004", "S101", "TID252", "ANN"]
+"examples/**/*" = ["T201", "E501", "ANN"]
 
 [tool.coverage.run]
 source = ["haystack_integrations"]

integrations/mcp/src/haystack_integrations/tools/mcp/mcp_tool.py

@@ -74,7 +74,7 @@ def get_instance(cls) -> "AsyncExecutor":
                 cls._singleton_instance = cls()
             return cls._singleton_instance
 
-    def __init__(self):
+    def __init__(self) -> None:
         """Initialize a dedicated event loop"""
         self._loop: asyncio.AbstractEventLoop = asyncio.new_event_loop()
         self._thread: threading.Thread = threading.Thread(target=self._run_loop, daemon=True)
@@ -84,7 +84,7 @@ def __init__(self):
             message = "AsyncExecutor failed to start background event loop"
             raise RuntimeError(message)
 
-    def _run_loop(self):
+    def _run_loop(self) -> None:
         """Run the event loop"""
         asyncio.set_event_loop(self._loop)
         self._started.set()
@@ -107,7 +107,7 @@ def run(self, coro: Coroutine[Any, Any, Any], timeout: float | None = None) -> A
             message = f"Operation timed out after {timeout} seconds"
             raise TimeoutError(message) from e
 
-    def get_loop(self):
+    def get_loop(self) -> asyncio.AbstractEventLoop:
         """
         Get the event loop.
 
@@ -135,7 +135,7 @@ def run_background(
         # correct loop and can safely be set from other threads via *call_soon_threadsafe*.
         stop_event_promise: Future[asyncio.Event] = Future()
 
-        async def _coroutine_with_stop_event():
+        async def _coroutine_with_stop_event() -> None:
             stop_event = asyncio.Event()
             stop_event_promise.set_result(stop_event)
             await coro_factory(stop_event)
@@ -155,7 +155,7 @@ def shutdown(self, timeout: float = 2) -> None:
         :param timeout: Timeout in seconds for shutting down the event loop
         """
 
-        def _stop_loop():
+        def _stop_loop() -> None:
             self._loop.stop()
 
         asyncio.run_coroutine_threadsafe(asyncio.sleep(0), self._loop).result(timeout=timeout)
@@ -680,7 +680,7 @@ class SSEServerInfo(MCPServerInfo):
     base_delay: float = 1.0
     max_delay: float = 30.0
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         """Validate that either url or base_url is provided."""
         if not self.url and not self.base_url:
             message = "Either url or base_url must be provided"
@@ -766,7 +766,7 @@ class StreamableHttpServerInfo(MCPServerInfo):
     base_delay: float = 1.0
     max_delay: float = 30.0
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         """Validate the URL."""
         if not is_valid_http_url(self.url):
             message = f"Invalid url: {self.url}"
@@ -911,7 +911,7 @@ def __init__(
         outputs_to_string: dict[str, Any] | None = None,
         inputs_from_state: dict[str, str] | None = None,
         outputs_to_state: dict[str, dict[str, Any]] | None = None,
-    ):
+    ) -> None:
         """
         Initialize the MCP tool.
 
@@ -1062,7 +1062,7 @@ def _invoke_tool(self, **kwargs: Any) -> str | dict[str, Any]:
             # Connect on first use if eager_connect is turned off
             self.warm_up()
 
-            async def invoke():
+            async def invoke() -> Any:
                 logger.debug(f"TOOL: Inside invoke coroutine for '{self.name}'")
                 client = cast(MCPClient, self._client)
                 result = await asyncio.wait_for(client.call_tool(self.name, kwargs), timeout=self._invocation_timeout)
@@ -1274,7 +1274,7 @@ def from_dict(cls, data: dict[str, Any]) -> "Tool":
             outputs_to_state=outputs_to_state,
         )
 
-    def close(self):
+    def close(self) -> None:
         """Close the tool synchronously."""
         if hasattr(self, "_client") and self._client:
             try:
@@ -1284,7 +1284,7 @@ def close(self):
             except Exception as e:
                 logger.debug(f"TOOL: Error during synchronous worker stop: {e!s}")
 
-    def __del__(self):
+    def __del__(self) -> None:
         """Cleanup resources when the tool is garbage collected."""
         logger.debug(f"TOOL: __del__ called for MCPTool '{self.name if hasattr(self, 'name') else 'unknown'}'")
 
@@ -1309,7 +1309,7 @@ class _MCPClientSessionManager:
     # Maximum time to wait for worker shutdown in seconds
     WORKER_SHUTDOWN_TIMEOUT = 2.0
 
-    def __init__(self, client: "MCPClient", *, timeout: float | None = None):
+    def __init__(self, client: "MCPClient", *, timeout: float | None = None) -> None:
         self._client = client
         self.executor = AsyncExecutor.get_instance()
 

integrations/mcp/src/haystack_integrations/tools/mcp/mcp_toolset.py

@@ -232,7 +232,7 @@ def __init__(
         inputs_from_state: dict[str, dict[str, str]] | None = None,
         outputs_to_state: dict[str, dict[str, dict[str, Any]]] | None = None,
         outputs_to_string: dict[str, dict[str, Any]] | None = None,
-    ):
+    ) -> None:
         """
         Initialize the MCP toolset.
 
@@ -531,13 +531,13 @@ def from_dict(cls, data: dict[str, Any]) -> "MCPToolset":
             outputs_to_string=outputs_to_string if outputs_to_string else None,
         )
 
-    def close(self):
+    def close(self) -> None:
         """Close the underlying MCP client safely."""
         if hasattr(self, "_worker") and self._worker:
             try:
                 self._worker.stop()
             except Exception as e:
                 logger.debug(f"TOOLSET: error during worker stop: {e!s}")
 
-    def __del__(self):
+    def __del__(self) -> None:
         self.close()

integrations/meta_llama/pyproject.toml

@@ -79,6 +79,7 @@ line-length = 120
 [tool.ruff.lint]
 select = [
   "A",
+  "ANN",
   "ARG",
   "B",
   "C",
@@ -119,6 +120,8 @@ ignore = [
   # Misc
   "B008",
   "S101",
+  # Allow `Any` - used legitimately for dynamic types and SDK boundaries
+  "ANN401",
 ]
 
 [tool.ruff.lint.isort]
@@ -129,7 +132,7 @@ ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252"]
+"tests/**/*" = ["PLR2004", "S101", "TID252", "ANN"]
 
 [tool.coverage.run]
 source = ["haystack_integrations"]

integrations/meta_llama/src/haystack_integrations/components/generators/meta_llama/chat/chat_generator.py

@@ -74,7 +74,7 @@ def __init__(
         timeout: float | None = None,
         max_retries: int | None = None,
         tools: ToolsType | None = None,
-    ):
+    ) -> None:
         """
         Creates an instance of LlamaChatGenerator. Unless specified otherwise in the `model`, this is for Llama's
         `Llama-4-Scout-17B-16E-Instruct-FP8` model.

integrations/mistral/pyproject.toml

@@ -82,6 +82,7 @@ line-length = 120
 [tool.ruff.lint]
 select = [
   "A",
+  "ANN",
   "ARG",
   "B",
   "C",
@@ -122,6 +123,8 @@ ignore = [
   # Misc
   "B008",
   "S101",
+  # Allow `Any` - used legitimately for dynamic types and SDK boundaries
+  "ANN401",
 ]
 
 [tool.ruff.lint.isort]
@@ -132,7 +135,7 @@ ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252"]
+"tests/**/*" = ["PLR2004", "S101", "TID252", "ANN"]
 
 [tool.coverage.run]
 source = ["haystack_integrations"]