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

mirascope/llm/formatting/from_call_args.py

@@ -0,0 +1,30 @@
+"""The `FromCallArgs` class annotation for marking a field as a call argument."""
+
+
+class FromCallArgs:
+    """A marker class for indicating that a field is a call argument.
+
+    This ensures that the LLM call does not attempt to generate this field. Instead, it
+    will populate this field with the call argument with a matching name.
+
+    This is useful for colocating e.g. validation of a generated output against and
+    input argument (such as the length of an output given a number input).
+
+    Example:
+
+    ```
+    class Book(BaseModel):
+        title: Annotated[str, llm.formatting.FromCallArgs()]
+        author: Annotated[str, llm.formatting.FromCallArgs()]
+        summary: str
+
+
+    @llm.call(
+        provider_id="openai",
+        model_id="openai/gpt-5-mini",
+        format=Book,
+    )
+    def summarize_book(title: str, author: str):
+        return f"Summarize {title} by {author}."
+    ```
+    """

mirascope/llm/formatting/output_parser.py

@@ -0,0 +1,178 @@
+"""The `llm.output_parser` decorator for creating custom output parsers."""
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from typing_extensions import TypeIs
+
+if TYPE_CHECKING:
+    from ..responses import AnyResponse
+
+OutputT = TypeVar("OutputT")
+
+
+class OutputParser(Generic[OutputT]):
+    """Represents a custom output parser created with @llm.output_parser.
+
+    This class wraps a parsing function and stores formatting instructions.
+    It is created by the @llm.output_parser decorator and used as a format
+    argument in LLM calls.
+
+    Unlike BaseModel and primitive type formats that use structured outputs
+    (JSON schema, tools, strict mode), OutputParser works with raw text responses
+    and custom parsing logic.
+
+    Example:
+        ```python
+        @llm.output_parser(
+            formatting_instructions="Return XML: <book><title>...</title></book>"
+        )
+        def parse_book_xml(response: llm.AnyResponse) -> Book:
+            text = "".join(part.text for part in response.texts)
+            root = ET.fromstring(text)
+            return Book(title=root.find("title").text, ...)
+
+        @llm.call("openai/gpt-4o", format=parse_book_xml)
+        def recommend_book(genre: str):
+            return f"Recommend a {genre} book."
+
+        response = recommend_book("fantasy")
+        book = response.parse()  # Returns Book instance
+        ```
+    """
+
+    def __init__(
+        self,
+        func: Callable[["AnyResponse"], OutputT],
+        formatting_instructions: str,
+    ) -> None:
+        """Initialize the OutputParser.
+
+        Args:
+            func: The parsing function that takes a Response and returns parsed output.
+            formatting_instructions: Instructions for the LLM on how to format output.
+        """
+        self.func = func
+        self._formatting_instructions = formatting_instructions
+        self.__name__ = func.__name__
+        self.__doc__ = func.__doc__
+
+    def formatting_instructions(self) -> str:
+        """Return the formatting instructions for the LLM.
+
+        These instructions are added to the system prompt to guide the LLM
+        on how to format its output for parsing.
+
+        Returns:
+            The formatting instructions string.
+        """
+        return self._formatting_instructions
+
+    def __call__(self, response: "AnyResponse") -> OutputT:
+        """Parse the response using the wrapped function.
+
+        Args:
+            response: The response object from the LLM call.
+
+        Returns:
+            The parsed output of type OutputT.
+
+        Raises:
+            Any exception raised by the wrapped parsing function.
+        """
+        return self.func(response)
+
+
+def output_parser(
+    *,
+    formatting_instructions: str,
+) -> Callable[[Callable[["AnyResponse"], OutputT]], OutputParser[OutputT]]:
+    """Decorator to create an output parser for custom format parsing.
+
+    Use this decorator to create custom parsers for non-JSON formats like
+    XML, YAML, CSV, or any custom text structure. The decorated function
+    receives the full Response object and returns the parsed output.
+
+    This is the recommended way to handle custom output formats that don't
+    fit the JSON/BaseModel paradigm. The formatting instructions guide the
+    LLM on how to structure its output, and the parsing function extracts
+    the data you need.
+
+    Args:
+        formatting_instructions: Instructions for the LLM on how to format
+            the output. These will be added to the system prompt.
+
+    Returns:
+        Decorator that converts a function into an OutputParser.
+
+    Example:
+
+        XML parsing:
+        ```python
+        @llm.output_parser(
+            formatting_instructions='''
+            Return the book information in this XML structure:
+            <book>
+                <title>Book Title</title>
+                <author>Author Name</author>
+                <rating>5</rating>
+            </book>
+            '''
+        )
+        def parse_book_xml(response: llm.AnyResponse) -> Book:
+            import xml.etree.ElementTree as ET
+            text = "".join(part.text for part in response.texts)
+            root = ET.fromstring(text)
+            return Book(
+                title=root.find("title").text,
+                author=root.find("author").text,
+                rating=int(root.find("rating").text),
+            )
+        ```
+
+    Example:
+
+        CSV parsing:
+        ```python
+        @llm.output_parser(
+            formatting_instructions='''
+            Return book information as CSV format with header:
+            title,author,rating
+            Book 1,Author 1,5
+            Book 2,Author 2,4
+            '''
+        )
+        def parse_books_csv(response: llm.AnyResponse) -> list[Book]:
+            text = "".join(part.text for part in response.texts)
+            lines = text.strip().split('\\n')[1:]  # Skip header
+            return [
+                Book(
+                    title=line.split(',')[0].strip(),
+                    author=line.split(',')[1].strip(),
+                    rating=int(line.split(',')[2]),
+                )
+                for line in lines
+            ]
+        ```
+    """
+
+    def decorator(
+        func: Callable[["AnyResponse"], OutputT],
+    ) -> OutputParser[OutputT]:
+        return OutputParser(func, formatting_instructions)
+
+    return decorator
+
+
+def is_output_parser(obj: Any) -> TypeIs[OutputParser[Any]]:  # noqa: ANN401
+    """Check if an object is an OutputParser.
+
+    This is a type guard function that narrows the type of `obj` to
+    `OutputParser[Any, Any]` when it returns True.
+
+    Args:
+        obj: The object to check.
+
+    Returns:
+        True if the object is an OutputParser instance, False otherwise.
+    """
+    return isinstance(obj, OutputParser)

