Repository navigation
Make common.ai hooks report misconfiguration instead of failing silently - #74451
Merged
Merged
Conversation
Lee-W
force-pushed
the
common-ai-hooks-hardening
branch
2 times, most recently
from
October 8, 2026 09:44
857ad96 to
c4531f6
Compare
kaxil
reviewed
Oct 8, 2026
Lee-W
force-pushed
the
common-ai-hooks-hardening
branch
3 times, most recently
from
October 9, 2026 07:01
e11d2ca to
727b835
Compare
1 task done
kaxil
reviewed
Oct 10, 2026
Lee-W
force-pushed
the
common-ai-hooks-hardening
branch
2 times, most recently
from
October 11, 2026 09:38
9de8f2d to
ed40ddf
Compare
kaxil
reviewed
Oct 12, 2026
Lee-W
force-pushed
the
common-ai-hooks-hardening
branch
from
October 13, 2026 06:39
ed40ddf to
28074b5
Compare
kaxil
reviewed
Oct 14, 2026
Lee-W
force-pushed
the
common-ai-hooks-hardening
branch
2 times, most recently
from
October 14, 2026 16:19
91db3ae to
31c7231
Compare
Lee-W
force-pushed
the
common-ai-hooks-hardening
branch
from
October 15, 2026 07:54
31c7231 to
199a7e7
Compare
kaxil
reviewed
Oct 16, 2026
Lee-W
force-pushed
the
common-ai-hooks-hardening
branch
2 times, most recently
from
October 22, 2026 03:01
cdc4388 to
22919fe
Compare
kaxil
reviewed
Oct 22, 2026
kaxil
approved these changes
Oct 22, 2026
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.
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.
The docstrings described the old llm_model/embed_model ordering; they now state the behaviour under test.
…nit 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.
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.
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.
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.
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.
…reException 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.
…ex-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.
…ons 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
… 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
…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
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.
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.
…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
… 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
…Index 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
Lee-W
force-pushed
the
common-ai-hooks-hardening
branch
from
October 25, 2026 02:00
22919fe to
b285246
Compare
This was referenced Oct 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
apache-airflow-providers-common-ai1.0.0 shipped on 2026-10-19, and the hooks it exposes are now public API. This PR fixes silent failures and signature inconsistencies in the hooks, and announces the behaviour changes in the changelog.What
PydanticAIHooknow fails closed when a provider class rejects the fields forwarded from the connection:get_conn()raises aValueErrornaming the connection, the provider, the fields passed and the provider'sTypeErrortext instead of rebuilding the provider from environment variables, sotest_connectionreports the failure too. This also covers connections infallback_conn_ids.docs/provider_fallback.rstis updated to match.MCPHookvalidates the stdioargsextra and thetimeoutextra.argsmay be a list of strings, a single string, a JSON array string, ornull(treated as empty);timeoutmust be a non-negative finite number, and0andnullboth mean no init timeout (nullis mapped to0soFASTMCP_CLIENT_INIT_TIMEOUTcannot re-enable one). Invalid values raiseValueErrornaming the connection.docs/connections/mcp.rstis updated.MCPHook.get_connraisesAirflowOptionalProviderFeatureExceptioninstead of a bareImportErrorwhen themcpdependency is missing. Importing theLLMRetryPolicymodule on Airflow < 3.3 now raises the same exception.LlamaIndexHook.test_connectionnow reads the LLM's.metadata, so a model name that LlamaIndex's OpenAI class rejects (for example an Ollama or vLLM model) is reported as a failure. Before, it passed and failed only on the first.chat()call. It still does not call the LLM, so a revoked key or unreachable host still passes (docstring updated).llm_modelandembed_modelpositionally toLlamaIndexHookandLangChainHookemits anAirflowProviderDeprecationWarning. The two hooks had these two parameters in opposite positional order, so positional calls were easy to get wrong. Pass them by keyword. Positional calls still work until support is removed in a future release.vertexaiconnection field is labelled "Deprecated and ignored" inprovider.yamlandget_provider_info.py. Behaviour isunchanged, since the field was already ignored.
Was generative AI tooling used to co-author this PR?
{pr_number}.significant.rst, in airflow-core/newsfragments. You can add this file in a follow-up commit after the PR is created so you know the PR number.