mirascope 2.0.0a2__py3-none-any.whl → 2.0.0a3__py3-none-any.whl

mirascope/llm/{clients/anthropic/clients.py → providers/anthropic/provider.py}

@@ -1,10 +1,6 @@
 """Anthropic client implementation."""
 
-import os
 from collections.abc import Sequence
-from contextvars import ContextVar
-from functools import lru_cache
-from typing import overload
 from typing_extensions import Unpack
 
 from anthropic import Anthropic, AsyncAnthropic
@@ -32,60 +28,16 @@ from ...tools import (
     Tool,
     Toolkit,
 )
-from ..base import BaseClient, Params
+from ..base import BaseProvider, Params
 from . import _utils
-from .model_ids import AnthropicModelId
+from .model_id import AnthropicModelId, model_name
 
-ANTHROPIC_CLIENT_CONTEXT: ContextVar["AnthropicClient | None"] = ContextVar(
-    "ANTHROPIC_CLIENT_CONTEXT", default=None
-)
-
-
-@lru_cache(maxsize=256)
-def _anthropic_singleton(
-    api_key: str | None, base_url: str | None
-) -> "AnthropicClient":
-    """Return a cached Anthropic client instance for the given parameters."""
-    return AnthropicClient(api_key=api_key, base_url=base_url)
-
-
-def client(
-    *, api_key: str | None = None, base_url: str | None = None
-) -> "AnthropicClient":
-    """Create or retrieve an Anthropic client with the given parameters.
-
-    If a client has already been created with these parameters, it will be
-    retrieved from cache and returned.
-
-    Args:
-        api_key: API key for authentication. If None, uses ANTHROPIC_API_KEY env var.
-        base_url: Base URL for the API. If None, uses ANTHROPIC_BASE_URL env var.
 
-    Returns:
-        An Anthropic client instance.
-    """
-    api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
-    base_url = base_url or os.getenv("ANTHROPIC_BASE_URL")
-    return _anthropic_singleton(api_key, base_url)
-
-
-def get_client() -> "AnthropicClient":
-    """Retrieve the current Anthropic client from context, or a global default.
-
-    Returns:
-        The current Anthropic client from context if available, otherwise
-        a global default client based on environment variables.
-    """
-    ctx_client = ANTHROPIC_CLIENT_CONTEXT.get()
-    return ctx_client or client()
-
-
-class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
+class AnthropicProvider(BaseProvider[Anthropic]):
     """The client for the Anthropic LLM model."""
 
