From 17bfe7821facc9551afbeba4af649fbd4a7cdd3e Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Wed, 7 Oct 2026 18:58:00 +0100 Subject: [PATCH 01/18] Make common.ai hooks report misconfiguration instead of failing silently The provider is heading to 1.0, after which changing a public hook's behaviour needs a deprecation cycle, so this fixes the silent failures and signature inconsistencies now. - PydanticAIHook.test_connection names the provider and fields when the connection's credentials were rejected and env-var auth was used. - MCPHook validates the stdio "args" and "timeout" extras, and raises AirflowOptionalProviderFeatureException when the mcp extra is missing, as does the LLMRetryPolicy module on Airflow < 3.3. - LlamaIndexHook.test_connection reports a model name LlamaIndex's OpenAI class rejects (e.g. Ollama models) instead of passing. - LangChainHook and LlamaIndexHook take llm_model / embed_model as keyword-only arguments; their positional order differed. - The vertexai connection field is labelled deprecated and ignored. --- providers/common/ai/docs/connections/mcp.rst | 3 +- .../common/ai/docs/provider_fallback.rst | 11 ++-- providers/common/ai/provider.yaml | 2 +- .../providers/common/ai/get_provider_info.py | 2 +- .../providers/common/ai/hooks/langchain.py | 2 +- .../providers/common/ai/hooks/llamaindex.py | 20 ++++---- .../airflow/providers/common/ai/hooks/mcp.py | 28 ++++++++-- .../providers/common/ai/hooks/pydantic_ai.py | 22 ++++++-- .../providers/common/ai/policies/retry.py | 3 +- .../unit/common/ai/hooks/test_langchain.py | 5 ++ .../unit/common/ai/hooks/test_llamaindex.py | 15 ++++++ .../ai/tests/unit/common/ai/hooks/test_mcp.py | 50 ++++++++++++++++++ .../unit/common/ai/hooks/test_pydantic_ai.py | 51 +++++++++++++++++++ .../unit/common/ai/policies/test_retry.py | 13 +++++ 14 files changed, 198 insertions(+), 29 deletions(-) diff --git a/providers/common/ai/docs/connections/mcp.rst b/providers/common/ai/docs/connections/mcp.rst index dc51df1cada58..04cb73dcd34c0 100644 --- a/providers/common/ai/docs/connections/mcp.rst +++ b/providers/common/ai/docs/connections/mcp.rst @@ -70,7 +70,8 @@ Environment (Extra field) Timeout (Extra field) Connection init timeout in seconds for the ``stdio`` transport. Ignored - for ``http``/``sse``. Default: ``10``. + for ``http``/``sse``. Must be a non-negative finite number; ``0`` or ``null`` + disables the timeout. Default: ``10``. Examples: ``30`` diff --git a/providers/common/ai/docs/provider_fallback.rst b/providers/common/ai/docs/provider_fallback.rst index a8a74574b5c75..8e1b1d4c792b4 100644 --- a/providers/common/ai/docs/provider_fallback.rst +++ b/providers/common/ai/docs/provider_fallback.rst @@ -202,12 +202,11 @@ there rather than discovered mid-incident. Credential fields a provider class re ``TypeError`` are caught by the hook, which retries with the env-var-based provider constructor and logs a warning either way; if the required env var is also missing, that retry raises ``pydantic_ai.exceptions.UserError``, which ``test_connection`` does surface -since it wraps the whole resolution in a broad exception handler. What it cannot show is the -opposite case: the env var *is* set on the worker, the retry quietly succeeds, and -``test_connection`` reports success even though the credentials you configured on the -connection were silently ignored -- check the logs for that warning rather than relying on -``test_connection`` alone. It also does not call the provider, so a well-formed but revoked -key still passes -- that is what the drill below is for. +since it wraps the whole resolution in a broad exception handler. In the opposite case -- +the env var *is* set on the worker and the retry succeeds -- ``test_connection`` still +reports success, but its message names the provider and the connection fields that were +ignored. It does not call the provider, so a well-formed but revoked key still passes -- +that is what the drill below is for. *Drill it.* Point the primary at an endpoint nothing listens on and run the Dag. The task should still succeed, and the run summary in its log names the model that answered: diff --git a/providers/common/ai/provider.yaml b/providers/common/ai/provider.yaml index a985704dbea2e..814a850a20b6b 100644 --- a/providers/common/ai/provider.yaml +++ b/providers/common/ai/provider.yaml @@ -426,7 +426,7 @@ connection-types: - 'null' vertexai: label: Force Vertex AI Mode - description: "Ignored (kept for compatibility); mode is now selected via the Model field's prefix." + description: "Deprecated and ignored; the Model field's prefix selects the mode." schema: type: - boolean diff --git a/providers/common/ai/src/airflow/providers/common/ai/get_provider_info.py b/providers/common/ai/src/airflow/providers/common/ai/get_provider_info.py index 19775160600c5..97364eb0c5030 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/get_provider_info.py +++ b/providers/common/ai/src/airflow/providers/common/ai/get_provider_info.py @@ -341,7 +341,7 @@ def get_provider_info(): }, "vertexai": { "label": "Force Vertex AI Mode", - "description": "Ignored (kept for compatibility); mode is now selected via the Model field's prefix.", + "description": "Deprecated and ignored; the Model field's prefix selects the mode.", "schema": {"type": ["boolean", "null"]}, }, "api_key": { diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/langchain.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/langchain.py index 1d6122359a177..21d5b24154a45 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/langchain.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/langchain.py @@ -96,9 +96,9 @@ def __init__( self, llm_conn_id: str | None = None, embed_conn_id: str | None = None, + *, llm_model: str | None = None, embed_model: str | None = None, - *, embedding_kwargs: dict[str, Any] | None = None, **kwargs: Any, ) -> None: diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/llamaindex.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/llamaindex.py index 6a3b01f9edd1e..31375080942e4 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/llamaindex.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/llamaindex.py @@ -75,7 +75,8 @@ class LlamaIndexHook(BaseHook): still fails on the model name, not on connectivity. ``get_embedding_model()`` raises immediately at construction; ``get_llm()`` defers the error until the first call that reads - ``.metadata`` (``.chat()`` / ``.complete()``). + ``.metadata`` (``.chat()`` / ``.complete()``); ``test_connection()`` + reads it, so it reports such a model name as a failure. Connection fields: @@ -115,9 +116,9 @@ def __init__( self, llm_conn_id: str | None = None, embed_conn_id: str | None = None, - embed_model: str | None = None, - llm_model: str | None = None, *, + llm_model: str | None = None, + embed_model: str | None = None, embedding_kwargs: dict[str, Any] | None = None, **kwargs: Any, ) -> None: @@ -233,15 +234,16 @@ def get_llm(self) -> LLM: def test_connection(self) -> tuple[bool, str]: """ - Test connection by resolving the LLM. + Test connection by resolving the LLM and reading its metadata. - Validates that the model identifier is valid and the provider can be - instantiated with the supplied credentials. Does NOT make an LLM API - call -- that would be expensive and fail for reasons unrelated to - connectivity (quotas, billing, rate limits). + Reading ``.metadata`` makes LlamaIndex validate the model name against its + OpenAI-only allowlist, so an Ollama or vLLM model name fails here instead of at the + first ``.chat()`` call. Does NOT make an LLM API call -- that would be expensive and + fail for reasons unrelated to connectivity (quotas, billing, rate limits), so a + revoked API key or an unreachable **host** still passes. """ try: - self.get_llm() + self.get_llm().metadata return True, "Model resolved successfully." except Exception as e: return False, str(e) diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py index 46c81d3fcc072..7b13329a98c22 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py @@ -18,7 +18,11 @@ from typing import TYPE_CHECKING, Any -from airflow.providers.common.compat.sdk import BaseHook, mask_secret +from airflow.providers.common.compat.sdk import ( + AirflowOptionalProviderFeatureException, + BaseHook, + mask_secret, +) if TYPE_CHECKING: from collections.abc import Callable @@ -203,10 +207,10 @@ def get_conn(self) -> Any: try: from fastmcp.client.transports import SSETransport, StdioTransport, StreamableHttpTransport from pydantic_ai.mcp import MCPToolset - except ImportError: - raise ImportError( + except ImportError as e: + raise AirflowOptionalProviderFeatureException( 'MCP support requires the `mcp` package. Install it with: pip install "pydantic-ai-slim[mcp]"' - ) + ) from e conn = self.get_connection(self.mcp_conn_id) extra = conn.extra_dejson @@ -229,7 +233,23 @@ def get_conn(self) -> Any: args = extra.get("args", []) if isinstance(args, str): args = [args] + if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args): + raise ValueError( + f"'args' in extra for connection {self.mcp_conn_id!r} must be a string or a " + f"list of strings, got {args!r}." + ) timeout = extra.get("timeout", 10) + # ``None`` and ``0`` are kept valid: fastmcp's ``normalize_timeout_to_seconds`` + # treats both as "no init timeout". + if timeout is not None and ( + isinstance(timeout, bool) + or not isinstance(timeout, (int, float)) + or not 0 <= timeout < float("inf") + ): + raise ValueError( + f"'timeout' in extra for connection {self.mcp_conn_id!r} must be a non-negative " + f"finite number of seconds, got {timeout!r}." + ) toolset = MCPToolset( StdioTransport(command=command, args=args, env=self._stdio_env(extra)), init_timeout=timeout, diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py index 146560881e4a9..192ca6a80443b 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py @@ -179,6 +179,9 @@ def __init__( self._model: Model | None = None self._conn: Connection | None = None self._conn_extra_dejson: dict[str, Any] = {} + # Providers that rejected this connection's credentials and were rebuilt from env + # vars instead, as ``" (ignored: , ...)"``; surfaced by test_connection. + self._env_auth_fallbacks: list[str] = [] @classmethod def get_hook(cls, conn_id: str, hook_params: dict | None = None): @@ -457,6 +460,7 @@ def _provider_factory(pname: str) -> Any: pname, list(_kwargs), ) + self._env_auth_fallbacks.append(f"{pname} (ignored: {', '.join(_kwargs)})") return infer_provider(pname) return infer_model(model_name, provider_factory=_provider_factory) @@ -557,6 +561,7 @@ def _resolve_fallback_models(self) -> list[Model]: forwarded_model_provider=self.model_provider, ) ) + self._env_auth_fallbacks.extend(f"{conn_id}: {entry}" for entry in hook._env_auth_fallbacks) return models @@ -679,10 +684,12 @@ def test_connection(self) -> tuple[bool, str]: Test connection by resolving the model. A success here can come from this connection's own credentials, or -- when a - provider class rejects them with a ``TypeError`` -- from a silent retry against - the standard environment variables, which ignores those credentials entirely. - See :doc:`/provider_fallback`'s *Verifying a chain* section for how to tell the - two apart. Does NOT make an LLM API call — that would be expensive and fail for + provider class rejects them with a ``TypeError`` -- from a retry against the + standard environment variables, which ignores those credentials entirely. In the + second case the returned message names the provider and the ignored fields. + See :doc:`/provider_fallback`'s *Verifying a chain* section. + + Does NOT make an LLM API call — that would be expensive and fail for reasons unrelated to connectivity (quotas, billing, rate limits). Every connection in ``fallback_conn_ids`` is resolved too, so a @@ -691,9 +698,14 @@ def test_connection(self) -> tuple[bool, str]: """ try: self.get_conn() - return True, "Model resolved successfully." except Exception as e: return False, str(e) + if self._env_auth_fallbacks: + return True, ( + "Model resolved successfully, but the configured credentials were rejected and " + f"environment-variable auth is used instead: {'; '.join(self._env_auth_fallbacks)}." + ) + return True, "Model resolved successfully." class PydanticAIAzureHook(PydanticAIHook): diff --git a/providers/common/ai/src/airflow/providers/common/ai/policies/retry.py b/providers/common/ai/src/airflow/providers/common/ai/policies/retry.py index 637679b1177d5..7c3f086284b9d 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/policies/retry.py +++ b/providers/common/ai/src/airflow/providers/common/ai/policies/retry.py @@ -57,6 +57,7 @@ threshold_for, ) from airflow.providers.common.ai.utils.masking import mask_secrets +from airflow.providers.common.compat.sdk import AirflowOptionalProviderFeatureException try: from airflow.sdk.definitions.retry_policy import ( @@ -66,7 +67,7 @@ RetryPolicy, ) except ImportError: - raise ImportError( + raise AirflowOptionalProviderFeatureException( "LLMRetryPolicy requires Airflow 3.3+ which includes RetryPolicy support. " "Please upgrade apache-airflow-core." ) from None diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py b/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py index 58fb66f1bf293..9585276e4428f 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py @@ -72,6 +72,11 @@ def test_embed_conn_falls_back_to_llm_conn(self): assert hook.llm_conn_id == "my_conn" assert hook.embed_conn_id == "my_conn" + def test_model_arguments_are_keyword_only(self): + """``llm_model`` / ``embed_model`` sit in opposite order across the two hooks.""" + with pytest.raises(TypeError, match="positional argument"): + LangChainHook("llm", "embed", "openai:gpt-4o") + def test_explicit_separate_conns_and_models(self): hook = LangChainHook( llm_conn_id="chat_conn", diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py b/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py index ac0fcfd71cbfa..a8f8e72aa129f 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py @@ -56,6 +56,11 @@ def test_explicit_separate_conns_and_models(self): assert hook.embed_model == "text-embedding-3-large" assert hook.llm_model == "gpt-4o" + def test_model_arguments_are_keyword_only(self): + """``llm_model`` / ``embed_model`` sit in opposite order across the two hooks.""" + with pytest.raises(TypeError, match="positional argument"): + LlamaIndexHook("llm", "embed", "text-embedding-3-small") + def test_conn_type_is_llamaindex(self): assert LlamaIndexHook.conn_type == "llamaindex" assert LlamaIndexHook.default_conn_name == "llamaindex_default" @@ -266,6 +271,16 @@ def test_failed_connection(self, mock_get_conn, mock_cls): assert success is False assert "Invalid API key" in message + @patch.object(LlamaIndexHook, "get_connection") + def test_non_openai_model_name_fails(self, mock_get_conn): + """The real ``OpenAI`` class only rejects a model name once ``.metadata`` is read.""" + mock_get_conn.return_value = _conn(password="sk-test", extra={"llm_model": "llama3.2"}) + + success, message = LlamaIndexHook().test_connection() + + assert success is False + assert "Unknown model 'llama3.2'" in message + @patch.object(LlamaIndexHook, "get_connection") def test_failed_connection_no_model(self, mock_get_conn): mock_get_conn.return_value = _conn() diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py b/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py index d226d585dd7ab..6b455a2bfad37 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py @@ -17,12 +17,14 @@ from __future__ import annotations import json +import sys from unittest.mock import MagicMock, patch import pytest from airflow.models.connection import Connection from airflow.providers.common.ai.hooks.mcp import MCPHook +from airflow.providers.common.compat.sdk import AirflowOptionalProviderFeatureException # The hook imports these lazily inside get_conn(), so we patch them at their # source modules rather than on the hook module. MCPToolset is the unified @@ -207,6 +209,54 @@ def test_stdio_without_command_raises(self): with pytest.raises(ValueError, match="requires 'command'"): hook.get_conn() + def test_missing_mcp_dependency_raises_optional_feature_exception(self): + hook = MCPHook(mcp_conn_id="test_conn") + with patch.dict(sys.modules, {"fastmcp.client.transports": None}): + with pytest.raises(AirflowOptionalProviderFeatureException, match="pydantic-ai-slim"): + hook.get_conn() + + @pytest.mark.parametrize("bad_args", [{"a": 1}, ["-m", 1], 5], ids=["dict", "non_string_item", "int"]) + def test_stdio_invalid_args_raises(self, bad_args): + hook = MCPHook(mcp_conn_id="test_conn") + conn = Connection( + conn_id="test_conn", + conn_type="mcp", + extra=json.dumps({"transport": "stdio", "command": "uvx", "args": bad_args}), + ) + with patch.object(hook, "get_connection", return_value=conn): + with pytest.raises(ValueError, match="'args' in extra"): + hook.get_conn() + + @pytest.mark.parametrize( + "bad_timeout", + ["30", -5, -0.5, float("nan"), float("inf"), True, [10]], + ids=["str", "neg", "neg_float", "nan", "inf", "bool", "list"], + ) + def test_stdio_invalid_timeout_raises(self, bad_timeout): + hook = MCPHook(mcp_conn_id="test_conn") + conn = Connection( + conn_id="test_conn", + conn_type="mcp", + extra=json.dumps({"transport": "stdio", "command": "uvx", "args": [], "timeout": bad_timeout}), + ) + with patch.object(hook, "get_connection", return_value=conn): + with pytest.raises(ValueError, match="'timeout' in extra"): + hook.get_conn() + + @patch(_MCP_TOOLSET, autospec=True) + @patch(_STDIO_TRANSPORT, autospec=True) + def test_stdio_float_zero_and_null_timeout_accepted(self, mock_transport_cls, mock_toolset_cls): + for timeout in (2.5, 0, 0.0, None): + hook = MCPHook(mcp_conn_id="test_conn") + conn = Connection( + conn_id="test_conn", + conn_type="mcp", + extra=json.dumps({"transport": "stdio", "command": "uvx", "args": [], "timeout": timeout}), + ) + with patch.object(hook, "get_connection", return_value=conn): + hook.get_conn() + mock_toolset_cls.assert_called_with(mock_transport_cls.return_value, init_timeout=timeout) + def test_unknown_transport_raises(self): hook = MCPHook(mcp_conn_id="test_conn") conn = Connection( diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py b/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py index 2340189bb9140..cc4c1b6f80e9d 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py @@ -1561,6 +1561,20 @@ def test_caller_instrument_short_circuits(self, mock_infer_model, mock_settings, mock_settings.assert_not_called() +class _RejectsKwargsProvider: + """Stand-in for a provider class whose constructor takes none of the connection's fields.""" + + def __init__(self): + pass + + +def _call_provider_factory(model_name, provider_factory=None): + """Stand-in for ``infer_model`` that, like the real one, builds the provider eagerly.""" + if provider_factory is not None: + provider_factory(model_name.split(":", 1)[0]) + return MagicMock(spec=Model) + + class TestPydanticAIHookTestConnection: @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_model", autospec=True) def test_successful_connection(self, mock_infer_model): @@ -1610,6 +1624,43 @@ def test_failed_connection_no_model(self): assert success is False assert "No model specified" in message + @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider", autospec=True) + @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider_class", autospec=True) + @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_model", autospec=True) + def test_reports_credentials_dropped_by_env_var_retry( + self, mock_infer_model, mock_infer_provider_class, mock_infer_provider, registry + ): + """A provider class rejecting the connection's kwargs is retried from env vars; the + success message must name the ignored fields instead of reporting a clean pass.""" + mock_infer_provider_class.return_value = _RejectsKwargsProvider + mock_infer_model.side_effect = _call_provider_factory + registry.add("primary", password="sk-key", extra={"model": "openai:gpt-5.6-sol"}) + + success, message = PydanticAIHook(llm_conn_id="primary").test_connection() + + assert success is True + assert "environment-variable auth is used instead" in message + assert "openai (ignored: api_key)" in message + mock_infer_provider.assert_called_once_with("openai") + + @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider", autospec=True) + @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider_class", autospec=True) + @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_model", autospec=True) + def test_reports_credentials_dropped_in_a_fallback_connection( + self, mock_infer_model, mock_infer_provider_class, mock_infer_provider, registry + ): + mock_infer_provider_class.return_value = _RejectsKwargsProvider + mock_infer_model.side_effect = _call_provider_factory + registry.add("primary", extra={"model": "openai:gpt-5.6-sol"}) + registry.add("second", password="sk-key", extra={"model": "openai:gpt-5.6-sol"}) + + success, message = PydanticAIHook( + llm_conn_id="primary", fallback_conn_ids=["second"] + ).test_connection() + + assert success is True + assert "second: openai (ignored: api_key)" in message + # --------------------------------------------------------------------------- # Subclass hook tests diff --git a/providers/common/ai/tests/unit/common/ai/policies/test_retry.py b/providers/common/ai/tests/unit/common/ai/policies/test_retry.py index a317988efe8e8..de4c217d52177 100644 --- a/providers/common/ai/tests/unit/common/ai/policies/test_retry.py +++ b/providers/common/ai/tests/unit/common/ai/policies/test_retry.py @@ -17,10 +17,12 @@ from __future__ import annotations import copy +import importlib.util import json import logging import math import re +import sys import traceback import warnings from datetime import timedelta @@ -37,6 +39,7 @@ # Skip the entire test module on older Airflow versions tested in compat CI. pytest.importorskip("airflow.sdk.definitions.retry_policy", reason="RetryPolicy requires Airflow 3.3+") +from airflow.providers.common.ai.policies import retry as retry_module from airflow.providers.common.ai.policies.retry import ( CLASSIFIER_INSTRUCTIONS, DEFAULT_CATEGORIES, @@ -48,6 +51,7 @@ redact_registered_secrets, ) from airflow.providers.common.ai.utils.decision import picked_key +from airflow.providers.common.compat.sdk import AirflowOptionalProviderFeatureException from airflow.sdk._shared.secrets_masker import reset_secrets_masker from airflow.sdk.definitions.retry_policy import RetryAction, RetryDecision, RetryPolicy, RetryRule from airflow.sdk.log import mask_secret @@ -109,6 +113,15 @@ def test_redact_registered_secrets_masks_only_registered_values(): ) +def test_import_without_retry_policy_support_raises_optional_feature_exception(): + """A fresh copy of the module is executed so the real one in ``sys.modules`` stays intact.""" + spec = importlib.util.spec_from_file_location("_retry_without_support", retry_module.__file__) + module = importlib.util.module_from_spec(spec) + with patch.dict(sys.modules, {"airflow.sdk.definitions.retry_policy": None}): + with pytest.raises(AirflowOptionalProviderFeatureException, match="Airflow 3.3"): + spec.loader.exec_module(module) + + class TestErrorCategory: @pytest.mark.parametrize("description", ["", " ", None, 3]) def test_description_must_be_a_non_empty_string(self, description): From f7ab6f807615a3e2f1eaf2ac6212896a4a2ae147 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Thu, 8 Oct 2026 19:17:32 +0100 Subject: [PATCH 02/18] Skip the LLMRetryPolicy example Dag on cores without RetryPolicy support The example's guard caught only ImportError, but LLMRetryPolicy raises AirflowOptionalProviderFeatureException on Airflow < 3.3, so the example Dag failed to import there instead of being skipped. --- .../common/ai/example_dags/example_llm_retry_policy.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/providers/common/ai/src/airflow/providers/common/ai/example_dags/example_llm_retry_policy.py b/providers/common/ai/src/airflow/providers/common/ai/example_dags/example_llm_retry_policy.py index 8a9f17ce845e4..3da0d71b1fd98 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/example_dags/example_llm_retry_policy.py +++ b/providers/common/ai/src/airflow/providers/common/ai/example_dags/example_llm_retry_policy.py @@ -36,7 +36,7 @@ from dataclasses import replace from datetime import timedelta -from airflow.providers.common.compat.sdk import dag, task +from airflow.providers.common.compat.sdk import AirflowOptionalProviderFeatureException, dag, task try: from airflow.providers.common.ai.policies.retry import ( @@ -181,6 +181,7 @@ def task_ambiguous(): task_ambiguous() example_llm_retry_policy_classifier() -except ImportError: - # RetryPolicy requires Airflow 3.3+; example DAG is skipped on older versions. +except (ImportError, AirflowOptionalProviderFeatureException): + # RetryPolicy requires Airflow 3.3+; policies/retry.py raises AirflowOptionalProviderFeatureException + # (not an ImportError) on older versions, so the example Dag is skipped there. pass From 12a7cbb52289f966ca91d39ef7767cde1da4fd2c Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Thu, 8 Oct 2026 19:17:48 +0100 Subject: [PATCH 03/18] Describe what the keyword-only model argument tests pin The docstrings described the old llm_model/embed_model ordering; they now state the behaviour under test. --- .../common/ai/tests/unit/common/ai/hooks/test_langchain.py | 2 +- .../common/ai/tests/unit/common/ai/hooks/test_llamaindex.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py b/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py index 9585276e4428f..806d5f259dcde 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py @@ -73,7 +73,7 @@ def test_embed_conn_falls_back_to_llm_conn(self): assert hook.embed_conn_id == "my_conn" def test_model_arguments_are_keyword_only(self): - """``llm_model`` / ``embed_model`` sit in opposite order across the two hooks.""" + """The model arguments cannot be passed positionally.""" with pytest.raises(TypeError, match="positional argument"): LangChainHook("llm", "embed", "openai:gpt-4o") diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py b/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py index a8f8e72aa129f..9a1be4e75752c 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py @@ -57,7 +57,7 @@ def test_explicit_separate_conns_and_models(self): assert hook.llm_model == "gpt-4o" def test_model_arguments_are_keyword_only(self): - """``llm_model`` / ``embed_model`` sit in opposite order across the two hooks.""" + """The model arguments cannot be passed positionally.""" with pytest.raises(TypeError, match="positional argument"): LlamaIndexHook("llm", "embed", "text-embedding-3-small") From c4374b6d3b8453cc27ff223768e1e8d9fd25c3e6 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Thu, 8 Oct 2026 20:12:36 +0100 Subject: [PATCH 04/18] Keep a null MCP stdio timeout from falling back to fastmcp's global init timeout fastmcp replaces init_timeout=None with FASTMCP_CLIENT_INIT_TIMEOUT, so a null timeout still timed out on workers that set it. Map None to 0 before building the toolset, and parametrize the accepted-timeout test. --- .../airflow/providers/common/ai/hooks/mcp.py | 7 +++-- .../ai/tests/unit/common/ai/hooks/test_mcp.py | 30 ++++++++++++------- 2 files changed, 23 insertions(+), 14 deletions(-) diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py index 7b13329a98c22..7403a88bc95ae 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py @@ -239,8 +239,9 @@ def get_conn(self) -> Any: f"list of strings, got {args!r}." ) timeout = extra.get("timeout", 10) - # ``None`` and ``0`` are kept valid: fastmcp's ``normalize_timeout_to_seconds`` - # treats both as "no init timeout". + # ``None`` and ``0`` are both valid "no timeout" values, but fastmcp replaces + # ``init_timeout=None`` with its global ``client_init_timeout`` setting, so ``None`` + # is mapped to ``0`` to keep ``FASTMCP_CLIENT_INIT_TIMEOUT`` from re-enabling a timeout. if timeout is not None and ( isinstance(timeout, bool) or not isinstance(timeout, (int, float)) @@ -252,7 +253,7 @@ def get_conn(self) -> Any: ) toolset = MCPToolset( StdioTransport(command=command, args=args, env=self._stdio_env(extra)), - init_timeout=timeout, + init_timeout=0 if timeout is None else timeout, ) else: raise ValueError( diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py b/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py index 6b455a2bfad37..73501bdf0f7e8 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py @@ -243,19 +243,27 @@ def test_stdio_invalid_timeout_raises(self, bad_timeout): with pytest.raises(ValueError, match="'timeout' in extra"): hook.get_conn() + @pytest.mark.parametrize( + ("timeout", "expected_init_timeout"), + [(2.5, 2.5), (0, 0), (0.0, 0.0), (None, 0)], + ids=["float", "zero", "zero_float", "null_maps_to_zero"], + ) @patch(_MCP_TOOLSET, autospec=True) @patch(_STDIO_TRANSPORT, autospec=True) - def test_stdio_float_zero_and_null_timeout_accepted(self, mock_transport_cls, mock_toolset_cls): - for timeout in (2.5, 0, 0.0, None): - hook = MCPHook(mcp_conn_id="test_conn") - conn = Connection( - conn_id="test_conn", - conn_type="mcp", - extra=json.dumps({"transport": "stdio", "command": "uvx", "args": [], "timeout": timeout}), - ) - with patch.object(hook, "get_connection", return_value=conn): - hook.get_conn() - mock_toolset_cls.assert_called_with(mock_transport_cls.return_value, init_timeout=timeout) + def test_stdio_float_zero_and_null_timeout_accepted( + self, mock_transport_cls, mock_toolset_cls, timeout, expected_init_timeout + ): + hook = MCPHook(mcp_conn_id="test_conn") + conn = Connection( + conn_id="test_conn", + conn_type="mcp", + extra=json.dumps({"transport": "stdio", "command": "uvx", "args": [], "timeout": timeout}), + ) + with patch.object(hook, "get_connection", return_value=conn): + hook.get_conn() + mock_toolset_cls.assert_called_once_with( + mock_transport_cls.return_value, init_timeout=expected_init_timeout + ) def test_unknown_transport_raises(self): hook = MCPHook(mcp_conn_id="test_conn") From c99c3323eb58efbc2350b301d8bf8a124150e615 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Thu, 8 Oct 2026 20:15:02 +0100 Subject: [PATCH 05/18] Accept the MCP stdio args shapes the connection form produces A blank Arguments field is stored as null and is now treated as an empty list. A string starting with [ is parsed as a JSON array, as the field description promises, instead of being passed as one literal argument; malformed JSON raises a ValueError naming the connection. --- .../airflow/providers/common/ai/hooks/mcp.py | 22 ++++++++++--- .../ai/tests/unit/common/ai/hooks/test_mcp.py | 31 ++++++++++++++++++- 2 files changed, 47 insertions(+), 6 deletions(-) diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py index 7403a88bc95ae..4bea1a7fc4381 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py @@ -16,6 +16,7 @@ # under the License. from __future__ import annotations +import json from typing import TYPE_CHECKING, Any from airflow.providers.common.compat.sdk import ( @@ -230,13 +231,24 @@ def get_conn(self) -> Any: raise ValueError( f"Connection {self.mcp_conn_id!r} requires 'command' in extra for stdio transport." ) - args = extra.get("args", []) - if isinstance(args, str): - args = [args] + args = extra.get("args") + if args is None: + args = [] + elif isinstance(args, str): + if args.strip().startswith("["): + try: + args = json.loads(args) + except ValueError as e: + raise ValueError( + f"'args' in extra for connection {self.mcp_conn_id!r} looks like a JSON array " + f"but is not valid JSON: {args!r}." + ) from e + else: + args = [args] if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args): raise ValueError( - f"'args' in extra for connection {self.mcp_conn_id!r} must be a string or a " - f"list of strings, got {args!r}." + f"'args' in extra for connection {self.mcp_conn_id!r} must be a string, a JSON " + f"array of strings or a list of strings, got {args!r}." ) timeout = extra.get("timeout", 10) # ``None`` and ``0`` are both valid "no timeout" values, but fastmcp replaces diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py b/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py index 73501bdf0f7e8..7b2141d431a1f 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py @@ -180,6 +180,31 @@ def test_args_string_converted_to_list(self, mock_transport_cls, mock_toolset_cl mock_transport_cls.assert_called_once_with(command="uvx", args=["mcp-run-python"], env=None) + @pytest.mark.parametrize( + ("raw_args", "expected_args"), + [ + (None, []), + ('["mcp-run-python"]', ["mcp-run-python"]), + (' ["-m", "server"]', ["-m", "server"]), + ], + ids=["null", "json_array_string", "json_array_string_leading_space"], + ) + @patch(_MCP_TOOLSET, autospec=True) + @patch(_STDIO_TRANSPORT, autospec=True) + def test_args_from_connection_form_shapes( + self, mock_transport_cls, mock_toolset_cls, raw_args, expected_args + ): + hook = MCPHook(mcp_conn_id="test_conn") + conn = Connection( + conn_id="test_conn", + conn_type="mcp", + extra=json.dumps({"transport": "stdio", "command": "uvx", "args": raw_args}), + ) + with patch.object(hook, "get_connection", return_value=conn): + hook.get_conn() + + mock_transport_cls.assert_called_once_with(command="uvx", args=expected_args, env=None) + def test_http_without_host_raises(self): hook = MCPHook(mcp_conn_id="test_conn") conn = Connection(conn_id="test_conn", conn_type="mcp") @@ -215,7 +240,11 @@ def test_missing_mcp_dependency_raises_optional_feature_exception(self): with pytest.raises(AirflowOptionalProviderFeatureException, match="pydantic-ai-slim"): hook.get_conn() - @pytest.mark.parametrize("bad_args", [{"a": 1}, ["-m", 1], 5], ids=["dict", "non_string_item", "int"]) + @pytest.mark.parametrize( + "bad_args", + [{"a": 1}, ["-m", 1], 5, '["-m", 1]', '["-m"', '["-m"] trailing'], + ids=["dict", "non_string_item", "int", "json_non_string_item", "malformed_json", "trailing_text"], + ) def test_stdio_invalid_args_raises(self, bad_args): hook = MCPHook(mcp_conn_id="test_conn") conn = Connection( From 872b15277b6c8a7cec0687f7503408c649c9ab0f Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Thu, 8 Oct 2026 20:19:40 +0100 Subject: [PATCH 06/18] Fail closed when a provider class rejects the connection's credentials get_conn() used to log a warning and rebuild the provider from environment variables, authenticating as a different identity than the connection names. It now raises a ValueError naming the connection, the provider and the ignored fields, so test_connection reports the failure too. The _env_auth_fallbacks bookkeeping that only existed to report the old retry is removed. --- .../common/ai/docs/provider_fallback.rst | 13 ++--- .../providers/common/ai/hooks/pydantic_ai.py | 41 +++++---------- .../unit/common/ai/hooks/test_pydantic_ai.py | 51 ++++++++++--------- 3 files changed, 45 insertions(+), 60 deletions(-) diff --git a/providers/common/ai/docs/provider_fallback.rst b/providers/common/ai/docs/provider_fallback.rst index 8e1b1d4c792b4..4e7d1487717f5 100644 --- a/providers/common/ai/docs/provider_fallback.rst +++ b/providers/common/ai/docs/provider_fallback.rst @@ -199,14 +199,11 @@ Two checks, neither of which requires waiting for a real outage: *Test the connection.* ``test_connection`` on the primary resolves every connection in the chain, so a fallback with a missing ``model`` or an unknown connection ID is reported by name there rather than discovered mid-incident. Credential fields a provider class rejects with a -``TypeError`` are caught by the hook, which retries with the env-var-based provider -constructor and logs a warning either way; if the required env var is also missing, that -retry raises ``pydantic_ai.exceptions.UserError``, which ``test_connection`` does surface -since it wraps the whole resolution in a broad exception handler. In the opposite case -- -the env var *is* set on the worker and the retry succeeds -- ``test_connection`` still -reports success, but its message names the provider and the connection fields that were -ignored. It does not call the provider, so a well-formed but revoked key still passes -- -that is what the drill below is for. +``TypeError`` fail the resolution with a ``ValueError`` naming the connection, the provider and +the ignored fields -- the hook never falls back to environment-variable auth, which would +authenticate as a different identity -- and ``test_connection`` reports it as a failure. It +does not call the provider, so a well-formed but revoked key still passes -- that is what the +drill below is for. *Drill it.* Point the primary at an endpoint nothing listens on and run the Dag. The task should still succeed, and the run summary in its log names the model that answered: diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py index 192ca6a80443b..518fc575f73cd 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py @@ -25,7 +25,7 @@ from pydantic_ai.exceptions import ModelAPIError from pydantic_ai.models import infer_model from pydantic_ai.models.fallback import FallbackModel -from pydantic_ai.providers import infer_provider, infer_provider_class +from pydantic_ai.providers import infer_provider_class from airflow.providers.common.ai.observability import genai_instrumentation_settings from airflow.providers.common.ai.utils.toolset_base import MaskingCapability @@ -179,9 +179,6 @@ def __init__( self._model: Model | None = None self._conn: Connection | None = None self._conn_extra_dejson: dict[str, Any] = {} - # Providers that rejected this connection's credentials and were rebuilt from env - # vars instead, as ``" (ignored: , ...)"``; surfaced by test_connection. - self._env_auth_fallbacks: list[str] = [] @classmethod def get_hook(cls, conn_id: str, hook_params: dict | None = None): @@ -454,14 +451,12 @@ def _resolve_own_model( def _provider_factory(pname: str) -> Any: try: return infer_provider_class(pname)(**_kwargs) - except TypeError: - self.log.warning( - "Provider '%s' rejected kwargs %s; falling back to env-var auth", - pname, - list(_kwargs), - ) - self._env_auth_fallbacks.append(f"{pname} (ignored: {', '.join(_kwargs)})") - return infer_provider(pname) + except TypeError as e: + raise ValueError( + f"Provider '{pname}' rejected the credentials from connection " + f"'{self.llm_conn_id}' (ignored: {', '.join(_kwargs)}). Not falling back to " + "environment-variable auth, which would authenticate as a different identity." + ) from e return infer_model(model_name, provider_factory=_provider_factory) @@ -561,7 +556,6 @@ def _resolve_fallback_models(self) -> list[Model]: forwarded_model_provider=self.model_provider, ) ) - self._env_auth_fallbacks.extend(f"{conn_id}: {entry}" for entry in hook._env_auth_fallbacks) return models @@ -683,11 +677,8 @@ def test_connection(self) -> tuple[bool, str]: """ Test connection by resolving the model. - A success here can come from this connection's own credentials, or -- when a - provider class rejects them with a ``TypeError`` -- from a retry against the - standard environment variables, which ignores those credentials entirely. In the - second case the returned message names the provider and the ignored fields. - See :doc:`/provider_fallback`'s *Verifying a chain* section. + A provider class rejecting the connection's credentials is reported as a failure + naming the provider and the ignored fields. Does NOT make an LLM API call — that would be expensive and fail for reasons unrelated to connectivity (quotas, billing, rate limits). @@ -700,11 +691,6 @@ def test_connection(self) -> tuple[bool, str]: self.get_conn() except Exception as e: return False, str(e) - if self._env_auth_fallbacks: - return True, ( - "Model resolved successfully, but the configured credentials were rejected and " - f"environment-variable auth is used instead: {'; '.join(self._env_auth_fallbacks)}." - ) return True, "Model resolved successfully." @@ -939,11 +925,10 @@ def _get_provider_kwargs( # "vertexai" predates pydantic-ai splitting GoogleProvider (Generative Language API) # from GoogleCloudProvider (Vertex AI, which hardcodes vertexai=True internally and # accepts no such constructor kwarg) in pydantic/pydantic-ai#5336. Forwarding it would - # raise TypeError, which the base hook's `except TypeError` in get_conn() would then - # catch: it logs a warning and falls back to env-var auth rather than raising -- - # authenticating as the wrong identity (with *all* other kwargs discarded). Accept - # the field for backward compatibility but never forward it: which API is used is - # now controlled by the model prefix. + # raise TypeError, which the base hook's `except TypeError` in get_conn() would turn + # into a ValueError rejecting the whole connection. Accept the field for backward + # compatibility but never forward it: which API is used is now controlled by the + # model prefix. if extra.get("vertexai") is not None: self.log.warning( "The 'vertexai' connection field is ignored; Vertex AI vs. Generative Language " diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py b/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py index cc4c1b6f80e9d..2679b15162609 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py @@ -1624,42 +1624,48 @@ def test_failed_connection_no_model(self): assert success is False assert "No model specified" in message - @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider", autospec=True) @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider_class", autospec=True) @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_model", autospec=True) - def test_reports_credentials_dropped_by_env_var_retry( - self, mock_infer_model, mock_infer_provider_class, mock_infer_provider, registry + def test_get_conn_raises_when_provider_class_rejects_credentials( + self, mock_infer_model, mock_infer_provider_class, registry ): - """A provider class rejecting the connection's kwargs is retried from env vars; the - success message must name the ignored fields instead of reporting a clean pass.""" mock_infer_provider_class.return_value = _RejectsKwargsProvider mock_infer_model.side_effect = _call_provider_factory registry.add("primary", password="sk-key", extra={"model": "openai:gpt-5.6-sol"}) - success, message = PydanticAIHook(llm_conn_id="primary").test_connection() + with pytest.raises(ValueError, match="rejected the credentials") as exc_info: + PydanticAIHook(llm_conn_id="primary").get_conn() - assert success is True - assert "environment-variable auth is used instead" in message - assert "openai (ignored: api_key)" in message - mock_infer_provider.assert_called_once_with("openai") + assert isinstance(exc_info.value.__cause__, TypeError) - @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider", autospec=True) + @pytest.mark.parametrize( + ("fallback_conn_ids", "expected_conn_id"), + [ + pytest.param(None, "primary", id="primary"), + pytest.param(["second"], "second", id="fallback_connection"), + ], + ) @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider_class", autospec=True) @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_model", autospec=True) - def test_reports_credentials_dropped_in_a_fallback_connection( - self, mock_infer_model, mock_infer_provider_class, mock_infer_provider, registry + def test_reports_credentials_rejected_by_provider_class( + self, mock_infer_model, mock_infer_provider_class, registry, fallback_conn_ids, expected_conn_id ): mock_infer_provider_class.return_value = _RejectsKwargsProvider mock_infer_model.side_effect = _call_provider_factory - registry.add("primary", extra={"model": "openai:gpt-5.6-sol"}) + registry.add( + "primary", + password="sk-key" if fallback_conn_ids is None else None, + extra={"model": "openai:gpt-5.6-sol"}, + ) registry.add("second", password="sk-key", extra={"model": "openai:gpt-5.6-sol"}) success, message = PydanticAIHook( - llm_conn_id="primary", fallback_conn_ids=["second"] + llm_conn_id="primary", fallback_conn_ids=fallback_conn_ids ).test_connection() - assert success is True - assert "second: openai (ignored: api_key)" in message + assert success is False + assert f"Provider 'openai' rejected the credentials from connection '{expected_conn_id}'" in message + assert "(ignored: api_key)" in message # --------------------------------------------------------------------------- @@ -2071,13 +2077,12 @@ def test_get_conn_uses_explicit_project(self, mock_infer_provider_class, mock_in mock_provider_cls.assert_called_with(project="my-project", location="europe-west4") @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_model", autospec=True) - @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider", autospec=True) @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider_class", autospec=True) - def test_get_conn_vertexai_flag_does_not_trigger_typeerror_fallback( - self, mock_infer_provider_class, mock_infer_provider, mock_infer_model + def test_get_conn_vertexai_flag_does_not_trigger_typeerror_rejection( + self, mock_infer_provider_class, mock_infer_model ): - """Setting ``vertexai`` must not push ``get_conn`` onto the ``except TypeError`` - fallback path, which would silently discard project/location/credentials. + """Setting ``vertexai`` must not make the provider class reject the connection's + kwargs with ``TypeError``, which ``get_conn`` turns into a ``ValueError``. The stand-in below has the exact keyword-only signature of the real ``GoogleCloudProvider.__init__`` (verified against the installed pydantic-ai) so @@ -2131,8 +2136,6 @@ def __init__( assert isinstance(provider, FakeGoogleCloudProvider) assert provider.kwargs["project"] == "my-project" assert provider.kwargs["location"] == "us-central1" - # The TypeError fallback must never have been reached. - mock_infer_provider.assert_not_called() def test_documented_model_prefix_is_a_valid_pydantic_ai_provider(self): """Regression test: the model-prefix documented in the connection form and From ea7cccf8f5ff27fdead94b23989ee9bfb24bc719 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Fri, 9 Oct 2026 07:51:32 +0100 Subject: [PATCH 07/18] Stop the Snowflake Cortex test patching the removed env-var fallback PydanticAIHook no longer falls back to infer_provider when a provider class rejects the connection's credentials, so the test patched an attribute that is gone. A model that resolves now proves the explicit-credentials path, because rejected credentials raise a ValueError. --- .../unit/snowflake/hooks/test_cortex_model.py | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/providers/snowflake/tests/unit/snowflake/hooks/test_cortex_model.py b/providers/snowflake/tests/unit/snowflake/hooks/test_cortex_model.py index 8371c9505f856..1449dcb640c88 100644 --- a/providers/snowflake/tests/unit/snowflake/hooks/test_cortex_model.py +++ b/providers/snowflake/tests/unit/snowflake/hooks/test_cortex_model.py @@ -248,17 +248,14 @@ async def handler(request: httpx2.Request) -> httpx2.Response: class TestGetConn: @mock.patch(f"{MODULE_PATH}.SnowflakeRestTokenProvider", autospec=True) @mock.patch(f"{MODULE_PATH}.SnowflakeHook", autospec=True) - @mock.patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider", autospec=True) def test_get_conn_uses_explicit_credentials_despite_connection_password( - self, mock_infer_provider, mock_hook_cls, mock_provider_cls + self, mock_hook_cls, mock_provider_cls ): - """End-to-end: get_conn() must not raise and must not fall back to env-var auth. + """End-to-end: get_conn() must not raise when the connection also carries a password. - ``infer_provider`` is only reached by the base hook's ``except TypeError`` fallback - (``pydantic_ai.py``'s ``_provider_factory``), so asserting it was never called pins that - the explicit-credentials path was taken -- ``model is not None`` alone would also pass - if this hook's kwargs were rejected and pydantic-ai silently fell back to - ``SNOWFLAKE_ACCOUNT``/``SNOWFLAKE_TOKEN`` env vars instead. + The base hook raises ``ValueError`` (it never falls back to env-var auth) when the + provider class rejects the kwargs it derives from the connection, so a model that + resolves means the explicit-credentials path was taken. """ mock_hook_cls.return_value._get_static_conn_params = {"account": "airflow"} @@ -276,7 +273,6 @@ def test_get_conn_uses_explicit_credentials_despite_connection_password( assert model is not None mock_hook_cls.assert_called_once_with(snowflake_conn_id="snowflake_conn") - mock_infer_provider.assert_not_called() @mock.patch(f"{MODULE_PATH}.SnowflakeRestTokenProvider", autospec=True) @mock.patch(f"{MODULE_PATH}.SnowflakeHook", autospec=True) From 2633c2822458310976806051f72de857ac97b88c Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Sat, 10 Oct 2026 19:13:38 +0100 Subject: [PATCH 08/18] Show which fields a provider class rejected when failing closed The ValueError raised by get_conn() when a provider class rejects the connection's credentials now carries the provider's TypeError text and lists the fields as "fields passed" rather than "ignored", so test_connection says which field broke. The LiteLLMProvider note, the provider fallback guide and the Snowflake Cortex test docstring now describe the ValueError instead of the removed warning and environment-variable fallback. --- providers/common/ai/docs/provider_fallback.rst | 8 ++++---- providers/common/ai/docs/self_hosted_models.rst | 10 +++++----- .../airflow/providers/common/ai/hooks/pydantic_ai.py | 6 +++--- .../ai/tests/unit/common/ai/hooks/test_pydantic_ai.py | 3 ++- .../tests/unit/snowflake/hooks/test_cortex_model.py | 4 ++-- 5 files changed, 16 insertions(+), 15 deletions(-) diff --git a/providers/common/ai/docs/provider_fallback.rst b/providers/common/ai/docs/provider_fallback.rst index 4e7d1487717f5..318fe41bea187 100644 --- a/providers/common/ai/docs/provider_fallback.rst +++ b/providers/common/ai/docs/provider_fallback.rst @@ -200,10 +200,10 @@ Two checks, neither of which requires waiting for a real outage: chain, so a fallback with a missing ``model`` or an unknown connection ID is reported by name there rather than discovered mid-incident. Credential fields a provider class rejects with a ``TypeError`` fail the resolution with a ``ValueError`` naming the connection, the provider and -the ignored fields -- the hook never falls back to environment-variable auth, which would -authenticate as a different identity -- and ``test_connection`` reports it as a failure. It -does not call the provider, so a well-formed but revoked key still passes -- that is what the -drill below is for. +the fields passed, with the provider's ``TypeError`` text -- the hook never falls back to +environment-variable auth, which would authenticate as a different identity -- and +``test_connection`` reports it as a failure. It does not call the provider, so a well-formed +but revoked key still passes -- that is what the drill below is for. *Drill it.* Point the primary at an endpoint nothing listens on and run the Dag. The task should still succeed, and the run summary in its log names the model that answered: diff --git a/providers/common/ai/docs/self_hosted_models.rst b/providers/common/ai/docs/self_hosted_models.rst index f454d0a2a2b4e..ce449cd65fa55 100644 --- a/providers/common/ai/docs/self_hosted_models.rst +++ b/providers/common/ai/docs/self_hosted_models.rst @@ -317,11 +317,11 @@ its OpenAI provider, and there's no separate ``ollama`` extra. ``LiteLLMProvider`` is an exception: its constructor takes ``api_base`` instead of ``base_url``, so passing ``host`` raises a ``TypeError`` that - the hook catches, logs a warning, and falls back to environment-variable - auth, ignoring ``host`` entirely. Point a LiteLLM proxy's OpenAI-compatible - endpoint via ``openai:`` instead -- this is the same proxy role - used in the gateway section above, just addressed through the working - prefix rather than the rejected ``litellm:`` one. + the hook re-raises as a ``ValueError``: the connection is rejected rather + than falling back to environment-variable auth. Point a LiteLLM proxy's + OpenAI-compatible endpoint via ``openai:`` instead -- this is the + same proxy role used in the gateway section above, just addressed through + the working prefix rather than the rejected ``litellm:`` one. .. _self_hosted_models_other_servers: diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py index 518fc575f73cd..070baf4ee3959 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py @@ -454,8 +454,8 @@ def _provider_factory(pname: str) -> Any: except TypeError as e: raise ValueError( f"Provider '{pname}' rejected the credentials from connection " - f"'{self.llm_conn_id}' (ignored: {', '.join(_kwargs)}). Not falling back to " - "environment-variable auth, which would authenticate as a different identity." + f"'{self.llm_conn_id}' (fields passed: {', '.join(_kwargs)}): {e}. " + "Not falling back to environment-variable auth, which would authenticate as a different identity." ) from e return infer_model(model_name, provider_factory=_provider_factory) @@ -678,7 +678,7 @@ def test_connection(self) -> tuple[bool, str]: Test connection by resolving the model. A provider class rejecting the connection's credentials is reported as a failure - naming the provider and the ignored fields. + naming the provider, the fields passed and the provider's ``TypeError`` text. Does NOT make an LLM API call — that would be expensive and fail for reasons unrelated to connectivity (quotas, billing, rate limits). diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py b/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py index 2679b15162609..b7969cbf3a99d 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py @@ -1665,7 +1665,8 @@ def test_reports_credentials_rejected_by_provider_class( assert success is False assert f"Provider 'openai' rejected the credentials from connection '{expected_conn_id}'" in message - assert "(ignored: api_key)" in message + assert "(fields passed: api_key)" in message + assert "unexpected keyword argument 'api_key'" in message # --------------------------------------------------------------------------- diff --git a/providers/snowflake/tests/unit/snowflake/hooks/test_cortex_model.py b/providers/snowflake/tests/unit/snowflake/hooks/test_cortex_model.py index 1449dcb640c88..c3fcbaf937f1a 100644 --- a/providers/snowflake/tests/unit/snowflake/hooks/test_cortex_model.py +++ b/providers/snowflake/tests/unit/snowflake/hooks/test_cortex_model.py @@ -65,8 +65,8 @@ class TestGetProviderKwargs: def test_ignores_connection_password_and_omits_api_key(self, mock_hook_cls, mock_provider_cls): """Regression: a leftover Password on the pydanticai_snowflake connection must not be forwarded as api_key -- the base hook's generic handling raises TypeError against - SnowflakeProvider (which takes `token`, not `api_key`) and silently falls back to - env-var auth; this hook's own kwargs must never trigger that path.""" + SnowflakeProvider (which takes `token`, not `api_key`), which fails the connection + with a ValueError; this hook's own kwargs must never trigger that path.""" mock_hook_cls.return_value._get_static_conn_params = {"account": "airflow"} hook = PydanticAISnowflakeHook(snowflake_conn_id="snowflake_conn") From 5f9b4dac06a8714502616901cc04367fb8c56167 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Sat, 10 Oct 2026 19:15:20 +0100 Subject: [PATCH 09/18] Document that a missing mcp extra raises AirflowOptionalProviderFeatureException The toolsets page said MCPToolset raises ImportError on first connect when the mcp extra is missing, but MCPHook.get_conn() raises AirflowOptionalProviderFeatureException, the same exception SQLToolset and DataFusionToolset raise. The page now describes the three together and keeps when each one raises. --- providers/common/ai/docs/toolsets/index.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/providers/common/ai/docs/toolsets/index.rst b/providers/common/ai/docs/toolsets/index.rst index 8be3079b1d60d..1e9351cbb4b1f 100644 --- a/providers/common/ai/docs/toolsets/index.rst +++ b/providers/common/ai/docs/toolsets/index.rst @@ -113,10 +113,11 @@ Every toolset imports from the ``airflow.providers.common.ai.toolsets`` package SQLToolset, ) -``SQLToolset`` and ``DataFusionToolset`` depend on optional extras. If the extra is not -installed, the first access to the name raises ``AirflowOptionalProviderFeatureException``. -``MCPToolset`` imports without its extra; the missing dependency raises ``ImportError`` -when the toolset first connects to the MCP server. +``SQLToolset``, ``DataFusionToolset`` and ``MCPToolset`` depend on optional extras. If the +extra is not installed, they raise ``AirflowOptionalProviderFeatureException``. For +``SQLToolset`` and ``DataFusionToolset`` this happens on the first access to the name. +``MCPToolset`` imports without its extra; it raises only when the toolset first connects +to the MCP server. Every toolset here implements pydantic-ai's `AbstractToolset `__ interface, so it works in any From ba6b4d7d32a163c0177e881a71de2dcd9d82648b Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Mon, 12 Oct 2026 22:02:15 +0100 Subject: [PATCH 10/18] State that google: on the Vertex connection needs api_key and no Vertex-only fields GoogleProvider accepts only api_key/base_url, so a Vertex connection with project/location set is now rejected for a google: model. The hook docstring and the connection docs still said that spelling works regardless of the connection's fields, which only held through the removed env-var fallback. --- providers/common/ai/docs/connections/pydantic_ai_vertex.rst | 6 ++++-- .../ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/providers/common/ai/docs/connections/pydantic_ai_vertex.rst b/providers/common/ai/docs/connections/pydantic_ai_vertex.rst index 03eb1290da42f..6488156b1ace9 100644 --- a/providers/common/ai/docs/connections/pydantic_ai_vertex.rst +++ b/providers/common/ai/docs/connections/pydantic_ai_vertex.rst @@ -57,8 +57,10 @@ Model mean Vertex AI Express Mode credentials (see "Credentials" below), so its presence alone cannot tell the two platforms apart. To reach the Generative Language API instead, prefix the model explicitly with - ``google:`` -- that spelling routes to a different provider regardless of - which fields this connection sets. + ``google:``. On this connection type that spelling requires ``API Key`` + and must not set Vertex-only fields (``GCP Project``, ``Location / Region``, + ``Service Account Info``), because the ``google:`` provider accepts only + an API key. GCP Project Google Cloud project ID. Falls back to the ``GOOGLE_CLOUD_PROJECT`` diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py index 070baf4ee3959..045717e2a541d 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py @@ -878,8 +878,10 @@ class PydanticAIVertexHook(PydanticAIHook): above), so its presence alone cannot tell the two platforms apart; guessing would risk silently authenticating against the wrong endpoint. To use the Generative Language API, set an explicit ``google:``-prefixed model id (on - the hook or the connection's ``model`` extra) -- that spelling already - works today. + the hook or the connection's ``model`` extra). On this connection type that + spelling requires ``api_key`` and must not set Vertex-only fields + (``project``, ``location``, ``service_account_info``), because + ``GoogleProvider`` accepts none of them. :param llm_conn_id: Airflow connection ID. :param model_id: Model identifier, e.g. ``"google-cloud:gemini-2.5-flash"``. A From 57450dc2096ef55b751754b9759c8107e6feddb4 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Wed, 14 Oct 2026 16:25:14 +0100 Subject: [PATCH 11/18] Resolve the retry policies' hook through get_hook() so Azure connections work _ModelRetryPolicy._hook() built a bare PydanticAIHook, so a pydanticai_azure connection got the base {api_key, base_url} kwargs and AzureProvider rejected base_url. Now that a rejected provider class fails closed, every LLMRetryPolicy / ClassifierRetryPolicy classification on such a connection raised and fell back to fallback_rules. - _hook() calls PydanticAIHook.get_hook(llm_conn_id, hook_params={"model_id": ...}) so the connection type picks the hook subclass, like the operators do - Add a test that a pydanticai_azure connection resolves to PydanticAIAzureHook --- .../providers/common/ai/policies/retry.py | 2 +- .../unit/common/ai/policies/test_retry.py | 52 ++++++++++++++----- 2 files changed, 39 insertions(+), 15 deletions(-) diff --git a/providers/common/ai/src/airflow/providers/common/ai/policies/retry.py b/providers/common/ai/src/airflow/providers/common/ai/policies/retry.py index 7c3f086284b9d..4f14db9dd0ddb 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/policies/retry.py +++ b/providers/common/ai/src/airflow/providers/common/ai/policies/retry.py @@ -318,7 +318,7 @@ def __init__( def _hook(self) -> PydanticAIHook: from airflow.providers.common.ai.hooks.pydantic_ai import PydanticAIHook - return PydanticAIHook(llm_conn_id=self.llm_conn_id, model_id=self.model_id) + return PydanticAIHook.get_hook(self.llm_conn_id, hook_params={"model_id": self.model_id}) def _prompt(self, exception: BaseException, try_number: int, max_tries: int) -> str: if self.include_traceback: diff --git a/providers/common/ai/tests/unit/common/ai/policies/test_retry.py b/providers/common/ai/tests/unit/common/ai/policies/test_retry.py index de4c217d52177..33e638eeb4d46 100644 --- a/providers/common/ai/tests/unit/common/ai/policies/test_retry.py +++ b/providers/common/ai/tests/unit/common/ai/policies/test_retry.py @@ -39,6 +39,8 @@ # Skip the entire test module on older Airflow versions tested in compat CI. pytest.importorskip("airflow.sdk.definitions.retry_policy", reason="RetryPolicy requires Airflow 3.3+") +from airflow.models.connection import Connection +from airflow.providers.common.ai.hooks.pydantic_ai import PydanticAIAzureHook, PydanticAIHook from airflow.providers.common.ai.policies import retry as retry_module from airflow.providers.common.ai.policies.retry import ( CLASSIFIER_INSTRUCTIONS, @@ -83,14 +85,21 @@ def _agent(output, **kwargs): return agent +def _stub_hook(mock_hook_cls): + """Make ``get_hook`` return a hook instance that keeps the real method signatures.""" + hook = create_autospec(PydanticAIHook, instance=True) + mock_hook_cls.get_hook.return_value = hook + return hook + + def _install(mock_hook_cls, agent): """Wire a mock agent behind the patched hook class and return the mock agent.""" - mock_hook_cls.return_value.create_agent.return_value = agent + _stub_hook(mock_hook_cls).create_agent.return_value = agent return agent def _output_type(mock_hook_cls): - return mock_hook_cls.return_value.create_agent.call_args.kwargs["output_type"] + return mock_hook_cls.get_hook.return_value.create_agent.call_args.kwargs["output_type"] def _options(output_type): @@ -190,7 +199,20 @@ def test_construction_makes_no_connection_or_network_call(self, mock_hook_cls): min_confidence=0.6, ) - mock_hook_cls.assert_not_called() + mock_hook_cls.get_hook.assert_not_called() + + def test_hook_resolves_to_the_connection_types_subclass(self): + """An Azure connection must get ``PydanticAIAzureHook``, not the base hook's ``base_url`` kwargs.""" + policy = ClassifierRetryPolicy( + llm_conn_id="azure_conn", model_id="azure:gpt-5", categories=DEFAULT_CATEGORIES + ) + conn = Connection(conn_id="azure_conn", conn_type="pydanticai_azure") + + with patch.object(PydanticAIHook, "get_connection", return_value=conn): + hook = policy._hook() + + assert isinstance(hook, PydanticAIAzureHook) + assert hook.model_id == "azure:gpt-5" def test_categories_must_be_a_mapping(self): with pytest.raises(TypeError, match="categories must be a mapping"): @@ -379,7 +401,7 @@ def capture(**kwargs): agent.run_sync.return_value = _run_result(kwargs["output_type"]("rate_limit")) return agent - mock_hook_cls.return_value.create_agent.side_effect = capture + _stub_hook(mock_hook_cls).create_agent.side_effect = capture policy = ClassifierRetryPolicy(llm_conn_id="test", categories=DEFAULT_CATEGORIES) decision = policy.evaluate(RuntimeError("429"), try_number=1, max_tries=3) @@ -404,7 +426,7 @@ def capture(**kwargs): agent.run_sync.return_value = _run_result(kwargs["output_type"](name)) return agent - mock_hook_cls.return_value.create_agent.side_effect = capture + _stub_hook(mock_hook_cls).create_agent.side_effect = capture policy = ClassifierRetryPolicy( llm_conn_id="test", categories={ @@ -502,7 +524,7 @@ def test_custom_instructions_forwarded_to_agent(self, mock_hook_cls): policy.evaluate(RuntimeError("x"), try_number=1, max_tries=3) assert ( - mock_hook_cls.return_value.create_agent.call_args.kwargs["instructions"] + mock_hook_cls.get_hook.return_value.create_agent.call_args.kwargs["instructions"] == "Snowflake errors only." ) @@ -515,7 +537,9 @@ def test_model_id_and_connection_reach_the_hook(self, mock_hook_cls): policy.evaluate(RuntimeError("x"), try_number=1, max_tries=3) - mock_hook_cls.assert_called_once_with(llm_conn_id="jev_default", model_id="typesafe:jev-1.13.0") + mock_hook_cls.get_hook.assert_called_once_with( + "jev_default", hook_params={"model_id": "typesafe:jev-1.13.0"} + ) @patch(HOOK, autospec=True) def test_timeout_passed_via_model_settings(self, mock_hook_cls): @@ -984,7 +1008,7 @@ def test_agent_run_sync_failure_triggers_fallback(self, mock_hook_cls): @patch(HOOK, autospec=True) def test_hook_creation_failure_triggers_fallback(self, mock_hook_cls): - mock_hook_cls.return_value.create_agent.side_effect = RuntimeError("unexpected") + _stub_hook(mock_hook_cls).create_agent.side_effect = RuntimeError("unexpected") policy = ClassifierRetryPolicy( llm_conn_id="test", fallback_rules=[RetryRule(exception=ValueError, action=RetryAction.FAIL, reason="caught")], @@ -1071,7 +1095,7 @@ def _chain(self, mock_hook_cls, classifier_answer, confidence, llm_answer, *, ba def create_agent(**kwargs): return llm if kwargs["output_type"] is ErrorClassification else classifier - mock_hook_cls.return_value.create_agent.side_effect = create_agent + _stub_hook(mock_hook_cls).create_agent.side_effect = create_agent return ClassifierRetryPolicy( llm_conn_id="jev", min_confidence=bar, @@ -1110,7 +1134,7 @@ def test_confident_classifier_answer_never_consults_the_llm(self, mock_hook_cls) assert decision.action == RetryAction.RETRY assert decision.reason == "category=network confidence=0.95 threshold=0.80 action=retry delay=10s" - assert mock_hook_cls.return_value.create_agent.call_count == 1 + assert mock_hook_cls.get_hook.return_value.create_agent.call_count == 1 @patch(HOOK, autospec=True) def test_unsure_classifier_escalates_to_the_llm(self, mock_hook_cls): @@ -1269,7 +1293,7 @@ def evaluate(self, exception, try_number, max_tries, context=None): @patch(HOOK, autospec=True) def test_nested_classifiers_both_down_still_reach_the_outer_fail_rule(self, mock_hook_cls): """A ClassifierRetryPolicy as fallback_policy falls back with a DEFAULT of its own; the outer rules must still run.""" - mock_hook_cls.return_value.create_agent.return_value.run_sync.side_effect = TimeoutError("down") + _stub_hook(mock_hook_cls).create_agent.return_value.run_sync.side_effect = TimeoutError("down") inner = ClassifierRetryPolicy(llm_conn_id="jev_b", min_confidence=0.5) policy = ClassifierRetryPolicy( llm_conn_id="jev_a", @@ -1284,7 +1308,7 @@ def test_nested_classifiers_both_down_still_reach_the_outer_fail_rule(self, mock assert decision.action == RetryAction.FAIL assert decision.reason == "classifier answer not applied (model_error); never retry 403" - assert mock_hook_cls.return_value.create_agent.call_count == 2 + assert mock_hook_cls.get_hook.return_value.create_agent.call_count == 2 def _open_agent(category, should_retry, delay=0, reasoning="test"): @@ -1329,7 +1353,7 @@ def test_model_output_type_is_error_classification(self, mock_hook_cls): _install(mock_hook_cls, _open_agent("auth", should_retry=False)) LLMRetryPolicy(llm_conn_id="test").evaluate(PermissionError("403"), try_number=1, max_tries=3) - kwargs = mock_hook_cls.return_value.create_agent.call_args.kwargs + kwargs = mock_hook_cls.get_hook.return_value.create_agent.call_args.kwargs assert kwargs["output_type"] is ErrorClassification assert kwargs["instructions"] == DEFAULT_INSTRUCTIONS @@ -1381,7 +1405,7 @@ def test_custom_taxonomy_in_instructions_keeps_working(self, mock_hook_cls): assert decision.action == RetryAction.RETRY assert decision.retry_delay == timedelta(seconds=30) assert decision.reason == "warehouse_suspended: auto-resume" - assert mock_hook_cls.return_value.create_agent.call_args.kwargs["instructions"].startswith( + assert mock_hook_cls.get_hook.return_value.create_agent.call_args.kwargs["instructions"].startswith( "'Warehouse suspended'" ) From 31018e07458766380b311c54f1c3037a08e6bd0b Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Wed, 14 Oct 2026 17:16:23 +0100 Subject: [PATCH 12/18] Say the provider could not be built from the connection's fields, not that credentials were rejected A provider class can reject a field that is not a credential: the Bedrock hook forwards aws_read_timeout / aws_connect_timeout whenever they are set and BedrockMantleProvider accepts neither, so the old message sent users hunting for a credential problem. - Reword the fail-closed ValueError to "Could not build provider ... from the fields on connection ...", keeping the fields passed and the TypeError text - Update the hook docstring and provider_fallback.rst to match - Rename the two tests that still described the failure as rejected credentials --- providers/common/ai/docs/provider_fallback.rst | 4 ++-- .../airflow/providers/common/ai/hooks/pydantic_ai.py | 4 ++-- .../ai/tests/unit/common/ai/hooks/test_pydantic_ai.py | 10 ++++++---- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/providers/common/ai/docs/provider_fallback.rst b/providers/common/ai/docs/provider_fallback.rst index 318fe41bea187..7b2821c105420 100644 --- a/providers/common/ai/docs/provider_fallback.rst +++ b/providers/common/ai/docs/provider_fallback.rst @@ -198,8 +198,8 @@ Two checks, neither of which requires waiting for a real outage: *Test the connection.* ``test_connection`` on the primary resolves every connection in the chain, so a fallback with a missing ``model`` or an unknown connection ID is reported by name -there rather than discovered mid-incident. Credential fields a provider class rejects with a -``TypeError`` fail the resolution with a ``ValueError`` naming the connection, the provider and +there rather than discovered mid-incident. Fields a provider class cannot be built from (a +``TypeError``) fail the resolution with a ``ValueError`` naming the connection, the provider and the fields passed, with the provider's ``TypeError`` text -- the hook never falls back to environment-variable auth, which would authenticate as a different identity -- and ``test_connection`` reports it as a failure. It does not call the provider, so a well-formed diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py index 045717e2a541d..db7120729cfa7 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py @@ -453,7 +453,7 @@ def _provider_factory(pname: str) -> Any: return infer_provider_class(pname)(**_kwargs) except TypeError as e: raise ValueError( - f"Provider '{pname}' rejected the credentials from connection " + f"Could not build provider '{pname}' from the fields on connection " f"'{self.llm_conn_id}' (fields passed: {', '.join(_kwargs)}): {e}. " "Not falling back to environment-variable auth, which would authenticate as a different identity." ) from e @@ -677,7 +677,7 @@ def test_connection(self) -> tuple[bool, str]: """ Test connection by resolving the model. - A provider class rejecting the connection's credentials is reported as a failure + A provider class that cannot be built from the connection's fields is reported as a failure naming the provider, the fields passed and the provider's ``TypeError`` text. Does NOT make an LLM API call — that would be expensive and fail for diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py b/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py index b7969cbf3a99d..d86365ed00a0f 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py @@ -1626,14 +1626,14 @@ def test_failed_connection_no_model(self): @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider_class", autospec=True) @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_model", autospec=True) - def test_get_conn_raises_when_provider_class_rejects_credentials( + def test_get_conn_raises_when_provider_class_cannot_be_built( self, mock_infer_model, mock_infer_provider_class, registry ): mock_infer_provider_class.return_value = _RejectsKwargsProvider mock_infer_model.side_effect = _call_provider_factory registry.add("primary", password="sk-key", extra={"model": "openai:gpt-5.6-sol"}) - with pytest.raises(ValueError, match="rejected the credentials") as exc_info: + with pytest.raises(ValueError, match="Could not build provider") as exc_info: PydanticAIHook(llm_conn_id="primary").get_conn() assert isinstance(exc_info.value.__cause__, TypeError) @@ -1647,7 +1647,7 @@ def test_get_conn_raises_when_provider_class_rejects_credentials( ) @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_provider_class", autospec=True) @patch("airflow.providers.common.ai.hooks.pydantic_ai.infer_model", autospec=True) - def test_reports_credentials_rejected_by_provider_class( + def test_reports_provider_class_build_failure( self, mock_infer_model, mock_infer_provider_class, registry, fallback_conn_ids, expected_conn_id ): mock_infer_provider_class.return_value = _RejectsKwargsProvider @@ -1664,7 +1664,9 @@ def test_reports_credentials_rejected_by_provider_class( ).test_connection() assert success is False - assert f"Provider 'openai' rejected the credentials from connection '{expected_conn_id}'" in message + assert ( + f"Could not build provider 'openai' from the fields on connection '{expected_conn_id}'" in message + ) assert "(fields passed: api_key)" in message assert "unexpected keyword argument 'api_key'" in message From df8fa69bbf0f0975c3c09a893de045db0eb6a516 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Wed, 14 Oct 2026 17:16:32 +0100 Subject: [PATCH 13/18] Describe what the Azure and Vertex connections forward to a prefixed provider class The Azure page said an openai: model bypasses Azure entirely, but the hook always forwards Host as azure_endpoint, which OpenAIProvider does not take, so that connection now fails get_conn(). The Vertex pages said google: requires an API key and accepts only an API key, which is stricter than GoogleProvider: it also takes base_url and reads GOOGLE_API_KEY when no key is set. - Azure page: a model prefixed with another platform works only if that provider class accepts the forwarded fields, otherwise get_conn() raises - Vertex page and PydanticAIVertexHook docstring: google: accepts the API key and Custom Endpoint URL, and rejects the Vertex-only fields --- .../ai/docs/connections/pydantic_ai_azure.rst | 13 +++++++++---- .../ai/docs/connections/pydantic_ai_vertex.rst | 12 +++++++----- .../providers/common/ai/hooks/pydantic_ai.py | 9 +++++---- 3 files changed, 21 insertions(+), 13 deletions(-) diff --git a/providers/common/ai/docs/connections/pydantic_ai_azure.rst b/providers/common/ai/docs/connections/pydantic_ai_azure.rst index 0332412d3b430..d26c416bca8e6 100644 --- a/providers/common/ai/docs/connections/pydantic_ai_azure.rst +++ b/providers/common/ai/docs/connections/pydantic_ai_azure.rst @@ -52,10 +52,15 @@ Model this connection type's own platform, so nothing else needs naming it explicitly. Writing the ``azure:`` prefix yourself has the same effect and is still accepted. A name prefixed with a *different*, recognized platform (e.g. - ``openai:gpt-5``) is used verbatim instead, pinning that platform and - bypassing Azure OpenAI entirely -- a name is only treated as already prefixed - when the segment before its first ``:`` is itself a real pydantic-ai - provider, not merely present. + ``openai:gpt-5``) is used verbatim instead -- a name is only treated as + already prefixed when the segment before its first ``:`` is itself a real + pydantic-ai provider, not merely present. That other platform's provider + class is built from the fields this connection forwards (``API Key``, + ``Azure Endpoint`` as ``azure_endpoint``, ``API Version``), so it works only + if it accepts all of them. ``OpenAIProvider`` does not accept + ``azure_endpoint`` or ``api_version``, so ``openai:`` with an endpoint or API + version set fails with a ``ValueError`` naming the fields passed; it never + silently falls back to environment-variable credentials. API Key (Password field) The Azure OpenAI API key. diff --git a/providers/common/ai/docs/connections/pydantic_ai_vertex.rst b/providers/common/ai/docs/connections/pydantic_ai_vertex.rst index 6488156b1ace9..3cd9e20852a2a 100644 --- a/providers/common/ai/docs/connections/pydantic_ai_vertex.rst +++ b/providers/common/ai/docs/connections/pydantic_ai_vertex.rst @@ -57,10 +57,12 @@ Model mean Vertex AI Express Mode credentials (see "Credentials" below), so its presence alone cannot tell the two platforms apart. To reach the Generative Language API instead, prefix the model explicitly with - ``google:``. On this connection type that spelling requires ``API Key`` - and must not set Vertex-only fields (``GCP Project``, ``Location / Region``, - ``Service Account Info``), because the ``google:`` provider accepts only - an API key. + ``google:``. The ``google:`` provider accepts only the ``API Key`` and + ``Custom Endpoint URL`` fields (without an API key it reads ``GOOGLE_API_KEY``), so on this + connection type that spelling must not be combined with Vertex-only fields + (``GCP Project``, ``Location / Region``, ``Service Account Info``): the + connection fails with a ``ValueError`` instead of silently falling back to + environment-variable credentials. GCP Project Google Cloud project ID. Falls back to the ``GOOGLE_CLOUD_PROJECT`` @@ -89,7 +91,7 @@ API Key ``project`` / ``location`` / ``service_account_info`` (those select the credentials/ADC path instead, which takes precedence and nulls the API key). For the Generative Language API - (non-Vertex, API-key-only), use the ``google:`` prefix on the generic + (non-Vertex; API key or ``GOOGLE_API_KEY``), use the ``google:`` prefix on the generic :doc:`pydantic_ai` connection instead. Service Account Info diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py index db7120729cfa7..f95c3de6b2eec 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py @@ -878,10 +878,11 @@ class PydanticAIVertexHook(PydanticAIHook): above), so its presence alone cannot tell the two platforms apart; guessing would risk silently authenticating against the wrong endpoint. To use the Generative Language API, set an explicit ``google:``-prefixed model id (on - the hook or the connection's ``model`` extra). On this connection type that - spelling requires ``api_key`` and must not set Vertex-only fields - (``project``, ``location``, ``service_account_info``), because - ``GoogleProvider`` accepts none of them. + the hook or the connection's ``model`` extra). ``GoogleProvider`` accepts only + ``api_key`` and ``base_url`` (without a key it reads ``GOOGLE_API_KEY``), so on + this connection type that spelling must not set Vertex-only fields + (``project``, ``location``, ``service_account_info``): they are rejected + (fail closed). :param llm_conn_id: Airflow connection ID. :param model_id: Model identifier, e.g. ``"google-cloud:gemini-2.5-flash"``. A From 6a42d171debe2175c8764a34c05a4e5c74906188 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Mon, 19 Oct 2026 11:48:14 +0800 Subject: [PATCH 14/18] Stop echoing the MCP stdio args value in its validation errors The args list can carry credentials (e.g. a Bearer header passed to mcp-remote) and the secrets masker does not cover it, so the error text could put a token in the task log. Report the offending item's type and index instead. --- .../airflow/providers/common/ai/hooks/mcp.py | 12 ++++-- .../ai/tests/unit/common/ai/hooks/test_mcp.py | 41 +++++++++++++++++++ 2 files changed, 50 insertions(+), 3 deletions(-) diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py index 4bea1a7fc4381..810b0fccbc45f 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/mcp.py @@ -241,15 +241,21 @@ def get_conn(self) -> Any: except ValueError as e: raise ValueError( f"'args' in extra for connection {self.mcp_conn_id!r} looks like a JSON array " - f"but is not valid JSON: {args!r}." + "but is not valid JSON." ) from e else: args = [args] - if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args): + if not isinstance(args, list): raise ValueError( f"'args' in extra for connection {self.mcp_conn_id!r} must be a string, a JSON " - f"array of strings or a list of strings, got {args!r}." + f"array of strings or a list of strings, got {type(args).__name__}." ) + for index, arg in enumerate(args): + if not isinstance(arg, str): + raise ValueError( + f"'args' in extra for connection {self.mcp_conn_id!r} must contain only strings, " + f"got {type(arg).__name__} at index {index}." + ) timeout = extra.get("timeout", 10) # ``None`` and ``0`` are both valid "no timeout" values, but fastmcp replaces # ``init_timeout=None`` with its global ``client_init_timeout`` setting, so ``None`` diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py b/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py index 7b2141d431a1f..d0efd7f64ddef 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_mcp.py @@ -256,6 +256,47 @@ def test_stdio_invalid_args_raises(self, bad_args): with pytest.raises(ValueError, match="'args' in extra"): hook.get_conn() + @pytest.mark.parametrize( + "bad_args", + [["--header", "Authorization: Bearer s3cr3t", 1], '["--header", "Bearer s3cr3t", 1]'], + ids=["list", "json_string"], + ) + def test_stdio_non_string_arg_error_reports_type_and_index_not_values(self, bad_args): + hook = MCPHook(mcp_conn_id="test_conn") + conn = Connection( + conn_id="test_conn", + conn_type="mcp", + extra=json.dumps({"transport": "stdio", "command": "uvx", "args": bad_args}), + ) + with patch.object(hook, "get_connection", return_value=conn): + with pytest.raises(ValueError, match=r"int at index 2") as exc_info: + hook.get_conn() + assert "s3cr3t" not in str(exc_info.value) + + def test_stdio_non_list_args_error_does_not_echo_value(self): + hook = MCPHook(mcp_conn_id="test_conn") + conn = Connection( + conn_id="test_conn", + conn_type="mcp", + extra=json.dumps({"transport": "stdio", "command": "uvx", "args": {"token": "s3cr3t"}}), + ) + with patch.object(hook, "get_connection", return_value=conn): + with pytest.raises(ValueError, match="got dict") as exc_info: + hook.get_conn() + assert "s3cr3t" not in str(exc_info.value) + + def test_stdio_invalid_json_args_error_does_not_echo_value(self): + hook = MCPHook(mcp_conn_id="test_conn") + conn = Connection( + conn_id="test_conn", + conn_type="mcp", + extra=json.dumps({"transport": "stdio", "command": "uvx", "args": '["Bearer s3cr3t"'}), + ) + with patch.object(hook, "get_connection", return_value=conn): + with pytest.raises(ValueError, match="looks like a JSON array") as exc_info: + hook.get_conn() + assert "s3cr3t" not in str(exc_info.value) + @pytest.mark.parametrize( "bad_timeout", ["30", -5, -0.5, float("nan"), float("inf"), True, [10]], From 1dad87b8c895509de009534c9a801e20f39587f8 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Mon, 19 Oct 2026 13:03:15 +0800 Subject: [PATCH 15/18] Name GoogleCloudProvider as the class that takes the Vertex credentials The Vertex hook's docstring and a kwargs comment attributed service_account_info, project and location to GoogleProvider, which only accepts api_key and base_url. --- .../ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py index f95c3de6b2eec..741dfe5a30d02 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py @@ -846,7 +846,7 @@ class PydanticAIVertexHook(PydanticAIHook): 1. ``service_account_info`` (JSON object) in ``extra`` — loaded into a ``google.auth.credentials.Credentials`` - object and passed as ``credentials`` to ``GoogleProvider``. + object and passed as ``credentials`` to ``GoogleCloudProvider``. 2. ``api_key`` in ``extra`` — for Generative Language API (non-Vertex) or Vertex API-key auth. 3. Application Default Credentials (``GOOGLE_APPLICATION_CREDENTIALS``, @@ -920,7 +920,7 @@ def _get_provider_kwargs( sa_info = extra.get("service_account_info") kwargs: dict[str, Any] = {} - # Direct GoogleProvider scalar kwargs. + # Scalar kwargs: GoogleCloudProvider takes all four; GoogleProvider only api_key/base_url. for _key in ("api_key", "project", "location", "base_url"): if extra.get(_key): kwargs[_key] = extra[_key] From 64db0e86a762c92a3d0dfacb6f6c064c04a5b0ce Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Fri, 23 Oct 2026 22:03:57 +0900 Subject: [PATCH 16/18] Announce the breaking changes to the 1.0.0 hooks and retry policy in the changelog - Say LlamaIndexHook and LangChainHook now take embed_model and llm_model by keyword only - Say PydanticAIHook raises ValueError instead of falling back to environment-variable auth - Say the retry module raises AirflowOptionalProviderFeatureException, so a 1.0.0-style except ImportError guard needs to catch both --- providers/common/ai/docs/changelog.rst | 27 ++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/providers/common/ai/docs/changelog.rst b/providers/common/ai/docs/changelog.rst index 4093a86db8f39..d343100cb689a 100644 --- a/providers/common/ai/docs/changelog.rst +++ b/providers/common/ai/docs/changelog.rst @@ -48,6 +48,33 @@ Changelog ``"PT1M30S"`` for a ``timedelta``. Tuples and sets in that model now arrive as lists. See :doc:`structured_output`. +.. warning:: + The following changes are breaking for code written against 1.0.0: + + * ``LlamaIndexHook`` and ``LangChainHook`` (both experimental, see :doc:`stability`): + ``embed_model`` and ``llm_model`` are now keyword-only. + In 1.0.0 they were the third and fourth positional parameters (after ``llm_conn_id`` and + ``embed_conn_id``), and the two hooks listed them in opposite order, so positional calls silently + swapped meanings between the hooks. Pass them by keyword, e.g. ``LlamaIndexHook(llm_model="gpt-5")``. + * ``PydanticAIHook``: when a connection supplies credentials (password or host) and the provider class + rejects the resulting keyword arguments (``TypeError``), the hook now raises ``ValueError``. In 1.0.0 + it logged a warning and fell back to environment-variable authentication, which could authenticate + as a different identity than the connection. Fix the connection fields for that provider, or remove + the credentials from the connection if environment-variable authentication is what you want. + * ``airflow.providers.common.ai.policies.retry``: importing it without the Airflow ``RetryPolicy`` + support (Airflow older than 3.3) now raises ``AirflowOptionalProviderFeatureException`` instead of + ``ImportError``. It is not an ``ImportError`` subclass (it derives from ``AirflowException``), so a + Dag that guards the import with ``except ImportError:`` as in the 1.0.0 example Dag now fails to + parse on those versions. Catch both, importing the exception from + ``airflow.providers.common.compat.sdk`` (works on Airflow 2.11 and 3.x):: + + from airflow.providers.common.compat.sdk import AirflowOptionalProviderFeatureException + + try: + from airflow.providers.common.ai.policies.retry import LLMRetryPolicy + except (ImportError, AirflowOptionalProviderFeatureException): + LLMRetryPolicy = None + 1.1.0 ..... From 8c014079210abb3c55e11dbf8074aaba17c93514 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Fri, 23 Oct 2026 22:13:17 +0900 Subject: [PATCH 17/18] Describe the fail-closed ValueError, not the retired fallback, in the Codex auth comment - Say a connection with a password or host raises ValueError when the provider rejects its fields - Say only a connection with neither lets the ambient Codex CLI login apply --- .../ai/tests/unit/common/ai/test_provider_metadata.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/providers/common/ai/tests/unit/common/ai/test_provider_metadata.py b/providers/common/ai/tests/unit/common/ai/test_provider_metadata.py index 16a3aa58232bd..400829ba0ffd1 100644 --- a/providers/common/ai/tests/unit/common/ai/test_provider_metadata.py +++ b/providers/common/ai/tests/unit/common/ai/test_provider_metadata.py @@ -132,15 +132,16 @@ def _extract_toolset_block() -> dict: # only `credentials`, `credential_source`, `openai_client`, and `http_client` -- no parameter # exists to receive what the hook sends; confirmed empirically (as of pydantic-ai-slim 2.44.0): # `OpenAICodexProvider(api_key=..., base_url=...)` raises -# ``TypeError: unexpected keyword argument 'api_key'``. `PydanticAIHook.get_conn()`'s -# `_provider_factory` catches that `TypeError` and retries via `infer_provider(pname)`, i.e. +# ``TypeError: unexpected keyword argument 'api_key'``. `PydanticAIHook.get_conn()` +# re-raises that `TypeError` as a `ValueError` when the connection has a password or host. Only +# a connection with neither falls through to `infer_model(model_name)`, i.e. # `OpenAICodexProvider()` with no arguments, which falls through to its # `_read_codex_cli_credentials()` helper: a read-only load of the Codex CLI's on-disk # `~/.codex/auth.json`, populated by the OAuth authorization-code + PKCE login flow the Codex CLI # itself performs (see `pydantic_ai.providers.openai_codex`'s module docstring and # `OpenAICodexOAuthFlow`) -- not by anything `hooks/pydantic_ai.py` can express. So credentials # configured on a `pydanticai` connection (password/host) can never drive this provider; only -# the ambient Codex CLI login can, via that fallback. The services page lists only vendors a +# the ambient Codex CLI login can, with no password/host set. The services page lists only vendors a # connection's credentials can drive, so these modules stay off it. # `test_hook_incompatible_auth_modules_stay_incompatible` below guards the reversal: if # pydantic-ai gives one of these providers an `api_key`/`base_url` constructor parameter, this From b285246538fcec846d276f55e03f9ee7d1964c2e Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Sun, 25 Oct 2026 10:56:22 +0900 Subject: [PATCH 18/18] Deprecate passing llm_model and embed_model positionally to the LlamaIndex and LangChain hooks - Accept the 1.0.0 positional order again (embed_model, llm_model for LlamaIndexHook; llm_model, embed_model for LangChainHook) and emit AirflowProviderDeprecationWarning for each one - Raise TypeError for a third positional argument or one that is also passed by keyword - Replace the changelog's keyword-only breaking-change entry with a deprecation note --- providers/common/ai/docs/changelog.rst | 15 ++-- .../providers/common/ai/hooks/langchain.py | 29 ++++++- .../providers/common/ai/hooks/llamaindex.py | 28 ++++++- .../unit/common/ai/hooks/test_langchain.py | 77 ++++++++++++++++++- .../unit/common/ai/hooks/test_llamaindex.py | 77 ++++++++++++++++++- 5 files changed, 207 insertions(+), 19 deletions(-) diff --git a/providers/common/ai/docs/changelog.rst b/providers/common/ai/docs/changelog.rst index d343100cb689a..ee9c5ac955255 100644 --- a/providers/common/ai/docs/changelog.rst +++ b/providers/common/ai/docs/changelog.rst @@ -51,11 +51,6 @@ Changelog .. warning:: The following changes are breaking for code written against 1.0.0: - * ``LlamaIndexHook`` and ``LangChainHook`` (both experimental, see :doc:`stability`): - ``embed_model`` and ``llm_model`` are now keyword-only. - In 1.0.0 they were the third and fourth positional parameters (after ``llm_conn_id`` and - ``embed_conn_id``), and the two hooks listed them in opposite order, so positional calls silently - swapped meanings between the hooks. Pass them by keyword, e.g. ``LlamaIndexHook(llm_model="gpt-5")``. * ``PydanticAIHook``: when a connection supplies credentials (password or host) and the provider class rejects the resulting keyword arguments (``TypeError``), the hook now raises ``ValueError``. In 1.0.0 it logged a warning and fell back to environment-variable authentication, which could authenticate @@ -75,6 +70,16 @@ Changelog except (ImportError, AirflowOptionalProviderFeatureException): LLMRetryPolicy = None +.. note:: + ``LlamaIndexHook`` and ``LangChainHook`` (both experimental, see :doc:`stability`): + passing ``embed_model`` and ``llm_model`` positionally is deprecated. In 1.0.0 they were the third and + fourth positional parameters (after ``llm_conn_id`` and ``embed_conn_id``), and the two hooks listed + them in opposite order (``embed_model`` then ``llm_model`` for ``LlamaIndexHook``, ``llm_model`` then + ``embed_model`` for ``LangChainHook``). Positional calls still work and emit an + ``AirflowProviderDeprecationWarning``, but support will be removed in a future release. Pass them by + keyword, e.g. ``LlamaIndexHook(llm_model="gpt-5")``, which also avoids the meanings swapping between + the two hooks. + 1.1.0 ..... diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/langchain.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/langchain.py index 21d5b24154a45..8c7b37c777feb 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/langchain.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/langchain.py @@ -18,8 +18,10 @@ from __future__ import annotations +import warnings from typing import TYPE_CHECKING, Any +from airflow.exceptions import AirflowProviderDeprecationWarning from airflow.providers.common.compat.sdk import BaseHook if TYPE_CHECKING: @@ -68,12 +70,13 @@ class LangChainHook(BaseHook): single hook instance. :param llm_model: Chat model identifier in ``provider:name`` format (e.g. ``"openai:gpt-5"``, ``"anthropic:claude-sonnet-5"``). - Overrides ``extra["model"]`` on the connection. + Overrides ``extra["model"]`` on the connection. Passing it positionally + (1.0.0 order: ``llm_model, embed_model``) is deprecated. :param embed_model: Embedding model identifier in ``provider:name`` format (e.g. ``"openai:text-embedding-3-small"``). Overrides ``extra["embed_model"]`` on the connection. When ``embedding_kwargs`` supplies ``provider`` explicitly, use a model name without the provider - prefix. + prefix. Passing it positionally (1.0.0 order: ``llm_model, embed_model``) is deprecated. :param embedding_kwargs: Additional keyword arguments to pass to the embedding model constructor without filtering. Values can override hook-provided settings, including the endpoint and credentials. In particular, @@ -96,12 +99,32 @@ def __init__( self, llm_conn_id: str | None = None, embed_conn_id: str | None = None, - *, + *args: Any, llm_model: str | None = None, embed_model: str | None = None, embedding_kwargs: dict[str, Any] | None = None, **kwargs: Any, ) -> None: + # ``*args`` only exists to keep the 1.0.0 positional order working: ``llm_model``, ``embed_model``. + if len(args) > 2: + raise TypeError( + f"{type(self).__name__}.__init__() takes from 1 to 5 positional arguments " + f"but {3 + len(args)} were given" + ) + legacy_values = dict(zip(("llm_model", "embed_model"), args)) + keyword_values = {"llm_model": llm_model, "embed_model": embed_model} + for name in legacy_values: + # A keyword of None counts as not provided, so ``name=None`` plus a positional keeps the positional. + if keyword_values[name] is not None: + raise TypeError(f"{type(self).__name__}.__init__() got multiple values for argument '{name}'") + warnings.warn( + f"Parameter `{name}` passed positionally is deprecated. Use `{name}=...` instead; " + f"positional support will be removed in a future release.", + category=AirflowProviderDeprecationWarning, + stacklevel=2, + ) + llm_model = legacy_values.get("llm_model", llm_model) + embed_model = legacy_values.get("embed_model", embed_model) super().__init__(**kwargs) # Resolve at runtime so a future subclass with its own # `default_conn_name` is honoured. A bare `llm_conn_id: str = diff --git a/providers/common/ai/src/airflow/providers/common/ai/hooks/llamaindex.py b/providers/common/ai/src/airflow/providers/common/ai/hooks/llamaindex.py index 31375080942e4..ede87d85922d7 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/hooks/llamaindex.py +++ b/providers/common/ai/src/airflow/providers/common/ai/hooks/llamaindex.py @@ -19,8 +19,10 @@ from __future__ import annotations import inspect +import warnings from typing import TYPE_CHECKING, Any +from airflow.exceptions import AirflowProviderDeprecationWarning from airflow.providers.common.compat.sdk import ( AirflowOptionalProviderFeatureException, BaseHook, @@ -96,10 +98,10 @@ class LlamaIndexHook(BaseHook): embedding provider. Falls back to ``llm_conn_id`` when not set. :param embed_model: Embedding model name (e.g. ``"text-embedding-3-small"``). Overrides ``extra["embed_model"]`` - on the connection. + on the connection. Passing it positionally (1.0.0 order: ``embed_model, llm_model``) is deprecated. :param llm_model: LLM model name (e.g. ``"gpt-5"``). Overrides ``extra["llm_model"]`` on the connection. Required when calling - :meth:`get_llm`. + :meth:`get_llm`. Passing it positionally (1.0.0 order: ``embed_model, llm_model``) is deprecated. :param embedding_kwargs: Additional keyword arguments to pass to the embedding model constructor without filtering. Connection ``api_key`` and ``api_base`` values take precedence at the top level, but nested options supported by the @@ -116,12 +118,32 @@ def __init__( self, llm_conn_id: str | None = None, embed_conn_id: str | None = None, - *, + *args: Any, llm_model: str | None = None, embed_model: str | None = None, embedding_kwargs: dict[str, Any] | None = None, **kwargs: Any, ) -> None: + # ``*args`` only exists to keep the 1.0.0 positional order working: ``embed_model``, ``llm_model``. + if len(args) > 2: + raise TypeError( + f"{type(self).__name__}.__init__() takes from 1 to 5 positional arguments " + f"but {3 + len(args)} were given" + ) + legacy_values = dict(zip(("embed_model", "llm_model"), args)) + keyword_values = {"embed_model": embed_model, "llm_model": llm_model} + for name in legacy_values: + # A keyword of None counts as not provided, so ``name=None`` plus a positional keeps the positional. + if keyword_values[name] is not None: + raise TypeError(f"{type(self).__name__}.__init__() got multiple values for argument '{name}'") + warnings.warn( + f"Parameter `{name}` passed positionally is deprecated. Use `{name}=...` instead; " + f"positional support will be removed in a future release.", + category=AirflowProviderDeprecationWarning, + stacklevel=2, + ) + embed_model = legacy_values.get("embed_model", embed_model) + llm_model = legacy_values.get("llm_model", llm_model) super().__init__(**kwargs) # Resolve at runtime so a future per-vendor subclass with its own # ``default_conn_name`` is honoured. diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py b/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py index 806d5f259dcde..17feedcdca1e9 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_langchain.py @@ -17,10 +17,12 @@ from __future__ import annotations import sys +import warnings from unittest.mock import MagicMock, patch import pytest +from airflow.exceptions import AirflowProviderDeprecationWarning from airflow.providers.common.ai.hooks.langchain import LangChainHook @@ -72,10 +74,77 @@ def test_embed_conn_falls_back_to_llm_conn(self): assert hook.llm_conn_id == "my_conn" assert hook.embed_conn_id == "my_conn" - def test_model_arguments_are_keyword_only(self): - """The model arguments cannot be passed positionally.""" - with pytest.raises(TypeError, match="positional argument"): - LangChainHook("llm", "embed", "openai:gpt-4o") + @pytest.mark.parametrize( + ("positional", "expected"), + [ + pytest.param(("llm-pos",), {"llm_model": "llm-pos", "embed_model": None}, id="one"), + pytest.param( + ("llm-pos", "embed-pos"), + {"llm_model": "llm-pos", "embed_model": "embed-pos"}, + id="two", + ), + ], + ) + def test_positional_model_emits_deprecation_warning(self, positional, expected): + with pytest.warns(AirflowProviderDeprecationWarning) as record: + hook = LangChainHook("c1", "c2", *positional) + assert len(record) == len(positional) + assert "Parameter `llm_model` passed positionally is deprecated" in str(record[0].message) + assert hook.llm_conn_id == "c1" + assert hook.embed_conn_id == "c2" + assert hook.llm_model == expected["llm_model"] + assert hook.embed_model == expected["embed_model"] + + def test_positional_warning_stacklevel_points_to_caller(self): + with pytest.warns(AirflowProviderDeprecationWarning) as record: + LangChainHook("c1", "c2", "llm-pos") + assert record[0].filename == __file__ + + def test_one_warning_per_positional_argument(self): + with pytest.warns(AirflowProviderDeprecationWarning) as record: + LangChainHook("c1", "c2", "llm-pos", "embed-pos") + messages = [str(w.message) for w in record] + assert len(messages) == 2 + assert "`llm_model`" in messages[0] + assert "`embed_model`" in messages[1] + + def test_keyword_model_arguments_do_not_warn(self): + with warnings.catch_warnings(): + warnings.simplefilter("error", AirflowProviderDeprecationWarning) + hook = LangChainHook("c1", "c2", llm_model="llm-pos", embed_model="embed-pos") + assert hook.llm_model == "llm-pos" + assert hook.embed_model == "embed-pos" + + def test_connection_positional_arguments_do_not_warn(self): + with warnings.catch_warnings(): + warnings.simplefilter("error", AirflowProviderDeprecationWarning) + hook = LangChainHook("c1", "c2") + assert hook.embed_model is None + assert hook.llm_model is None + + def test_too_many_positional_arguments_raise_type_error(self): + with warnings.catch_warnings(): + warnings.simplefilter("error", AirflowProviderDeprecationWarning) + with pytest.raises(TypeError, match="positional argument"): + LangChainHook("c1", "c2", "llm-pos", "embed-pos", "extra") + + def test_positional_and_keyword_same_parameter_raise_type_error(self): + with pytest.raises(TypeError, match="multiple values for argument 'llm_model'"): + LangChainHook("c1", "c2", "llm-pos", llm_model="other") + + def test_second_positional_and_keyword_same_parameter_raise_type_error(self): + with ( + pytest.warns(AirflowProviderDeprecationWarning), + pytest.raises(TypeError, match="multiple values for argument 'embed_model'"), + ): + LangChainHook("c1", "c2", "L", "E", embed_model="X") + + def test_positional_and_keyword_different_parameters_combine(self): + with pytest.warns(AirflowProviderDeprecationWarning) as record: + hook = LangChainHook("c1", "c2", "llm-pos", embed_model="embed-pos") + assert len(record) == 1 + assert hook.llm_model == "llm-pos" + assert hook.embed_model == "embed-pos" def test_explicit_separate_conns_and_models(self): hook = LangChainHook( diff --git a/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py b/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py index 9a1be4e75752c..3274519629cce 100644 --- a/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py +++ b/providers/common/ai/tests/unit/common/ai/hooks/test_llamaindex.py @@ -16,10 +16,12 @@ # under the License. from __future__ import annotations +import warnings from unittest.mock import MagicMock, patch import pytest +from airflow.exceptions import AirflowProviderDeprecationWarning from airflow.providers.common.ai.hooks.llamaindex import LlamaIndexHook @@ -56,10 +58,77 @@ def test_explicit_separate_conns_and_models(self): assert hook.embed_model == "text-embedding-3-large" assert hook.llm_model == "gpt-4o" - def test_model_arguments_are_keyword_only(self): - """The model arguments cannot be passed positionally.""" - with pytest.raises(TypeError, match="positional argument"): - LlamaIndexHook("llm", "embed", "text-embedding-3-small") + @pytest.mark.parametrize( + ("positional", "expected"), + [ + pytest.param(("embed-pos",), {"embed_model": "embed-pos", "llm_model": None}, id="one"), + pytest.param( + ("embed-pos", "llm-pos"), + {"embed_model": "embed-pos", "llm_model": "llm-pos"}, + id="two", + ), + ], + ) + def test_positional_model_emits_deprecation_warning(self, positional, expected): + with pytest.warns(AirflowProviderDeprecationWarning) as record: + hook = LlamaIndexHook("c1", "c2", *positional) + assert len(record) == len(positional) + assert "Parameter `embed_model` passed positionally is deprecated" in str(record[0].message) + assert hook.llm_conn_id == "c1" + assert hook.embed_conn_id == "c2" + assert hook.embed_model == expected["embed_model"] + assert hook.llm_model == expected["llm_model"] + + def test_positional_warning_stacklevel_points_to_caller(self): + with pytest.warns(AirflowProviderDeprecationWarning) as record: + LlamaIndexHook("c1", "c2", "embed-pos") + assert record[0].filename == __file__ + + def test_one_warning_per_positional_argument(self): + with pytest.warns(AirflowProviderDeprecationWarning) as record: + LlamaIndexHook("c1", "c2", "embed-pos", "llm-pos") + messages = [str(w.message) for w in record] + assert len(messages) == 2 + assert "`embed_model`" in messages[0] + assert "`llm_model`" in messages[1] + + def test_keyword_model_arguments_do_not_warn(self): + with warnings.catch_warnings(): + warnings.simplefilter("error", AirflowProviderDeprecationWarning) + hook = LlamaIndexHook("c1", "c2", embed_model="embed-pos", llm_model="llm-pos") + assert hook.embed_model == "embed-pos" + assert hook.llm_model == "llm-pos" + + def test_connection_positional_arguments_do_not_warn(self): + with warnings.catch_warnings(): + warnings.simplefilter("error", AirflowProviderDeprecationWarning) + hook = LlamaIndexHook("c1", "c2") + assert hook.embed_model is None + assert hook.llm_model is None + + def test_too_many_positional_arguments_raise_type_error(self): + with warnings.catch_warnings(): + warnings.simplefilter("error", AirflowProviderDeprecationWarning) + with pytest.raises(TypeError, match="positional argument"): + LlamaIndexHook("c1", "c2", "embed-pos", "llm-pos", "extra") + + def test_positional_and_keyword_same_parameter_raise_type_error(self): + with pytest.raises(TypeError, match="multiple values for argument 'embed_model'"): + LlamaIndexHook("c1", "c2", "embed-pos", embed_model="other") + + def test_second_positional_and_keyword_same_parameter_raise_type_error(self): + with ( + pytest.warns(AirflowProviderDeprecationWarning), + pytest.raises(TypeError, match="multiple values for argument 'llm_model'"), + ): + LlamaIndexHook("c1", "c2", "E", "L", llm_model="X") + + def test_positional_and_keyword_different_parameters_combine(self): + with pytest.warns(AirflowProviderDeprecationWarning) as record: + hook = LlamaIndexHook("c1", "c2", "embed-pos", llm_model="llm-pos") + assert len(record) == 1 + assert hook.embed_model == "embed-pos" + assert hook.llm_model == "llm-pos" def test_conn_type_is_llamaindex(self): assert LlamaIndexHook.conn_type == "llamaindex"