llmswitch-sdk 0.1.0__py3-none-any.whl

llmswitch/__init__.py

@@ -0,0 +1,47 @@
+"""
+llmswitch
+
+One client interface for chat completions and embeddings across OpenAI, Azure
+OpenAI, Azure AI Foundry, Anthropic and Vertex AI.
+
+    from llmswitch import LLMSwitch
+"""
+import logging
+
+__version__ = "0.1.0"
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+from .core import AsyncLLMSwitch, LLMSwitch  # noqa: E402
+from .errors import (  # noqa: E402
+    APIConnectionError,
+    AuthenticationError,
+    ChatCompletionError,
+    ConfigurationError,
+    ContentFilterError,
+    EmbeddingGenerationError,
+    InvalidResponseError,
+    LLMSwitchError,
+    ModelNotFoundError,
+    RateLimitExceededError,
+    TimeOutError,
+)
+from .models import ProviderExtensions  # noqa: E402
+
+__all__ = [
+    "__version__",
+    "LLMSwitch",
+    "AsyncLLMSwitch",
+    "LLMSwitchError",
+    "ConfigurationError",
+    "ModelNotFoundError",
+    "APIConnectionError",
+    "AuthenticationError",
+    "RateLimitExceededError",
+    "ChatCompletionError",
+    "EmbeddingGenerationError",
+    "InvalidResponseError",
+    "ContentFilterError",
+    "TimeOutError",
+    "ProviderExtensions",
+]

llmswitch/base.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractmethod
+
+
+class BaseChatProvider(ABC):
+    """
+    Abstract base class for chat providers.
+    """
+
+    @abstractmethod
+    def create(self, messages, **kwargs):
+        """
+        Create a chat completion.
+
+        Args:
+            messages: List of message dicts or objects.
+            **kwargs: Additional parameters for provider.
+
+        Returns:
+            ChatCompletion or generator of ChatCompletionChunk.
+        """
+
+
+class BaseEmbeddingProvider(ABC):
+    """
+    Abstract base class for embedding providers.
+    """
+
+    @abstractmethod
+    def create(self, inputs, **kwargs):
+        """
+        Create embeddings for the given inputs.
+
+        Args:
+            inputs: List of input strings or objects.
+            **kwargs: Additional parameters for provider.
+
+        Returns:
+            Embedding response object.
+        """

llmswitch/config.py

