Make vercel dep optional

Author: anbuzin

README.md

@@ -8,13 +8,14 @@ A toolkit for building LLM-powered applications and agent loops.
 uv add ai
 ```
 
-AI Gateway usage works with the base package. Direct providers that use an
-OpenAI-compatible or Anthropic-compatible adapter load the corresponding
-official SDK lazily and require optional extras:
+AI Gateway API-key usage works with the base package. Direct providers that
+use an OpenAI-compatible or Anthropic-compatible adapter load the corresponding
+official SDK lazily. Vercel OIDC for AI Gateway also uses an optional extra:
 
 ```bash
 uv add "ai[openai]"      # OpenAI-compatible providers
 uv add "ai[anthropic]"   # Anthropic-compatible providers
+uv add "ai[vercel]"      # Vercel OIDC for AI Gateway
 ```
 
 ```python

pyproject.toml

@@ -32,13 +32,15 @@ dependencies = [
     "modelsdotdev==0.*",
     "pydantic>=2.12.5",
     "typing-extensions>=4.15.0",
-    "vercel>=0.5.9",
 ]
 
 [project.optional-dependencies]
 anthropic = ["anthropic>=0.83.0"]
 mcp = ["mcp>=1.18.0"]
 openai = ["openai>=2.14.0"]
+vercel = [
+    "vercel>=0.5.9",
+]
 
 [build-system]
 requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]

src/ai/providers/ai_gateway/provider.py

@@ -7,8 +7,6 @@
 
 from typing import TYPE_CHECKING, Any, ClassVar
 
-from vercel import oidc
-
 from ... import errors as ai_errors
 from .. import base
 from . import client as gateway_client
@@ -17,7 +15,7 @@
 from .client import errors as client_errors
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncGenerator, Mapping, Sequence
+    from collections.abc import AsyncGenerator, Callable, Mapping, Sequence
     from types import ModuleType
 
     import httpx
@@ -35,6 +33,27 @@
 _VERCEL_ENV = "VERCEL"
 _OIDC_TOKEN_ENV = "VERCEL_OIDC_TOKEN"
 
+_get_vercel_oidc_token_impl: Callable[[], str] | None
+try:
+    from vercel import oidc as _vercel_oidc
+except ModuleNotFoundError as exc:
+    if exc.name != "vercel":
+        raise
+    _get_vercel_oidc_token_impl = None
+else:
+    _get_vercel_oidc_token_impl = _vercel_oidc.get_vercel_oidc_token
+
+
+def _get_vercel_oidc_token() -> str:
+    if _get_vercel_oidc_token_impl is None:
+        raise ai_errors.InstallationError(
+            "AI Gateway OIDC authentication requires the optional `vercel` "
+            'package. Install it with `pip install "ai[vercel]"` or '
+            '`uv add "ai[vercel]"`, or set `AI_GATEWAY_API_KEY` to use '
+            "API key authentication."
+        )
+    return _get_vercel_oidc_token_impl()
+
 
 class GatewayProvider(base.Provider[gateway_client.GatewayClient]):
     """Provider configuration for the Vercel AI Gateway."""
@@ -87,7 +106,7 @@ def _gateway_auth(
         if self._config_value(_VERCEL_ENV) == "1" or self._config_value(
             _OIDC_TOKEN_ENV
         ):
-            return oidc.get_vercel_oidc_token(), "oidc"
+            return _get_vercel_oidc_token(), "oidc"
         return None, None
 
     def is_configured(self) -> bool:

tests/providers/ai_gateway/test_provider.py

@@ -1,13 +1,34 @@
 from __future__ import annotations
 
+from collections.abc import Callable
+
 import httpx
 import pytest
-from vercel import oidc as vercel_oidc
 
 import ai
+from ai.providers.ai_gateway import provider as gateway_provider
 from ai.providers.ai_gateway.client import errors
 
 
+def _set_oidc_token(
+    monkeypatch: pytest.MonkeyPatch,
+    get_token: Callable[[], str],
+) -> None:
+    monkeypatch.setattr(
+        gateway_provider,
+        "_get_vercel_oidc_token_impl",
+        get_token,
+    )
+
+
+def _fail_oidc_import(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(
+        gateway_provider,
+        "_get_vercel_oidc_token_impl",
+        lambda: pytest.fail("OIDC should not be used when an API key is set"),
+    )
+
+
 async def test_list_models_gets_config_with_gateway_headers_and_sorts_ids() -> (
     None
 ):
@@ -79,11 +100,7 @@ async def test_list_models_uses_oidc_on_vercel_when_no_api_key(
 ) -> None:
     monkeypatch.delenv("AI_GATEWAY_API_KEY", raising=False)
     monkeypatch.setenv("VERCEL", "1")
-    monkeypatch.setattr(
-        vercel_oidc,
-        "get_vercel_oidc_token",
-        lambda: "oidc-test-token",
-    )
+    _set_oidc_token(monkeypatch, lambda: "oidc-test-token")
     captured_headers: dict[str, str] = {}
 
     def _handler(request: httpx.Request) -> httpx.Response:
@@ -115,11 +132,7 @@ async def test_list_models_uses_oidc_token_env_without_vercel_flag(
     monkeypatch.delenv("AI_GATEWAY_API_KEY", raising=False)
     monkeypatch.delenv("VERCEL", raising=False)
     monkeypatch.setenv("VERCEL_OIDC_TOKEN", "pulled-oidc-token")
-    monkeypatch.setattr(
-        vercel_oidc,
-        "get_vercel_oidc_token",
-        lambda: "pulled-oidc-token",
-    )
+    _set_oidc_token(monkeypatch, lambda: "pulled-oidc-token")
     captured_headers: dict[str, str] = {}
 
     def _handler(request: httpx.Request) -> httpx.Response:
@@ -141,20 +154,43 @@ def _handler(request: httpx.Request) -> httpx.Response:
     assert captured_headers["ai-gateway-auth-method"] == "oidc"
 
 
-async def test_api_key_env_takes_precedence_over_oidc(
+async def test_oidc_expected_without_vercel_extra_raises_installation_error(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    monkeypatch.setenv("AI_GATEWAY_API_KEY", "env-test-key")
+    monkeypatch.delenv("AI_GATEWAY_API_KEY", raising=False)
     monkeypatch.setenv("VERCEL", "1")
+    monkeypatch.setattr(
+        gateway_provider,
+        "_get_vercel_oidc_token_impl",
+        None,
+    )
 
-    def _fail_oidc() -> str:
-        pytest.fail("OIDC should not be fetched when an API key is set")
+    def _handler(request: httpx.Request) -> httpx.Response:
+        pytest.fail("Gateway should not be called without the OIDC helper")
 
-    monkeypatch.setattr(
-        vercel_oidc,
-        "get_vercel_oidc_token",
-        _fail_oidc,
+    provider = ai.get_provider(
+        "vercel",
+        base_url="https://gateway.test/v3/ai",
+        client=httpx.AsyncClient(transport=httpx.MockTransport(_handler)),
     )
+
+    try:
+        with pytest.raises(ai.InstallationError) as exc_info:
+            await provider.list_models()
+    finally:
+        await provider.aclose()
+
+    assert "AI Gateway OIDC authentication requires" in str(exc_info.value)
+    assert "ai[vercel]" in str(exc_info.value)
+    assert "AI_GATEWAY_API_KEY" in str(exc_info.value)
+
+
+async def test_api_key_env_takes_precedence_over_oidc(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("AI_GATEWAY_API_KEY", "env-test-key")
+    monkeypatch.setenv("VERCEL", "1")
+    _fail_oidc_import(monkeypatch)
     captured_headers: dict[str, str] = {}
 
     def _handler(request: httpx.Request) -> httpx.Response:
@@ -181,15 +217,7 @@ async def test_explicit_api_key_takes_precedence_over_oidc(
 ) -> None:
     monkeypatch.setenv("AI_GATEWAY_API_KEY", "env-test-key")
     monkeypatch.setenv("VERCEL", "1")
-
-    def _fail_oidc() -> str:
-        pytest.fail("OIDC should not be fetched when an API key is set")
-
-    monkeypatch.setattr(
-        vercel_oidc,
-        "get_vercel_oidc_token",
-        _fail_oidc,
-    )
+    _fail_oidc_import(monkeypatch)
     captured_headers: dict[str, str] = {}
 
     def _handler(request: httpx.Request) -> httpx.Response: