Implement mirrored provider clients (AnthropicVertex)

Author: koxudaxi

python/mirascope/llm/clients/__init__.py

@@ -5,6 +5,7 @@
     AnthropicModelId,
 )
 from .anthropic_bedrock import AnthropicBedrockClient
+from .anthropic_vertex import AnthropicVertexClient
 from .azure_openai.completions import AzureOpenAICompletionsClient
 from .azure_openai.responses import AzureOpenAIResponsesClient
 from .base import BaseClient, ClientT, Params
@@ -22,6 +23,7 @@
     "AnthropicBedrockClient",
     "AnthropicClient",
     "AnthropicModelId",
+    "AnthropicVertexClient",
     "AzureOpenAICompletionsClient",
     "AzureOpenAIResponsesClient",
     "BaseClient",

python/mirascope/llm/clients/anthropic/base_client.py

@@ -85,7 +85,7 @@ async def _prepare_messages_async(
 
     @property
     @abstractmethod
-    def provider(self) -> Literal["anthropic", "anthropic-bedrock"]:
+    def provider(self) -> Literal["anthropic", "anthropic-bedrock", "anthropic-vertex"]:
         """Return the provider name for Anthropic-compatible clients."""
         ...
 

python/mirascope/llm/clients/anthropic_vertex/__init__.py

@@ -0,0 +1,13 @@
+"""Anthropic Vertex AI client implementations."""
+
+from .clients import (
+    AnthropicVertexClient,
+    client,
+    get_client,
+)
+
+__all__ = [
+    "AnthropicVertexClient",
+    "client",
+    "get_client",
+]

python/mirascope/llm/clients/anthropic_vertex/clients.py

@@ -0,0 +1,133 @@
+"""Anthropic Vertex AI client implementation."""
+
+import os
+from contextvars import ContextVar
+from functools import lru_cache
+from typing import Literal
+
+from anthropic import NOT_GIVEN
+from anthropic.lib.vertex._client import AnthropicVertex, AsyncAnthropicVertex
+
+from ..anthropic import BaseAnthropicClient
+
+ANTHROPIC_VERTEX_CLIENT_CONTEXT: ContextVar["AnthropicVertexClient | None"] = (
+    ContextVar("ANTHROPIC_VERTEX_CLIENT_CONTEXT", default=None)
+)
+
+
+@lru_cache(maxsize=256)
+def _anthropic_vertex_singleton(
+    project_id: str | None,
+    region: str | None,
+) -> "AnthropicVertexClient":
+    """Return a cached AnthropicVertexClient instance for the given parameters."""
+    return AnthropicVertexClient(
+        project_id=project_id,
+        region=region,
+    )
+
+
+def client(
+    *,
+    project_id: str | None = None,
+    region: str | None = None,
+) -> "AnthropicVertexClient":
+    """Return an `AnthropicVertexClient`.
+
+    Args:
+        project_id: GCP project ID. If None, uses GOOGLE_CLOUD_PROJECT, GCLOUD_PROJECT,
+            CLOUD_ML_PROJECT_ID, or GCP_PROJECT_ID env vars (in that order).
+        region: GCP region. If None, uses CLOUD_ML_REGION, GOOGLE_CLOUD_REGION, or
+            GOOGLE_CLOUD_LOCATION env vars (in that order).
+
+    Returns:
+        An `AnthropicVertexClient` instance.
+
+    Examples:
+        # Use environment variables
+        client = client()
+
+        # Use explicit parameters
+        client = client(
+            project_id="my-gcp-project",
+            region="us-central1"
+        )
+    """
+    project_id = (
+        project_id
+        or os.getenv("GOOGLE_CLOUD_PROJECT")
+        or os.getenv("GCLOUD_PROJECT")
+        or os.getenv("CLOUD_ML_PROJECT_ID")
+        or os.getenv("GCP_PROJECT_ID")
+    )
+    region = (
+        region
+        or os.getenv("CLOUD_ML_REGION")
+        or os.getenv("GOOGLE_CLOUD_REGION")
+        or os.getenv("GOOGLE_CLOUD_LOCATION")
+    )
+
+    return _anthropic_vertex_singleton(
+        project_id,
+        region,
+    )
+
+
+def clear_cache() -> None:
+    """Clear the client singleton cache.
+
+    This is useful for testing or when you need to force recreation
+    of clients with updated configuration.
+    """
+    _anthropic_vertex_singleton.cache_clear()
+
+
+def get_client() -> "AnthropicVertexClient":
+    """Retrieve the current Anthropic Vertex client from context, or a global default.
+
+    Returns:
+        The current Anthropic Vertex client from context if available, otherwise
+        a global default client based on environment variables.
+    """
+    ctx_client = ANTHROPIC_VERTEX_CLIENT_CONTEXT.get()
+    return ctx_client or client()
+
+
+class AnthropicVertexClient(
+    BaseAnthropicClient[AnthropicVertex, AsyncAnthropicVertex, "AnthropicVertexClient"]
+):
+    """Anthropic Vertex AI client that inherits from BaseAnthropicClient.
+
+    Only overrides initialization to use Vertex-specific SDK classes and
+    provider naming to return 'anthropic-vertex'.
+    """
+
+    @property
+    def _context_var(self) -> ContextVar["AnthropicVertexClient | None"]:
+        return ANTHROPIC_VERTEX_CLIENT_CONTEXT
+
+    def __init__(
+        self,
+        *,
+        project_id: str | None = None,
+        region: str | None = None,
+    ) -> None:
+        """Initialize the Anthropic Vertex AI client.
+
+        Args:
+            project_id: GCP project ID.
+            region: GCP region for Vertex AI.
+        """
+        self.client = AnthropicVertex(
+            project_id=project_id or NOT_GIVEN,
+            region=region or NOT_GIVEN,
+        )
+        self.async_client = AsyncAnthropicVertex(
+            project_id=project_id or NOT_GIVEN,
+            region=region or NOT_GIVEN,
+        )
+
+    @property
+    def provider(self) -> Literal["anthropic-vertex"]:
+        """Return the provider name for Anthropic Vertex AI."""
+        return "anthropic-vertex"

python/mirascope/llm/clients/providers.py

@@ -13,6 +13,11 @@
     client as anthropic_bedrock_client,
     get_client as get_anthropic_bedrock_client,
 )
