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

mirascope/retries/fallback.py

@@ -1,131 +0,0 @@
-"""The `fallback` module provides a fallback retry strategy."""
-
-import inspect
-from collections.abc import Callable, Coroutine
-from typing import Any, ParamSpec, Protocol, TypeVar, overload
-
-from pydantic import BaseModel
-from typing_extensions import NotRequired, Required, TypedDict
-
-from .. import llm
-from ..core.base import CommonCallParams
-from ..core.base.types import Provider
-
-_P = ParamSpec("_P")
-_R = TypeVar("_R")
-
-
-class FallbackDecorator(Protocol):
-    @overload
-    def __call__(
-        self, fn: Callable[_P, Coroutine[_R, Any, Any]]
-    ) -> Callable[_P, Coroutine[_R, Any, Any]]: ...
-
-    @overload
-    def __call__(self, fn: Callable[_P, _R]) -> Callable[_P, _R]: ...
-
-    def __call__(
-        self,
-        fn: Callable[_P, _R] | Callable[_P, Coroutine[_R, Any, Any]],
-    ) -> Callable[_P, _R] | Callable[_P, Coroutine[_R, Any, Any]]: ...
-
-
-class Fallback(TypedDict):
-    """The override arguments to use for this fallback attempt."""
-
-    catch: Required[type[Exception] | tuple[type[Exception]]]
-    provider: Required[Provider]
-    model: Required[str]
-    call_params: NotRequired[CommonCallParams]
-    client: NotRequired[Any]
-
-
-class FallbackError(Exception):
-    """An error raised when all fallbacks fail."""
-
-
-def fallback(
-    catch: type[Exception] | tuple[type[Exception]],
-    fallbacks: list[Fallback],
-) -> FallbackDecorator:
-    """A decorator that retries the function call with a fallback strategy.
-
-    This must use the provider-agnostic `llm.call` decorator.
-
-    Args:
-        catch: The exception(s) to catch for the original call.
-        backups: The list of backup providers to try in order. Each backup provider
-            is a tuple of the provider name, the model name, and the call params.
-            The call params may be `None` if no change is wanted.
-
-    Returns:
-        The decorated function.
-
-    Raises:
-        FallbackError: If all fallbacks fail.
-    """
-
-    @overload
-    def decorator(
-        fn: Callable[_P, Coroutine[_R, Any, Any]],
-    ) -> Callable[_P, Coroutine[_R, Any, Any]]: ...
-
-    @overload
-    def decorator(fn: Callable[_P, _R]) -> Callable[_P, _R]: ...
-
-    def decorator(
-        fn: Callable[_P, _R] | Callable[_P, Coroutine[_R, Any, Any]],
-    ) -> Callable[_P, _R] | Callable[_P, Coroutine[_R, Any, Any]]:
-        fn_to_check = fn._original_fn if hasattr(fn, "_original_fn") else fn  # pyright: ignore [reportFunctionMemberAccess]
-        if inspect.iscoroutinefunction(fn_to_check):
-
-            async def inner_async(*args: _P.args, **kwargs: _P.kwargs) -> _R:
-                caught: list[Exception] = []
-                try:
-                    return await fn(*args, **kwargs)  # pyright: ignore [reportReturnType,reportGeneralTypeIssues]
-                except catch as e:
-                    caught.append(e)
-                    for backup in fallbacks:
-                        try:
-                            with llm.context(
-                                provider=backup["provider"],
-                                model=backup["model"],
-                                call_params=backup.get("call_params", None),
-                                client=backup.get("client", None),
-                            ):
-                                response = await fn(*args, **kwargs)  # pyright: ignore [reportGeneralTypeIssues]
-                                if isinstance(response, BaseModel):
-                                    response._caught = caught  # pyright: ignore [reportAttributeAccessIssue]
-                                return response  # pyright: ignore [reportReturnType]
-                        except backup["catch"] as be:
-                            caught.append(be)
-                raise FallbackError(f"All fallbacks failed:\n{caught}")
-
-            return inner_async
-        else:
-
-            def inner(*args: _P.args, **kwargs: _P.kwargs) -> _R:
-                caught: list[Exception] = []
-                try:
-                    return fn(*args, **kwargs)  # pyright: ignore [reportReturnType]
-                except catch as e:
-                    caught.append(e)
-                    for backup in fallbacks:
-                        try:
-                            with llm.context(
-                                provider=backup["provider"],
-                                model=backup["model"],
-                                call_params=backup.get("call_params", None),
-                                client=backup.get("client", None),
-                            ):
-                                response = fn(*args, **kwargs)
-                                if isinstance(response, BaseModel):
-                                    response._caught = caught  # pyright: ignore [reportAttributeAccessIssue]
-                                return response  # pyright: ignore [reportReturnType]
-                        except backup["catch"] as be:
-                            caught.append(be)
-                raise FallbackError(f"All fallbacks failed:\n{caught}")
-
-            return inner
-
-    return decorator

mirascope/retries/tenacity.py

@@ -1,50 +0,0 @@
-"""Utitlies for more easily using Tenacity to reinsert errors on failed API calls."""
-
-from collections.abc import Callable
-
-from tenacity import RetryCallState
-
-
-def collect_errors(
-    *args: type[Exception],
-) -> Callable[[RetryCallState], None]:
-    """Collects specified errors into an `errors` keyword argument.
-
-    Example:
-
-    ```python
-    from mirascope.integrations.tenacity import collect_errors
-    from tenacity import retry, stop_after_attempt
-
-    @retry(stop=stop_after_attempt(3), after=collect_errors(ValueError))
-    def throw_value_error(*, errors: list[ValueError] | None = None):
-        if errors:
-            print(errors[-1])
-        raise ValueError("Throwing Error")
-
-
-    try:
-        throw_value_error()
-        # > Throwing Error
-        # > Throwing Error
-    except RetryError:
-        ...
-    ```
-
-    Args:
-        *args: The `Exception` types to catch.
-    """
-
-    def inner(retry_state: RetryCallState) -> None:
-        """Collect errors into a `errors` kwarg of the wrapped function."""
-        if (
-            (outcome := retry_state.outcome)
-            and (exception := outcome.exception())
-            and type(exception) in args
-        ):
-            errors = retry_state.kwargs.pop("errors", [])
-            retry_state.kwargs["errors"] = (
-                errors + [exception] if errors else [exception]
-            )
-
-    return inner

mirascope/tools/__init__.py

@@ -1,37 +0,0 @@
-from contextlib import suppress
-
-from .system._file_system import FileSystemToolKit, FileSystemToolKitConfig
-
-with suppress(ImportError):
-    from .system._docker_operation import (
-        DockerOperationToolKit,
-        DockerOperationToolKitConfig,
-    )
-
-with suppress(ImportError):
-    from .web._duckduckgo import DuckDuckGoSearch, DuckDuckGoSearchConfig
-
-with suppress(ImportError):
-    from .web._httpx import HTTPX, AsyncHTTPX, HTTPXConfig
-
-with suppress(ImportError):
-    from .web._parse_url_content import ParseURLConfig, ParseURLContent
-
-with suppress(ImportError):
-    from .web._requests import Requests, RequestsConfig
-
-__all__ = [
-    "HTTPX",
-    "AsyncHTTPX",
-    "DockerOperationToolKit",
-    "DockerOperationToolKitConfig",
-    "DuckDuckGoSearch",
-    "DuckDuckGoSearchConfig",
-    "FileSystemToolKit",
-    "FileSystemToolKitConfig",
-    "HTTPXConfig",
-    "ParseURLConfig",
-    "ParseURLContent",
-    "Requests",
-    "RequestsConfig",
-]

mirascope/tools/base.py

@@ -1,98 +0,0 @@
-from __future__ import annotations
-
-import inspect
-from abc import ABC
-from typing import ClassVar, Generic, TypeVar, cast
-
-from pydantic import BaseModel, ConfigDict, create_model
-
-from mirascope.core import BaseTool, BaseToolKit
-from mirascope.core.base._utils import DEFAULT_TOOL_DOCSTRING
-
-
-class _ConfigurableToolConfig(BaseModel, ABC):
-    """Base configuration for tools"""
-
-    @classmethod
-    def from_env(cls: type[_ConfigurableToolConfigT]) -> _ConfigurableToolConfigT:
-        """Returns a configuration instance from environment variables."""
-        return cls()
-
-
-_ConfigurableToolConfigT = TypeVar(
-    "_ConfigurableToolConfigT", bound=_ConfigurableToolConfig
-)
-
-_ToolSchemaT = TypeVar("_ToolSchemaT")
-
-
-class ConfigurableTool(BaseTool, Generic[_ConfigurableToolConfigT], ABC):
-    """Abstract base class for configurable tools.
-
-    Subclasses must define a `__prompt_usage_description__` class variable
-    and __configurable_tool_config__ class variable with a subclass of _ToolConfig.
-    """
-
-    __configurable_tool_config__: ClassVar[_ConfigurableToolConfig]
-    __prompt_usage_description__: ClassVar[str]
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    @classmethod
-    def _get_config(cls) -> _ConfigurableToolConfigT:
-        """Get tool configuration"""
-        return cast(_ConfigurableToolConfigT, cls.__configurable_tool_config__)
-
-    @classmethod
-    def from_config(
-        cls: type[_ConfigurableToolT], config: _ConfigurableToolConfigT
-    ) -> type[_ConfigurableToolT]:
-        """Create tool class with custom configuration"""
-
-        # ClassVar cannot get TypeVar Type. So, we need the comment to ignore the error.
-        config = cls._get_config().model_validate(config)  # pyright: ignore [reportAssignmentType]
-        new_model = create_model(
-            cls.__name__,
-            __base__=cls,
-            __module__=cls.__module__,
-            __doc__=cls.__doc__ if cls.__doc__ else DEFAULT_TOOL_DOCSTRING,
-        )
-        new_model.__prompt_usage_description__ = cls.__prompt_usage_description__
-        new_model.__configurable_tool_config__ = config
-        return new_model
-
-    @classmethod
-    def usage_description(cls) -> str:
-        """Returns instructions for using this tool."""
-        return inspect.cleandoc(cls.__prompt_usage_description__)
-
-
-_ConfigurableToolT = TypeVar("_ConfigurableToolT", bound=ConfigurableTool)
-
-
-class ConfigurableToolKit(BaseToolKit, Generic[_ConfigurableToolConfigT], ABC):
-    """Abstract base class for configurable toolkit.
-
-    Subclasses must define a `__prompt_usage_description__` class variable
-    and __config__ class variable with a subclass of _ToolConfig.
-    """
-
-    config: _ConfigurableToolConfigT
-    __prompt_usage_description__: ClassVar[str]
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    def create_tools(self) -> list[type[BaseTool]]:
-        """The method to create the tools."""
-        return [
-            tool.from_config(self.config)
-            if issubclass(tool, ConfigurableTool) and "config" in self.model_fields_set
-            else tool
-            for tool in super().create_tools()
-        ]
-
-    @classmethod
-    def usage_description(cls) -> str:
-        """Returns instructions for using this toolkit."""
-        return inspect.cleandoc(cls.__prompt_usage_description__)
-
-
-_ConfigurableToolKitT = TypeVar("_ConfigurableToolKitT", bound=ConfigurableToolKit)

mirascope/tools/system/_docker_operation.py