@@ -0,0 +1,115 @@
+"""
+config.py
+
+Pydantic configuration models, one per supported provider. ``CONFIG_REGISTRY``
+maps each provider name to its configuration class.
+"""
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator
+
+# Native-SDK client arguments that the unified constructor sets itself. They cannot
+# be overridden through ``client_options``; pass them as the unified arguments instead.
+RESERVED_CLIENT_OPTIONS = frozenset({
+    "api_key", "api_version", "azure_endpoint", "azure_deployment", "base_url", "endpoint",
+    "organization", "project", "timeout", "credential", "credentials", "location",
+    "vertexai", "http_options",
+})
+
+
+class BaseLLMConfig(BaseModel):
+    """Fields shared by every provider. Provider configs inherit from this class."""
+
+    # The unified constructor accepts the union of provider-specific fields;
+    # each provider reads what it needs and ignores the rest.
+    model_config = ConfigDict(extra="allow", str_strip_whitespace=True)
+
+    provider: str = Field(..., min_length=1, description="Provider name (openai, azure_openai, ...)")
+    model: Optional[str] = Field(default=None, description="Model name or ID")
+    deployment_name: Optional[str] = Field(
+        default=None,
+        description="Deployment or model alias; when set it takes precedence over the per-call model",
+    )
+    timeout: Optional[float] = Field(default=None, gt=0, allow_inf_nan=False,
+                                     description="Request timeout in seconds")
+    client_options: Optional[dict[str, Any]] = Field(
+        default=None,
+        description="Extra keyword arguments passed to the native SDK client constructor, "
+                    "for example default_headers or max_retries",
+    )
+
+    @field_validator("client_options")
+    @classmethod
+    def reject_reserved_client_options(cls, value: Optional[dict[str, Any]]) -> Optional[dict[str, Any]]:
+        if value is None:
+            return None
+        reserved = sorted(RESERVED_CLIENT_OPTIONS.intersection(value))
+        if reserved:
+            raise ValueError(
+                f"client_options cannot set {', '.join(reserved)}; use the unified constructor arguments instead"
+            )
+        return value
+
+    @field_validator("provider", mode="before")
+    @classmethod
+    def required_string_fields(cls, v, info: ValidationInfo):
+        if v is None or (isinstance(v, str) and not v.strip()):
+            raise ValueError(f"{info.field_name} is required and cannot be empty")
+        return v
+
+
+class AzureOpenAIConfig(BaseLLMConfig):
+    """Azure OpenAI: API key, endpoint, API version and deployment name are required."""
+
+    api_key: str = Field(..., min_length=1, description="API key for authentication")
+    endpoint: str = Field(..., min_length=1, description="Azure OpenAI resource endpoint")
+    api_version: str = Field(..., min_length=1, description="Azure OpenAI API version")
+    deployment_name: str = Field(..., min_length=1, description="Azure OpenAI deployment name")
+
+
+class AzureFoundryConfig(BaseLLMConfig):
+    """Azure AI Foundry: API key, endpoint, API version and deployment name are required."""
+
+    api_key: str = Field(..., min_length=1, description="API key for authentication")
+    endpoint: str = Field(..., min_length=1, description="Azure AI Foundry endpoint")
+    deployment_name: str = Field(..., min_length=1, description="Deployment or model name")
+    api_version: str = Field(..., min_length=1, description="Azure AI Foundry API version")
+
+
+class VertexAIConfig(BaseLLMConfig):
+    """Vertex AI: location and service-account credentials are required."""
+
+    location: str = Field(..., min_length=1, description="GCP location (e.g. us-central1)")
+    credentials_path: str = Field(..., min_length=1, description="Path to GCP credentials JSON file")
+    scopes: list[str] = Field(default_factory=lambda: ["https://www.googleapis.com/auth/cloud-platform"],
+                              description="OAuth scopes for GCP authentication")
+
+
+class OpenAIConfig(BaseLLMConfig):
+    """Native OpenAI: API key is required; endpoint, organization and project are optional."""
+
+    api_key: str = Field(..., min_length=1, description="OpenAI API key")
+    endpoint: Optional[str] = Field(default=None, description="Custom base URL for compatible APIs")
+    organization: Optional[str] = Field(default=None, description="OpenAI organization ID")
+    project: Optional[str] = Field(default=None, description="OpenAI project ID")
+
+
+class AnthropicConfig(BaseLLMConfig):
+    """Anthropic (Claude): API key is required. Prompt caching is on by default."""
+
+    api_key: str = Field(..., min_length=1, description="Anthropic API key")
+    endpoint: Optional[str] = Field(default=None, description="Custom base URL for an Anthropic-compatible gateway")
+    enable_prompt_caching: bool = Field(
+        default=True,
+        description="Inject cache_control on system messages and tool definitions",
+    )
+
+
+CONFIG_REGISTRY = {
+    "azure_openai": AzureOpenAIConfig,
+    "azure_foundry": AzureFoundryConfig,
+    "vertexai": VertexAIConfig,
+    "openai": OpenAIConfig,
+    "anthropic": AnthropicConfig,
+}

llmswitch/constants.py

@@ -0,0 +1 @@
+DEFAULT_ANTHROPIC_MODEL = "claude-opus-4-5"

llmswitch/core/__init__.py

@@ -0,0 +1,7 @@
+"""Public client classes."""
+from __future__ import annotations
+
+from .async_client import AsyncLLMSwitch
+from .sync_client import LLMSwitch
+
+__all__ = ["LLMSwitch", "AsyncLLMSwitch"]

llmswitch/core/async_client.py

