kaxil commented on code in PR #76797: URL: https://github.com/apache/airflow/pull/76797#discussion_r4622820718
########## providers/databricks/docs/connections/pydantic_ai_databricks.rst: ########## @@ -0,0 +1,163 @@ + .. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + .. http://www.apache.org/licenses/LICENSE-2.0 + + .. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _howto/connection:pydanticai_databricks: + +Pydantic AI (Databricks Model Serving) connection +================================================= + +The ``pydanticai_databricks`` connection type configures access to +`Databricks Model Serving <https://docs.databricks.com/aws/en/machine-learning/model-serving/>`__ +through its OpenAI-compatible Chat Completions API, via the pydantic-ai framework. It backs +``PydanticAIDatabricksHook``, the dedicated subclass of ``PydanticAIHook`` for Databricks. + +.. note:: + This hook has been unit-tested only and has not been run against a live workspace. Review Comment: Can this be run against a real workspace before merge? A released guide saying the hook has never been run live is hard to recommend, and one live call would also confirm the `openai-chat` path and the per-request token refresh. ########## providers/databricks/src/airflow/providers/databricks/hooks/model_serving.py: ########## @@ -0,0 +1,253 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +"""Expose Databricks Model Serving's OpenAI-compatible chat endpoint as a pydantic-ai model hook.""" + +from __future__ import annotations + +import asyncio +import concurrent.futures +import contextvars +import functools +import inspect +from typing import TYPE_CHECKING, Any +from urllib.parse import urlsplit + +from airflow.providers.common.compat.sdk import AirflowOptionalProviderFeatureException +from airflow.providers.databricks.hooks.databricks_base import BaseDatabricksHook + +_COMMON_AI_REQUIREMENT_MESSAGE = ( + "This feature requires apache-airflow-providers-common-ai>=1.0.0 (a PydanticAIHook with " + "'fallback_conn_ids'). " + "Install with apache-airflow-providers-databricks[common.ai]." +) + +try: + import httpx2 + + from airflow.providers.common.ai.hooks.pydantic_ai import PydanticAIHook +except ImportError: + raise AirflowOptionalProviderFeatureException(_COMMON_AI_REQUIREMENT_MESSAGE) + +if "fallback_conn_ids" not in inspect.signature(PydanticAIHook.__init__).parameters: + raise AirflowOptionalProviderFeatureException(_COMMON_AI_REQUIREMENT_MESSAGE) + +if TYPE_CHECKING: + from collections.abc import AsyncGenerator, Generator + + from httpx2 import Request, Response + +# OpenAIProvider rejects an empty api_key, but _DatabricksServingAuth overwrites Authorization on +# every request, so this value is never sent. +_UNUSED_TOKEN_PLACEHOLDER = "unused-overridden-per-request" + +# Token refreshes run here, never on asyncio's default executor: ``asend()`` reads its reply on that +# executor while holding the comms lock, so blocking lookups that fill it leave nothing to run the +# read and the task hangs (common.ai>=1.1.0 guards against the same thing with ``_executor`` in +# ``hooks/pydantic_ai.py``). Some ``_get_token`` paths do such lookups at request time (AWS +# federation resolves a second Airflow connection through ``StsHook``). Kept local: common.ai's +# ``_run_off_loop`` only exists from 1.1.0. +_executor = concurrent.futures.ThreadPoolExecutor(max_workers=1, thread_name_prefix="databricks-serving-auth") + + +def _is_valid_host(host: str | None) -> bool: + """Return whether ``host`` is a bare ``hostname[:port]`` as left by ``BaseDatabricksHook._parse_host``.""" + if not host or host.endswith(":") or any(char.isspace() for char in host): + return False + parsed = urlsplit(f"//{host}") + if not parsed.hostname or parsed.netloc != host or parsed.username is not None: + return False + try: + parsed.port + except ValueError: + return False + return True + + +class _DatabricksServingAuth(httpx2.Auth): + """ + Refresh the ``Authorization`` header on every request from a Databricks hook. + + ``_get_token()`` may block: the OAuth service principal, Azure AD and federation paths make + HTTP or SDK calls, with retries, to fetch an expiring token. ``async_auth_flow`` is overridden + to run the refresh on a worker thread instead of the httpx2 default of driving the sync + ``auth_flow`` inline on the event loop. ``auth_flow`` itself is kept for sync ``httpx2.Client`` + callers, which have no event loop to block. + """ + + def __init__(self, databricks_hook: BaseDatabricksHook) -> None: + self._databricks_hook = databricks_hook + + def _get_auth_header(self) -> str: + return f"Bearer {self._databricks_hook._get_token(raise_error=True)}" Review Comment: If `_get_token` raises here (say the OAuth token endpoint is down), does `fallback_conn_ids` actually fail over? On openai 3.15+ the send only catches `request_exceptions()`, so the `AirflowException` comes out raw rather than as a `ModelAPIError`, and `FallbackModel` lets it fail the task. Older openai (3.14 and below, which common.ai still allows) wraps any exception in `APIConnectionError` after retrying, so a bad config there silently goes to the fallback instead. Maybe raise an `httpx2.RequestError` yourself for the unreachable case? A test with a real fallback chain and a failing token fetch would catch both. ########## providers/databricks/src/airflow/providers/databricks/hooks/model_serving.py: ########## @@ -0,0 +1,253 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +"""Expose Databricks Model Serving's OpenAI-compatible chat endpoint as a pydantic-ai model hook.""" + +from __future__ import annotations + +import asyncio +import concurrent.futures +import contextvars +import functools +import inspect +from typing import TYPE_CHECKING, Any +from urllib.parse import urlsplit + +from airflow.providers.common.compat.sdk import AirflowOptionalProviderFeatureException +from airflow.providers.databricks.hooks.databricks_base import BaseDatabricksHook + +_COMMON_AI_REQUIREMENT_MESSAGE = ( + "This feature requires apache-airflow-providers-common-ai>=1.0.0 (a PydanticAIHook with " + "'fallback_conn_ids'). " + "Install with apache-airflow-providers-databricks[common.ai]." +) + +try: + import httpx2 + + from airflow.providers.common.ai.hooks.pydantic_ai import PydanticAIHook +except ImportError: + raise AirflowOptionalProviderFeatureException(_COMMON_AI_REQUIREMENT_MESSAGE) + +if "fallback_conn_ids" not in inspect.signature(PydanticAIHook.__init__).parameters: + raise AirflowOptionalProviderFeatureException(_COMMON_AI_REQUIREMENT_MESSAGE) + +if TYPE_CHECKING: + from collections.abc import AsyncGenerator, Generator + + from httpx2 import Request, Response + +# OpenAIProvider rejects an empty api_key, but _DatabricksServingAuth overwrites Authorization on +# every request, so this value is never sent. +_UNUSED_TOKEN_PLACEHOLDER = "unused-overridden-per-request" + +# Token refreshes run here, never on asyncio's default executor: ``asend()`` reads its reply on that +# executor while holding the comms lock, so blocking lookups that fill it leave nothing to run the +# read and the task hangs (common.ai>=1.1.0 guards against the same thing with ``_executor`` in +# ``hooks/pydantic_ai.py``). Some ``_get_token`` paths do such lookups at request time (AWS +# federation resolves a second Airflow connection through ``StsHook``). Kept local: common.ai's +# ``_run_off_loop`` only exists from 1.1.0. +_executor = concurrent.futures.ThreadPoolExecutor(max_workers=1, thread_name_prefix="databricks-serving-auth") + + +def _is_valid_host(host: str | None) -> bool: + """Return whether ``host`` is a bare ``hostname[:port]`` as left by ``BaseDatabricksHook._parse_host``.""" + if not host or host.endswith(":") or any(char.isspace() for char in host): + return False + parsed = urlsplit(f"//{host}") + if not parsed.hostname or parsed.netloc != host or parsed.username is not None: + return False + try: + parsed.port + except ValueError: + return False + return True + + +class _DatabricksServingAuth(httpx2.Auth): + """ + Refresh the ``Authorization`` header on every request from a Databricks hook. + + ``_get_token()`` may block: the OAuth service principal, Azure AD and federation paths make + HTTP or SDK calls, with retries, to fetch an expiring token. ``async_auth_flow`` is overridden + to run the refresh on a worker thread instead of the httpx2 default of driving the sync + ``auth_flow`` inline on the event loop. ``auth_flow`` itself is kept for sync ``httpx2.Client`` + callers, which have no event loop to block. + """ + + def __init__(self, databricks_hook: BaseDatabricksHook) -> None: + self._databricks_hook = databricks_hook + + def _get_auth_header(self) -> str: + return f"Bearer {self._databricks_hook._get_token(raise_error=True)}" + + def auth_flow(self, request: Request) -> Generator[Request, Response, None]: + request.headers["Authorization"] = self._get_auth_header() + yield request + + async def async_auth_flow(self, request: Request) -> AsyncGenerator[Request, Response]: + call = functools.partial(contextvars.copy_context().run, self._get_auth_header) + request.headers["Authorization"] = await asyncio.get_running_loop().run_in_executor(_executor, call) + yield request + + +class PydanticAIDatabricksHook(PydanticAIHook): + """ + Hook for Databricks Model Serving's OpenAI-compatible chat endpoint via pydantic-ai. + + Unlike the other ``PydanticAI*`` hooks, credentials do not live on this connection: they are + read from an existing ``databricks`` connection (personal access token, OAuth, Azure or + federated credentials -- whichever that connection is configured for) and refreshed on every + request through ``BaseDatabricksHook._get_token``. Username/password basic auth is not + supported. The underlying ``httpx2.AsyncClient`` is built once and lives as long as this hook + instance; nothing currently closes it. + + Connection fields: + - **extra** JSON: ``{"model": "my-serving-endpoint", + "databricks_conn_id": "databricks_default"}`` + + A bare model name is a serving endpoint name and is qualified as ``openai-chat:<endpoint>``, + so requests use the Chat Completions API. Databricks documents that API for chat endpoints + (Foundation Model APIs, external models and custom LLM endpoints), not for every endpoint + type. Databricks' own limits on function calling and structured outputs apply; see the + connection documentation for pointers. + + A Databricks connection that sets the ``proxies`` or ``azure_resource_id`` extra is rejected, + because this hook does not route requests through a proxy or send the Azure workspace resource + headers. + + :param llm_conn_id: Airflow connection ID for this ``pydanticai_databricks`` connection. + :param model_id: Serving endpoint name, e.g. ``"my-serving-endpoint"``. + :param fallback_conn_ids: See :class:`~airflow.providers.common.ai.hooks.pydantic_ai.PydanticAIHook`. + :param databricks_conn_id: Connection ID of an existing Databricks connection to source the + workspace host and credentials from. Takes precedence over the connection extra's + ``databricks_conn_id``; one of the two is required. + """ + + conn_type = "pydanticai_databricks" + default_conn_name = "pydanticai_databricks_default" + hook_name = "Pydantic AI (Databricks Model Serving)" + model_provider = "openai-chat" + + def __init__( + self, + llm_conn_id: str | None = None, + model_id: str | None = None, + fallback_conn_ids: list[str] | None = None, + *, + databricks_conn_id: str | None = None, + **kwargs: Any, + ) -> None: + super().__init__(llm_conn_id, model_id, fallback_conn_ids, **kwargs) + self.databricks_conn_id = databricks_conn_id + self._databricks_hook: BaseDatabricksHook | None = None + self._base_url: str | None = None + self._http_client: httpx2.AsyncClient | None = None + + @staticmethod + def get_ui_field_behaviour() -> dict[str, Any]: + """Return custom field behaviour for the Airflow connection form.""" + return { + "hidden_fields": ["schema", "port", "login", "host", "password"], + "relabeling": {}, + "placeholders": { + "extra": '{"model": "my-serving-endpoint", "databricks_conn_id": "databricks_default"}', + }, + } + + def _get_databricks_conn_id(self, extra: dict[str, Any]) -> str: + databricks_conn_id = self.databricks_conn_id or extra.get("databricks_conn_id") + if not databricks_conn_id: + raise ValueError( + f"Connection '{self.llm_conn_id}' has no Databricks connection to source credentials " + "from. Set databricks_conn_id on the hook or the connection's extra field, pointing " + "at an existing Databricks connection." + ) + return databricks_conn_id + + def _get_databricks_hook(self, extra: dict[str, Any]) -> BaseDatabricksHook: + """ + Build the Databricks hook, base URL, and HTTP client once. + + Reused for this hook's lifetime -- including the ``httpx2.AsyncClient``, which nothing + else owns or closes, so building a fresh one on every call would leak one per call. + """ + if self._databricks_hook is None: + databricks_hook = BaseDatabricksHook( + databricks_conn_id=self._get_databricks_conn_id(extra), + caller="PydanticAIDatabricksHook", + ) + if not _is_valid_host(databricks_hook.host): + # Must not include the host: it may carry credentials (``user:password@host``). + raise ValueError( + f"Databricks connection '{databricks_hook.databricks_conn_id}' has no valid host. " + "Set the workspace host (hostname and optional port, no path or credentials) on " + "the connection or in its extra field." + ) + if databricks_hook.proxies: + raise ValueError( + f"Databricks connection '{databricks_hook.databricks_conn_id}' sets the 'proxies' " + "extra, which PydanticAIDatabricksHook does not support. Remove it, or use a " + "Databricks connection without a proxy." + ) + if "azure_resource_id" in databricks_hook.databricks_conn.extra_dejson: + raise ValueError( + f"Databricks connection '{databricks_hook.databricks_conn_id}' sets the " + "'azure_resource_id' extra, which PydanticAIDatabricksHook does not support. " + "Remove it, or use a Databricks connection that does not need it." + ) + base_url = databricks_hook._endpoint_url("serving-endpoints") + http_client = httpx2.AsyncClient(auth=_DatabricksServingAuth(databricks_hook)) + self._databricks_hook = databricks_hook + self._base_url = base_url + self._http_client = http_client + return self._databricks_hook + + def _get_provider_kwargs( + self, + api_key: str | None, + base_url: str | None, + extra: dict[str, Any], + ) -> dict[str, Any]: + """ + Return kwargs for ``OpenAIProvider``. + + .. note:: + ``api_key`` and ``base_url`` (sourced from ``conn.password`` and ``conn.host``) are + intentionally ignored: this connection hides those fields in the UI, and credentials + and host come from the Databricks connection named by ``databricks_conn_id`` instead. + """ + self._get_databricks_hook(extra) + return { + "base_url": self._base_url, + "api_key": _UNUSED_TOKEN_PLACEHOLDER, + "http_client": self._http_client, + } + + def test_connection(self) -> tuple[bool, str]: + """ + Test connection by resolving the model and fetching a Databricks token. + + A bad credential is reported here. Does NOT call the serving endpoint. Review Comment: For a PAT, `_get_token` returns the password (or `extra["token"]`) without a network call, so a revoked or mistyped PAT still reports "Databricks token fetched successfully". Is a cheap authenticated read of the serving endpoint worth doing here, or should the docstring and message say a PAT is only checked for presence? ########## providers/databricks/pyproject.toml: ########## @@ -90,7 +90,7 @@ dependencies = [ "azure-identity>=1.25.3", ] "common.ai" = [ - "apache-airflow-providers-common-ai[mcp]>=1.0.0", + "apache-airflow-providers-common-ai[mcp,openai]>=1.0.0", Review Comment: Adding `openai` here means `databricks[common.ai]` can no longer be installed next to `common-ai[llamaindex]`, since the root `pyproject.toml` lists those two common-ai extras as conflicting. That also reaches people who use this extra only for the Unity MCP toolset or the agent hook. Would a separate extra for the model hook, or telling users to add `common-ai[openai]` in the connection guide, keep this one as it was? ########## providers/databricks/docs/connections/pydantic_ai_databricks.rst: ########## @@ -0,0 +1,163 @@ + .. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + .. http://www.apache.org/licenses/LICENSE-2.0 + + .. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _howto/connection:pydanticai_databricks: + +Pydantic AI (Databricks Model Serving) connection +================================================= + +The ``pydanticai_databricks`` connection type configures access to +`Databricks Model Serving <https://docs.databricks.com/aws/en/machine-learning/model-serving/>`__ +through its OpenAI-compatible Chat Completions API, via the pydantic-ai framework. It backs +``PydanticAIDatabricksHook``, the dedicated subclass of ``PydanticAIHook`` for Databricks. + +.. note:: + This hook has been unit-tested only and has not been run against a live workspace. + +This connection type sources credentials from an existing +:ref:`Databricks connection <howto/connection:databricks>`, so the token-based authentication +methods that connection supports (OAuth, Azure AD, managed identity, federation) are reused and +refreshed on every request, except for the settings this hook rejects (see Authentication below). + +Install with: + +.. code-block:: bash + + pip install 'apache-airflow-providers-databricks[common.ai]' + +Default Connection IDs +---------------------- + +The ``PydanticAIDatabricksHook`` uses ``pydanticai_databricks_default`` by default. + +Configuring the Connection +-------------------------- + +This connection type needs two connections: this one, and an existing ``databricks`` connection it +points at. All fields below are ``extra`` (JSON) fields on the ``pydanticai_databricks`` +connection; ``Schema``, ``Port``, ``Login``, ``Host``, and ``Password`` are hidden in the +connection form because the workspace host and credentials come from the Databricks connection +instead. + +Model + Serving endpoint name (e.g. ``my-serving-endpoint``). + + A bare name is resolved to ``openai-chat:<name>``, which uses the Chat Completions API. + Databricks documents querying chat models through the OpenAI client for + `Foundation Model APIs + <https://docs.databricks.com/aws/en/machine-learning/model-serving/score-foundation-models>`__, + `external models <https://docs.databricks.com/aws/en/machine-learning/foundation-models/external-models>`__ and + `custom LLM endpoints + <https://docs.databricks.com/aws/en/machine-learning/model-serving/serve-custom-llms>`__ + served with the chat task. Databricks does not document Chat Completions for other endpoint types, + such as embedding or traditional ML endpoints; this hook is not intended for them. + + In pydantic-ai, the ``openai:`` prefix selects the Responses API and ``openai-chat:`` selects + Chat Completions, as described in the + `pydantic-ai OpenAI documentation <https://pydantic.dev/docs/ai/models/openai/>`__. An explicit + ``openai:<name>`` therefore sends Responses API requests. Databricks documents its Responses API + passthrough for OpenAI models; see + `Query chat models + <https://docs.databricks.com/aws/en/machine-learning/model-serving/query-chat-models>`__. + +Fallback Connections + Other connection IDs to fail over to, in order, while this provider is unavailable. Stored in + ``extra["fallback_conn_ids"]``. Entries may name any ``pydanticai`` connection type, so one + chain can span vendors. See :doc:`apache-airflow-providers-common-ai:provider_fallback`. + +Databricks Connection ID + Connection ID of an existing :ref:`Databricks connection <howto/connection:databricks>` to + source credentials from. Stored in ``extra["databricks_conn_id"]``. Also + settable via the ``PydanticAIDatabricksHook(databricks_conn_id=...)`` constructor argument, + which takes precedence over the extra field. One of the two is required. + +Authentication +-------------- + +Credentials are not configured on this connection. A token is requested from the referenced +Databricks connection on every request, so it works with the token-based methods described on the +:doc:`Databricks connection <databricks>` page, except for the settings listed below that this hook +rejects. Username/password basic auth is not supported: the token request fails with "Token +authentication isn't configured", which surfaces in **Test connection** and on the first request. + +Databricks documents that +`route-optimized endpoints <https://docs.databricks.com/aws/en/machine-learning/model-serving/route-optimization>`__ +are queried differently from other endpoints, including using a different URL and authentication +using OAuth tokens. This hook only sends requests to ``/serving-endpoints``, so it does not support +route-optimized endpoints. + +This hook does not route requests through a proxy and does not send the Azure workspace resource +headers. A Databricks connection that sets the ``proxies`` or ``azure_resource_id`` extra is +rejected with a ``ValueError`` when the model is built, instead of the setting being ignored +silently. + +Limitations +----------- + +The hook does not rewrite requests, so the limits of Databricks Model Serving apply. Those limits +vary by model and endpoint type and change over time. At the time of writing, Databricks' pages on +`function calling <https://docs.databricks.com/aws/en/machine-learning/model-serving/function-calling>`__ +and +`structured outputs <https://docs.databricks.com/aws/en/machine-learning/model-serving/structured-outputs>`__ +list the following, among others, which are the authoritative and more complete source: + +- For Foundation Model APIs and external model endpoints, function calling does not support parallel + function calls, allows at most 32 functions in ``tools``, and rejects JSON schema keywords such as + ``pattern``, ``anyOf``, ``oneOf``, ``allOf``, ``prefixItems`` and ``$ref``. Databricks lists + these under limitations during Public Preview. +- For Claude models, ``response_format`` cannot be combined with ``tools`` or ``tool_choice``. + Databricks also lists newer Claude models that return HTTP 400 for ``response_format`` on Chat + Completions. +- Databricks' structured outputs page also lists that structured outputs are not supported with + streaming. + +The hook sends requests to the ``/serving-endpoints`` base URL that Databricks documents for the +OpenAI client (see the +`custom LLM endpoints <https://docs.databricks.com/aws/en/machine-learning/model-serving/serve-custom-llms>`__ +page); other base URLs are not supported. + +Example +------- + +Two connections: the Databricks connection holding credentials, and this one pointing at it. + +.. code-block:: json + + { + "conn_type": "databricks", + "host": "https://adb-1234567890123456.7.azuredatabricks.net", + "password": "<personal_access_token>" Review Comment: For a PAT, isn't a plain `pydanticai` connection with model `openai-chat:<endpoint>`, host `https://<workspace>/serving-endpoints` and the PAT as Password already enough? What this hook adds is token refresh for OAuth, Azure and federation. Could the example use one of those, and the guide say when to pick which, the way the Snowflake row in `model_providers.rst` does? ########## providers/databricks/tests/unit/databricks/hooks/test_model_serving.py: ########## @@ -0,0 +1,548 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +from __future__ import annotations + +import pytest + +pytest.importorskip("airflow.providers.common.ai.hooks.pydantic_ai") +pytest.importorskip("pydantic_ai.providers.openai") + +import contextvars +import importlib +import json +import sys +import threading +from unittest import mock + +import httpx2 +from pydantic_ai import Agent +from pydantic_ai.models.openai import OpenAIChatModel + +from airflow.models import Connection +from airflow.providers.common.ai.hooks.pydantic_ai import PydanticAIHook +from airflow.providers.common.compat.sdk import AirflowOptionalProviderFeatureException +from airflow.providers.databricks import hooks as databricks_hooks +from airflow.providers.databricks.get_provider_info import get_provider_info +from airflow.providers.databricks.hooks.databricks_base import BaseDatabricksHook +from airflow.providers.databricks.hooks.model_serving import ( + _UNUSED_TOKEN_PLACEHOLDER, + PydanticAIDatabricksHook, + _DatabricksServingAuth, +) + +MODULE_PATH = "airflow.providers.databricks.hooks.model_serving" +SERVING_URL = "https://adb-1.azuredatabricks.net/serving-endpoints" +CONNECTION_EXTRA = {"model": "databricks-claude-sonnet-4-5", "databricks_conn_id": "databricks_conn"} +DATABRICKS_CONN_URI = Connection(conn_type="pydanticai_databricks", extra=CONNECTION_EXTRA).get_uri() +LEFTOVER_PASSWORD_CONN_URI = Connection( + conn_type="pydanticai_databricks", password="leftover-password", extra=CONNECTION_EXTRA +).get_uri() +PRIMARY_CONN_URI = Connection( + conn_type="pydanticai", + password="sk-test", + extra={"model": "openai:gpt-5", "fallback_conn_ids": ["fallback_conn"]}, +).get_uri() + + +def _mock_databricks_hook(mock_hook_cls): + mock_hook = mock_hook_cls.return_value + mock_hook.host = "adb-1.azuredatabricks.net" + mock_hook.databricks_conn_id = "databricks_conn" + mock_hook.proxies = None + mock_hook.databricks_conn.extra_dejson = {} + mock_hook._endpoint_url.return_value = SERVING_URL + mock_hook._get_token.return_value = "real-token" + return mock_hook + + +class TestDatabricksConnIdResolution: + def test_hook_argument_wins_over_extra(self): + hook = PydanticAIDatabricksHook(databricks_conn_id="explicit_conn") + assert hook._get_databricks_conn_id({"databricks_conn_id": "extra_conn"}) == "explicit_conn" + + def test_falls_back_to_extra(self): + hook = PydanticAIDatabricksHook() + assert hook._get_databricks_conn_id({"databricks_conn_id": "extra_conn"}) == "extra_conn" + + def test_raises_when_neither_is_set(self): + hook = PydanticAIDatabricksHook(llm_conn_id="pydanticai_conn") + with pytest.raises(ValueError, match="Databricks connection"): + hook._get_databricks_conn_id({}) + + +class TestGetProviderKwargs: + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_ignores_connection_password_and_host(self, mock_hook_cls): + """Leftover Password/Host on the pydanticai_databricks connection must not reach the provider.""" + _mock_databricks_hook(mock_hook_cls) + + hook = PydanticAIDatabricksHook(databricks_conn_id="databricks_conn") + kwargs = hook._get_provider_kwargs( + api_key="leftover-password", base_url="https://ignored.example.com", extra={} + ) + + assert kwargs["base_url"] == SERVING_URL + mock_hook_cls.return_value._endpoint_url.assert_called_once_with("serving-endpoints") + assert kwargs["api_key"] == _UNUSED_TOKEN_PLACEHOLDER + mock_hook_cls.return_value._get_token.assert_not_called() + assert isinstance(kwargs["http_client"], httpx2.AsyncClient) + # Pin that per-request refresh is actually wired up: deleting `auth=...` from + # `_get_databricks_hook` would leave every assertion above green. + client_auth = kwargs["http_client"].auth + assert isinstance(client_auth, _DatabricksServingAuth) + assert client_auth._databricks_hook is mock_hook_cls.return_value + + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_databricks_hook_built_once(self, mock_hook_cls): + """A second call must reuse the same Databricks hook, not rebuild it.""" + _mock_databricks_hook(mock_hook_cls) + + hook = PydanticAIDatabricksHook(databricks_conn_id="databricks_conn") + first = hook._get_provider_kwargs(None, None, {}) + second = hook._get_provider_kwargs(None, None, {}) + + mock_hook_cls.assert_called_once_with( + databricks_conn_id="databricks_conn", caller="PydanticAIDatabricksHook" + ) + assert first["http_client"] is second["http_client"] + + @pytest.mark.parametrize( + "raw_host", + [ + pytest.param(None, id="none"), + pytest.param("", id="empty"), + pytest.param("https://", id="scheme-only"), + pytest.param(" ", id="blank"), + pytest.param("adb-1.azuredatabricks.net/serving-endpoints", id="with-path"), + pytest.param("adb-1.azuredatabricks.net#frag", id="with-fragment"), + pytest.param("adb-1.azuredatabricks.net:", id="empty-port"), + pytest.param("adb-1.azuredatabricks.net:abc", id="non-numeric-port"), + pytest.param("adb-1.azuredatabricks.net:99999", id="port-out-of-range"), + pytest.param("[email protected]", id="userinfo-username"), + pytest.param("@adb-1.azuredatabricks.net", id="userinfo-empty-username"), + pytest.param("svc:[email protected]", id="userinfo-username-and-password"), + pytest.param("svc:[email protected]/serving-endpoints", id="userinfo-and-path"), + pytest.param(":443", id="port-only"), + pytest.param("https://[::1]:443", id="ipv6-with-scheme"), + pytest.param("https://adb-1.azuredatabricks.net ", id="trailing-whitespace-with-scheme"), + ], + ) + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_raises_when_databricks_connection_has_no_valid_host(self, mock_hook_cls, raw_host): + mock_hook = _mock_databricks_hook(mock_hook_cls) + # Feed the host through the real normalisation the Databricks hook applies to the connection. + mock_hook.host = BaseDatabricksHook._parse_host(raw_host) if raw_host else raw_host + + hook = PydanticAIDatabricksHook(databricks_conn_id="databricks_conn") + with pytest.raises(ValueError, match="'databricks_conn' has no valid host") as exc_info: + hook._get_provider_kwargs(None, None, {}) + + # The host may carry credentials, so the message must never echo any part of it. + assert "s3cr3t" not in str(exc_info.value) + assert "svc" not in str(exc_info.value) + mock_hook._endpoint_url.assert_not_called() + assert hook._databricks_hook is None + + @pytest.mark.parametrize( + "raw_host", + [ + pytest.param("adb-1.azuredatabricks.net", id="bare"), + pytest.param("https://adb-1.azuredatabricks.net", id="with-scheme"), + pytest.param("adb-1.azuredatabricks.net/", id="trailing-slash"), + pytest.param("https://adb-1.azuredatabricks.net/", id="scheme-and-trailing-slash"), + pytest.param("adb-1.azuredatabricks.net:443", id="with-port"), + pytest.param("https://svc:[email protected]", id="scheme-drops-userinfo"), + pytest.param("[::1]:443", id="ipv6-bare"), + ], + ) + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_accepts_host_shapes_the_databricks_hook_accepts(self, mock_hook_cls, raw_host): + mock_hook = _mock_databricks_hook(mock_hook_cls) + mock_hook.host = BaseDatabricksHook._parse_host(raw_host) + + hook = PydanticAIDatabricksHook(databricks_conn_id="databricks_conn") + + assert hook._get_provider_kwargs(None, None, {})["base_url"] == SERVING_URL + mock_hook._endpoint_url.assert_called_once_with("serving-endpoints") + + @pytest.mark.parametrize( + "proxies", + [ + pytest.param({"https": "http://user:[email protected]:3128"}, id="https"), + pytest.param({"http": "http://proxy.example:3128"}, id="http"), + pytest.param( + {"http": "http://proxy.example:3128", "https": "http://proxy.example:3128"}, id="both" + ), + ], + ) + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_raises_when_databricks_connection_sets_proxies(self, mock_hook_cls, proxies): + mock_hook = _mock_databricks_hook(mock_hook_cls) + mock_hook.proxies = proxies + + hook = PydanticAIDatabricksHook(databricks_conn_id="databricks_conn") + with pytest.raises(ValueError, match="'databricks_conn' sets the 'proxies' extra") as exc_info: + hook._get_provider_kwargs(None, None, {}) + + assert "secret" not in str(exc_info.value) + assert hook._databricks_hook is None + + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_raises_when_databricks_connection_sets_azure_resource_id(self, mock_hook_cls): + mock_hook = _mock_databricks_hook(mock_hook_cls) + mock_hook.databricks_conn.extra_dejson = {"azure_resource_id": "/subscriptions/s3cr3t-sub"} + + hook = PydanticAIDatabricksHook(databricks_conn_id="databricks_conn") + with pytest.raises( + ValueError, match="'databricks_conn' sets the 'azure_resource_id' extra" + ) as exc_info: + hook._get_provider_kwargs(None, None, {}) + + assert "s3cr3t-sub" not in str(exc_info.value) + mock_hook._endpoint_url.assert_not_called() + assert hook._databricks_hook is None + + @pytest.mark.parametrize( + ("databricks_conn_kwargs", "expected_error"), + [ + pytest.param( + {"host": "adb-1.azuredatabricks.net", "extra": {"proxies": {"https": "http://p:1"}}}, + "sets the 'proxies' extra", + id="proxies", + ), + pytest.param( + { + "host": "adb-1.azuredatabricks.net", + "extra": {"azure_resource_id": "/subscriptions/s3cr3t-sub"}, + }, + "sets the 'azure_resource_id' extra", + id="azure-resource-id", + ), + pytest.param( + {"extra": {"host": "svc:[email protected]"}}, + "has no valid host", + id="extra-host-with-userinfo", + ), + pytest.param( + {"host": "svc:[email protected]"}, + "has no valid host", + id="connection-host-with-userinfo", + ), + ], + ) + def test_rejects_unsupported_settings_on_a_real_databricks_connection( + self, databricks_conn_kwargs, expected_error + ): + """Run the guards against a real ``BaseDatabricksHook`` so a change in its attributes is caught.""" + databricks_conn = Connection(conn_type="databricks", password="tok", **databricks_conn_kwargs) + + with mock.patch.dict("os.environ", AIRFLOW_CONN_DBX=databricks_conn.get_uri()): + hook = PydanticAIDatabricksHook(databricks_conn_id="dbx") + with pytest.raises(ValueError, match=expected_error) as exc_info: + hook._get_databricks_hook({}) + + for secret in ("s3cr3t", "p:1", "svc"): + assert secret not in str(exc_info.value) + assert hook._databricks_hook is None + + @mock.patch.dict( + "os.environ", + AIRFLOW_CONN_DBX=Connection( + conn_type="databricks", host="https://adb-1.azuredatabricks.net", password="tok" + ).get_uri(), + ) + def test_accepts_a_plain_real_databricks_connection(self): + hook = PydanticAIDatabricksHook(databricks_conn_id="dbx") + + databricks_hook = hook._get_databricks_hook({}) + + assert isinstance(databricks_hook, BaseDatabricksHook) + assert hook._base_url == SERVING_URL + + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_failed_first_build_is_not_remembered(self, mock_hook_cls): + """A failed first build must not leave half-built state that the second call silently reuses.""" + _mock_databricks_hook(mock_hook_cls) + mock_hook_cls.return_value._endpoint_url.side_effect = [RuntimeError("no host"), SERVING_URL] + + hook = PydanticAIDatabricksHook(databricks_conn_id="databricks_conn") + with pytest.raises(RuntimeError, match="no host"): + hook._get_provider_kwargs(None, None, {}) + kwargs = hook._get_provider_kwargs(None, None, {}) + + assert kwargs["base_url"] == SERVING_URL + assert isinstance(kwargs["http_client"], httpx2.AsyncClient) + + +class TestBareModelNameQualification: + def test_bare_model_name_gets_openai_chat_prefix(self): + hook = PydanticAIDatabricksHook(model_id="databricks-claude-sonnet-4-5") + assert ( + hook._qualify_model_name("databricks-claude-sonnet-4-5") + == "openai-chat:databricks-claude-sonnet-4-5" + ) + + def test_already_prefixed_model_name_is_unchanged(self): + hook = PydanticAIDatabricksHook(model_id="openai:my-endpoint") + assert hook._qualify_model_name("openai:my-endpoint") == "openai:my-endpoint" + + +class TestDatabricksServingAuth: + def test_auth_flow_refreshes_token_per_request(self): + """Each request must ask the Databricks hook again, not reuse headers set on the client.""" + databricks_hook = mock.create_autospec(BaseDatabricksHook, instance=True) + databricks_hook._get_token.side_effect = ["token-1", "token-2"] + seen_auth_headers = [] + + def handler(request: httpx2.Request) -> httpx2.Response: + seen_auth_headers.append(request.headers["Authorization"]) + return httpx2.Response(200, json={"ok": True}) + + client = httpx2.Client( + auth=_DatabricksServingAuth(databricks_hook), transport=httpx2.MockTransport(handler) + ) + client.get("https://example.com/x") + client.get("https://example.com/x") + + assert seen_auth_headers == ["Bearer token-1", "Bearer token-2"] + databricks_hook._get_token.assert_called_with(raise_error=True) + + @pytest.mark.asyncio + async def test_async_auth_flow_refreshes_off_the_event_loop(self): + """`_get_token` may block (OAuth refresh, a connection lookup); it must run in a worker + thread, not inline on the event loop -- calling `BaseHook.get_connection` synchronously + from the loop thread while an async send is in flight raises `DeadlockImminentError`.""" + loop_thread_ident = threading.get_ident() + seen_threads: list[threading.Thread] = [] + tokens = iter(["token-1", "token-2"]) + + def get_token(raise_error: bool = False) -> str: + seen_threads.append(threading.current_thread()) + return next(tokens) + + databricks_hook = mock.create_autospec(BaseDatabricksHook, instance=True) + databricks_hook._get_token.side_effect = get_token + seen_auth_headers = [] + + async def handler(request: httpx2.Request) -> httpx2.Response: + seen_auth_headers.append(request.headers["Authorization"]) + return httpx2.Response(200, json={"ok": True}) + + async with httpx2.AsyncClient( + auth=_DatabricksServingAuth(databricks_hook), transport=httpx2.MockTransport(handler) + ) as client: + await client.get("https://example.com/x") + await client.get("https://example.com/x") + + assert seen_auth_headers == ["Bearer token-1", "Bearer token-2"] + assert seen_threads, "_get_token was never called" + assert all(thread.ident != loop_thread_ident for thread in seen_threads) + # The dedicated executor, not asyncio's default one: blocking lookups there can starve + # `asend()`'s reply read. + assert all(thread.name.startswith("databricks-serving-auth") for thread in seen_threads) + + @pytest.mark.asyncio + async def test_async_auth_flow_carries_contextvars_into_worker_thread(self): + """`_get_token` may resolve Airflow connections, which relies on the caller's context.""" + marker: contextvars.ContextVar[str] = contextvars.ContextVar("marker", default="unset") + seen_values: list[str] = [] + + def get_token(raise_error: bool = False) -> str: + seen_values.append(marker.get()) + return "token" + + databricks_hook = mock.create_autospec(BaseDatabricksHook, instance=True) + databricks_hook._get_token.side_effect = get_token + + async with httpx2.AsyncClient( + auth=_DatabricksServingAuth(databricks_hook), + transport=httpx2.MockTransport(lambda request: httpx2.Response(200, json={})), + ) as client: + marker.set("from-caller") + await client.get("https://example.com/x") + + assert seen_values == ["from-caller"] + + +class TestGetConn: + @mock.patch.dict("os.environ", AIRFLOW_CONN_TEST_CONN=DATABRICKS_CONN_URI) + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + @pytest.mark.asyncio + async def test_get_conn_does_not_fetch_token_until_request(self, mock_hook_cls): + mock_hook = _mock_databricks_hook(mock_hook_cls) + + hook = PydanticAIDatabricksHook(llm_conn_id="test_conn") + model = hook.get_conn() + mock_hook._get_token.assert_not_called() + + client = httpx2.AsyncClient( + auth=hook._http_client.auth, + transport=httpx2.MockTransport(lambda request: httpx2.Response(200, json={})), + ) + await client.get("https://example.com/x") + + assert isinstance(model, OpenAIChatModel) + mock_hook._get_token.assert_called_once_with(raise_error=True) + + @mock.patch.dict("os.environ", AIRFLOW_CONN_TEST_CONN=LEFTOVER_PASSWORD_CONN_URI) + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_get_conn_returns_chat_model_for_endpoint(self, mock_hook_cls): + _mock_databricks_hook(mock_hook_cls) + model = PydanticAIDatabricksHook(llm_conn_id="test_conn").get_conn() + + assert isinstance(model, OpenAIChatModel) + assert model.model_name == "databricks-claude-sonnet-4-5" + mock_hook_cls.assert_called_once_with( + databricks_conn_id="databricks_conn", caller="PydanticAIDatabricksHook" + ) + + @mock.patch.dict("os.environ", AIRFLOW_CONN_TEST_CONN=DATABRICKS_CONN_URI) + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + @pytest.mark.asyncio + async def test_request_goes_to_serving_endpoints_with_databricks_token(self, mock_hook_cls): + """Drive a real request through the model: URL, bearer token and endpoint name on the wire.""" + mock_hook = _mock_databricks_hook(mock_hook_cls) + mock_hook._get_token.return_value = "real-token" + seen: list[httpx2.Request] = [] + + def handler(request: httpx2.Request) -> httpx2.Response: + seen.append(request) + return httpx2.Response( + 200, + json={ + "id": "1", + "object": "chat.completion", + "created": 0, + "model": "databricks-claude-sonnet-4-5", + "choices": [ + { + "index": 0, + "finish_reason": "stop", + "message": {"role": "assistant", "content": "hi"}, + } + ], + }, + ) + + hook = PydanticAIDatabricksHook(llm_conn_id="test_conn") + kwargs = hook._get_provider_kwargs(None, None, hook._get_conn_and_extra()[1]) + # Reuse the hook's real auth object but swap in a MockTransport. `_http_client` is private; + # there is no public seam for injecting a transport. + client = httpx2.AsyncClient(auth=kwargs["http_client"].auth, transport=httpx2.MockTransport(handler)) + with mock.patch.object(hook, "_http_client", client): + result = await Agent(hook.get_conn()).run("hello") + + assert result.output == "hi" + assert len(seen) == 1 + assert str(seen[0].url) == f"{SERVING_URL}/chat/completions" + assert seen[0].headers["Authorization"] == "Bearer real-token" + assert _UNUSED_TOKEN_PLACEHOLDER not in seen[0].headers["Authorization"] + assert json.loads(seen[0].content)["model"] == "databricks-claude-sonnet-4-5" + + @mock.patch.dict( + "os.environ", + AIRFLOW_CONN_PRIMARY_CONN=PRIMARY_CONN_URI, + AIRFLOW_CONN_FALLBACK_CONN=DATABRICKS_CONN_URI, + ) + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_fallback_chain_dispatches_to_databricks_hook(self, mock_hook_cls): + """A generic pydanticai primary can fail over to a pydanticai_databricks connection.""" + _mock_databricks_hook(mock_hook_cls) + model = PydanticAIHook(llm_conn_id="primary_conn").get_conn() + + assert type(model).__name__ == "FallbackModel" + mock_hook_cls.assert_called_once_with( + databricks_conn_id="databricks_conn", caller="PydanticAIDatabricksHook" + ) + + +class TestTestConnection: + @mock.patch.dict("os.environ", AIRFLOW_CONN_TEST_CONN=DATABRICKS_CONN_URI) + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_success_fetches_token_once(self, mock_hook_cls): + _mock_databricks_hook(mock_hook_cls) + ok, message = PydanticAIDatabricksHook(llm_conn_id="test_conn").test_connection() + + assert ok is True + assert message + mock_hook_cls.return_value._get_token.assert_called_once_with(raise_error=True) + + @mock.patch.dict("os.environ", AIRFLOW_CONN_TEST_CONN=DATABRICKS_CONN_URI) + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_token_failure_is_reported(self, mock_hook_cls): + _mock_databricks_hook(mock_hook_cls) + mock_hook_cls.return_value._get_token.side_effect = RuntimeError("boom") + ok, message = PydanticAIDatabricksHook(llm_conn_id="test_conn").test_connection() + + assert ok is False + assert "boom" in message + + @pytest.mark.parametrize( + "extra", + [ + pytest.param({"model": "databricks-claude-sonnet-4-5"}, id="no-databricks-conn-id"), + pytest.param({"databricks_conn_id": "databricks_conn"}, id="no-model"), + ], + ) + @mock.patch(f"{MODULE_PATH}.BaseDatabricksHook", autospec=True) + def test_unresolvable_model_is_reported_without_token_fetch(self, mock_hook_cls, extra): + _mock_databricks_hook(mock_hook_cls) + connection = Connection(conn_type="pydanticai_databricks", extra=extra) + with mock.patch.dict("os.environ", AIRFLOW_CONN_TEST_CONN=connection.get_uri()): + ok, message = PydanticAIDatabricksHook(llm_conn_id="test_conn").test_connection() + + assert ok is False + assert message + mock_hook_cls.return_value._get_token.assert_not_called() + + +class TestUiFieldBehaviour: Review Comment: `check_ui_field_behaviour_matches_hook` in `scripts/in_container/run_provider_yaml_files_check.py` already compares every hook's `get_ui_field_behaviour()` with its provider.yaml entry, so this class can go. ########## providers/databricks/docs/connections/pydantic_ai_databricks.rst: ########## @@ -0,0 +1,163 @@ + .. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + .. http://www.apache.org/licenses/LICENSE-2.0 + + .. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _howto/connection:pydanticai_databricks: + +Pydantic AI (Databricks Model Serving) connection +================================================= + +The ``pydanticai_databricks`` connection type configures access to +`Databricks Model Serving <https://docs.databricks.com/aws/en/machine-learning/model-serving/>`__ +through its OpenAI-compatible Chat Completions API, via the pydantic-ai framework. It backs +``PydanticAIDatabricksHook``, the dedicated subclass of ``PydanticAIHook`` for Databricks. + +.. note:: + This hook has been unit-tested only and has not been run against a live workspace. + +This connection type sources credentials from an existing +:ref:`Databricks connection <howto/connection:databricks>`, so the token-based authentication +methods that connection supports (OAuth, Azure AD, managed identity, federation) are reused and +refreshed on every request, except for the settings this hook rejects (see Authentication below). + +Install with: + +.. code-block:: bash + + pip install 'apache-airflow-providers-databricks[common.ai]' + +Default Connection IDs +---------------------- + +The ``PydanticAIDatabricksHook`` uses ``pydanticai_databricks_default`` by default. + +Configuring the Connection +-------------------------- + +This connection type needs two connections: this one, and an existing ``databricks`` connection it +points at. All fields below are ``extra`` (JSON) fields on the ``pydanticai_databricks`` +connection; ``Schema``, ``Port``, ``Login``, ``Host``, and ``Password`` are hidden in the +connection form because the workspace host and credentials come from the Databricks connection +instead. + +Model + Serving endpoint name (e.g. ``my-serving-endpoint``). + + A bare name is resolved to ``openai-chat:<name>``, which uses the Chat Completions API. + Databricks documents querying chat models through the OpenAI client for + `Foundation Model APIs + <https://docs.databricks.com/aws/en/machine-learning/model-serving/score-foundation-models>`__, + `external models <https://docs.databricks.com/aws/en/machine-learning/foundation-models/external-models>`__ and + `custom LLM endpoints + <https://docs.databricks.com/aws/en/machine-learning/model-serving/serve-custom-llms>`__ + served with the chat task. Databricks does not document Chat Completions for other endpoint types, + such as embedding or traditional ML endpoints; this hook is not intended for them. + + In pydantic-ai, the ``openai:`` prefix selects the Responses API and ``openai-chat:`` selects + Chat Completions, as described in the + `pydantic-ai OpenAI documentation <https://pydantic.dev/docs/ai/models/openai/>`__. An explicit + ``openai:<name>`` therefore sends Responses API requests. Databricks documents its Responses API + passthrough for OpenAI models; see + `Query chat models + <https://docs.databricks.com/aws/en/machine-learning/model-serving/query-chat-models>`__. + +Fallback Connections + Other connection IDs to fail over to, in order, while this provider is unavailable. Stored in + ``extra["fallback_conn_ids"]``. Entries may name any ``pydanticai`` connection type, so one + chain can span vendors. See :doc:`apache-airflow-providers-common-ai:provider_fallback`. + +Databricks Connection ID + Connection ID of an existing :ref:`Databricks connection <howto/connection:databricks>` to + source credentials from. Stored in ``extra["databricks_conn_id"]``. Also + settable via the ``PydanticAIDatabricksHook(databricks_conn_id=...)`` constructor argument, + which takes precedence over the extra field. One of the two is required. + +Authentication +-------------- + +Credentials are not configured on this connection. A token is requested from the referenced +Databricks connection on every request, so it works with the token-based methods described on the +:doc:`Databricks connection <databricks>` page, except for the settings listed below that this hook +rejects. Username/password basic auth is not supported: the token request fails with "Token Review Comment: The Databricks connection page documents Login `token` with the PAT in Password as a valid PAT setup. `_get_token` only returns the password when Login is empty, so that connection fails here with "Token authentication isn't configured", which reads as if it had no credentials at all. Could Login `token` be treated as a PAT, or rejected up front with a `ValueError` that says to clear Login, like `proxies` is? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
