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

mirascope/mcp/client.py

@@ -1,167 +0,0 @@
-"""The `MCPServer` Class and context managers."""
-
-import contextlib
-from collections.abc import AsyncIterator, Awaitable, Callable
-from datetime import timedelta
-from typing import Any
-
-from mcp import ClientSession
-from mcp.client.session import ListRootsFnT, SamplingFnT
-from mcp.client.sse import sse_client as mcp_sse_client
-from mcp.client.stdio import StdioServerParameters
-from mcp.client.stdio import stdio_client as mcp_stdio_client
-from mcp.types import (
-    BlobResourceContents,
-    Resource,
-)
-from pydantic import AnyUrl
-
-from mirascope.core import BaseMessageParam, BaseTool, TextPart
-from mirascope.mcp import _utils
-
-
-class MCPClient(ClientSession):
-    """The SSE client session that connects to the MCP server.
-
-    All of the results from the server are converted into Mirascope-friendly types.
-    """
-
-    _session: ClientSession
-
-    def __init__(self, session: ClientSession) -> None:
-        """Initializes an instance of `MCPClient`.
-
-        Args:
-            session: The original MCP `ClientSession`.
-        """
-        self._session = session
-
-    async def list_resources(self) -> list[Resource]:  # pyright: ignore [reportIncompatibleMethodOverride]
-        """List all resources available on the MCP server.
-
-        Returns:
-            A list of Resource objects
-        """
-        result = await self._session.list_resources()
-        return result.resources
-
-    async def read_resource(  # pyright: ignore [reportIncompatibleMethodOverride]
-        self, uri: str | AnyUrl
-    ) -> list[TextPart | BlobResourceContents]:
-        """Read a resource from the MCP server.
-
-        Args:
-            uri: URI of the resource to read
-
-        Returns:
-            Contents of the resource, either as string or BlobResourceContents
-        """
-        result = await self._session.read_resource(
-            uri if isinstance(uri, AnyUrl) else AnyUrl(uri)
-        )
-        parsed_results: list[TextPart | BlobResourceContents] = []
-        for content in result.contents:
-            if isinstance(content, BlobResourceContents):
-                parsed_results.append(content)
-            else:
-                parsed_results.append(TextPart(type="text", text=content.text))
-        return parsed_results
-
-    async def list_prompts(self) -> list[Any]:  # pyright: ignore [reportIncompatibleMethodOverride]
-        """List all prompts available on the MCP server.
-
-        Returns:
-            A list of Prompt objects
-        """
-        result = await self._session.list_prompts()
-        return result.prompts
-
-    async def get_prompt_template(
-        self, name: str
-    ) -> Callable[..., Awaitable[list[BaseMessageParam]]]:
-        """Get a prompt template from the MCP server.
-
-        Args:
-            name: Name of the prompt template
-
-        Returns:
-            A callable that accepts keyword arguments and returns a list of BaseMessageParam
-        """
-
-        # TODO: wrap this with `llm.prompt` once it's implemented so that they prompts
-        # can be run super easily inside of an `llm.context` block.
-        async def async_prompt(**kwargs: str) -> list[BaseMessageParam]:
-            result = await self._session.get_prompt(name, kwargs)  # type: ignore
-
-            return [
-                _utils.convert_prompt_message_to_base_message_params(prompt_message)
-                for prompt_message in result.messages
-            ]
-
-        return async_prompt
-
-    async def list_tools(self) -> list[type[BaseTool]]:  # pyright: ignore [reportIncompatibleMethodOverride]
-        """List all tools available on the MCP server.
-
-        Returns:
-            A list of dynamically created `BaseTool` types.
-        """
-        list_tool_result = await self._session.list_tools()
-
-        converted_tools = []
-        for tool in list_tool_result.tools:
-            model = _utils.create_tool_from_mcp_tool(tool)
-            tool_call_method = _utils.create_tool_call(
-                tool.name, self._session.call_tool
-            )
-            model.call = tool_call_method  # pyright: ignore [reportAttributeAccessIssue]
-            converted_tools.append(model)
-        return converted_tools
-
-
-@contextlib.asynccontextmanager
-async def sse_client(
-    url: str,
-    list_roots_callback: ListRootsFnT | None = None,
-    read_timeout_seconds: timedelta | None = None,
-    sampling_callback: SamplingFnT | None = None,
-    session: ClientSession | None = None,
-) -> AsyncIterator[MCPClient]:
-    async with (
-        mcp_sse_client(url) as (read, write),
-        ClientSession(
-            read,
-            write,
-            read_timeout_seconds=read_timeout_seconds,
-            sampling_callback=sampling_callback,
-            list_roots_callback=list_roots_callback,
-        ) as session,
-    ):
-        await session.initialize()
-        yield MCPClient(session)
-
-
-@contextlib.asynccontextmanager
-async def stdio_client(
-    server_parameters: StdioServerParameters,
-    read_stream_exception_handler: Callable[[Exception], None] | None = None,
-) -> AsyncIterator[MCPClient]:
-    """
-    Create a MCPClient instance with the given server parameters and exception handler.
-
-    Args:
-        server_parameters:
-        read_stream_exception_handler:
-
-    Returns:
-
-    """
-    async with (
-        mcp_stdio_client(server_parameters) as (read, write),
-        _utils.read_stream_exception_filer(
-            read, read_stream_exception_handler
-        ) as filtered_read,
-        ClientSession(filtered_read, write) as session,  # pyright: ignore [reportArgumentType]
-    ):
-        await session.initialize()
-        yield MCPClient(session)

mirascope/mcp/server.py

@@ -1,356 +0,0 @@
-"""The `MCPServer` Class and context managers."""
-
-import inspect
-import warnings
-from collections.abc import Awaitable, Callable, Iterable
-from typing import Literal, ParamSpec, cast, overload
-
-import mcp.server.stdio
-from docstring_parser import parse
-from mcp.server import NotificationOptions, Server
-from mcp.server.models import InitializationOptions
-from mcp.types import (
-    GetPromptResult,
-    ImageContent,
-    Prompt,
-    PromptArgument,
-    PromptMessage,
-    Resource,
-    TextContent,
-    Tool,
-)
-from pydantic import AnyUrl, BaseModel
-
-from mirascope.core import BaseDynamicConfig, BaseMessageParam, BaseTool
-from mirascope.core.base import ImagePart, TextPart
-from mirascope.core.base._utils import (
-    MessagesDecorator,
-    convert_base_model_to_base_tool,
-    convert_function_to_base_tool,
-    fn_is_async,
-)
-from mirascope.core.base._utils._messages_decorator import (
-    MessagesAsyncFunction,
-    MessagesSyncFunction,
-)
-from mirascope.core.base.prompt import PromptDecorator, prompt_template
-from mirascope.mcp.tools import MCPTool, ToolUseBlock
-
-_P = ParamSpec("_P")
-
-
-def _convert_base_message_param_to_prompt_messages(
-    base_message_param: BaseMessageParam,
-) -> list[PromptMessage]:
-    """
-    Convert BaseMessageParam to types.PromptMessage.
-
-    Args:
-        base_message_param: BaseMessageParam instance.
-
-    Returns:
-        A list of types.PromptMessage instances.
-    """
-
-    # Validate role
-    role = base_message_param.role
-    if role not in ["user", "assistant"]:
-        raise ValueError(f"invalid role: {role}")
-
-    if isinstance(base_message_param.content, str):
-        contents = [TextContent(type="text", text=base_message_param.content)]
-    elif isinstance(base_message_param.content, Iterable):
-        contents = []
-        for part in base_message_param.content:
-            if isinstance(part, TextPart):
-                contents.append(TextContent(type="text", text=part.text))
-            elif isinstance(part, ImagePart):
-                contents.append(
-                    ImageContent(
-                        type="image",
-                        data=part.image.decode("utf-8"),
-                        mimeType=part.media_type,
-                    )
-                )
-            else:
-                raise ValueError(f"Unsupported content type: {type(part)}")
-    else:
-        raise ValueError(
-            f"Unsupported content type: {type(base_message_param.content)}"
-        )
-
-    return [
-        PromptMessage(role=cast(Literal["user", "assistant"], role), content=content)
-        for content in contents
-    ]
-
-
-def _generate_prompt_from_function(fn: Callable) -> Prompt:
-    """
-    Generate a Prompt object from a function, extracting metadata like argument descriptions
-    from the function's docstring and type hints.
-
-    Args:
-        fn (Callable): The function to process.
-
-    Returns:
-        Prompt: A structured Prompt object with metadata.
-    """
-    # Parse the docstring for structured information
-    docstring = parse(fn.__doc__ or "")
-
-    # Extract general description from the docstring
-    description = docstring.short_description or ""
-
-    # Prepare to extract argument details
-    signature = inspect.signature(fn)
-    parameter_docs = {param.arg_name: param.description for param in docstring.params}
-
-    arguments = []
-    for parameter in signature.parameters.values():
-        arg_desc = parameter_docs.get(parameter.name, "")
-        required = parameter.default is inspect.Parameter.empty
-        arguments.append(
-            PromptArgument(name=parameter.name, description=arg_desc, required=required)
-        )
-
-    return Prompt(name=fn.__name__, description=description, arguments=arguments)
-
-
-class MCPServer:
-    """MCP server implementation.
-
-    DEPRECATED: The MCPServer implementation is deprecated and will be removed in a future version.
-    Mirascope will only implement the client-side of MCP in the future, allowing it to connect to any
-    MCP server implementation, even if not built with Mirascope.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        version: str = "1.0.0",
-        tools: list[Callable | type[BaseTool]] | None = None,
-        resources: list[tuple[Resource, Callable]] | None = None,
-        prompts: list[
-            Callable[
-                ...,
-                list[BaseMessageParam]
-                | Callable[..., Awaitable[list[BaseMessageParam]]],
-            ]
-        ]
-        | None = None,
-    ) -> None:
-        warnings.warn(
-            "MCPServer is deprecated and will be removed in a future version. "
-            "Mirascope will only implement the client-side of MCP in the future. "
-            "We recommend using the official MCP SDK (e.g. `FastMCP`) for server-side implementations.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self.name: str = name
-        self.version: str = version
-        self.server: Server = Server(name)
-        self._tools: dict[str, tuple[Tool, type[MCPTool]]] = {}
-        self._resources: dict[str, tuple[Resource, Callable]] = {}
-        self._prompts: dict[
-            str,
-            tuple[
-                Prompt,
-                Callable[..., Awaitable[list[BaseMessageParam]]]
-                | Callable[..., list[BaseMessageParam]],
-            ],
-        ] = {}
-        if tools:
-            for tool in tools:
-                self.tool()(tool)
-        if resources:
-            for resource, resource_func in resources:
-                self.resource(
-                    uri=str(resource.uri),
-                    name=resource.name,
-                    description=resource.description,
-                    mime_type=resource.mimeType,
-                )(resource_func)
-        if prompts:
-            for prompt in prompts:
-                self._register_prompt(prompt)
-
-    def tool(
-        self,
-    ) -> Callable[[Callable | type[BaseTool]], type[BaseTool]]:
-        """Decorator to register tools."""
-
-        def decorator(
-            tool: Callable | type[BaseTool],
-        ) -> type[BaseTool]:
-            if inspect.isclass(tool):
-                if issubclass(tool, MCPTool):
-                    converted_tool = tool
-                else:
-                    converted_tool = convert_base_model_to_base_tool(
-                        cast(type[BaseModel], tool), MCPTool
-                    )
-            else:
-                converted_tool = convert_function_to_base_tool(tool, MCPTool)
-            tool_schema = converted_tool.tool_schema()
-            name = tool_schema["name"]
-            if name in self._tools:
-                # Raise KeyError if tool name already exists
-                raise KeyError(f"Tool {name} already exists.")
-
-            self._tools[name] = (
-                Tool(
-                    name=name,
-                    description=tool_schema.get("description"),
-                    inputSchema=tool_schema["input_schema"],
-                ),
-                converted_tool,
-            )
-            return converted_tool
-
-        return decorator
-
-    def resource(
-        self,
-        uri: str,
-        name: str | None = None,
-        description: str | None = None,
-        mime_type: str | None = None,
-    ) -> Callable[[Callable], Callable]:
-        """Decorator to register resources."""
-
-        def decorator(func: Callable) -> Callable:
-            # Normalize URI so it always ends with a slash if needed
-            uri_with_slash = uri + "/" if not uri.endswith("/") else uri
-
-            if uri_with_slash in self._resources:
-                # Raise KeyError if resource URI already exists
-                raise KeyError(f"Resource {uri_with_slash} already exists.")
-
-            resource = Resource(
-                uri=cast(AnyUrl, uri_with_slash),
-                name=name or func.__name__,
-                mimeType=mime_type,
-                description=description
-                or parse(func.__doc__ or "").short_description
-                or "",
-            )
-            self._resources[str(resource.uri)] = resource, func
-            return func
-
-        return decorator
-
-    def _register_prompt(self, decorated_func: Callable) -> None:
-        prompt = _generate_prompt_from_function(decorated_func)
-        name = prompt.name
-        if name in self._prompts:
-            # Raise KeyError if prompt name already exists
-            raise KeyError(f"Prompt {name} already exists.")
-
-        self._prompts[prompt.name] = prompt, decorated_func
-
-    @overload
-    def prompt(self, template: str) -> PromptDecorator: ...
-
-    @overload
-    def prompt(self, template: None = None) -> MessagesDecorator: ...
-
-    def prompt(
-        self,
-        template: str | None = None,
-    ) -> PromptDecorator | MessagesDecorator:
-        """Decorator to register prompts."""
-
-        def decorator(
-            func: MessagesSyncFunction | MessagesAsyncFunction,
-        ) -> (
-            Callable[..., Awaitable[list[BaseMessageParam] | BaseDynamicConfig]]
-            | Callable[..., list[BaseMessageParam] | BaseDynamicConfig]
-        ):
-            decorated_prompt = prompt_template(template)(func)
-            self._register_prompt(decorated_prompt)
-            return decorated_prompt
-
-        return decorator  # pyright: ignore [reportReturnType]
-
-    async def run(self) -> None:
-        """Run the MCP server."""
-
-        @self.server.read_resource()
-        async def handle_read_resource(uri: AnyUrl) -> str:
-            resource_and_func = self._resources.get(str(uri))
-            if resource_and_func is None:
-                raise ValueError(f"Unknown resource: {uri}")
-
-            resource, func = resource_and_func
-            if fn_is_async(func):
-                ret = await func()
-            else:
-                ret = func()
-            return ret
-
-        @self.server.list_resources()
-        async def handle_list_resource() -> list[Resource]:
-            return [resource for resource, _ in self._resources.values()]
-
-        @self.server.list_tools()
-        async def list_tools() -> list[Tool]:
-            return [tool for tool, _ in self._tools.values()]
-
-        @self.server.call_tool()
-        async def call_tool(name: str, arguments: dict) -> list[TextContent]:
-            if name not in self._tools:
-                raise KeyError(f"Tool {name} not found.")
-            _, tool_type = self._tools[name]
-
-            tool = tool_type.from_tool_call(
-                tool_call=ToolUseBlock(id=name, name=name, input=arguments)
-            )
-            if fn_is_async(tool.call):
-                result = await tool.call()
-            else:
-                result = tool.call()
-            return [TextContent(type="text", text=result)]
-
-        @self.server.list_prompts()
-        async def handle_list_prompts() -> list[Prompt]:
-            return [prompt for prompt, _ in self._prompts.values()]
-
-        @self.server.get_prompt()
-        async def handle_get_prompt(
-            name: str, arguments: dict[str, str] | None
-        ) -> GetPromptResult:
-            if name not in self._prompts:
-                raise ValueError(f"Unknown prompt: {name}")
-            if arguments is None:
-                arguments = {}
-            prompt, decorated_func = self._prompts[name]
-            if fn_is_async(decorated_func):
-                messages: list[BaseMessageParam] = await decorated_func(**arguments)
-            else:
-                messages = decorated_func(**arguments)
-
-            return GetPromptResult(
-                description=f"{prompt.name} template for {arguments}",
-                messages=[
-                    prompt_message
-                    for message in messages
-                    for prompt_message in _convert_base_message_param_to_prompt_messages(
-                        message
-                    )
-                ],
-            )
-
-        async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
-            await self.server.run(
-                read_stream,
-                write_stream,
-                InitializationOptions(
-                    server_name=self.name,
-                    server_version=self.version,
-                    capabilities=self.server.get_capabilities(
-                        notification_options=NotificationOptions(),
-                        experimental_capabilities={},
-                    ),
-                ),
-            )

mirascope/mcp/tools.py

@@ -1,110 +0,0 @@
-"""The `MCPTool` class for easy tool usage with MCPTool LLM calls.
-
-usage docs: learn/tools.md
-
-DEPRECATED: The MCPTool class is deprecated and will be removed in a future version.
-Mirascope will only implement the client-side of MCP in the future, allowing it to connect to any
-MCP server implementation, even if not built with Mirascope.
-"""
-
-from __future__ import annotations
-
-import warnings
-from typing import Any
-
-from pydantic import BaseModel
-from pydantic.json_schema import SkipJsonSchema
-from typing_extensions import Required, TypedDict
-
-from mirascope.core import BaseTool
-from mirascope.core.base import ToolConfig
-
-
-class ToolParam(TypedDict, total=False):
-    input_schema: Required[dict[str, Any]]
-    name: Required[str]
-    description: str
-
-
-class ToolUseBlock(BaseModel):
-    id: str
-    input: dict[str, Any]
-    name: str
-
-
-class MCPToolToolConfig(ToolConfig, total=False):
-    """A tool configuration for mcp-specific features."""
-
-
-class MCPTool(BaseTool):
-    """A class for defining tools for MCP LLM calls.
-
-    DEPRECATED: The MCPTool class is deprecated and will be removed in a future version.
-    Mirascope will only implement the client-side of MCP in the future.
-
-    Example:
-
-    ```python
-    import asyncio
-
-    from mirascope.mcp import MCPServer
-
-    app = MCPServer("book-recommend")
-
-
-    @app.tool()
-    async def recommend_book(genre: str) -> str:
-        return f"Recommend a {genre} book"
-
-    asyncio.run(app.run())
-    ```
-    """
-
-    __provider__ = "mcp"
-    __tool_config_type__ = MCPToolToolConfig
-
-    tool_call: SkipJsonSchema[ToolUseBlock]
-
-    @classmethod
-    def tool_schema(cls) -> ToolParam:
-        """Constructs a `ToolParam` tool schema from the `BaseModel` schema defined.
-
-        Example:
-        ```python
-        from mirascope.mcp import MCPTool
-
-
-        def format_book(title: str, author: str) -> str:
-            return f"{title} by {author}"
-
-
-        tool_type = MCPTool.type_from_fn(format_book)
-        print(tool_type.tool_schema())  # prints the MCP-specific tool schema
-        ```
-        """
-        # Show deprecation warning
-        warnings.warn(
-            "The MCPTool class is deprecated and will be removed in a future version. "
-            "Mirascope will only implement the client-side of MCP in the future. "
-            "We recommend using the official MCP SDK (e.g. `FastMCP`) for server-side implementations.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        kwargs = {
-            "input_schema": cls.model_json_schema(),
-            "name": cls._name(),
-            "description": cls._description(),
-        }
-        return ToolParam(**kwargs)
-
-    @classmethod
-    def from_tool_call(cls, tool_call: ToolUseBlock) -> MCPTool:
-        """Constructs an `MCPTool` instance from a `tool_call`.
-
-        Args:
-            tool_call: The MCP tool call from which to construct this tool
-                instance.
-        """
-        model_json = {"tool_call": tool_call}
-        model_json |= tool_call.input
-        return cls.model_validate(model_json)

mirascope/retries/__init__.py

@@ -1,11 +0,0 @@
-"""Utilities for retrying failed API calls."""
-
-from contextlib import suppress
-
-from .fallback import FallbackError, fallback
-
-with suppress(ImportError):
-    from . import tenacity as tenacity
-
-
-__all__ = ["FallbackError", "fallback", "tenacity"]