@@ -0,0 +1,132 @@
+"""
+core.async_client
+
+Asynchronous ``AsyncLLMSwitch`` client. Chat completions use each provider's
+native async client. Embedding providers are synchronous, so they run in a
+worker thread to keep the event loop free.
+
+Native async chat is available for azure_openai, azure_foundry, openai and
+anthropic. vertexai is sync-only in this release.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from ..errors import LLMSwitchError
+from .common import (
+    build_config,
+    map_chat_error,
+    map_embedding_error,
+    normalize_embedding_input,
+    provider_kwargs,
+    resolve_model,
+    validate_messages,
+)
+from .registry import ASYNC_CHAT_PROVIDER_REGISTRY, EMBEDDING_PROVIDER_REGISTRY
+
+logger = logging.getLogger(__name__)
+
+
+class _AsyncChatCompletions:
+    def __init__(self, client: "AsyncLLMSwitch") -> None:
+        self._client = client
+
+    async def create(self, messages: list[dict[str, Any]], stream: bool = False, **kwargs: Any) -> Any:
+        """Async counterpart of ``LLMSwitch.chat.completions.create``.
+
+        With ``stream=True`` the awaited result is an async generator of chunks.
+        """
+        config = self._client.config
+        validate_messages(messages)
+        provider_cls = ASYNC_CHAT_PROVIDER_REGISTRY.get(config.provider)
+        if provider_cls is None:
+            raise LLMSwitchError(f"Unsupported provider for async chat completion: {config.provider}",
+                                 provider=config.provider)
+        if stream:
+            kwargs.setdefault("stream_options", {"include_usage": True})
+        resolve_model(config, kwargs)
+        provider = self._client._provider(provider_cls)
+        try:
+            return await provider.create(messages=messages, stream=stream, **kwargs)
+        except Exception as exc:
+            raise map_chat_error(exc, config) from exc
+
+    async def parse(self, messages: list[dict[str, Any]], response_format: Any, **kwargs: Any) -> Any:
+        """Async structured output. See ``LLMSwitch.chat.completions.parse``."""
+        return await self.create(messages, stream=False, response_format=response_format, **kwargs)
+
+
+class _AsyncEmbeddings:
+    def __init__(self, client: "AsyncLLMSwitch") -> None:
+        self._client = client
+
+    async def create(self, input: str | list[str], **kwargs: Any) -> Any:  # noqa: A002
+        """Create embeddings without blocking the event loop."""
+        config = self._client.config
+        inputs = normalize_embedding_input(input)
+        provider_cls = EMBEDDING_PROVIDER_REGISTRY.get(config.provider)
+        if provider_cls is None:
+            raise LLMSwitchError(f"Unsupported provider for embeddings: {config.provider}",
+                                 provider=config.provider)
+        resolve_model(config, kwargs)
+        provider = self._client._provider(provider_cls)
+        try:
+            return await asyncio.to_thread(provider.create, inputs, **kwargs)
+        except Exception as exc:
+            raise map_embedding_error(exc, config) from exc
+
+
+class AsyncLLMSwitch:
+    """
+    Unified asynchronous client, mirroring ``LLMSwitch``.
+
+    Usage::
+
+        client = AsyncLLMSwitch(provider="openai", api_key="...", model="gpt-4o")
+        reply = await client.chat.completions.create(messages=[{"role": "user", "content": "Hi"}])
+        vectors = await client.embeddings.create(["hello", "world"])
+        await client.aclose()
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self.config = build_config(kwargs)
+        self._providers: dict[type, Any] = {}
+        self.chat = _AsyncChat(self)
+        self.embeddings = _AsyncEmbeddings(self)
+
+    def __repr__(self) -> str:
+        return f"AsyncLLMSwitch(provider={self.config.provider!r}, model={self.config.model!r})"
+
+    async def __aenter__(self) -> "AsyncLLMSwitch":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.aclose()
+
+    def _provider(self, provider_cls: type) -> Any:
+        """Return the cached provider client for ``provider_cls``, building it on first use."""
+        provider = self._providers.get(provider_cls)
+        if provider is None:
+            provider = provider_cls(**provider_kwargs(self.config))
+            self._providers[provider_cls] = provider
+        return provider
+
+    async def aclose(self) -> None:
+        """Close the provider clients this client created, awaiting async close hooks."""
+        for provider in self._providers.values():
+            close_fn = getattr(provider, "aclose", None) or getattr(provider, "close", None)
+            if close_fn is None:
+                close_fn = getattr(getattr(provider, "client", None), "aclose", None) or getattr(
+                    getattr(provider, "client", None), "close", None)
+            if callable(close_fn):
+                result = close_fn()
+                if asyncio.iscoroutine(result):
+                    await result
+        self._providers.clear()
+
+
+class _AsyncChat:
+    def __init__(self, client: AsyncLLMSwitch) -> None:
+        self.completions = _AsyncChatCompletions(client)

