mirascope 2.0.0a4__py3-none-any.whl → 2.0.0a6__py3-none-any.whl

mirascope/llm/__init__.py

@@ -92,8 +92,10 @@ from .providers import (
     Params,
     Provider,
     ProviderId,
-    load_provider,
+    ThinkingConfig,
+    ThinkingLevel,
     register_provider,
+    reset_provider_registry,
 )
 from .responses import (
     AsyncChunkIterator,
@@ -205,6 +207,8 @@ __all__ = [
     "TextEndChunk",
     "TextStartChunk",
     "TextStream",
+    "ThinkingConfig",
+    "ThinkingLevel",
     "Thought",
     "ThoughtChunk",
     "ThoughtEndChunk",
@@ -232,7 +236,6 @@ __all__ = [
     "exceptions",
     "format",
     "formatting",
-    "load_provider",
     "mcp",
     "messages",
     "model",
@@ -242,6 +245,7 @@ __all__ = [
     "prompts",
     "providers",
     "register_provider",
+    "reset_provider_registry",
     "responses",
     "tool",
     "tools",

mirascope/llm/content/tool_call.py

@@ -49,6 +49,9 @@ class ToolCallChunk:
     content_type: Literal["tool_call"] = "tool_call"
     """The type of content reconstructed by this chunk."""
 
+    id: str
+    """A unique identifier for this tool call."""
+
     delta: str
     """The incremental json args added in this chunk."""
 
@@ -61,3 +64,6 @@ class ToolCallEndChunk:
 
     content_type: Literal["tool_call"] = "tool_call"
     """The type of content reconstructed by this chunk."""
+
+    id: str
+    """A unique identifier for this tool call."""

mirascope/llm/exceptions.py

@@ -11,6 +11,7 @@ class MirascopeLLMError(Exception):
     """Base exception for all Mirascope LLM errors."""
 
     original_exception: Exception | None
+    provider: "ProviderId | None"
 
 
 class APIError(MirascopeLLMError):
@@ -18,6 +19,10 @@ class APIError(MirascopeLLMError):
 
     status_code: int | None
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
 
 class ConnectionError(MirascopeLLMError):
     """Raised when unable to connect to the API (network issues, timeouts)."""
@@ -26,18 +31,30 @@ class ConnectionError(MirascopeLLMError):
 class AuthenticationError(APIError):
     """Raised for authentication failures (401, invalid API keys)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 401)
+
 
 class PermissionError(APIError):
     """Raised for permission/authorization failures (403)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 403)
+
 
 class BadRequestError(APIError):
     """Raised for malformed requests (400, 422)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 400)
+
 
 class NotFoundError(APIError):
     """Raised when requested resource is not found (404)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 404)
+
 
 class ToolNotFoundError(MirascopeLLMError):
     """Raised if a tool_call cannot be converted to any corresponding tool."""
@@ -96,15 +113,26 @@ class FormattingModeNotSupportedError(FeatureNotSupportedError):
 class RateLimitError(APIError):
     """Raised when rate limits are exceeded (429)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 429)
+
 
 class ServerError(APIError):
     """Raised for server-side errors (500+)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 500)
+
 
 class TimeoutError(MirascopeLLMError):
     """Raised when requests timeout or deadline exceeded."""
 
 
+# This wraps the APIResponseValidationErrors that OpenAI and Anthropic both return.
+class ResponseValidationError(MirascopeLLMError):
+    """Raised when API response fails validation."""
+
+
 class NoRegisteredProviderError(MirascopeLLMError):
     """Raised when no provider is registered for a given model_id."""
 

mirascope/llm/formatting/__init__.py

@@ -5,10 +5,10 @@ The `@format` decorator can be applied to classes to specify how LLM
 outputs should be structured and parsed.
 """
 
-from .format import format, resolve_format
+from .format import Format, format, resolve_format
 from .from_call_args import FromCallArgs
 from .partial import Partial
-from .types import Format, FormattableT, FormattingMode
+from .types import FormattableT, FormattingMode
 
 __all__ = [
     "Format",

mirascope/llm/formatting/format.py

@@ -1,10 +1,128 @@
 """The `llm.format` decorator for defining response formats as classes."""
 
 import inspect
+import json
+from dataclasses import dataclass
+from typing import Any, Generic, cast
 
+from ..tools import FORMAT_TOOL_NAME, ToolFn, ToolParameterSchema, ToolSchema
 from ..types import NoneType
-from ._utils import default_formatting_instructions
-from .types import Format, FormattableT, FormattingMode, HasFormattingInstructions
+from .types import FormattableT, FormattingMode, HasFormattingInstructions
+
+TOOL_MODE_INSTRUCTIONS = f"""Always respond to the user's query using the {FORMAT_TOOL_NAME} tool for structured output."""
+
+
+JSON_MODE_INSTRUCTIONS = (
+    "Respond only with valid JSON that matches this exact schema:\n{json_schema}"
+)
+
+
+@dataclass(kw_only=True)
+class Format(Generic[FormattableT]):
+    """Class representing a structured output format for LLM responses.
+
+    A `Format` contains metadata needed to describe a structured output type
+    to the LLM, including the expected schema. This class is not instantiated directly,
+    but is created by calling `llm.format`, or is automatically generated by LLM
+    providers when a `Formattable` is passed to a call method.
+
+    Example:
+
+      ```python
+      from mirascope import llm
+
+      class Book:
+          title: str
+          author: str
+
+      print(llm.format(Book, mode="tool"))
+      ```
+    """
+
+    name: str
+    """The name of the response format."""
+
+    description: str | None
+    """A description of the response format, if available."""
+
+    schema: dict[str, object]
+    """JSON schema representation of the structured output format."""
+
+    mode: FormattingMode
+    """The decorator-provided mode of the response format. 
+    
+    Determines how the LLM call may be modified in order to extract the expected format.
+    """
+
+    formattable: type[FormattableT]
+    """The `Formattable` type that this `Format` describes.
+    
+    While the `FormattbleT` typevar allows for `None`, a `Format` will never be
+    constructed when the `FormattableT` is `None`, so you may treat this as 
+    a `RequiredFormattableT` in practice.
+    """
+
+    @property
+    def formatting_instructions(self) -> str | None:
+        """The formatting instructions that will be added to the LLM system prompt.
+
+        If the format type has a `formatting_instructions` class method, the output of that
+        call will be used for instructions. Otherwise, instructions may be auto-generated
+        based on the formatting mode.
+        """
+        if isinstance(self.formattable, HasFormattingInstructions):
+            return self.formattable.formatting_instructions()
+        if self.mode == "tool":
+            return TOOL_MODE_INSTRUCTIONS
+        elif self.mode == "json":
+            json_schema = json.dumps(self.schema, indent=2)
+            instructions = JSON_MODE_INSTRUCTIONS.format(json_schema=json_schema)
+            return inspect.cleandoc(instructions)
+
+    def create_tool_schema(
+        self,
+    ) -> ToolSchema[ToolFn[..., None]]:
+        """Generate a `ToolSchema` for parsing this format.
+
+        Returns:
+            `ToolSchema` for the format tool
+        """
+
+        schema_dict: dict[str, Any] = self.schema.copy()
+        schema_dict["type"] = "object"
+
+        properties = schema_dict.get("properties")
+        if not properties or not isinstance(properties, dict):
+            properties = {}  # pragma: no cover
+        properties = cast(dict[str, Any], properties)
+        required: list[str] = list(properties.keys())
+
+        description = (
+            f"Use this tool to extract data in {self.name} format for a final response."
+        )
+        if self.description:
+            description += "\n" + self.description
+
+        parameters = ToolParameterSchema(
+            properties=properties,
+            required=required,
+            additionalProperties=False,
+        )
+        if "$defs" in schema_dict and isinstance(schema_dict["$defs"], dict):
+            parameters.defs = schema_dict["$defs"]
+
+        def _unused_format_fn() -> None:
+            raise TypeError(
+                "Format tool function should not be called."
+            )  # pragma: no cover
+
+        return ToolSchema(
+            fn=cast(ToolFn[..., None], _unused_format_fn),
+            name=FORMAT_TOOL_NAME,
+            description=description,
+            parameters=parameters,
+            strict=True,
+        )
 
 
 def format(
@@ -77,18 +195,12 @@ def format(
         description = inspect.cleandoc(formattable.__doc__)
 
     schema = formattable.model_json_schema()
-    formatting_instructions = None
-    if isinstance(formattable, HasFormattingInstructions):
-        formatting_instructions = formattable.formatting_instructions()
-    else:
-        formatting_instructions = default_formatting_instructions(schema, mode)
 
     return Format[FormattableT](
         name=formattable.__name__,
         description=description,
         schema=schema,
         mode=mode,
-        formatting_instructions=formatting_instructions,
         formattable=formattable,
     )
 

mirascope/llm/formatting/types.py

@@ -1,7 +1,6 @@
 """Type for the formatting module."""
 
-from dataclasses import dataclass
-from typing import Generic, Literal, Protocol, runtime_checkable
+from typing import Literal, Protocol, runtime_checkable
 from typing_extensions import TypeVar
 
 from pydantic import BaseModel
@@ -47,60 +46,6 @@ Note: When `llm.format` is not used, the provider will automatically choose a mo
 """
 
 
-@dataclass(kw_only=True)
-class Format(Generic[FormattableT]):
-    """Class representing a structured output format for LLM responses.
-
-    A `Format` contains metadata needed to describe a structured output type
-    to the LLM, including the expected schema. This class is not instantiated directly,
-    but is created by calling `llm.format`, or is automatically generated by LLM
-    providers when a `Formattable` is passed to a call method.
-
-    Example:
-
-      ```python
-      from mirascope import llm
-
-      class Book:
-          title: str
-          author: str
-
-      print(llm.format(Book, mode="tool"))
-      ```
-    """
-
-    name: str
-    """The name of the response format."""
-
-    description: str | None
-    """A description of the response format, if available."""
-
-    schema: dict[str, object]
-    """JSON schema representation of the structured output format."""
-
-    mode: FormattingMode
-    """The decorator-provided mode of the response format. 
-    
-    Determines how the LLM call may be modified in order to extract the expected format.
-    """
-
-    formatting_instructions: str | None
-    """The formatting instructions that will be added to the LLM system prompt.
-
-    If the format type has a `formatting_instructions` class method, the output of that
-    call will be used for instructions. Otherwise, instructions may be auto-generated
-    based on the formatting mode.
-    """
-
-    formattable: type[FormattableT]
-    """The `Formattable` type that this `Format` describes.
-    
-    While the `FormattbleT` typevar allows for `None`, a `Format` will never be
-    constructed when the `FormattableT` is `None`, so you may treat this as 
-    a `RequiredFormattableT` in practice.
-    """
-
-
 @runtime_checkable
 class HasFormattingInstructions(Protocol):
     """Protocol for classes that have been decorated with `@format()`."""

mirascope/llm/mcp/__init__.py

@@ -1,5 +1,5 @@
 """MCP compatibility module."""
 
-from .client import MCPClient, sse_client, stdio_client, streamablehttp_client
+from .mcp_client import MCPClient, sse_client, stdio_client, streamable_http_client
 
-__all__ = ["MCPClient", "sse_client", "stdio_client", "streamablehttp_client"]
+__all__ = ["MCPClient", "sse_client", "stdio_client", "streamable_http_client"]

mirascope/llm/mcp/mcp_client.py

@@ -0,0 +1,130 @@
+import contextlib
+from collections.abc import AsyncIterator
+from datetime import timedelta
+from typing import cast
+
+from mcp import ClientSession
+from mcp.client.sse import sse_client as mcp_sse_client
+from mcp.client.stdio import StdioServerParameters, stdio_client as mcp_stdio_client
+from mcp.client.streamable_http import (
+    streamable_http_client as mcp_streamable_http_client,
+)
+from mcp.types import CallToolResult, Tool as MCPTool
+
+from ..tools import AsyncTool
+from ..tools.tool_schema import ToolParameterSchema
+from ..types import Jsonable
+
+
+class MCPClient:
+    """Mirascope wrapper around a MCP ClientSession.
+
+    It provides a way to get MCP results that are pre-converted into Mirascope-friendly
+    types.
+
+    The underlying MCP ClientSession may be accessed by .session if needed.
+    """
+
+    def __init__(self, session: ClientSession) -> None:
+        self._session = session
+
+    @property
+    def session(self) -> ClientSession:
+        """Access the underlying MCP ClientSession if needed."""
+        return self._session
+
+    def _convert_mcp_tool_to_async_tool(self, mcp_tool: MCPTool) -> AsyncTool:
+        """Convert an MCP Tool to a Mirascope AsyncTool.
+
+        Args:
+            mcp_tool: The MCP tool to convert.
+
+        Returns:
+            An `AsyncTool` that wraps the MCP tool.
+        """
+
+        # Create an async function that calls the MCP tool
+        async def tool_fn(**kwargs: object) -> Jsonable:
+            tool_result: CallToolResult = await self._session.call_tool(
+                mcp_tool.name, kwargs
+            )
+            # Convert ContentBlock objects to JSON-serializable dicts
+            # Cast to Jsonable since model_dump() returns dict[str, Any]
+            return cast(
+                Jsonable, [content.model_dump() for content in tool_result.content]
+            )
+
+        # Convert MCP tool's inputSchema to Mirascope's ToolParameterSchema
+        input_schema = mcp_tool.inputSchema
+        parameters = ToolParameterSchema(
+            properties=input_schema.get("properties", {}),
+            required=input_schema.get("required", []),
+            additionalProperties=input_schema.get("additionalProperties", False),
+        )
+        if "$defs" in input_schema:
+            parameters.defs = input_schema["$defs"]
+
+        # Create the AsyncTool instance
+        return AsyncTool(
+            fn=tool_fn,
+            name=mcp_tool.name,
+            description=mcp_tool.description or mcp_tool.name,
+            parameters=parameters,
+            strict=False,
+        )
+
+    async def list_tools(self) -> list[AsyncTool]:
+        """List all tools available on the MCP server.
+
+        Returns:
+            A list of dynamically created `AsyncTool`s.
+        """
+        result = await self._session.list_tools()
+        return [self._convert_mcp_tool_to_async_tool(tool) for tool in result.tools]
+
+
+@contextlib.asynccontextmanager
+async def streamable_http_client(
+    url: str,
+) -> AsyncIterator[MCPClient]:  # pragma: no cover
+    """Create a Mirascope MCPClient using StreamableHTTP."""
+    # NOTE: If updating this function, unskip and manually run the TestTransportModes
+    # tests in test_mcp_client.py. (Skipped because they are flaky)
+    async with (
+        mcp_streamable_http_client(url) as (read, write, _),
+        ClientSession(read, write) as session,
+    ):
+        await session.initialize()
+        yield MCPClient(session)
+
+
+@contextlib.asynccontextmanager
+async def stdio_client(
+    server_parameters: StdioServerParameters,
+    name: str | None = None,
+) -> AsyncIterator[MCPClient]:
+    """Create a Mirascope MCPClient using stdio."""
+    async with (
+        mcp_stdio_client(server_parameters) as (read, write),
+        ClientSession(read, write) as session,
+    ):
+        await session.initialize()
+        yield MCPClient(session)
+
+
+@contextlib.asynccontextmanager
+async def sse_client(
+    url: str,
+    read_timeout_seconds: timedelta | None = None,
+) -> AsyncIterator[MCPClient]:  # pragma: no cover
+    """Create a Mirascope MCPClient using sse."""
+    # NOTE: If updating this function, unskip and manually run the TestTransportModes
+    # tests in test_mcp_client.py. (Skipped because they are flaky)
+    async with (
+        mcp_sse_client(url) as (read, write),
+        ClientSession(
+            read, write, read_timeout_seconds=read_timeout_seconds
+        ) as session,
+    ):
+        await session.initialize()
+        yield MCPClient(session)

mirascope/llm/providers/__init__.py

@@ -1,12 +1,27 @@
 """Interfaces for LLM providers."""
 
+from ..._stubs import stub_module_if_missing
+
+# Stub modules for missing optional dependencies BEFORE importing
+# This must happen before any imports from these modules
+# Note: We only stub top-level provider modules, not their submodules.
+# The _StubModule will automatically handle nested attribute access.
+stub_module_if_missing("mirascope.llm.providers.anthropic", "anthropic")
+stub_module_if_missing("mirascope.llm.providers.google", "google")
+stub_module_if_missing("mirascope.llm.providers.mlx", "mlx")
+stub_module_if_missing("mirascope.llm.providers.openai", "openai")
+stub_module_if_missing("mirascope.llm.providers.together", "openai")
+stub_module_if_missing("mirascope.llm.providers.ollama", "openai")
+
+# Now imports work regardless of which packages are installed
+# ruff: noqa: E402
 from .anthropic import (
     AnthropicModelId,
     AnthropicProvider,
 )
-from .base import BaseProvider, Params, Provider
+from .base import BaseProvider, Params, Provider, ThinkingConfig, ThinkingLevel
 from .google import GoogleModelId, GoogleProvider
-from .load_provider import load, load_provider
+from .mirascope import MirascopeProvider
 from .mlx import MLXModelId, MLXProvider
 from .model_id import ModelId
 from .ollama import OllamaProvider
@@ -16,7 +31,11 @@ from .openai import (
 )
 from .openai.completions import BaseOpenAICompletionsProvider
 from .provider_id import KNOWN_PROVIDER_IDS, ProviderId
-from .provider_registry import get_provider_for_model, register_provider
+from .provider_registry import (
+    get_provider_for_model,
+    register_provider,
+    reset_provider_registry,
+)
 from .together import TogetherProvider
 
 __all__ = [
@@ -29,6 +48,7 @@ __all__ = [
     "GoogleProvider",
     "MLXModelId",
     "MLXProvider",
+    "MirascopeProvider",
     "ModelId",
     "OllamaProvider",
     "OpenAIModelId",
@@ -36,9 +56,10 @@ __all__ = [
     "Params",
     "Provider",
     "ProviderId",
+    "ThinkingConfig",
+    "ThinkingLevel",
     "TogetherProvider",
     "get_provider_for_model",
-    "load",
-    "load_provider",
     "register_provider",
+    "reset_provider_registry",
 ]

mirascope/llm/providers/anthropic/__init__.py

@@ -1,26 +1,8 @@
 """Anthropic client implementation."""
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .beta_provider import AnthropicBetaProvider
-    from .model_id import AnthropicModelId
-    from .provider import AnthropicProvider
-else:
-    try:
-        from .beta_provider import AnthropicBetaProvider
-        from .model_id import AnthropicModelId
-        from .provider import AnthropicProvider
-    except ImportError:  # pragma: no cover
-        from .._missing_import_stubs import (
-            create_provider_stub,
-        )
-
-        AnthropicBetaProvider = create_provider_stub(
-            "anthropic", "AnthropicBetaProvider"
-        )
-        AnthropicProvider = create_provider_stub("anthropic", "AnthropicProvider")
-        AnthropicModelId = str
+from .beta_provider import AnthropicBetaProvider
+from .model_id import AnthropicModelId
+from .provider import AnthropicProvider
 
 __all__ = [
     "AnthropicBetaProvider",

mirascope/llm/providers/anthropic/_utils/__init__.py

@@ -9,8 +9,10 @@ from .encode import (
     encode_request,
     process_params,
 )
+from .errors import ANTHROPIC_ERROR_MAP
 
 __all__ = [
+    "ANTHROPIC_ERROR_MAP",
     "DEFAULT_FORMAT_MODE",
     "DEFAULT_MAX_TOKENS",
     "AnthropicImageMimeType",

mirascope/llm/providers/anthropic/_utils/beta_decode.py

@@ -174,7 +174,9 @@ class _BetaChunkProcessor:
                         f"Received input_json_delta for {self.current_block_param['type']} block"
                     )
                 self.accumulated_tool_json += delta.partial_json
-                yield ToolCallChunk(delta=delta.partial_json)
+                yield ToolCallChunk(
+                    id=self.current_block_param["id"], delta=delta.partial_json
+                )
             elif delta.type == "thinking_delta":
                 if self.current_block_param["type"] != "thinking":  # pragma: no cover
                     raise RuntimeError(
@@ -211,7 +213,7 @@ class _BetaChunkProcessor:
                     if self.accumulated_tool_json
                     else {}
                 )
-                yield ToolCallEndChunk()
+                yield ToolCallEndChunk(id=self.current_block_param["id"])
             elif block_type == "thinking":
                 yield ThoughtEndChunk()
             else: