mirascope 1.0.5__py3-none-any.whl → 2.1.1__py3-none-any.whl

mirascope/api/_generated/types/pricing_unavailable_error.py

@@ -0,0 +1,23 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+
+
+class PricingUnavailableError(UniversalBaseModel):
+    message: str
+    provider: typing.Optional[str] = None
+    model: typing.Optional[str] = None
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
+            extra="allow", frozen=True
+        )  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

mirascope/api/_generated/types/property_key.py

@@ -0,0 +1,7 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from .property_key_key import PropertyKeyKey
+
+PropertyKey = typing.Union[str, float, PropertyKeyKey]

mirascope/api/_generated/types/property_key_key.py

@@ -0,0 +1,25 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from .property_key_key_tag import PropertyKeyKeyTag
+
+
+class PropertyKeyKey(UniversalBaseModel):
+    """
+    an object to be decoded into a globally shared symbol
+    """
+
+    tag: PropertyKeyKeyTag
+    key: str
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

mirascope/api/_generated/types/property_key_key_tag.py

@@ -0,0 +1,5 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+PropertyKeyKeyTag = typing.Union[typing.Literal["symbol"], typing.Any]

mirascope/api/_generated/types/rate_limit_error.py

@@ -0,0 +1,31 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+import typing_extensions
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from ..core.serialization import FieldMetadata
+from .rate_limit_error_tag import RateLimitErrorTag
+
+
+class RateLimitError(UniversalBaseModel):
+    message: str
+    organization_id: typing_extensions.Annotated[
+        str, FieldMetadata(alias="organizationId")
+    ]
+    limit: float
+    retry_after: typing_extensions.Annotated[float, FieldMetadata(alias="retryAfter")]
+    plan_tier: typing_extensions.Annotated[str, FieldMetadata(alias="planTier")]
+    tag: RateLimitErrorTag
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
+            extra="allow", frozen=True
+        )  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

mirascope/api/_generated/types/rate_limit_error_tag.py

@@ -0,0 +1,5 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+RateLimitErrorTag = typing.Union[typing.Literal["RateLimitError"], typing.Any]

mirascope/api/_generated/types/service_unavailable_error_body.py

@@ -0,0 +1,24 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from .service_unavailable_error_tag import ServiceUnavailableErrorTag
+
+
+class ServiceUnavailableErrorBody(UniversalBaseModel):
+    message: str
+    service: typing.Optional[str] = None
+    tag: ServiceUnavailableErrorTag
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
+            extra="allow", frozen=True
+        )  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

mirascope/api/_generated/types/service_unavailable_error_tag.py

@@ -0,0 +1,7 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+ServiceUnavailableErrorTag = typing.Union[
+    typing.Literal["ServiceUnavailableError"], typing.Any
+]

mirascope/api/_generated/types/stripe_error.py

@@ -0,0 +1,20 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+
+
+class StripeError(UniversalBaseModel):
+    message: str
+    cause: typing.Optional[typing.Optional[typing.Any]] = None
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

mirascope/api/_generated/types/subscription_past_due_error.py

@@ -0,0 +1,31 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+import typing_extensions
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from ..core.serialization import FieldMetadata
+from .subscription_past_due_error_tag import SubscriptionPastDueErrorTag
+
+
+class SubscriptionPastDueError(UniversalBaseModel):
+    message: str
+    stripe_customer_id: typing_extensions.Annotated[
+        str, FieldMetadata(alias="stripeCustomerId")
+    ]
+    past_due_subscription_ids: typing_extensions.Annotated[
+        typing.List[str], FieldMetadata(alias="pastDueSubscriptionIds")
+    ]
+    tag: SubscriptionPastDueErrorTag
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
+            extra="allow", frozen=True
+        )  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

mirascope/api/_generated/types/subscription_past_due_error_tag.py

@@ -0,0 +1,7 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+SubscriptionPastDueErrorTag = typing.Union[
+    typing.Literal["SubscriptionPastDueError"], typing.Any
+]

mirascope/api/_generated/types/unauthorized_error_body.py

@@ -0,0 +1,21 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from .unauthorized_error_tag import UnauthorizedErrorTag
+
+
+class UnauthorizedErrorBody(UniversalBaseModel):
+    message: str
+    tag: UnauthorizedErrorTag
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

mirascope/api/_generated/types/unauthorized_error_tag.py

@@ -0,0 +1,5 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+UnauthorizedErrorTag = typing.Union[typing.Literal["UnauthorizedError"], typing.Any]

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,99 @@
+"""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://mirascope.com/api/v2")
+    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
+
+
+def update_settings(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> None:
+    """Update the current settings with provided values.
+
+    This allows programmatic configuration of settings (e.g., from ops.configure)
+    that will be used by get_sync_client() and get_async_client().
+
+    Args:
+        api_key: API key to set (if provided)
+        base_url: Base URL to set (if provided)
+    """
+    current = get_settings()
+    current.update(api_key=api_key, base_url=base_url)
+
+
+@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)