llmswitch/core/common.py

@@ -0,0 +1,122 @@
+"""
+core.common
+
+Helpers shared by the synchronous and asynchronous clients: configuration
+loading, model resolution, input validation, provider construction and error
+translation.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from ..config import CONFIG_REGISTRY
+from ..constants import DEFAULT_ANTHROPIC_MODEL
+from ..errors import (
+    APIConnectionError,
+    AuthenticationError,
+    ChatCompletionError,
+    ConfigurationError,
+    EmbeddingGenerationError,
+    LLMSwitchError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def build_config(kwargs: dict[str, Any]) -> Any:
+    """Validate constructor kwargs against the provider's configuration model."""
+    provider = kwargs.get("provider")
+    if not isinstance(provider, str):
+        raise LLMSwitchError(f"Unsupported provider config: {provider}")
+    config_cls = CONFIG_REGISTRY.get(provider)
+    if config_cls is None:
+        raise LLMSwitchError(f"Unsupported provider config: {provider}")
+    try:
+        return config_cls(**kwargs)
+    except ValueError as exc:
+        if hasattr(exc, "errors"):
+            errors = exc.errors()
+            reasons = "; ".join(str(error["msg"]).removeprefix("Value error, ") for error in errors)
+            raise ConfigurationError(f"Invalid switch configuration: {reasons}", details=errors) from exc
+        raise ConfigurationError(f"Invalid switch configuration: {exc}", details=str(exc)) from exc
+
+
+def resolve_model(config: Any, kwargs: dict[str, Any]) -> Optional[str]:
+    """Pick the effective model and write it into ``kwargs``.
+
+    A configured deployment wins over everything. Otherwise a per-call ``model``
+    overrides the configured model. Anthropic falls back to a default model.
+    """
+    deployment_name = getattr(config, "deployment_name", None)
+    model = deployment_name or kwargs.get("model") or getattr(config, "model", None)
+    if model is None and config.provider == "anthropic":
+        model = DEFAULT_ANTHROPIC_MODEL
+    if model is not None:
+        kwargs["model"] = model
+    return model
+
+
+def validate_messages(messages: Any) -> None:
+    if not isinstance(messages, list) or not messages:
+        raise ValueError("messages must be a non-empty list of message dicts")
+    if not all(isinstance(message, dict) for message in messages):
+        raise ValueError("every message must be a dict")
+
+
+def normalize_embedding_input(input: Any) -> list[str]:  # noqa: A002
+    inputs = [input] if isinstance(input, str) else list(input or [])
+    if not inputs:
+        raise ValueError("Embedding input must contain at least one string")
+    if not all(isinstance(text, str) and text for text in inputs):
+        raise ValueError("Embedding input must be a non-empty string or a list of non-empty strings")
+    return inputs
+
+
+def provider_kwargs(config: Any) -> dict[str, Any]:
+    """Union of constructor kwargs; each provider reads the ones it understands."""
+    endpoint = getattr(config, "endpoint", None)
+    deployment_name = getattr(config, "deployment_name", None)
+    return {
+        "api_key": getattr(config, "api_key", None),
+        "endpoint": endpoint,
+        "azure_endpoint": endpoint,
+        "api_version": getattr(config, "api_version", None),
+        "deployment_name": deployment_name,
+        "azure_deployment": deployment_name,
+        "model": getattr(config, "model", None),
+        "location": getattr(config, "location", None),
+        "credentials_path": getattr(config, "credentials_path", None),
+        "scopes": getattr(config, "scopes", None),
+        "organization": getattr(config, "organization", None),
+        "project": getattr(config, "project", None),
+        "timeout": getattr(config, "timeout", None),
+        "enable_prompt_caching": getattr(config, "enable_prompt_caching", None),
+        "client_options": getattr(config, "client_options", None),
+    }
+
+
+def map_chat_error(exc: Exception, config: Any) -> LLMSwitchError:
+    """Translate a provider exception into the public error hierarchy."""
+    if isinstance(exc, LLMSwitchError):
+        return exc
+    if isinstance(exc, ValueError):
+        return ChatCompletionError(str(exc), status_code=400, provider=config.provider)
+    if isinstance(exc, ConnectionError):
+        return APIConnectionError(config.endpoint, provider=config.provider)
+    if isinstance(exc, PermissionError):
+        return AuthenticationError(provider=config.provider)
+    return ChatCompletionError(str(exc), status_code=getattr(exc, "status_code", 500), provider=config.provider)
+
+
+def map_embedding_error(exc: Exception, config: Any) -> LLMSwitchError:
+    if isinstance(exc, LLMSwitchError):
+        return exc
+    if isinstance(exc, ValueError):
+        return EmbeddingGenerationError(str(exc), status_code=400, provider=config.provider)
+    if isinstance(exc, ConnectionError):
+        return APIConnectionError(config.endpoint, provider=config.provider)
+    if isinstance(exc, PermissionError):
+        return AuthenticationError(provider=config.provider)
+    return EmbeddingGenerationError(str(exc), status_code=getattr(exc, "status_code", 500),
+                                    provider=config.provider)

llmswitch/core/registry.py

@@ -0,0 +1,66 @@
+"""
+core.registry
+
+Maps provider names to their chat, async chat and embedding provider classes.
+Each provider SDK is an optional extra, so every import is guarded: a missing
+SDK leaves that provider out of the registry instead of breaking the package.
+"""
+from __future__ import annotations
+
+CHAT_PROVIDER_REGISTRY: dict[str, type] = {}
+ASYNC_CHAT_PROVIDER_REGISTRY: dict[str, type] = {}
+EMBEDDING_PROVIDER_REGISTRY: dict[str, type] = {}
+
+try:
+    from ..providers.openai_provider import (
+        AsyncOpenAIChatProvider,
+        OpenAIChatProvider,
+        OpenAIEmbeddingProvider,
+    )
+
+    CHAT_PROVIDER_REGISTRY["openai"] = OpenAIChatProvider
+    ASYNC_CHAT_PROVIDER_REGISTRY["openai"] = AsyncOpenAIChatProvider
+    EMBEDDING_PROVIDER_REGISTRY["openai"] = OpenAIEmbeddingProvider
+except ImportError:
+    pass
+
+try:
+    from ..providers.azureopenai_provider import (
+        AsyncAzureOpenAIChatProvider,
+        AzureOpenAIChatProvider,
+        AzureOpenAIEmbeddingProvider,
+    )
+
+    CHAT_PROVIDER_REGISTRY["azure_openai"] = AzureOpenAIChatProvider
+    ASYNC_CHAT_PROVIDER_REGISTRY["azure_openai"] = AsyncAzureOpenAIChatProvider
+    EMBEDDING_PROVIDER_REGISTRY["azure_openai"] = AzureOpenAIEmbeddingProvider
+except ImportError:
+    pass
+
+try:
+    from ..providers.azurefoundry_provider import (
+        AsyncAzureFoundryChatProvider,
+        AzureFoundryChatProvider,
+        AzureFoundryEmbeddingProvider,
+    )
+
+    CHAT_PROVIDER_REGISTRY["azure_foundry"] = AzureFoundryChatProvider
+    ASYNC_CHAT_PROVIDER_REGISTRY["azure_foundry"] = AsyncAzureFoundryChatProvider
+    EMBEDDING_PROVIDER_REGISTRY["azure_foundry"] = AzureFoundryEmbeddingProvider
+except ImportError:
+    pass
+
+try:
+    from ..providers.anthropic_provider import AnthropicChatProvider, AsyncAnthropicChatProvider
+
+    CHAT_PROVIDER_REGISTRY["anthropic"] = AnthropicChatProvider
+    ASYNC_CHAT_PROVIDER_REGISTRY["anthropic"] = AsyncAnthropicChatProvider
+except ImportError:
+    pass
+
+try:
+    from ..providers.vertexai_provider import VertexAIChatProvider
+
+    CHAT_PROVIDER_REGISTRY["vertexai"] = VertexAIChatProvider
+except ImportError:
+    pass

llmswitch/core/sync_client.py

