Add a generated supported services page for the common.ai provider

devel-common/src/sphinx_exts/providers_extensions.py

@@ -25,13 +25,12 @@
 from typing import Any
 
 # No stub exists for docutils.parsers.rst.directives. See https://github.com/python/typeshed/issues/5755.
-from provider_yaml_utils import load_package_data
-
 from sphinx_exts.operators_and_hooks_ref import (
     DEFAULT_HEADER_SEPARATOR,
     BaseJinjaReferenceDirective,
     _render_template,
 )
+from sphinx_exts.provider_yaml_utils import load_package_data
 
 
 def find_class_methods_with_specific_calls(
@@ -515,8 +514,39 @@ def render_content(self, *, tags: set[str] | None, header_separator: str = DEFAU
         return _render_openlineage_supported_classes_content()
 
 
+def _find_provider_package_data(package_name: str) -> dict[str, Any]:
+    for provider in load_package_data():
+        if provider["package-name"] == package_name:
+            return provider
+    raise ValueError(f"No provider.yaml found for package '{package_name}'")
+
+
+def _render_connection_services_content(package_name: str) -> str:
+    provider = _find_provider_package_data(package_name)
+    rows = [
+        {
+            "hook_name": conn["hook-name"],
+            "services": conn.get("external-services") or [],
+            "ref": f"howto/connection:{conn['connection-type']}",
+        }
+        for conn in provider.get("connection-types", [])
+    ]
+    return _render_template("provider_connection_services.rst.jinja2", rows=rows)
+
+
+class ProviderConnectionServicesDirective(BaseJinjaReferenceDirective):
+    """Render a table of a provider's connection types and the external services each reaches."""
+
+    required_arguments = 1
+    optional_arguments = 0
+
+    def render_content(self, *, tags: set[str] | None, header_separator: str = DEFAULT_HEADER_SEPARATOR):
+        return _render_connection_services_content(self.arguments[0])
+
+
 def setup(app):
     """Setup plugin"""
     app.add_directive("airflow-providers-openlineage-supported-classes", OpenLineageSupportedClassesDirective)
+    app.add_directive("provider-connection-services", ProviderConnectionServicesDirective)
 
     return {"parallel_read_safe": True, "parallel_write_safe": True}

devel-common/src/sphinx_exts/templates/provider_connection_services.rst.jinja2

@@ -0,0 +1,28 @@
+{#
+ 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.
+#}
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Connection type
+     - External services
+   {% for row in rows -%}
+   * - :ref:`{{ row.hook_name }} <{{ row.ref }}>`
+     - {{ row.services | join(', ') }}
+   {% endfor %}

devel-common/tests/unit/sphinx_exts/test_providers_extensions.py

@@ -0,0 +1,57 @@
+# 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
+
+from unittest import mock
+
+import pytest
+
+from sphinx_exts.providers_extensions import (
+    _render_connection_services_content,
+)
+
+FAKE_PACKAGE_DATA = [
+    {
+        "package-name": "apache-airflow-providers-example",
+        "connection-types": [
+            {
+                "hook-class-name": "airflow.providers.example.hooks.example.ExampleHook",
+                "hook-name": "Example",
+                "connection-type": "example",
+                "external-services": ["OpenAI", "Anthropic"],
+            }
+        ],
+    }
+]
+
+
+@mock.patch("sphinx_exts.providers_extensions.load_package_data", autospec=True)
+def test_render_connection_services_content_renders_one_row_per_connection_type(mock_load_package_data):
+    mock_load_package_data.return_value = FAKE_PACKAGE_DATA
+
+    rendered = _render_connection_services_content("apache-airflow-providers-example")
+
+    assert ":ref:`Example <howto/connection:example>`" in rendered
+    assert "OpenAI, Anthropic" in rendered
+
+
+@mock.patch("sphinx_exts.providers_extensions.load_package_data", autospec=True)
+def test_render_connection_services_content_unknown_package_raises(mock_load_package_data):
+    mock_load_package_data.return_value = FAKE_PACKAGE_DATA
+
+    with pytest.raises(ValueError, match="No provider.yaml found"):
+        _render_connection_services_content("apache-airflow-providers-does-not-exist")

docs/spelling_wordlist.txt

@@ -233,6 +233,7 @@ ccache
 cdc
 celltags
 centric
+Cerebras
 cfg
 cgi
 cgitb
@@ -327,6 +328,7 @@ contextmgr
 contrib
 convertToIri
 cooldown
+Copilot
 copyable
 coreutils
 CoreV
@@ -1157,6 +1159,7 @@ NCUs
 nd
 ndjson
 nearText
+Nebius
 neighbours
 neo
 Neo4j
@@ -1929,6 +1932,7 @@ Vectorizers
 vendored
 venv
 venvs
+Vercel
 Vertica
 vertica
 Vespa
@@ -1981,6 +1985,7 @@ WTF
 wtf
 wtforms
 www
+xAI
 XCom
 Xcom
 xcom

providers/common/ai/docs/connections/langchain.rst

@@ -71,11 +71,11 @@ Supported providers
 
 The hook forwards two values to LangChain: the connection's password as
 ``api_key`` and its host as ``base_url``. Any provider whose LangChain model
-class accepts those two keyword arguments works, which includes OpenAI,
-Anthropic, Groq, Mistral AI, DeepSeek, Ollama and vLLM. Providers whose
-classes expect their own credential shape (AWS Bedrock, Google Vertex AI and
-GenAI, Azure OpenAI, Cohere, HuggingFace) reject these kwargs and are not
-usable through this connection type.
+class accepts those two keyword arguments works. Providers whose classes
+expect their own credential shape (AWS Bedrock, Google Vertex AI and GenAI,
+Azure OpenAI, Cohere, HuggingFace) reject these kwargs and are not usable
+through this connection type. See :doc:`../supported_services` for the
+current list of providers this connection type reaches.
 
 Model resolution order
 -----------------------

providers/common/ai/docs/index.rst

@@ -105,6 +105,7 @@ waits for the result, use that vendor's provider.
     What you can build <use_cases/index>
     Connections <connections/index>
     Models and providers <model_providers>
+    Supported services <supported_services>
     Operators and decorators <operators/index>
     Toolsets <toolsets/index>
     Agent frameworks <frameworks/index>

providers/common/ai/docs/model_providers.rst

@@ -26,6 +26,9 @@ name picks the vendor. Switching vendors is a connection
 change, not a Dag change. Find your vendor below, install the extra, create the connection
 type shown, and set the model name with that prefix.
 
+For the exhaustive, generated-and-hand-written list of every service this provider
+reaches (connections and toolsets alike), see :doc:`supported_services`.
+
 .. list-table::
    :header-rows: 1
    :widths: 18 16 18 20 28

providers/common/ai/docs/supported_services.rst

@@ -0,0 +1,82 @@
+ .. 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.
+
+Supported services
+===================
+
+``common.ai`` reaches external services on two axes: the model providers its connections
+talk to, and the systems its toolsets talk to. For per-model detail beyond the vendor level
+(exact model ids, pricing, capabilities), see `pydantic-ai's model list
+<https://ai.pydantic.dev/models/>`__.
+
+This page is the complete list of what this provider reaches; for a curated, install- and
+credential-oriented walkthrough of each model vendor, see :doc:`model_providers`.
+
+Connections
+-----------
+
+.. provider-connection-services:: apache-airflow-providers-common-ai
+
+Toolsets
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Toolset
+     - External services
+   * - :doc:`HookToolset <toolsets/hook>`
+     - Any Airflow connection, through its provider hook
+   * - :doc:`SQLToolset <toolsets/sql>`
+     - Any common.sql database connection (with table allowlists and AST validation)
+   * - :doc:`DataFusionToolset <toolsets/datafusion>`
+     - Object storage (S3, local filesystem, Apache Iceberg) via Apache DataFusion
+   * - :doc:`LoggingToolset <toolsets/logging>`
+     - Airflow task logs
+   * - :doc:`MCPToolset <toolsets/mcp>`
+     - Any MCP server (user-supplied endpoint)
+   * - :doc:`ObjectStorageToolset <toolsets/object_storage>`
+     - Object storage (S3, GCS, Azure Blob Storage, or any store
+       :class:`~airflow.sdk.ObjectStoragePath` can open), read-only
+   * - :doc:`SandboxToolset <sandbox/index>`
+     - Docker Sandboxes (the shipped sbx backend; other backends can be added via SandboxBackend)
+   * - :doc:`AgentSkillsToolset <toolsets/skills>`
+     - Agent skills from local paths and remote Git repositories
+   * - :doc:`LangChain Bridge <toolsets/langchain>`
+     - LangChain tools
+   * - :doc:`Managed Agent Toolsets <toolsets/managed_agent>`
+     - Snowflake Cortex Agents; Amazon Bedrock AgentCore; Azure AI Foundry; Vertex AI Agent Engine
+
+Notes
+-----
+
+* The ``langchain`` connection type's row above is limited to OpenAI-compatible credential
+  surfaces (``api_key`` + optional ``base_url``); see :ref:`Supported providers
+  <langchain-supported-providers>` for the providers that reject those kwargs and are not
+  usable through it.
+* Azure OpenAI, Google Vertex AI, and AWS Bedrock are also reachable through the generic
+  ``pydanticai`` connection type, but each has its own dedicated connection type
+  (:doc:`connections/pydantic_ai_azure`, :doc:`connections/pydantic_ai_vertex`,
+  :doc:`connections/pydantic_ai_bedrock`) for their non-standard auth.
+* Most model providers need an extra installed alongside ``apache-airflow-providers-common-ai``
+  — see the "Choosing extras" section of :doc:`installation`.
+* "Pydantic AI Gateway" in the ``pydanticai`` row is a routing layer, not an upstream vendor
+  in its own right: set the connection's Model field to ``gateway/<vendor>:<model>`` (for
+  example ``gateway/anthropic:claude-sonnet-5``) to send the request through it instead of
+  directly to the vendor. It currently routes to Anthropic, AWS Bedrock, Google Gemini,
+  Google Vertex AI, Groq, and OpenAI — all already listed above in their own right.

providers/common/ai/provider.yaml

@@ -162,15 +162,39 @@ connection-types:
     hook-name: "Pydantic AI"
     connection-type: pydanticai
     external-services:
-      - OpenAI
+      - Alibaba Cloud Model Studio
       - Anthropic
-      - Google
       - AWS Bedrock
+      - AWS Bedrock Mantle
+      - Azure OpenAI
+      - Cerebras
+      - Cohere
+      - Crusoe
+      - DeepSeek
+      - Fireworks AI
+      - GitHub Copilot
+      - Google Gemini
+      - Google Vertex AI
       - Groq
+      - Heroku
+      - Hugging Face
+      - LiteLLM
       - Mistral AI
-      - DeepSeek
+      - Moonshot AI
+      - Nebius
       - Ollama
+      - OpenAI
+      - OpenRouter
+      - OVHcloud
+      - Pydantic AI Gateway
+      - SambaNova
+      - Snowflake Cortex
+      - Together AI
+      - TypeSafe
+      - Vercel AI Gateway
       - vLLM
+      - xAI
+      - Z.AI
     ui-field-behaviour:
       hidden-fields:
         - schema
@@ -415,6 +439,8 @@ connection-types:
   - hook-class-name: airflow.providers.common.ai.hooks.mcp.MCPHook
     hook-name: "MCP Server"
     connection-type: mcp
+    external-services:
+      - Any MCP server (user-supplied endpoint)
     ui-field-behaviour:
       hidden-fields:
         - schema