+from .anthropic_vertex import (
+    AnthropicVertexClient,
+    client as anthropic_vertex_client,
+    get_client as get_anthropic_vertex_client,
+)
 from .azure_openai.completions import (
     AzureOpenAICompletionsClient,
     client as azure_openai_completions_client,
@@ -43,6 +48,7 @@
 Provider: TypeAlias = Literal[
     "anthropic",
     "anthropic-bedrock",  # AnthropicBedrockClient
+    "anthropic-vertex",  # AnthropicVertexClient
     "azure-openai:completions",  # AzureOpenAICompletionsClient
     "azure-openai:responses",  # AzureOpenAIResponsesClient
     "google",
@@ -73,6 +79,12 @@ def get_client(provider: Literal["anthropic-bedrock"]) -> AnthropicBedrockClient
     ...
 
 
+@overload
+def get_client(provider: Literal["anthropic-vertex"]) -> AnthropicVertexClient:
+    """Get an Anthropic Vertex AI client instance."""
+    ...
+
+
 @overload
 def get_client(
     provider: Literal["azure-openai:completions"],
@@ -114,6 +126,7 @@ def get_client(
 ) -> (
     AnthropicClient
     | AnthropicBedrockClient
+    | AnthropicVertexClient
     | AzureOpenAICompletionsClient
     | AzureOpenAIResponsesClient
     | GoogleClient
@@ -132,6 +145,7 @@ def get_client(
         - "openai:responses" returns `OpenAIResponsesClient` (Responses API)
         - "anthropic" returns `AnthropicClient`
         - "anthropic-bedrock" returns `AnthropicBedrockClient`
+        - "anthropic-vertex" returns `AnthropicVertexClient`
         - "azure-openai:completions" returns `AzureOpenAICompletionsClient`
         - "azure-openai:responses" returns `AzureOpenAIResponsesClient`
         - "google" returns `GoogleClient`
@@ -147,6 +161,8 @@ def get_client(
             return get_anthropic_client()
         case "anthropic-bedrock":
             return get_anthropic_bedrock_client()
+        case "anthropic-vertex":
+            return get_anthropic_vertex_client()
         case "azure-openai:completions":
             return get_azure_openai_completions_client()
         case "azure-openai:responses":
@@ -209,6 +225,17 @@ def client(
     ...
 
 
+@overload
+def client(
+    provider: Literal["anthropic-vertex"],
+    *,
+    project_id: str | None = None,
+    region: str | None = None,
+) -> AnthropicVertexClient:
+    """Create a cached Anthropic Vertex AI client with the given parameters."""
+    ...
+
+
 @overload
 def client(
     provider: Literal["google"],
@@ -255,6 +282,7 @@ def client(
 ) -> (
     AnthropicClient
     | AnthropicBedrockClient
+    | AnthropicVertexClient
     | AzureOpenAICompletionsClient
     | AzureOpenAIResponsesClient
     | GoogleClient
@@ -278,6 +306,9 @@ def client(
                 - aws_secret_key: AWS secret key
                 - aws_session_token: AWS session token
                 - aws_profile: AWS profile name
+            - For Vertex AI provider:
+                - project_id: GCP project ID
+                - region: GCP region
 
     Returns:
         A cached client instance for the specified provider with the given parameters.
@@ -297,6 +328,11 @@ def client(
                 aws_session_token=kwargs.get("aws_session_token"),
                 aws_profile=kwargs.get("aws_profile"),
             )
+        case "anthropic-vertex":
+            return anthropic_vertex_client(
+                project_id=kwargs.get("project_id"),
+                region=kwargs.get("region"),
+            )
         case "azure-openai:completions":
             return azure_openai_completions_client(
                 api_key=api_key,