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

mirascope/api/client.py

@@ -0,0 +1,255 @@
+"""Client interfaces and factory for Mirascope SDK.
+
+This module provides interfaces and factory functions for creating Mirascope clients
+that support both the Fern-generated API client and OpenTelemetry exporters.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import weakref
+from collections.abc import Callable
+from functools import lru_cache
+from typing import ParamSpec, TypeAlias, TypeVar
+
+import httpx
+
+from ._generated.client import (
+    AsyncMirascope as _BaseAsyncMirascope,
+    Mirascope as _BaseMirascope,
+)
+from .settings import get_settings
+
+ApiKey: TypeAlias = str
+BaseUrl: TypeAlias = str
+Token: TypeAlias = str | Callable[[], str] | None
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+logger = logging.getLogger(__name__)
+
+
+class Mirascope(_BaseMirascope):
+    """Enhanced Mirascope client with error handling.
+
+    This client automatically handles API errors and provides fallback behavior
+    for non-critical failures while preserving important exceptions like NotFoundError.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        token: Token = None,
+        timeout: float | None = None,
+        follow_redirects: bool | None = True,
+        httpx_client: httpx.Client | None = None,
+    ) -> None:
+        """Initialize the enhanced Mirascope client."""
+        try:
+            settings = get_settings()
+            self.api_key = api_key or settings.api_key
+            if not self.api_key:
+                raise ValueError("`Mirascope` client requires `api_key`.")
+
+            self.base_url = base_url or settings.base_url
+
+            headers = {"Authorization": f"Bearer {self.api_key}"}
+            if httpx_client:
+                if hasattr(httpx_client, "headers"):
+                    httpx_client.headers.update(headers)
+            else:
+                httpx_client = httpx.Client(
+                    headers=headers,
+                    timeout=timeout or 30.0,
+                    follow_redirects=follow_redirects
+                    if follow_redirects is not None
+                    else True,
+                )
+
+            super().__init__(
+                base_url=self.base_url,
+                timeout=timeout,
+                follow_redirects=follow_redirects,
+                httpx_client=httpx_client,
+            )
+
+        except Exception as e:
+            logger.error("Failed to initialize Mirascope client: %s", e)
+            raise RuntimeError(f"Client initialization failed: {e}") from e
+
+    def close(self) -> None:
+        """Close the underlying synchronous HTTP client."""
+        wrapper_client = getattr(self._client_wrapper, "httpx_client", None)
+        underlying_httpx_client = getattr(wrapper_client, "httpx_client", None)
+        if underlying_httpx_client is not None:
+            underlying_httpx_client.close()
+
+
+class AsyncMirascope(_BaseAsyncMirascope):
+    """Enhanced async Mirascope client with error handling.
+
+    This client automatically handles API errors and provides fallback behavior
+    for non-critical failures while preserving important exceptions like NotFoundError.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        token: Token = None,
+        timeout: float | None = None,
+        follow_redirects: bool | None = True,
+        httpx_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """Initialize the enhanced async Mirascope client."""
+        try:
+            settings = get_settings()
+            self.api_key = api_key or settings.api_key
+            if not self.api_key:
+                raise ValueError("`AsyncMirascope` client requires `api_key`.")
+
+            self.base_url = base_url or settings.base_url
+
+            headers = {"Authorization": f"Bearer {self.api_key}"}
+            if httpx_client:
+                if hasattr(httpx_client, "headers"):
+                    httpx_client.headers.update(headers)
+            else:
+                httpx_client = httpx.AsyncClient(
+                    headers=headers,
+                    timeout=timeout or 30.0,
+                    follow_redirects=follow_redirects
+                    if follow_redirects is not None
+                    else True,
+                )
+
+            super().__init__(
+                base_url=self.base_url,
+                timeout=timeout,
+                follow_redirects=follow_redirects,
+                httpx_client=httpx_client,
+            )
+
+        except Exception as e:
+            logger.error("Failed to initialize AsyncMirascope client: %s", e)
+            raise RuntimeError(f"Async client initialization failed: {e}") from e
+
+    async def aclose(self) -> None:
+        """Close the underlying asynchronous HTTP client."""
+        wrapper_client = getattr(self._client_wrapper, "httpx_client", None)
+        underlying_httpx_client = getattr(wrapper_client, "httpx_client", None)
+        if underlying_httpx_client is not None:
+            await underlying_httpx_client.aclose()
+
+
+@lru_cache(maxsize=256)
+def _sync_singleton(api_key: str | None, base_url: str | None) -> Mirascope:
+    """Return the process-wide synchronous client, creating one if none yet exists"""
+    try:
+        logger.debug("Creating sync client with api_key=*****, base_url=%s", base_url)
+        return Mirascope(api_key=api_key, base_url=base_url)
+    except Exception as e:
+        logger.error("Failed to create singleton Mirascope client: %s", e)
+        raise RuntimeError(f"Failed to create cached client: {e}") from e
+
+
+def get_sync_client(
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> Mirascope:
+    """Get or create a cached synchronous client.
+
+    Args:
+        api_key: API key for authentication
+        base_url: Base URL for the API
+
+    Returns:
+        Cached Mirascope client instance
+    """
+    settings = get_settings()
+
+    return _sync_singleton(
+        api_key or settings.api_key,
+        base_url or settings.base_url,
+    )
+
+
+@lru_cache(maxsize=256)
+def _async_singleton(
+    _loop_id_for_cache: int, api_key: str | None, base_url: str | None
+) -> AsyncMirascope:
+    """Return the loop-specific asynchronous client, creating one if none yet exists"""
+    try:
+        logger.debug("Creating async client with api_key=*****, base_url=%s", base_url)
+        loop = asyncio.get_running_loop()
+        client = AsyncMirascope(api_key=api_key, base_url=base_url)
+        weakref.finalize(loop, _async_singleton.cache_clear)
+        return client
+    except Exception as e:
+        logger.error("Failed to create singleton AsyncMirascope client: %s", e)
+        raise RuntimeError(f"Failed to create cached async client: {e}") from e
+
+
+def get_async_client(
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> AsyncMirascope:
+    """Get or create a cached asynchronous client.
+
+    Args:
+        api_key: API key for authentication
+        base_url: Base URL for the API
+
+    Returns:
+        Cached AsyncMirascope client instance
+    """
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError as exc:
+        raise RuntimeError(
+            "get_async_client() must be called from within an active event loop."
+        ) from exc
+
+    settings = get_settings()
+
+    return _async_singleton(
+        id(loop),
+        api_key or settings.api_key,
+        base_url or settings.base_url,
+    )
+
+
+def create_export_client(
+    *,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    timeout: float = 30.0,
+    httpx_client: httpx.Client | None = None,
+) -> Mirascope:
+    """Create a client suitable for OpenTelemetry export.
+
+    Args:
+        base_url: Base URL for the API
+        api_key: API key for authentication
+        timeout: Request timeout in seconds
+        httpx_client: Optional custom httpx client
+
+    Returns:
+        Mirascope client configured for export use
+    """
+    return Mirascope(
+        base_url=base_url,
+        api_key=api_key,
+        timeout=timeout,
+        httpx_client=httpx_client,
+    )
+
+
+def close_cached_clients() -> None:
+    """Close all cached client instances."""
+    _sync_singleton.cache_clear()
+    _async_singleton.cache_clear()

mirascope/api/settings.py

@@ -0,0 +1,81 @@
+"""Settings and configuration for Mirascope SDK."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from functools import cache
+from typing import Any
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Global settings for Mirascope SDK."""
+
+    base_url: str = Field(default="https://v2.mirascope.com")
+    api_key: str | None = None
+
+    def update(self, **kwargs: Any) -> None:  # noqa: ANN401
+        """Update non-None fields in place."""
+        for k, v in kwargs.items():
+            if v is not None and hasattr(self, k):
+                setattr(self, k, v)
+
+    model_config = SettingsConfigDict(env_prefix="MIRASCOPE_")
+
+
+@cache
+def _default_settings() -> Settings:
+    return Settings()
+
+
+CURRENT_SETTINGS: ContextVar[Settings | None] = ContextVar(
+    "CURRENT_SETTINGS", default=None
+)
+
+
+def get_settings() -> Settings:
+    """Return Settings for the current context."""
+    settings = CURRENT_SETTINGS.get()
+    if settings is None:
+        settings = _default_settings()
+        CURRENT_SETTINGS.set(settings)
+    return settings
+
+
+@contextmanager
+def settings(
+    base_url: str | None = None,
+    api_key: str | None = None,
+) -> Iterator[Settings]:
+    """Context manager for temporarily overriding settings.
+
+    Args:
+        base_url: Override the base URL for API calls
+        api_key: Override the API key
+
+    Yields:
+        Settings instance with overrides applied
+
+    Example:
+        with settings(base_url="https://api.example.com", api_key="test-key"):
+            # Use custom settings within this context
+            client = MirascopeClient()
+    """
+    current = CURRENT_SETTINGS.get()
+    if current is None:
+        current = _default_settings()
+
+    new_settings = Settings(
+        base_url=base_url or current.base_url,
+        api_key=api_key or current.api_key,
+    )
+
+    token = CURRENT_SETTINGS.set(new_settings)
+    try:
+        yield new_settings
+    finally:
+        CURRENT_SETTINGS.reset(token)

mirascope/llm/__init__.py

@@ -1,4 +1,4 @@
-"""The `llm` module for writing provider-agnostic LLM Generations.
+"""LLM abstractions that aren't obstructions.
 
 This module provides a unified interface for interacting with different LLM providers,
 including messages, tools, response formatting, and streaming. It allows you to write
@@ -12,13 +12,13 @@ from contextlib import suppress
 
 from . import (
     calls,
-    clients,
     content,
     exceptions,
     formatting,
     messages,
     models,
     prompts,
+    providers,
     responses,
     tools,
     types,
@@ -26,8 +26,7 @@ from . import (
 
 with suppress(ImportError):
     from . import mcp
-from .calls import call
-from .clients import ModelId, Params, Provider, client, get_client
+from .calls import AsyncCall, AsyncContextCall, Call, CallDecorator, ContextCall, call
 from .content import (
     AssistantContentChunk,
     AssistantContentPart,
@@ -60,7 +59,8 @@ from .exceptions import (
     ConnectionError,
     FeatureNotSupportedError,
     FormattingModeNotSupportedError,
-    MirascopeError,
+    MirascopeLLMError,
+    NoRegisteredProviderError,
     NotFoundError,
     PermissionError,
     RateLimitError,
@@ -78,8 +78,23 @@ from .messages import (
     UserContent,
     UserMessage,
 )
-from .models import Model, model, use_model
-from .prompts import prompt
+from .models import Model, model, model_from_context, use_model
+from .prompts import (
+    AsyncContextPrompt,
+    AsyncPrompt,
+    ContextPrompt,
+    Prompt,
+    PromptDecorator,
+    prompt,
+)
+from .providers import (
+    ModelId,
+    Params,
+    Provider,
+    ProviderId,
+    load_provider,
+    register_provider,
+)
 from .responses import (
     AsyncChunkIterator,
     AsyncContextResponse,
@@ -121,11 +136,15 @@ __all__ = [
     "AssistantContentChunk",
     "AssistantContentPart",
     "AssistantMessage",
+    "AsyncCall",
     "AsyncChunkIterator",
+    "AsyncContextCall",
+    "AsyncContextPrompt",
     "AsyncContextResponse",
     "AsyncContextStreamResponse",
     "AsyncContextTool",
     "AsyncContextToolkit",
+    "AsyncPrompt",
     "AsyncResponse",
     "AsyncStream",
     "AsyncStreamResponse",
@@ -139,9 +158,13 @@ __all__ = [
     "BadRequestError",
     "Base64AudioSource",
     "Base64ImageSource",
+    "Call",
+    "CallDecorator",
     "ChunkIterator",
     "ConnectionError",
     "Context",
+    "ContextCall",
+    "ContextPrompt",
     "ContextResponse",
     "ContextStreamResponse",
     "ContextTool",
@@ -154,12 +177,18 @@ __all__ = [
     "FormattingModeNotSupportedError",
     "Image",
     "Message",
-    "MirascopeError",
+    "MirascopeLLMError",
     "Model",
+    "ModelId",
+    "NoRegisteredProviderError",
     "NotFoundError",
     "Params",
     "Partial",
     "PermissionError",
+    "Prompt",
+    "PromptDecorator",
+    "Provider",
+    "ProviderId",
     "RateLimitError",
     "RawMessageChunk",
     "Response",
@@ -195,19 +224,20 @@ __all__ = [
     "UserMessage",
     "call",
     "calls",
-    "client",
-    "clients",
     "content",
     "exceptions",
     "format",
     "formatting",
-    "get_client",
+    "load_provider",
     "mcp",
     "messages",
     "model",
+    "model_from_context",
     "models",
     "prompt",
     "prompts",
+    "providers",
+    "register_provider",
     "responses",
     "tool",
     "tools",

mirascope/llm/calls/calls.py

@@ -5,6 +5,7 @@ from typing import Generic, overload
 
 from ..context import Context, DepsT
 from ..formatting import FormattableT
+from ..models import Model, use_model
 from ..prompts import (
     AsyncContextPrompt,
     AsyncPrompt,
@@ -21,19 +22,37 @@ from ..responses import (
     Response,
     StreamResponse,
 )
-from ..tools import (
-    AsyncContextToolkit,
-    AsyncToolkit,
-    ContextToolkit,
-    Toolkit,
-)
 from ..types import P
-from .base_call import BaseCall
 
 
 @dataclass
-class Call(BaseCall[P, Prompt, Toolkit, FormattableT], Generic[P, FormattableT]):
-    """A class for generating responses using LLMs."""
+class BaseCall:
+    """Base class for all Call types with shared model functionality."""
+
+    default_model: Model
+    """The default model that will be used if no model is set in context."""
+
+    @property
+    def model(self) -> Model:
+        """The model used for generating responses. May be overwritten via `with llm.model(...)`."""
+        return use_model(self.default_model)
+
+
+@dataclass
+class Call(BaseCall, Generic[P, FormattableT]):
+    """A call that directly generates LLM responses without requiring a model argument.
+
+    Created by decorating a `MessageTemplate` with `llm.call`. The decorated function
+    becomes directly callable to generate responses, with the `Model` bundled in.
+
+    A `Call` is essentially: `MessageTemplate` + tools + format + `Model`.
+    It can be invoked directly: `call(*args, **kwargs)` (no model argument needed).
+
+    The model can be overridden at runtime using `with llm.model(...)` context manager.
+    """
+
+    prompt: Prompt[P, FormattableT]
+    """The underlying Prompt instance that generates messages with tools and format."""
 
     @overload
     def __call__(
@@ -63,10 +82,7 @@ class Call(BaseCall[P, Prompt, Toolkit, FormattableT], Generic[P, FormattableT])
         self, *args: P.args, **kwargs: P.kwargs
     ) -> Response | Response[FormattableT]:
         """Generates a response using the LLM."""
-        messages = self.fn(*args, **kwargs)
-        return self.model.call(
-            messages=messages, tools=self.toolkit, format=self.format
-        )
+        return self.prompt.call(self.model, *args, **kwargs)
 
     @overload
     def stream(
@@ -82,18 +98,24 @@ class Call(BaseCall[P, Prompt, Toolkit, FormattableT], Generic[P, FormattableT])
         self, *args: P.args, **kwargs: P.kwargs
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Generates a streaming response using the LLM."""
-        messages = self.fn(*args, **kwargs)
-        return self.model.stream(
-            messages=messages, tools=self.toolkit, format=self.format
-        )
+        return self.prompt.stream(self.model, *args, **kwargs)
 
 
 @dataclass
-class AsyncCall(
-    BaseCall[P, AsyncPrompt, AsyncToolkit, FormattableT],
-    Generic[P, FormattableT],
-):
-    """A class for generating responses using LLMs asynchronously."""
+class AsyncCall(BaseCall, Generic[P, FormattableT]):
+    """An async call that directly generates LLM responses without requiring a model argument.
+
+    Created by decorating an async `MessageTemplate` with `llm.call`. The decorated async
+    function becomes directly callable to generate responses asynchronously, with the `Model` bundled in.
+
+    An `AsyncCall` is essentially: async `MessageTemplate` + tools + format + `Model`.
+    It can be invoked directly: `await call(*args, **kwargs)` (no model argument needed).
+
+    The model can be overridden at runtime using `with llm.model(...)` context manager.
+    """
+
+    prompt: AsyncPrompt[P, FormattableT]
+    """The underlying AsyncPrompt instance that generates messages with tools and format."""
 
     @overload
     async def __call__(
@@ -108,7 +130,7 @@ class AsyncCall(
     async def __call__(
         self, *args: P.args, **kwargs: P.kwargs
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
-        """Generates a Asyncresponse using the LLM asynchronously."""
+        """Generates a response using the LLM asynchronously."""
         return await self.call(*args, **kwargs)
 
     @overload
@@ -125,10 +147,7 @@ class AsyncCall(
         self, *args: P.args, **kwargs: P.kwargs
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generates a response using the LLM asynchronously."""
-        messages = await self.fn(*args, **kwargs)
-        return await self.model.call_async(
-            messages=messages, tools=self.toolkit, format=self.format
-        )
+        return await self.prompt.call(self.model, *args, **kwargs)
 
     @overload
     async def stream(
@@ -144,18 +163,25 @@ class AsyncCall(
         self, *args: P.args, **kwargs: P.kwargs
     ) -> AsyncStreamResponse[FormattableT] | AsyncStreamResponse:
         """Generates a streaming response using the LLM asynchronously."""
-        messages = await self.fn(*args, **kwargs)
-        return await self.model.stream_async(
-            messages=messages, tools=self.toolkit, format=self.format
-        )
+        return await self.prompt.stream(self.model, *args, **kwargs)
 
 
 @dataclass
-class ContextCall(
-    BaseCall[P, ContextPrompt, ContextToolkit[DepsT], FormattableT],
-    Generic[P, DepsT, FormattableT],
-):
-    """A class for generating responses using LLMs."""
+class ContextCall(BaseCall, Generic[P, DepsT, FormattableT]):
+    """A context-aware call that directly generates LLM responses without requiring a model argument.
+
+    Created by decorating a `ContextMessageTemplate` with `llm.call`. The decorated function
+    (with first parameter `'ctx'` of type `Context[DepsT]`) becomes directly callable to generate
+    responses with context dependencies, with the `Model` bundled in.
+
+    A `ContextCall` is essentially: `ContextMessageTemplate` + tools + format + `Model`.
+    It can be invoked directly: `call(ctx, *args, **kwargs)` (no model argument needed).
+
+    The model can be overridden at runtime using `with llm.model(...)` context manager.
+    """
+
+    prompt: ContextPrompt[P, DepsT, FormattableT]
+    """The underlying ContextPrompt instance that generates messages with tools and format."""
 
     @overload
     def __call__(
@@ -199,10 +225,7 @@ class ContextCall(
         self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generates a response using the LLM."""
-        messages = self.fn(ctx, *args, **kwargs)
-        return self.model.context_call(
-            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
-        )
+        return self.prompt.call(self.model, ctx, *args, **kwargs)
 
     @overload
     def stream(
@@ -226,18 +249,25 @@ class ContextCall(
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
     ):
         """Generates a streaming response using the LLM."""
-        messages = self.fn(ctx, *args, **kwargs)
-        return self.model.context_stream(
-            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
-        )
+        return self.prompt.stream(self.model, ctx, *args, **kwargs)
 
 
 @dataclass
-class AsyncContextCall(
-    BaseCall[P, AsyncContextPrompt, AsyncContextToolkit[DepsT], FormattableT],
-    Generic[P, DepsT, FormattableT],
-):
-    """A class for generating responses using LLMs asynchronously."""
+class AsyncContextCall(BaseCall, Generic[P, DepsT, FormattableT]):
+    """An async context-aware call that directly generates LLM responses without requiring a model argument.
+
+    Created by decorating an async `ContextMessageTemplate` with `llm.call`. The decorated async
+    function (with first parameter `'ctx'` of type `Context[DepsT]`) becomes directly callable to generate
+    responses asynchronously with context dependencies, with the `Model` bundled in.
+
+    An `AsyncContextCall` is essentially: async `ContextMessageTemplate` + tools + format + `Model`.
+    It can be invoked directly: `await call(ctx, *args, **kwargs)` (no model argument needed).
+
+    The model can be overridden at runtime using `with llm.model(...)` context manager.
+    """
+
+    prompt: AsyncContextPrompt[P, DepsT, FormattableT]
+    """The underlying AsyncContextPrompt instance that generates messages with tools and format."""
 
     @overload
     async def __call__(
@@ -281,10 +311,7 @@ class AsyncContextCall(
         self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generates a response using the LLM asynchronously."""
-        messages = await self.fn(ctx, *args, **kwargs)
-        return await self.model.context_call_async(
-            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
-        )
+        return await self.prompt.call(self.model, ctx, *args, **kwargs)
 
     @overload
     async def stream(
@@ -309,7 +336,4 @@ class AsyncContextCall(
         | AsyncContextStreamResponse[DepsT, FormattableT]
     ):
         """Generates a streaming response using the LLM asynchronously."""
-        messages = await self.fn(ctx, *args, **kwargs)
-        return await self.model.context_stream_async(
-            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
-        )
+        return await self.prompt.stream(self.model, ctx, *args, **kwargs)