-    @property
-    def _context_var(self) -> ContextVar["AnthropicClient | None"]:
-        return ANTHROPIC_CLIENT_CONTEXT
+    id = "anthropic"
+    default_scope = "anthropic/"
 
     def __init__(
         self, *, api_key: str | None = None, base_url: str | None = None
@@ -94,46 +46,7 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
         self.client = Anthropic(api_key=api_key, base_url=base_url)
         self.async_client = AsyncAnthropic(api_key=api_key, base_url=base_url)
 
-    @overload
-    def call(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: None = None,
-        **params: Unpack[Params],
-    ) -> Response:
-        """Generate an `llm.Response` without a response format."""
-        ...
-
-    @overload
-    def call(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT],
-        **params: Unpack[Params],
-    ) -> Response[FormattableT]:
-        """Generate an `llm.Response` with a response format."""
-        ...
-
-    @overload
-    def call(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
-        **params: Unpack[Params],
-    ) -> Response | Response[FormattableT]:
-        """Generate an `llm.Response` with an optional response format."""
-        ...
-
-    def call(
+    def _call(
         self,
         *,
         model_id: AnthropicModelId,
@@ -170,8 +83,9 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
 
         return Response(
             raw=anthropic_response,
-            provider="anthropic",
+            provider_id="anthropic",
             model_id=model_id,
+            provider_model_name=model_name(model_id),
             params=params,
             tools=tools,
             input_messages=input_messages,
@@ -180,55 +94,7 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
             format=format,
         )
 
-    @overload
-    def context_call(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: None = None,
-        **params: Unpack[Params],
-    ) -> ContextResponse[DepsT, None]:
-        """Generate an `llm.ContextResponse` without a response format."""
-        ...
-
-    @overload
-    def context_call(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT] | Format[FormattableT],
-        **params: Unpack[Params],
-    ) -> ContextResponse[DepsT, FormattableT]:
-        """Generate an `llm.ContextResponse` with a response format."""
-        ...
-
-    @overload
-    def context_call(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
-        **params: Unpack[Params],
-    ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
-        """Generate an `llm.ContextResponse` with an optional response format."""
-        ...
-
-    def context_call(
+    def _context_call(
         self,
         *,
         ctx: Context[DepsT],
@@ -269,8 +135,9 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
 
         return ContextResponse(
             raw=anthropic_response,
-            provider="anthropic",
+            provider_id="anthropic",
             model_id=model_id,
+            provider_model_name=model_name(model_id),
             params=params,
             tools=tools,
             input_messages=input_messages,
@@ -279,46 +146,7 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
             format=format,
         )
 
-    @overload
-    async def call_async(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: None = None,
-        **params: Unpack[Params],
-    ) -> AsyncResponse:
-        """Generate an `llm.AsyncResponse` without a response format."""
-        ...
-
-    @overload
-    async def call_async(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT],
-        **params: Unpack[Params],
-    ) -> AsyncResponse[FormattableT]:
-        """Generate an `llm.AsyncResponse` with a response format."""
-        ...
-
-    @overload
-    async def call_async(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
-        **params: Unpack[Params],
-    ) -> AsyncResponse | AsyncResponse[FormattableT]:
-        """Generate an `llm.AsyncResponse` with an optional response format."""
-        ...
-
-    async def call_async(
+    async def _call_async(
         self,
         *,
         model_id: AnthropicModelId,
@@ -355,8 +183,9 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
 
         return AsyncResponse(
             raw=anthropic_response,
-            provider="anthropic",
+            provider_id="anthropic",
             model_id=model_id,
+            provider_model_name=model_name(model_id),
             params=params,
             tools=tools,
             input_messages=input_messages,
@@ -365,55 +194,7 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
             format=format,
         )
 
-    @overload
-    async def context_call_async(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: None = None,
-        **params: Unpack[Params],
-    ) -> AsyncContextResponse[DepsT, None]:
-        """Generate an `llm.AsyncContextResponse` without a response format."""
-        ...
-
-    @overload
-    async def context_call_async(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT] | Format[FormattableT],
-        **params: Unpack[Params],
-    ) -> AsyncContextResponse[DepsT, FormattableT]:
-        """Generate an `llm.AsyncContextResponse` with a response format."""
-        ...
-
-    @overload
-    async def context_call_async(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
-        **params: Unpack[Params],
-    ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
-        """Generate an `llm.AsyncContextResponse` with an optional response format."""
-        ...
-
-    async def context_call_async(
+    async def _context_call_async(
         self,
         *,
         ctx: Context[DepsT],
@@ -454,8 +235,9 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
 
         return AsyncContextResponse(
             raw=anthropic_response,
-            provider="anthropic",
+            provider_id="anthropic",
             model_id=model_id,
+            provider_model_name=model_name(model_id),
             params=params,
             tools=tools,
             input_messages=input_messages,
@@ -464,46 +246,7 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
             format=format,
         )
 
-    @overload
-    def stream(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: None = None,
-        **params: Unpack[Params],
-    ) -> StreamResponse:
-        """Stream an `llm.StreamResponse` without a response format."""
-        ...
-
-    @overload
-    def stream(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT],
-        **params: Unpack[Params],
-    ) -> StreamResponse[FormattableT]:
-        """Stream an `llm.StreamResponse` with a response format."""
-        ...
-
-    @overload
-    def stream(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
-        **params: Unpack[Params],
-    ) -> StreamResponse | StreamResponse[FormattableT]:
-        """Stream an `llm.StreamResponse` with an optional response format."""
-        ...
-
-    def stream(
+    def _stream(
         self,
         *,
         model_id: AnthropicModelId,
@@ -537,8 +280,9 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
         chunk_iterator = _utils.decode_stream(anthropic_stream)
 
         return StreamResponse(
-            provider="anthropic",
+            provider_id="anthropic",
             model_id=model_id,
+            provider_model_name=model_name(model_id),
             params=params,
             tools=tools,
             input_messages=input_messages,
@@ -546,55 +290,7 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
             format=format,
         )
 
-    @overload
-    def context_stream(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: None = None,
-        **params: Unpack[Params],
-    ) -> ContextStreamResponse[DepsT]:
-        """Stream an `llm.ContextStreamResponse` without a response format."""
-        ...
-
-    @overload
-    def context_stream(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT] | Format[FormattableT],
-        **params: Unpack[Params],
-    ) -> ContextStreamResponse[DepsT, FormattableT]:
-        """Stream an `llm.ContextStreamResponse` with a response format."""
-        ...
-
-    @overload
-    def context_stream(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
-        **params: Unpack[Params],
-    ) -> ContextStreamResponse[DepsT] | ContextStreamResponse[DepsT, FormattableT]:
-        """Stream an `llm.ContextStreamResponse` with an optional response format."""
-        ...
-
-    def context_stream(
+    def _context_stream(
         self,
         *,
         ctx: Context[DepsT],
@@ -632,8 +328,9 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
         chunk_iterator = _utils.decode_stream(anthropic_stream)
 
         return ContextStreamResponse(
-            provider="anthropic",
+            provider_id="anthropic",
             model_id=model_id,
+            provider_model_name=model_name(model_id),
             params=params,
             tools=tools,
             input_messages=input_messages,
@@ -641,46 +338,7 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
             format=format,
         )
 
-    @overload
-    async def stream_async(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: None = None,
-        **params: Unpack[Params],
-    ) -> AsyncStreamResponse:
-        """Stream an `llm.AsyncStreamResponse` without a response format."""
-        ...
-
-    @overload
-    async def stream_async(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT],
-        **params: Unpack[Params],
-    ) -> AsyncStreamResponse[FormattableT]:
-        """Stream an `llm.AsyncStreamResponse` with a response format."""
-        ...
-
-    @overload
-    async def stream_async(
-        self,
-        *,
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
-        **params: Unpack[Params],
-    ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
-        """Stream an `llm.AsyncStreamResponse` with an optional response format."""
-        ...
-
-    async def stream_async(
+    async def _stream_async(
         self,
         *,
         model_id: AnthropicModelId,
@@ -714,8 +372,9 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
         chunk_iterator = _utils.decode_async_stream(anthropic_stream)
 
         return AsyncStreamResponse(
-            provider="anthropic",
+            provider_id="anthropic",
             model_id=model_id,
+            provider_model_name=model_name(model_id),
             params=params,
             tools=tools,
             input_messages=input_messages,
@@ -723,55 +382,7 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
             format=format,
         )
 
-    @overload
-    async def context_stream_async(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: None = None,
-        **params: Unpack[Params],
-    ) -> AsyncContextStreamResponse[DepsT]:
-        """Stream an `llm.AsyncContextStreamResponse` without a response format."""
-        ...
-
-    @overload
-    async def context_stream_async(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT] | Format[FormattableT],
-        **params: Unpack[Params],
-    ) -> AsyncContextStreamResponse[DepsT, FormattableT]:
-        """Stream an `llm.AsyncContextStreamResponse` with a response format."""
-        ...
-
-    @overload
-    async def context_stream_async(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: AnthropicModelId,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
-        **params: Unpack[Params],
-    ) -> AsyncContextStreamResponse | AsyncContextStreamResponse[DepsT, FormattableT]:
-        """Stream an `llm.AsyncContextStreamResponse` with an optional response format."""
-        ...
-
-    async def context_stream_async(
+    async def _context_stream_async(
         self,
         *,
         ctx: Context[DepsT],
@@ -782,7 +393,10 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
         | None = None,
         format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
-    ) -> AsyncContextStreamResponse | AsyncContextStreamResponse[DepsT, FormattableT]:
+    ) -> (
+        AsyncContextStreamResponse[DepsT]
+        | AsyncContextStreamResponse[DepsT, FormattableT]
+    ):
         """Generate an `llm.AsyncContextStreamResponse` by asynchronously streaming from the Anthropic Messages API.
 
         Args:
@@ -809,8 +423,9 @@ class AnthropicClient(BaseClient[AnthropicModelId, Anthropic]):
         chunk_iterator = _utils.decode_async_stream(anthropic_stream)
 
         return AsyncContextStreamResponse(
-            provider="anthropic",
+            provider_id="anthropic",
             model_id=model_id,
+            provider_model_name=model_name(model_id),
             params=params,
             tools=tools,
             input_messages=input_messages,

mirascope/llm/{clients → providers}/base/__init__.py

@@ -1,15 +1,15 @@
 """Base client interfaces and types."""
 
 from . import _utils
-from .client import BaseClient, ClientT
+from .base_provider import BaseProvider, Provider
 from .kwargs import BaseKwargs, KwargsT
 from .params import Params
 
 __all__ = [
-    "BaseClient",
     "BaseKwargs",
-    "ClientT",
+    "BaseProvider",
     "KwargsT",
     "Params",
+    "Provider",
     "_utils",
 ]

mirascope/llm/{clients → providers}/base/_utils.py

@@ -5,10 +5,11 @@ from typing import TYPE_CHECKING, TypeAlias, get_type_hints
 
 from ...content import Text
 from ...messages import AssistantMessage, Message, SystemMessage, UserMessage
+from ..provider_id import ProviderId
 from .params import Params
 
 if TYPE_CHECKING:
-    from ..providers import ModelId, Provider
+    from ..model_id import ModelId
 
 logger = logging.getLogger(__name__)
 
@@ -61,8 +62,8 @@ def extract_system_message(
     This is intended for use in clients where the system message is not included in the
     input messages, but passed as an additional argument or metadata.
     """
-    system_message_content = None
-    remaining_messages = []
+    system_message_content: SystemMessageContent = None
+    remaining_messages: list[UserMessage | AssistantMessage] = []
 
     for i, message in enumerate(messages):
         if message.role == "system":
@@ -138,10 +139,10 @@ class SafeParamsAccessor:
         self,
         param_name: str,
         param_value: object,
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId | None" = None,
     ) -> None:
-        unsupported_by = f"provider: {provider}"
+        unsupported_by = f"provider: {provider_id}"
         if model_id:
             unsupported_by += f" with model_id: {model_id}"
         logger.warning(
@@ -159,7 +160,7 @@ class SafeParamsAccessor:
 def ensure_all_params_accessed(
     *,
     params: Params,
-    provider: "Provider",
+    provider_id: "ProviderId",
     unsupported_params: list[str] | None = None,
 ) -> Generator[SafeParamsAccessor, None, None]:
     """Context manager that ensures all parameters are accessed.
@@ -185,7 +186,9 @@ def ensure_all_params_accessed(
     unsupported_params = unsupported_params or []
     for unsupported in unsupported_params:
         if (val := params.get(unsupported)) is not None:
-            accessor.emit_warning_for_unused_param(unsupported, val, provider=provider)
+            accessor.emit_warning_for_unused_param(
+                unsupported, val, provider_id=provider_id
+            )
     try:
         yield accessor
     finally: