mirascope 2.0.0__py3-none-any.whl → 2.0.0a0__py3-none-any.whl

mirascope/ops/_internal/versioned_functions.py

@@ -1,357 +0,0 @@
-"""Versioned function implementations for Mirascope ops."""
-
-from __future__ import annotations
-
-import logging
-from collections.abc import Generator, Mapping
-from contextlib import contextmanager
-from dataclasses import dataclass, field
-from functools import cached_property, lru_cache
-from typing import Any, NewType, cast
-
-from ...api._generated.errors.not_found_error import NotFoundError
-from ...api._generated.functions.types.functions_create_request_dependencies_value import (
-    FunctionsCreateRequestDependenciesValue,
-)
-from ...api.client import get_async_client, get_sync_client
-from ..exceptions import ClosureComputationError
-from .closure import Closure
-from .spans import Span
-from .traced_functions import (
-    AsyncTrace,
-    BaseAsyncTracedFunction,
-    BaseSyncTracedFunction,
-    Trace,
-    _BaseTracedFunction,
-    record_result_to_span,
-)
-from .types import P, R
-
-logger = logging.getLogger(__name__)
-
-
-VersionId = NewType("VersionId", str)
-"""Unique identifier for a specific version."""
-
-VersionRef = NewType("VersionRef", str)
-"""Reference to a version (can be tag, hash, or semantic version)."""
-
-
-# NOTE: the `.get_version` methods will need to do some type-hint magic to get the
-# correct type-hints for the desired version (i.e. the input args and return type) since
-# those are not necessarily the same as the current version. This is what we did in v0,
-# so we'll just need to replicate that functionality here when we get there.
-
-
-@dataclass(kw_only=True, frozen=True)
-class VersionedResult(Trace[R]):
-    """Per-call handle returned by `.wrapped()` methods for versioned functions.
-
-    Provides access to the result and per-call operations for annotation,
-    tagging, and assignment within a specific trace span context.
-    """
-
-    function_uuid: str | None = None
-
-
-@dataclass(kw_only=True, frozen=True)
-class AsyncVersionedResult(AsyncTrace[R]):
-    """Per-call handle returned by async `.wrapped()` methods for versioned functions.
-
-    Provides access to the result and per-call operations for annotation,
-    tagging, and assignment within a specific trace span context.
-    """
-
-    function_uuid: str | None = None
-
-
-@dataclass(kw_only=True, frozen=True)
-class VersionInfo:
-    """Static version metadata for a versioned function.
-
-    Contains all information needed to identify and describe a specific version
-    of a function, including its computed version number and hashes.
-    """
-
-    uuid: str | None
-    """Server-assigned unique identifier for this version (None if not registered)."""
-
-    hash: str
-    """SHA256 hash of the complete closure code."""
-
-    signature_hash: str
-    """SHA256 hash of the function signature."""
-
-    name: str
-    """Display name for the versioned function."""
-
-    description: str | None
-    """Human-readable description of the versioned function."""
-
-    version: str
-    """Auto-computed semantic version in X.Y format."""
-
-    tags: tuple[str, ...]
-    """Tags associated with this version for filtering/classification."""
-
-    metadata: Mapping[str, str]
-    """Arbitrary key-value pairs for additional metadata."""
-
-    def __post_init__(self) -> None:
-        """Clean up tags and initialize frozen metadata after dataclass init."""
-        object.__setattr__(self, "tags", tuple(sorted(set(self.tags or []))))
-        object.__setattr__(self, "metadata", dict(self.metadata))
-
-
-@dataclass(kw_only=True)
-class _BaseVersionedFunction(_BaseTracedFunction[P, R, Any]):
-    """Base class for versioned functions."""
-
-    name: str | None = None
-    """Optional custom name for the versioned function (overrides function name)."""
-
-    metadata: dict[str, str] = field(default_factory=dict)
-    """Arbitrary key-value pairs for additional metadata."""
-
-    closure: Closure | None = field(init=False, default=None)
-
-    def __post_init__(self) -> None:
-        super().__post_init__()
-        try:
-            self.closure = Closure.from_fn(self.fn)
-        except ClosureComputationError as e:
-            logger.warning(
-                "Failed to build closure for %s; continuing without version registration: %s",
-                e.qualified_name,
-                e,
-            )
-
-    @classmethod
-    @lru_cache(maxsize=128)
-    def _compute_version(cls, hash: str) -> str:
-        """Computes the version string from the closure hash.
-
-        For new functions without server history, returns "1.0" as the initial version.
-
-        TODO: When API client is available, query the server for existing versions:
-        1. Check if a function with matching hash exists -> use its version
-        2. If no matches, return "1.0" as initial version
-
-        Args:
-            hash: SHA256 hash of the complete closure code.
-
-        Returns:
-            A version string.
-        """
-        return "1.0"
-
-    @cached_property
-    def version_info(self) -> VersionInfo | None:
-        """Returns static version metadata for this versioned function.
-
-        Lazily constructs and caches the VersionInfo from the closure and
-        decorator arguments. Returns None if the closure could not be computed.
-
-        Returns:
-            VersionInfo containing hashes, version string, and metadata,
-            or None if closure computation failed.
-        """
-        if self.closure is None:
-            return None
-
-        return VersionInfo(
-            uuid=None,
-            hash=self.closure.hash,
-            signature_hash=self.closure.signature_hash,
-            name=self.name or self.closure.name,
-            description=self.closure.docstring,
-            version=self._compute_version(self.closure.hash),
-            tags=self.tags,
-            metadata=self.metadata,
-        )
-
-    @contextmanager
-    def _versioned_span(
-        self, function_uuid: str | None, *args: P.args, **kwargs: P.kwargs
-    ) -> Generator[Span, None, None]:
-        with super()._span(*args, **kwargs) as span:
-            if self.closure is not None:
-                span.set(
-                    **{
-                        "mirascope.version.hash": self.closure.hash,
-                        "mirascope.version.signature_hash": self.closure.signature_hash,
-                    }
-                )
-                if self.closure.docstring:
-                    span.set(
-                        **{"mirascope.version.description": self.closure.docstring}
-                    )
-
-            if function_uuid:
-                span.set(**{"mirascope.version.uuid": function_uuid})
-
-            version_info = self.version_info
-            if version_info is not None:
-                span.set(**{"mirascope.version.version": version_info.version})
-            if self.name:
-                span.set(**{"mirascope.version.name": self.name})
-            if self.tags:
-                span.set(**{"mirascope.version.tags": self.tags})
-            if self.metadata:
-                for key, value in self.metadata.items():
-                    span.set(**{f"mirascope.version.meta.{key}": value})
-            yield span
-
-
-@dataclass(kw_only=True)
-class VersionedFunction(_BaseVersionedFunction[P, R], BaseSyncTracedFunction[P, R]):
-    """Wrapper for synchronous functions with versioning capabilities."""
-
-    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
-        """Returns the result of the versioned function directly.
-
-        A new version will be created if none yet exists for the specific version of
-        this function that's being run.
-        """
-        function_uuid = self._ensure_registration()
-        with self._versioned_span(function_uuid, *args, **kwargs) as span:
-            result = self.fn(*args, **kwargs)
-            record_result_to_span(span, result)
-            return result
-
-    def wrapped(self, *args: P.args, **kwargs: P.kwargs) -> VersionedResult[R]:
-        """Return a wrapper around the executed function's result for trace utilities.
-
-        Args:
-            *args: Positional arguments for the wrapped function.
-            **kwargs: Keyword arguments including 'version' for version reference.
-
-        Returns:
-            A VersionedResult containing the function result and trace context.
-        """
-        function_uuid = self._ensure_registration()
-        with self._versioned_span(function_uuid, *args, **kwargs) as span:
-            result = self.fn(*args, **kwargs)
-            record_result_to_span(span, result)
-            return VersionedResult(
-                result=result,
-                span=span,
-                function_uuid=function_uuid,
-            )
-
-    def get_version(self, version: VersionId) -> VersionedFunction[P, R]:
-        """Returns the specific version of this function requested."""
-        raise NotImplementedError("VersionedFunction.get_version not yet implemented")
-
-    def _ensure_registration(self) -> str | None:
-        """Returns function UUID after ensuring registration with API."""
-        if self.closure is None:
-            return None
-        try:
-            client = get_sync_client()
-        except Exception as e:
-            logger.warning("Failed to get client for function registration: %s", e)
-            return None
-
-        try:
-            existing = client.functions.findbyhash(self.closure.hash)
-            return existing.id
-        except NotFoundError:
-            dependencies: dict[str, FunctionsCreateRequestDependenciesValue | None] = {
-                name: FunctionsCreateRequestDependenciesValue(
-                    version=dep_info["version"],
-                    extras=dep_info.get("extras"),
-                )
-                for name, dep_info in self.closure.dependencies.items()
-            }
-            response = client.functions.create(
-                code=self.closure.code,
-                hash=self.closure.hash,
-                signature=self.closure.signature,
-                signature_hash=self.closure.signature_hash,
-                name=self.name or self.closure.name,
-                description=self.closure.docstring,
-                tags=list(self.tags) if self.tags else None,
-                metadata=cast(dict[str, str | None], self.metadata)
-                if self.metadata
-                else None,
-                dependencies=dependencies if dependencies else None,
-            )
-            return response.id
-        except Exception as e:
-            logger.warning("Failed to register function: %s", e)
-            return None
-
-
-@dataclass(kw_only=True)
-class AsyncVersionedFunction(
-    _BaseVersionedFunction[P, R], BaseAsyncTracedFunction[P, R]
-):
-    """Wrapper for asynchronous functions with versioning capabilities."""
-
-    async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
-        """Returns the result of the versioned function directly."""
-        function_uuid = await self._ensure_registration()
-        with self._versioned_span(function_uuid, *args, **kwargs) as span:
-            result = await self.fn(*args, **kwargs)
-            record_result_to_span(span, result)
-            return result
-
-    async def wrapped(
-        self, *args: P.args, **kwargs: P.kwargs
-    ) -> AsyncVersionedResult[R]:
-        """Returns a wrapper around the traced function's result for trace utilities."""
-        function_uuid = await self._ensure_registration()
-        with self._versioned_span(function_uuid, *args, **kwargs) as span:
-            result = await self.fn(*args, **kwargs)
-            record_result_to_span(span, result)
-            return AsyncVersionedResult(
-                result=result,
-                span=span,
-                function_uuid=function_uuid,
-            )
-
-    async def get_version(self, version: VersionId) -> VersionedFunction[P, R]:
-        """Returns the specific version of this function using an `AsyncLilypad` client."""
-        raise NotImplementedError(
-            "AsyncVersionedFunction.get_version not yet implemented"
-        )
-
-    async def _ensure_registration(self) -> str | None:
-        """Returns function UUID after ensuring registration with API."""
-        if self.closure is None:
-            return None
-        try:
-            client = get_async_client()
-        except Exception as e:
-            logger.warning("Failed to get client for function registration: %s", e)
-            return None
-
-        try:
-            existing = await client.functions.findbyhash(self.closure.hash)
-            return existing.id
-        except NotFoundError:
-            dependencies: dict[str, FunctionsCreateRequestDependenciesValue | None] = {
-                name: FunctionsCreateRequestDependenciesValue(
-                    version=dep_info["version"],
-                    extras=dep_info.get("extras"),
-                )
-                for name, dep_info in self.closure.dependencies.items()
-            }
-            response = await client.functions.create(
-                code=self.closure.code,
-                hash=self.closure.hash,
-                signature=self.closure.signature,
-                signature_hash=self.closure.signature_hash,
-                name=self.name or self.closure.name,
-                description=self.closure.docstring,
-                tags=list(self.tags) if self.tags else None,
-                metadata=cast(dict[str, str | None], self.metadata)
-                if self.metadata
-                else None,
-                dependencies=dependencies if dependencies else None,
-            )
-            return response.id
-        except Exception as e:
-            logger.warning("Failed to register function: %s", e)
-            return None