@@ -1,166 +0,0 @@
-from __future__ import annotations
-
-import io
-import tarfile
-from abc import ABC
-from contextlib import suppress
-from typing import ClassVar
-
-import docker
-from docker.models.containers import Container
-from pydantic import BaseModel, Field
-
-from mirascope.core import BaseTool, toolkit_tool
-from mirascope.tools.base import (
-    ConfigurableTool,
-    ConfigurableToolKit,
-    _ConfigurableToolConfig,
-)
-
-
-class DockerOperationToolKitConfig(_ConfigurableToolConfig):
-    """Configuration for `DockerOperationToolKit` toolkit"""
-
-    docker_image: str = Field(
-        default="python:3.13-slim", description="Docker image for code execution"
-    )
-    max_memory: str = Field(default="512m", description="Maximum memory allocation")
-    allow_network: bool = Field(default=True, description="Allow network access")
-
-
-class DockerOperation(ConfigurableTool[DockerOperationToolKitConfig], ABC):
-    """Base class for Docker operations."""
-
-    __configurable_tool_config__ = DockerOperationToolKitConfig()
-    _docker_container: DockerContainer
-
-    @classmethod
-    def _create_tar_stream(cls, files: dict[str, str]) -> io.BytesIO:
-        """Creates a tar stream from a dictionary of files."""
-        stream = io.BytesIO()
-        with tarfile.open(fileobj=stream, mode="w") as tar:
-            for name, content in files.items():
-                info = tarfile.TarInfo(name=name)
-                encoded_content = content.encode("utf-8")
-                info.size = len(encoded_content)
-                tar.addfile(info, io.BytesIO(encoded_content))
-        stream.seek(0)
-        return stream
-
-
-class DockerContainer(BaseModel):
-    config: DockerOperationToolKitConfig = DockerOperationToolKitConfig()
-    _container: Container | None = None
-
-    @property
-    def container(self) -> Container:
-        if not self._container:
-            self._container = self._setup_container(self.config)
-        return self._container
-
-    def __del__(self) -> None:
-        """Cleanup the container when the toolkit is destroyed."""
-        if container := self._container:
-            with suppress(Exception):
-                container.stop()
-
-    def _setup_container(self, config: DockerOperationToolKitConfig) -> Container:
-        """Sets up a persistent container for code execution."""
-        client = docker.from_env()
-        return client.containers.run(
-            self.config.docker_image,
-            "tail -f /dev/null",  # Keep container running
-            detach=True,
-            mem_limit=self.config.max_memory,
-            network_disabled=not self.config.allow_network,
-            remove=True,
-            security_opt=["no-new-privileges"],  # Prevent privilege escalation
-            cap_drop=["ALL"],  # Drop all capabilities
-        )
-
-
-class DockerOperationToolKit(ConfigurableToolKit[DockerOperationToolKitConfig]):
-    """ToolKit for executing Python code and shell commands in a Docker container."""
-
-    config: DockerOperationToolKitConfig = DockerOperationToolKitConfig()
-    docker_container: DockerContainer
-    __namespace__ = "docker"
-    __prompt_usage_description__: ClassVar[str] = """
-    - Tools for code execution:
-        - ExecutePython: Executes Python code with optional requirements in a Docker container
-        - ExecuteShell: Executes shell commands in a Docker container
-    """
-
-    def create_tools(self) -> list[type[BaseTool]]:
-        """The method to create the tools."""
-
-        tools = super().create_tools()
-        for tool in tools:
-            if issubclass(tool, DockerOperation):
-                tool._docker_container = self.docker_container
-        return tools
-
-    @toolkit_tool
-    class ExecutePython(DockerOperation):
-        """Tool for executing Python code in a Docker container."""
-
-        code: str
-        requirements: list[str] | None = None
-
-        def call(self) -> str:
-            """Executes Python code in a Docker container.
-
-            docker_image: {self.__config__.docker_image}
-            allow_network: {self.__config__.allow_network}
-
-            Returns:
-                str: Output of the code execution
-            """
-            try:
-                contents = {
-                    "main.py": self.code,
-                }
-                if self.requirements:
-                    if not self._get_config().allow_network:
-                        return "Error: Network access is disabled. Cannot install requirements via pip."
-                    contents["requirements.txt"] = "\n".join(self.requirements)
-                stream = self._create_tar_stream(contents)
-                self._docker_container.container.put_archive("/", stream)
-                if self.requirements:
-                    exit_code, output = self._docker_container.container.exec_run(
-                        cmd=["pip", "install", "-r", "/requirements.txt"],
-                    )
-                    if exit_code != 0:  # pragma: no cover
-                        return (
-                            f"Error installing requirements: {output.decode('utf-8')}"
-                        )
-                exit_code, output = self._docker_container.container.exec_run(
-                    cmd=["python", "/main.py"],
-                )
-                return output.decode("utf-8")
-
-            except Exception as e:
-                return f"Error executing code: {str(e)}"
-
-    @toolkit_tool
-    class ExecuteShell(DockerOperation):
-        """Tool for executing shell commands in a Docker container."""
-
-        command: str
-
-        def call(self) -> str:
-            """Executes shell commands in a Docker container.
-
-            docker_image: {self.__config__.docker_image}
-            allow_network: {self.__config__.allow_network}
-
-            Returns:
-                str: Output of the command execution
-            """
-            try:
-                exec_result = self._docker_container.container.exec_run(
-                    cmd=["sh", "-c", self.command],
-                )
-                return exec_result.output.decode("utf-8")
-            except Exception as e:  # pragma: no cover
-                return f"Error executing command: {str(e)}"