Cap pydantic-ai-skills below 2 for the Common AI skills extra (#74899)

Author: kaxil

providers/common/ai/README.rst

@@ -99,7 +99,7 @@ Extra            Dependencies
 ``openshell``    ``openshell>=0.1.2,<0.2``, ``grpcio>=1.78.0``, ``protobuf>=6.31.1``
 ``code-mode``    ``pydantic-ai-harness[codemode]>=0.35.0``
 ``shields``      ``pydantic-ai-shields>=0.3.4``
-``skills``       ``apache-airflow-providers-git>=0.4.0``, ``pydantic-ai-skills>=1.2.0``
+``skills``       ``apache-airflow-providers-git>=0.4.0``, ``pydantic-ai-skills>=1.2.0,<2``
 ``islo``         ``islo>=0.3.19``
 ``avro``         ``fastavro>=1.10.0; python_version < "3.14"``, ``fastavro>=1.12.1; python_version >= "3.14"``
 ``parquet``      ``pyarrow>=18.0.0; python_version < '3.14'``, ``pyarrow>=22.0.0; python_version >= '3.14'``

providers/common/ai/docs/features.rst

@@ -126,7 +126,7 @@ checklist.
        ``apache.iceberg`` extra for Iceberg
    * - :doc:`AgentSkillsToolset <toolsets/skills>`
      - Loads ``SKILL.md`` instruction bundles when the model asks for one.
-     - ``skills``; on Airflow 2, install ``pydantic-ai-skills``
+     - ``skills``; on Airflow 2, install ``pydantic-ai-skills>=1.2.0,<2``
    * - :doc:`SandboxToolset <sandbox/index>`
      - Gives the agent a shell and a filesystem in an isolated sandbox: a hosted
        service, a server you run, or a microVM on your machine for local development.

providers/common/ai/docs/index.rst

@@ -239,7 +239,7 @@ Extra            Dependencies
 ``openshell``    ``openshell>=0.1.2,<0.2``, ``grpcio>=1.78.0``, ``protobuf>=6.31.1``
 ``code-mode``    ``pydantic-ai-harness[codemode]>=0.35.0``
 ``shields``      ``pydantic-ai-shields>=0.3.4``
-``skills``       ``apache-airflow-providers-git>=0.4.0``, ``pydantic-ai-skills>=1.2.0``
+``skills``       ``apache-airflow-providers-git>=0.4.0``, ``pydantic-ai-skills>=1.2.0,<2``
 ``islo``         ``islo>=0.3.19``
 ``avro``         ``fastavro>=1.10.0; python_version < "3.14"``, ``fastavro>=1.12.1; python_version >= "3.14"``
 ``parquet``      ``pyarrow>=18.0.0; python_version < '3.14'``, ``pyarrow>=22.0.0; python_version >= '3.14'``

providers/common/ai/pyproject.toml

@@ -136,10 +136,11 @@ dependencies = [
 # the git provider supplies GitHook + GitPython for cloning GitSkills with
 # credentials from a `git` connection. pydantic-ai-harness's Skills capability is not
 # a replacement: it loads only SKILL.md instructions, with no skill resources and no
-# run_skill_script.
+# run_skill_script. pydantic-ai-skills 2.0 removed SkillsToolset, which AgentSkillsToolset
+# wraps, so the extra stays below 2 until the toolset moves to the 2.x capability API.
 "skills" = [
     "apache-airflow-providers-git>=0.4.0",
-    "pydantic-ai-skills>=1.2.0",
+    "pydantic-ai-skills>=1.2.0,<2",
 ]
 # Islo-hosted microVM sandboxes for SandboxToolset: like modal, needs no host-level
 # installation, only ISLO_API_KEY in the worker environment.
@@ -190,7 +191,7 @@ dev = [
     # Additional devel dependencies (do not remove this line and add extra development dependencies)
     "sqlglot>=30.0.0",
     "pydantic-ai-slim[mcp]>=2.36.0",
-    "pydantic-ai-skills>=1.2.0",
+    "pydantic-ai-skills>=1.2.0,<2",
     "apache-airflow-providers-common-sql[datafusion]",
     "langchain>=1.0.0",
     "llama-index-core>=0.14.5",

providers/common/ai/src/airflow/providers/common/ai/toolsets/skills.py

@@ -31,11 +31,16 @@
 from __future__ import annotations
 
 import dataclasses
+from importlib import metadata
 from typing import TYPE_CHECKING, Any
 
 from airflow.providers.common.ai.skills import SkillSource, _materialize_skills
 from airflow.providers.common.ai.utils.toolset_base import validate_max_retries
 
+# pydantic-ai-skills 2.0 removed SkillsToolset, leaving only SkillsCapability, so the
+# ``skills`` extra caps it below 2.
+_SUPPORTED_PYDANTIC_AI_SKILLS = ">=1.2.0,<2"
+
 try:
     from pydantic_ai.toolsets.abstract import AbstractToolset
 except ImportError:  # pragma: no cover - pydantic-ai is a provider dependency
@@ -114,13 +119,22 @@ async def for_run(self, ctx: RunContext) -> AbstractToolset:
 
     async def __aenter__(self) -> AgentSkillsToolset:
         # Resolve + clone at run time, on the worker -- not at DAG-parse time.
+        # pydantic-ai-skills is an optional extra, so it is imported here rather than at module level.
         try:
-            from pydantic_ai_skills import SkillsToolset
+            import pydantic_ai_skills
         except ImportError as e:
             raise ValueError(
                 "AgentSkillsToolset requires the optional 'skills' extra: "
                 "pip install 'apache-airflow-providers-common-ai[skills]'."
             ) from e
+        if not hasattr(pydantic_ai_skills, "SkillsToolset"):
+            raise ValueError(
+                f"AgentSkillsToolset needs pydantic-ai-skills{_SUPPORTED_PYDANTIC_AI_SKILLS}, but "
+                f"pydantic-ai-skills {metadata.version('pydantic-ai-skills')} is installed and has no "
+                "SkillsToolset. Install a supported version: "
+                f"pip install 'pydantic-ai-skills{_SUPPORTED_PYDANTIC_AI_SKILLS}'."
+            )
+        SkillsToolset = pydantic_ai_skills.SkillsToolset
 
         directories, cleanup = _materialize_skills(self._sources)
         self._cleanup = cleanup

providers/common/ai/tests/unit/common/ai/toolsets/test_skills.py

@@ -24,6 +24,7 @@
 
 import asyncio
 import sys
+import types
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -229,6 +230,22 @@ def test_helpful_error_when_package_missing(self):
             with pytest.raises(ValueError, match=r"\[skills\]"):
                 asyncio.run(toolset.__aenter__())
 
+    def test_unsupported_installed_version_names_version_and_range(self, tmp_path):
+        """pydantic-ai-skills 2.x imports but has no SkillsToolset; the error must not blame the extra."""
+        agent = Agent(
+            FunctionModel(lambda messages, info: ModelResponse(parts=[TextPart("done")])),
+            toolsets=[AgentSkillsToolset(sources=[str(tmp_path)])],
+        )
+        without_skills_toolset = types.ModuleType("pydantic_ai_skills")
+        with (
+            patch.dict(sys.modules, {"pydantic_ai_skills": without_skills_toolset}),
+            patch("importlib.metadata.version", autospec=True, return_value="2.1.0"),
+        ):
+            with pytest.raises(
+                ValueError, match=r"pydantic-ai-skills>=1\.2\.0,<2, but pydantic-ai-skills 2\.1\.0"
+            ):
+                agent.run_sync("go")
+
 
 async def _enter_exit(toolset):
     await toolset.__aenter__()

pyproject.toml

@@ -1634,12 +1634,6 @@ apache-airflow-task-sdk-integration-tests = false
 
 # Manual overrides (kept outside the auto-generated block above so the
 # update_airflow_pyproject_toml.py script doesn't clobber them).
-# Temporary: pydantic-ai-skills 1.2.0 (adds exclude_resources, required by the
-# apache-airflow-providers-common-ai[skills] floor) was published 2026-07-15,
-# inside the "4 days" exclude-newer window. This pins the per-package cutoff just
-# past that release so 1.2.0 resolves while any later release stays quarantined.
-# Remove once the rolling window advances past 2026-07-15.
-pydantic-ai-skills = "2026-07-16T00:00:00Z"
 # Temporary: google-cloud-aiplatform 1.164.0 is the first release whose "evaluation" extra
 # allows the litellm versions that carry the Python 3.14 security fixes, and it was published
 # 2026-08-12, inside the "4 days" exclude-newer window. This pins the per-package cutoff just
@@ -1841,8 +1835,6 @@ apache-airflow-task-sdk-integration-tests = false
 
 # Manual overrides — see the matching block under
 # `[tool.uv.exclude-newer-package]` above for rationale.
-# Temporary: see the pydantic-ai-skills note in `[tool.uv.exclude-newer-package]`.
-pydantic-ai-skills = "2026-07-16T00:00:00Z"
 # Temporary: see the google-cloud-aiplatform note in `[tool.uv.exclude-newer-package]`.
 google-cloud-aiplatform = "2026-08-13T00:00:00Z"
 # Temporary: see the typesafe-sdk note in `[tool.uv.exclude-newer-package]`.