mirascope/ops/_internal/versioning.py

@@ -1,303 +0,0 @@
-"""Version decorator for Mirascope ops."""
-
-from __future__ import annotations
-
-from collections.abc import Sequence
-from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, overload
-
-from ...llm.calls import AsyncCall, AsyncContextCall, Call, ContextCall
-from ...llm.context import DepsT
-from .protocols import AsyncFunction, SyncFunction, fn_is_async
-from .types import P, R
-from .versioned_calls import (
-    VersionedAsyncCall,
-    VersionedAsyncContextCall,
-    VersionedCall,
-    VersionedContextCall,
-    is_version_call_type,
-    wrap_version_call,
-)
-from .versioned_functions import AsyncVersionedFunction, VersionedFunction
-
-if TYPE_CHECKING:
-    from ...llm.formatting import FormattableT
-
-
-@dataclass(kw_only=True)
-class VersionDecorator:
-    """Decorator implementation for adding versioning capabilities to functions."""
-
-    tags: tuple[str, ...] = ()
-    """Tags to be associated with versioned function calls."""
-
-    name: str | None = None
-    """Optional custom name for the versioned function."""
-
-    metadata: dict[str, str] = field(default_factory=dict)
-    """Arbitrary key-value pairs for additional metadata."""
-
-    @overload
-    def __call__(  # pyright: ignore[reportOverlappingOverload]
-        self,
-        fn: AsyncContextCall[P, DepsT, FormattableT],
-    ) -> VersionedAsyncContextCall[P, DepsT, FormattableT]:
-        """Overload for applying decorator to an AsyncContextCall."""
-        ...
-
-    @overload
-    def __call__(
-        self,
-        fn: ContextCall[P, DepsT, FormattableT],
-    ) -> VersionedContextCall[P, DepsT, FormattableT]:
-        """Overload for applying decorator to a ContextCall."""
-        ...
-
-    @overload
-    def __call__(
-        self,
-        fn: AsyncCall[P, FormattableT],
-    ) -> VersionedAsyncCall[P, FormattableT]:
-        """Overload for applying decorator to an AsyncCall."""
-        ...
-
-    @overload
-    def __call__(
-        self,
-        fn: Call[P, FormattableT],
-    ) -> VersionedCall[P, FormattableT]:
-        """Overload for applying decorator to a Call."""
-        ...
-
-    @overload
-    def __call__(
-        self,
-        fn: AsyncFunction[P, R],
-    ) -> AsyncVersionedFunction[P, R]:
-        """Overload for applying decorator to an async function."""
-        ...
-
-    @overload
-    def __call__(
-        self,
-        fn: SyncFunction[P, R],
-    ) -> VersionedFunction[P, R]:
-        """Overload for applying decorator to a sync function."""
-        ...
-
-    def __call__(  # pyright: ignore[reportGeneralTypeIssues]
-        self,
-        fn: (
-            AsyncContextCall[P, DepsT, FormattableT]
-            | ContextCall[P, DepsT, FormattableT]
-            | AsyncCall[P, FormattableT]
-            | Call[P, FormattableT]
-            | AsyncFunction[P, R]
-            | SyncFunction[P, R]
-        ),
-    ) -> (
-        VersionedAsyncContextCall[P, DepsT, FormattableT]
-        | VersionedContextCall[P, DepsT, FormattableT]
-        | VersionedAsyncCall[P, FormattableT]
-        | VersionedCall[P, FormattableT]
-        | AsyncVersionedFunction[P, R]
-        | VersionedFunction[P, R]
-    ):
-        """Applies the decorator to the given function or Call object."""
-        if is_version_call_type(fn):
-            return wrap_version_call(
-                fn=fn,
-                tags=self.tags,
-                name=self.name,
-                metadata=self.metadata or {},
-            )
-        elif fn_is_async(fn):
-            return AsyncVersionedFunction(
-                fn=fn,
-                tags=self.tags,
-                name=self.name,
-                metadata=self.metadata,
-            )
-        else:
-            return VersionedFunction(
-                fn=fn,
-                tags=self.tags,
-                name=self.name,
-                metadata=self.metadata,
-            )
-
-
-@overload
-def version(
-    __fn: None = None,
-    *,
-    tags: Sequence[str] | None = None,
-    name: str | None = None,
-    metadata: dict[str, str] | None = None,
-) -> VersionDecorator:
-    """Overload for providing kwargs before decorating (e.g. tags)."""
-    ...
-
-
-@overload
-def version(  # pyright: ignore[reportOverlappingOverload]
-    __fn: AsyncContextCall[P, DepsT, FormattableT],
-    *,
-    tags: None = None,
-    name: None = None,
-    metadata: None = None,
-) -> VersionedAsyncContextCall[P, DepsT, FormattableT]:
-    """Overload for directly (no argument) decorating an AsyncContextCall."""
-    ...
-
-
-@overload
-def version(
-    __fn: ContextCall[P, DepsT, FormattableT],
-    *,
-    tags: None = None,
-    name: None = None,
-    metadata: None = None,
-) -> VersionedContextCall[P, DepsT, FormattableT]:
-    """Overload for directly (no argument) decorating a ContextCall."""
-    ...
-
-
-@overload
-def version(
-    __fn: AsyncCall[P, FormattableT],
-    *,
-    tags: None = None,
-    name: None = None,
-    metadata: None = None,
-) -> VersionedAsyncCall[P, FormattableT]:
-    """Overload for directly (no argument) decorating an AsyncCall."""
-    ...
-
-
-@overload
-def version(
-    __fn: Call[P, FormattableT],
-    *,
-    tags: None = None,
-    name: None = None,
-    metadata: None = None,
-) -> VersionedCall[P, FormattableT]:
-    """Overload for directly (no argument) decorating a Call."""
-    ...
-
-
-@overload
-def version(
-    __fn: AsyncFunction[P, R],
-    *,
-    tags: None = None,
-    name: None = None,
-    metadata: None = None,
-) -> AsyncVersionedFunction[P, R]:
-    """Overload for directly (no argument) decorating an asynchronous function"""
-    ...
-
-
-@overload
-def version(
-    __fn: SyncFunction[P, R],
-    *,
-    tags: None = None,
-    name: None = None,
-    metadata: None = None,
-) -> VersionedFunction[P, R]:
-    """Overload for directly (no argument) decorating a synchronous function"""
-    ...
-
-
-def version(  # pyright: ignore[reportGeneralTypeIssues]
-    __fn: (
-        AsyncContextCall[P, DepsT, FormattableT]
-        | ContextCall[P, DepsT, FormattableT]
-        | AsyncCall[P, FormattableT]
-        | Call[P, FormattableT]
-        | AsyncFunction[P, R]
-        | SyncFunction[P, R]
-        | None
-    ) = None,
-    *,
-    tags: Sequence[str] | None = None,
-    name: str | None = None,
-    metadata: dict[str, str] | None = None,
-) -> (
-    VersionDecorator
-    | VersionedAsyncContextCall[P, DepsT, FormattableT]
-    | VersionedContextCall[P, DepsT, FormattableT]
-    | VersionedAsyncCall[P, FormattableT]
-    | VersionedCall[P, FormattableT]
-    | AsyncVersionedFunction[P, R]
-    | VersionedFunction[P, R]
-):
-    """Add versioning capability to a callable function.
-
-    Enables version management for functions, allowing execution of specific
-    versions and version introspection. Can be composed with @trace and @remote.
-
-    Args:
-        __fn: The function to version (when used without parentheses).
-        tags: Optional version tags for this function.
-        name: Optional custom name for display (overrides function name).
-        metadata: Arbitrary key-value pairs for additional metadata.
-
-    Returns:
-        A versioned callable or a decorator function.
-
-    Examples:
-        ```python
-        @version()
-        def compute(x: int) -> int:
-            return x * 2
-        ```
-
-        ```python
-        @version(tags=["v1.0"])
-        async def process() -> str:
-            return "processed"
-        ```
-
-        ```python
-        @version(
-            name="book_recommender",
-            tags=["production"],
-            metadata={"owner": "team-ml", "ticket": "ENG-1234"},
-        )
-        def recommend_book(genre: str) -> str:
-            return f"Recommend a {genre} book"
-        ```
-    """
-    tags = tuple(sorted(set(tags or [])))
-    metadata = metadata or {}
-    if __fn is None:
-        return VersionDecorator(
-            tags=tags,
-            name=name,
-            metadata=metadata,
-        )
-
-    if is_version_call_type(__fn):
-        return wrap_version_call(
-            fn=__fn,
-            tags=tags,
-            name=name,
-            metadata=metadata,
-        )
-    elif fn_is_async(__fn):
-        return AsyncVersionedFunction(
-            fn=__fn,
-            tags=tags,
-            name=name,
-            metadata=metadata,
-        )
-    else:
-        return VersionedFunction(
-            fn=__fn,
-            tags=tags,
-            name=name,
-            metadata=metadata,
-        )

mirascope/ops/exceptions.py

@@ -1,21 +0,0 @@
-"""Mirascope Ops exception hierarchy for unified error handling across providers."""
-
-
-class MirascopeOpsError(Exception):
-    """Base exception for all Mirascope Ops errors."""
-
-    original_exception: Exception | None
-
-
-class ConfigurationError(MirascopeOpsError):
-    """Raised when Ops configuration is invalid."""
-
-
-class ClosureComputationError(MirascopeOpsError):
-    """Raised when the closure for a function cannot be computed properly."""
-
-    qualified_name: str
-
-    def __init__(self, qualified_name: str) -> None:
-        """Initializes an instance of `ClosureComputationError`."""
-        self.qualified_name = qualified_name