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

mirascope/llm/formatting/format.py

@@ -1,173 +1,32 @@
 """The `llm.format` decorator for defining response formats as classes."""
 
-from __future__ import annotations
-
 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 .output_parser import OutputParser, is_output_parser
-from .primitives import create_wrapper_model, is_primitive_type
-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] | OutputParser[FormattableT]
-    """The formattable type or custom output parser.
-
-    Can be one of:
-    - type[BaseModel]: A Pydantic model class for structured output
-    - PrimitiveType: A primitive type (str, int, list, etc.) for simple output
-    - OutputParser[FormattableT]: A custom parser created with @llm.output_parser
-
-    The type determines how the response will be parsed in response.parse().
-    OutputParser uses Any for the response type since it works with any response.
-    """
-
-    @property
-    def formatting_instructions(self) -> str | None:
-        """The formatting instructions that will be added to the LLM system prompt.
-
-        If the format has a custom `OutputParser`, its formatting instructions will be used.
-        Otherwise, if the format type has a `formatting_instructions` class method,
-        the output of that call will be used. Otherwise, instructions may be
-        auto-generated based on the formatting mode.
-        """
-        if is_output_parser(self.formattable) or 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)
-        elif self.mode == "parser":
-            return None  # pragma: no cover
-
-    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=None,  # Provider determines whether to use strict mode.
-        )
+from ._utils import default_formatting_instructions
+from .types import Format, FormattableT, FormattingMode, HasFormattingInstructions
 
 
 def format(
-    formattable: type[FormattableT] | OutputParser[FormattableT] | None,
+    formattable: type[FormattableT] | None,
     *,
     mode: FormattingMode,
 ) -> Format[FormattableT] | None:
-    """Returns a `Format` that describes structured output or custom parsing.
-
-    This function converts a Formattable type (e.g. Pydantic `BaseModel` or primitive type)
-    or an `OutputParser` into a `Format` object that describes how the output should be
-    formatted and parsed. Calling `llm.format` is optional, as all the APIs that expect
-    a `Format` can also take the Formattable type or `OutputParser` directly. However,
-    calling `llm.format` is necessary in order to specify the formatting mode for
-    `BaseModel`/primitive types.
+    """Returns a `Format` that describes structured output for a Formattable type.
 
-    Primitive types are automatically wrapped in a `BaseModel` with an "output" field
-    for schema generation, then unwrapped during parsing.
+    This function converts a Formattable type (e.g. Pydantic BaseModel) into a `Format`
+    object that describes how the object should be formatted. Calling `llm.format`
+    is optional, as all the APIs that expect a `Format` can also take the Formattable
+    type directly. However, calling `llm.format` is necessary in order to specify the
+    formatting mode that will be used.
 
     Args:
-        formattable: The type or parser to format:
-            - BaseModel type: Uses structured output with JSON schema
-            - Primitive type: Wrapped in schema for structured output
-            - OutputParser: Uses custom parsing with instructions
-        mode: The format mode to use (required):
+        mode: The format mode to use, one of the following:
             - "strict": Use model strict structured outputs, or fail if unavailable.
             - "tool": Use forced tool calling with a special tool that represents a
               formatted response.
             - "json": Use provider json mode if available, or modify prompt to request
               json if not.
-            - "parser": Must be used for OutputParser types.
 
     The Formattable type may provide custom formatting instructions via a
     `formatting_instructions(cls)` classmethod. If that method is present, it will be called,