mirascope/llm/formatting/partial.py

@@ -0,0 +1,131 @@
+"""
+--------------------------------------------------------------------------------
+Source: https://github.com/pydantic/pydantic/issues/6381#issuecomment-1831607091
+By: silviumarcu
+
+This code is used in accordance with the repository's license, and this reference
+serves as an acknowledgment of the original author's contribution to this project.
+--------------------------------------------------------------------------------
+"""
+
+import inspect
+from typing import Any, Generic, NoReturn, Union, cast, get_args, get_origin
+
+from pydantic import BaseModel, create_model
+
+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.
+
+    Notes:
+        This will wrap a class inheriting form BaseModel and will recursively
+        convert all its attributes and its children's attributes to optionals.
+
+    Example:
+        Partial[SomeModel]
+    """
+
+    def __new__(
+        cls,
+        *args: object,  # noqa :ARG003
+        **kwargs: object,  # noqa :ARG003
+    ) -> "Partial[FormattableT]":
+        """Cannot instantiate.
+
+        Raises:
+            TypeError: Direct instantiation not allowed.
+        """
+        raise TypeError(
+            "Cannot instantiate abstract Partial class."
+        )  # pragma: no cover
+
+    def __init_subclass__(
+        cls,
+        *args: object,
+        **kwargs: object,
+    ) -> NoReturn:
+        """Cannot subclass.
+
+        Raises:
+           TypeError: Subclassing not allowed.
+        """
+        raise TypeError(f"Cannot subclass {cls.__module__}.Partial")  # pragma: no cover
+
+    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)

mirascope/llm/formatting/primitives.py

@@ -0,0 +1,192 @@
+"""Utilities for handling primitive types in formatting."""
+
+import inspect
+from enum import Enum
+from types import UnionType
+from typing import (
+    Annotated,
+    Any,
+    Literal,
+    Protocol,
+    TypeAlias,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+)
+from typing_extensions import TypeIs
+
+from pydantic import create_model
+
+PrimitiveType: TypeAlias = (
+    str
+    | int
+    | float
+    | bool
+    | bytes
+    | list[Any]
+    | set[Any]
+    | tuple[Any, ...]
+    | dict[Any, Any]
+)
+"""Primitive types that can be used with format parameter.
+
+These types are automatically wrapped in a BaseModel for schema generation,
+then unwrapped after validation to return the primitive value.
+"""
+
+
+class PrimitiveWrapperModel(Protocol):
+    """Protocol for wrapper models with an output field."""
+
+    output: Any
+    model_fields: Any
+
+    def __init__(self, *, output: Any) -> None: ...  # noqa: ANN401
+
+    @classmethod
+    def model_json_schema(cls) -> dict[str, Any]: ...
+
+    @classmethod
+    def model_validate_json(cls, json_data: str) -> "PrimitiveWrapperModel": ...
+
+
+def is_primitive_type(
+    type_: Any,  # noqa: ANN401
+) -> TypeIs[type[PrimitiveType]]:
+    """Check if a type is a primitive type that needs wrapping.
+
+    Returns True for:
+    - Basic primitives: str, int, float, bool, bytes, list, set, tuple, dict
+    - Enum types
+    - Generic types with primitive origins: list[Book], dict[str, int]
+    - Literal types
+    - Union types (including Optional)
+    - Annotated types
+
+    Returns False for:
+    - BaseModel subclasses (already have model_json_schema)
+    - None/NoneType
+
+    Args:
+        type_: The type to check
+
+    Returns:
+        True if the type is a primitive that needs wrapping
+
+    Example:
+        >>> is_primitive_type(str)
+        True
+        >>> is_primitive_type(list[int])
+        True
+        >>> from pydantic import BaseModel
+        >>> class Book(BaseModel):
+        ...     title: str
+        >>> is_primitive_type(Book)
+        False
+    """
+    primitive_types: set[type[PrimitiveType]] = {
+        str,
+        int,
+        float,
+        bool,
+        bytes,
+        list,
+        set,
+        tuple,
+        dict,
+    }
+    special_types: set[Any] = {Annotated, Literal, Union, UnionType}
+
+    return (
+        (inspect.isclass(type_) and issubclass(type_, Enum))
+        or type_ in primitive_types
+        or get_origin(type_) in primitive_types.union(special_types)
+    )
+
+
+def _get_type_name(type_: Any) -> str:  # noqa: ANN401
+    """Extract a clean name from a type for use in model naming.
+
+    Handles Annotated types by extracting the underlying type,
+    and generates clean names for generic types.
+
+    Args:
+        type_: The type to extract a name from
+
+    Returns:
+        A clean string suitable for use in a Python class name
+
+    Example:
+        >>> _get_type_name(str)
+        'str'
+        >>> _get_type_name(list[int])
+        'list_int_'
+    """
+    # Import Annotated locally
+    # Check if this is an Annotated type
+    if get_origin(type_) in {Annotated}:
+        # For Annotated types, use the first arg (the actual type)
+        return _get_type_name(get_args(type_)[0])
+
+    # If the type has a __name__ attribute, use it
+    if hasattr(type_, "__name__"):
+        return type_.__name__
+
+    # For complex generics like list[Book], use string representation
+    type_str = str(type_)
+
+    # Clean up the string to make it a valid Python identifier
+    # Replace brackets and commas with underscores
+    clean = (
+        type_str.replace("[", "_")
+        .replace("]", "_")
+        .replace(", ", "_")
+        .replace(" ", "")
+        .replace("'", "")
+        .replace('"', "")
+    )
+
+    return clean
+
+
+def create_wrapper_model(
+    primitive_type: Any,  # noqa: ANN401
+) -> type[PrimitiveWrapperModel]:
+    """Create a wrapper BaseModel for a primitive type.
+
+    The wrapper has a single field called "output" containing the primitive value.
+    Uses Pydantic's create_model() to generate the wrapper dynamically.
+
+    Args:
+        primitive_type: The primitive type to wrap
+
+    Returns:
+        A dynamically created BaseModel with an "output" field
+
+    Example:
+        >>> wrapper = create_wrapper_model(str)
+        >>> instance = wrapper(output="hello")
+        >>> instance.output
+        'hello'
+
+        >>> from pydantic import BaseModel
+        >>> class Book(BaseModel):
+        ...     title: str
+        >>> wrapper = create_wrapper_model(list[Book])
+        >>> books = [Book(title="Test")]
+        >>> instance = wrapper(output=books)
+        >>> len(instance.output)
+        1
+    """
+    # Get a clean name for the wrapper class
+    type_name = _get_type_name(primitive_type)
+
+    # Create wrapper model with "output" field (required)
+    wrapper = create_model(
+        f"{type_name}Output",
+        __doc__=f"Wrapper for primitive type {type_name}",
+        output=(primitive_type, ...),  # ... means required
+    )
+
+    return cast(type[PrimitiveWrapperModel], wrapper)

mirascope/llm/formatting/types.py

@@ -0,0 +1,83 @@
+"""Type for the formatting module."""
+
+from typing import TYPE_CHECKING, Literal, Protocol, runtime_checkable
+from typing_extensions import TypeAliasType, TypeVar
+
+from pydantic import BaseModel
+
+from .primitives import PrimitiveType
+
+if TYPE_CHECKING:
+    from .format import Format
+    from .output_parser import OutputParser
+
+FormattableT = TypeVar(
+    "FormattableT", bound=BaseModel | PrimitiveType | None, default=None
+)
+
+FormatSpec = TypeAliasType(
+    "FormatSpec",
+    "type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT]",
+    type_params=(FormattableT,),
+)
+"""Type alias for format parameter types.
+
+A FormatSpec can be:
+- A type (class) that represents the format schema (e.g., a Pydantic BaseModel)
+- A Format wrapper that includes mode and other metadata
+- An OutputParser for custom parsing logic
+"""
+"""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
+"""
+
+
+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.
+
+- "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
+    the expected format schema. If the provider has explicit JSON mode, it will be used;
+    otherwise, Mirascope will modify the system prompt to request JSON output. May
+    raise an `llm.FeatureNotSupportedError` if tools are present and the
+    model does not support tool calling when using JSON mode.
+
+- "tool": Use forced tool calling to structure outputs. Mirascope will construct an
+    ad-hoc tool with the required json schema as tool args. When the LLM chooses that
+    tool, it will automatically be converted from a `ToolCall` into regular response
+    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.
+"""
+
+
+@runtime_checkable
+class HasFormattingInstructions(Protocol):
+    """Protocol for classes that have been decorated with `@format()`."""
+
+    @classmethod
+    def formatting_instructions(cls) -> str | None: ...

mirascope/llm/mcp/__init__.py

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