@@ -0,0 +1,131 @@
+"""
+core.sync_client
+
+Synchronous ``LLMSwitch`` client with an OpenAI-style ``chat.completions`` and
+``embeddings`` surface.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..errors import LLMSwitchError
+from .common import (
+    build_config,
+    map_chat_error,
+    map_embedding_error,
+    normalize_embedding_input,
+    provider_kwargs,
+    resolve_model,
+    validate_messages,
+)
+from .registry import CHAT_PROVIDER_REGISTRY, EMBEDDING_PROVIDER_REGISTRY
+
+logger = logging.getLogger(__name__)
+
+
+class _ChatCompletions:
+    def __init__(self, client: "LLMSwitch") -> None:
+        self._client = client
+
+    def create(self, messages: list[dict[str, Any]], stream: bool = False, **kwargs: Any) -> Any:
+        """
+        Create a chat completion.
+
+        Args:
+            messages: Message dicts. ``content`` may be a string or a list of content parts.
+            stream: Return a generator of ``ChatCompletionChunk`` instead of a ``ChatCompletion``.
+            **kwargs: Pass-through provider parameters (``response_format``, ``tools``,
+                ``temperature``, ``max_tokens``, ...). ``model`` overrides the configured model
+                unless a deployment name is configured.
+        """
+        config = self._client.config
+        validate_messages(messages)
+        provider_cls = CHAT_PROVIDER_REGISTRY.get(config.provider)
+        if provider_cls is None:
+            raise LLMSwitchError(f"Unsupported provider for chat completion: {config.provider}",
+                                 provider=config.provider)
+        if stream:
+            kwargs.setdefault("stream_options", {"include_usage": True})
+        resolve_model(config, kwargs)
+        provider = self._client._provider(provider_cls)
+        try:
+            return provider.create(messages=messages, stream=stream, **kwargs)
+        except Exception as exc:
+            raise map_chat_error(exc, config) from exc
+
+    def parse(self, messages: list[dict[str, Any]], response_format: Any, **kwargs: Any) -> Any:
+        """
+        Structured output. Pass a Pydantic model class as ``response_format``; the parsed
+        instance is available on ``choice.message.parsed``. Always non-streaming.
+        """
+        return self.create(messages, stream=False, response_format=response_format, **kwargs)
+
+
+class _Embeddings:
+    def __init__(self, client: "LLMSwitch") -> None:
+        self._client = client
+
+    def create(self, input: str | list[str], **kwargs: Any) -> Any:  # noqa: A002
+        """Create embeddings for one string or a list of strings."""
+        config = self._client.config
+        inputs = normalize_embedding_input(input)
+        provider_cls = EMBEDDING_PROVIDER_REGISTRY.get(config.provider)
+        if provider_cls is None:
+            raise LLMSwitchError(f"Unsupported provider for embeddings: {config.provider}",
+                                 provider=config.provider)
+        resolve_model(config, kwargs)
+        provider = self._client._provider(provider_cls)
+        try:
+            return provider.create(inputs, **kwargs)
+        except Exception as exc:
+            raise map_embedding_error(exc, config) from exc
+
+
+class LLMSwitch:
+    """
+    Unified synchronous client. Construct it with a ``provider`` name plus that
+    provider's credentials and settings; the same call shape works across providers.
+
+    Usage::
+
+        client = LLMSwitch(provider="openai", api_key="...", model="gpt-4o")
+        reply = client.chat.completions.create(messages=[{"role": "user", "content": "Hi"}])
+        vectors = client.embeddings.create(["hello", "world"])
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self.config = build_config(kwargs)
+        self._providers: dict[type, Any] = {}
+        self.chat = _Chat(self)
+        self.embeddings = _Embeddings(self)
+
+    def __repr__(self) -> str:
+        return f"LLMSwitch(provider={self.config.provider!r}, model={self.config.model!r})"
+
+    def __enter__(self) -> "LLMSwitch":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    def _provider(self, provider_cls: type) -> Any:
+        """Return the cached provider client for ``provider_cls``, building it on first use."""
+        provider = self._providers.get(provider_cls)
+        if provider is None:
+            provider = provider_cls(**provider_kwargs(self.config))
+            self._providers[provider_cls] = provider
+        return provider
+
+    def close(self) -> None:
+        """Close the provider clients this client created."""
+        for provider in self._providers.values():
+            close_fn = getattr(provider, "close", None) or getattr(getattr(provider, "client", None), "close", None)
+            if callable(close_fn):
+                close_fn()
+        self._providers.clear()
+
+
+class _Chat:
+    def __init__(self, client: LLMSwitch) -> None:
+        self.completions = _ChatCompletions(client)