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

mirascope/ops/_internal/versioned_functions.py

@@ -0,0 +1,357 @@
+"""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": list(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

@@ -0,0 +1,303 @@
+"""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

@@ -0,0 +1,21 @@
+"""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