@@ -178,44 +37,34 @@ def format(
     you can add the `formatting_instructions` classmethod and have it return `None`.
 
     Returns:
-      A `Format` object describing the format type or parser.
+      A `Format` object describing the Formattable type.
 
     Example:
-      Using with a BaseModel:
+      Using with an LLM call:
 
       ```python
       from pydantic import BaseModel
+
       from mirascope import llm
 
+
       class Book(BaseModel):
           title: str
           author: str
 
       format = llm.format(Book, mode="strict")
 
-      @llm.call("openai/gpt-5-mini", format=format)
+      @llm.call(
+          provider="openai:completions",
+          model_id="gpt-4o-mini",
+          format=format,
+      )
       def recommend_book(genre: str):
           return f"Recommend a {genre} book."
 
       response = recommend_book("fantasy")
       book: Book = response.parse()
-      ```
-
-    Example:
-
-      Using with an `OutputParser`:
-
-      ```python
-      @llm.output_parser(
-          formatting_instructions="Return XML: <book><title>...</title></book>"
-      )
-      def parse_book_xml(response: llm.AnyResponse) -> Book:
-          # ... parsing logic ...
-          return Book(...)
-
-      @llm.call("openai/gpt-5-mini", format=parse_book_xml)
-      def recommend_book(genre: str):
-          return f"Recommend a {genre} book."
+      print(f"{book.title} by {book.author}")
       ```
     """
     # TODO: Add caching or memoization to this function (e.g. functools.lru_cache)
@@ -223,71 +72,33 @@ def format(
     if formattable is None or formattable is NoneType:
         return None
 
-    if is_output_parser(formattable):
-        if mode != "parser":
-            raise ValueError(f"mode must be 'parser' for OutputParser, got '{mode}'")
-        return Format[Any](
-            name=formattable.__name__,
-            description=formattable.__doc__,
-            schema={},
-            mode="parser",
-            formattable=formattable,
-        )
-
-    if is_primitive_type(formattable):
-        wrapper_model = create_wrapper_model(formattable)
-        schema = wrapper_model.model_json_schema()
-        name = (
-            formattable.__name__
-            if hasattr(formattable, "__name__")
-            else str(formattable)
-        )
-
-        return Format[FormattableT](
-            name=name,
-            description=None,
-            schema=schema,
-            mode=mode,
-            formattable=formattable,
-        )
-
     description = None
     if formattable.__doc__:
         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,
     )
 
 
 def resolve_format(
-    formattable: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    ),
+    formattable: type[FormattableT] | Format[FormattableT] | None,
     default_mode: FormattingMode,
 ) -> Format[FormattableT] | None:
-    """Resolve a `Format` (or None) from a possible `Format`, Formattable, or `OutputParser`.
-
-    Args:
-        formattable: The format specification:
-            - Format: Returned as-is
-            - BaseModel/primitive type: Converted to Format with default_mode
-            - OutputParser: Converted to Format with mode='parser'
-        default_mode: The mode to use for BaseModel/primitive types.
-
-    Returns:
-        A Format object or None.
-    """
+    """Resolve a `Format` (or None) from a possible `Format` or Formattable."""
     if isinstance(formattable, Format):
         return formattable
-
-    if is_output_parser(formattable):
-        return format(formattable, mode="parser")
-
-    return format(formattable, mode=default_mode)
+    else:
+        return format(formattable, mode=default_mode)

mirascope/llm/formatting/from_call_args.py

@@ -20,8 +20,8 @@ class FromCallArgs:
 
 
     @llm.call(
-        provider_id="openai",
-        model_id="openai/gpt-5-mini",
+        provider="openai:completions",
+        model_id="gpt-4o-mini",
         format=Book,
     )
     def summarize_book(title: str, author: str):

mirascope/llm/formatting/partial.py

@@ -8,16 +8,10 @@ serves as an acknowledgment of the original author's contribution to this projec
 --------------------------------------------------------------------------------
 """
 
-import inspect
-from typing import Any, Generic, NoReturn, Union, cast, get_args, get_origin
-
-from pydantic import BaseModel, create_model
+from typing import Generic, NoReturn
 
 from .format import FormattableT
 
-# Cache for generated partial models to avoid recreation
-_partial_model_cache: dict[type[Any], type[Any]] = {}
-
 
 class Partial(Generic[FormattableT]):
     """Generate a new class with all attributes optionals.
@@ -40,9 +34,7 @@ class Partial(Generic[FormattableT]):
         Raises:
             TypeError: Direct instantiation not allowed.
         """
-        raise TypeError(
-            "Cannot instantiate abstract Partial class."
-        )  # pragma: no cover
+        raise TypeError("Cannot instantiate abstract Partial class.")
 
     def __init_subclass__(
         cls,
@@ -54,78 +46,13 @@ class Partial(Generic[FormattableT]):
         Raises:
            TypeError: Subclassing not allowed.
         """
-        raise TypeError(f"Cannot subclass {cls.__module__}.Partial")  # pragma: no cover
+        raise TypeError(f"Cannot subclass {cls.__module__}.Partial")
 
     def __class_getitem__(
         cls,
         wrapped_class: type[FormattableT],
     ) -> type[FormattableT]:
-        """Convert model to a partial model with all fields being optionals.
-
-        Recursively converts all fields in a Pydantic BaseModel to optional,
-        handling nested models and generic types like list[Book].
-
-        Args:
-            wrapped_class: The BaseModel class to make partial
-
-        Returns:
-            A new BaseModel class with all fields optional (or original if not BaseModel)
-
-        Example:
-            >>> class Author(BaseModel):
-            ...     first_name: str
-            ...     last_name: str
-            >>> class Book(BaseModel):
-            ...     title: str
-            ...     author: Author
-            >>> PartialBook = Partial[Book]
-            >>> partial = PartialBook(title="The Name")
-            >>> partial.author  # None
-        """
-        # Return non-BaseModel types unchanged
-        if not (
-            inspect.isclass(wrapped_class) and issubclass(wrapped_class, BaseModel)
-        ):
-            return wrapped_class
-
-        # Check cache to avoid regenerating
-        if wrapped_class in _partial_model_cache:
-            return cast(type[FormattableT], _partial_model_cache[wrapped_class])
-
-        # Recursively make all fields optional
-        partial_fields: dict[str, Any] = {}
-        for field_name, field_info in wrapped_class.model_fields.items():
-            field_type = field_info.annotation
-
-            # Recursively handle nested BaseModel fields
-            if inspect.isclass(field_type) and issubclass(field_type, BaseModel):
-                field_type = Partial[field_type]
-
-            # Handle generic types with BaseModel args (e.g., list[Book], dict[str, Book])
-            origin = get_origin(field_type)
-            if origin is not None:
-                args = get_args(field_type)
-                # Recursively convert BaseModel args to partial
-                new_args = tuple(
-                    Partial[arg]
-                    if inspect.isclass(arg) and issubclass(arg, BaseModel)
-                    else arg
-                    for arg in args
-                )
-                # Reconstruct generic type with new args
-                if new_args != args:
-                    field_type = origin[new_args]
-
-            # Make field optional with None default
-            optional_type = Union[field_type, None]  # noqa: UP007
-            partial_fields[field_name] = (optional_type, None)
-
-        # Create new model with "Partial" prefix
-        partial_model = create_model(
-            f"Partial{wrapped_class.__name__}", __base__=BaseModel, **partial_fields
-        )
-
-        # Cache the generated model
-        _partial_model_cache[wrapped_class] = partial_model
-
-        return cast(type[FormattableT], partial_model)
+        """Convert model to a partial model with all fields being optionals."""
+        # TODO: Implement proper partial model generation
+        # For now, return the original class to avoid import errors
+        return wrapped_class

mirascope/llm/formatting/types.py

@@ -1,26 +1,18 @@
 """Type for the formatting module."""
 
-from typing import Literal, Protocol, runtime_checkable
+from dataclasses import dataclass
+from typing import Generic, Literal, Protocol, runtime_checkable
 from typing_extensions import TypeVar
 
 from pydantic import BaseModel
 
-from .primitives import PrimitiveType
-
-FormattableT = TypeVar(
-    "FormattableT", bound=BaseModel | PrimitiveType | None, default=None
-)
+# TODO: Support primitive types (e.g. `format=list[Book]`)
+FormattableT = TypeVar("FormattableT", bound=BaseModel | None, default=None)
 """Type variable for structured response format types.
 
 This TypeVar represents the type of structured output format that LLM responses
-can be parsed into, or None if no format is specified.
-
-Supported format types:
-- Pydantic BaseModel subclasses
-- Primitive types: str, int, float, bool, bytes, list, set, tuple, dict
-- Generic collections: list[Book], dict[str, int], etc.
-- Union, Literal, and Annotated types
-- Enum types
+can be parsed into, or None if no format is specified. 
+If format is specified, it must extend Pydantic BaseModel. 
 """
 
 
@@ -28,14 +20,15 @@ FormattingMode = Literal[
     "strict",
     "json",
     "tool",
-    "parser",
 ]
 """Available modes for response format generation.
 
 - "strict": Use strict mode for structured outputs, asking the LLM to strictly adhere
     to a given JSON schema. Not all providers or models support it, and may not be
-    compatible with tool calling. When making a call using this mode, an
-    `llm.FeatureNotSupportedError` error may be raised if the mode is unsupported.
+    compatible with tool calling. When making a call using this mode, an 
+    `llm.FormattingModeNotSupportedError` error may be raised (if "strict" mode is wholly
+    unsupported), or an `llm.FeatureNotSupportedError` may be raised (if trying to use 
+    strict along with tools and that is unsupported).
 
 - "json": Use JSON mode for structured outputs. In contrast to strict mode, we ask the
     LLM to output JSON as text, though without guarantees that the model will output
@@ -50,14 +43,64 @@ FormattingMode = Literal[
     content (abstracting over the tool call). If other tools are present, they will
     be handled as regular tool calls.
 
-- "parser": Use custom parsing with formatting instructions. No schema generation or
-    structured output features. The LLM receives only formatting instructions and the
-    response is parsed using a custom parser function created with `@llm.output_parser`.
-
 Note: When `llm.format` is not used, the provider will automatically choose a mode at call time.
 """
 
 
+@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 .mcp_client import MCPClient, sse_client, stdio_client, streamable_http_client
+from .client import MCPClient, sse_client, stdio_client, streamablehttp_client
 
-__all__ = ["MCPClient", "sse_client", "stdio_client", "streamable_http_client"]
+__all__ = ["MCPClient", "sse_client", "stdio_client", "streamablehttp_client"]

mirascope/llm/mcp/client.py

@@ -0,0 +1,118 @@
+import contextlib
+from collections.abc import AsyncIterator, Callable
+from datetime import timedelta
+
+import httpx
+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.streamable_http import (
+    streamablehttp_client as mcp_streamablehttp_client,
+)
+from mcp.shared._httpx_utils import McpHttpClientFactory
+
+from ..tools import AsyncTool
+
+
+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
+
+    async def list_tools(self) -> list[AsyncTool]:
+        """List all tools available on the MCP server.
+
+        Returns:
+            A list of dynamically created `llm.Tool`s.
+        """
+        raise NotImplementedError()
+
+
+@contextlib.asynccontextmanager
+async def streamablehttp_client(
+    url: str,
+    headers: dict[str, str] | None = None,
+    timeout: float | timedelta | None = None,
+    sse_read_timeout: float | timedelta | None = None,
+    terminate_on_close: bool = True,
+    httpx_client_factory: McpHttpClientFactory | None = None,
+    auth: httpx.Auth | None = None,
+) -> AsyncIterator[MCPClient]:
+    """Create a Mirascope MCPClient using StreamableHTTP."""
+    kwargs = {}
+    if headers is not None:
+        kwargs["headers"] = headers
+    if timeout is not None:
+        kwargs["timeout"] = timeout
+    if sse_read_timeout is not None:
+        kwargs["sse_read_timeout"] = sse_read_timeout
+    if httpx_client_factory is not None:
+        kwargs["httpx_client_factory"] = httpx_client_factory
+    if auth is not None:
+        kwargs["auth"] = auth
+
+    async with (
+        mcp_streamablehttp_client(
+            url,
+            terminate_on_close=terminate_on_close,
+            **kwargs,
+        ) as (read, write, get_session_id),
+        ClientSession(
+            read,
+            write,
+        ) 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 Mirascope MCPClient using stdio."""
+
+    async with (
+        ClientSession(None, None) as session,  # pyright: ignore [reportArgumentType]
+    ):
+        raise NotImplementedError()
+        await session.initialize()
+        yield MCPClient(session)
+
+
+@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]:
+    """Create a Mirascope MCPClient using sse."""
+
+    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)