mirascope 2.0.0a6__py3-none-any.whl → 2.0.1__py3-none-any.whl

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

@@ -8,10 +8,16 @@ serves as an acknowledgment of the original author's contribution to this projec
 --------------------------------------------------------------------------------
 """
 
-from typing import Generic, NoReturn
+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.
@@ -34,7 +40,9 @@ class Partial(Generic[FormattableT]):
         Raises:
             TypeError: Direct instantiation not allowed.
         """
-        raise TypeError("Cannot instantiate abstract Partial class.")
+        raise TypeError(
+            "Cannot instantiate abstract Partial class."
+        )  # pragma: no cover
 
     def __init_subclass__(
         cls,
@@ -46,13 +54,78 @@ class Partial(Generic[FormattableT]):
         Raises:
            TypeError: Subclassing not allowed.
         """
-        raise TypeError(f"Cannot subclass {cls.__module__}.Partial")
+        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."""
-        # TODO: Implement proper partial model generation
-        # For now, return the original class to avoid import errors
-        return wrapped_class
+        """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

@@ -5,13 +5,22 @@ from typing_extensions import TypeVar
 
 from pydantic import BaseModel
 
-# TODO: Support primitive types (e.g. `format=list[Book]`)
-FormattableT = TypeVar("FormattableT", bound=BaseModel | None, default=None)
+from .primitives import PrimitiveType
+
+FormattableT = TypeVar(
+    "FormattableT", bound=BaseModel | PrimitiveType | 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. 
-If format is specified, it must extend Pydantic BaseModel. 
+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
 """
 
 
@@ -19,15 +28,14 @@ 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.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).
+    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
@@ -42,6 +50,10 @@ 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.
 """
 

mirascope/llm/messages/__init__.py

@@ -5,6 +5,7 @@ as a unified `Message` class with different roles (system, user, assistant) and
 content arrays that can include text, images, audio, documents, and tool interactions.
 """
 
+from ._utils import is_messages, promote_to_messages
 from .message import (
     AssistantContent,
     AssistantMessage,
@@ -27,6 +28,8 @@ __all__ = [
     "UserContent",
     "UserMessage",
     "assistant",
+    "is_messages",
+    "promote_to_messages",
     "system",
     "user",
 ]

mirascope/llm/messages/_utils.py

@@ -0,0 +1,34 @@
+"""Utility functions for message handling."""
+
+from collections.abc import Sequence
+from typing_extensions import TypeIs
+
+from .message import (
+    AssistantMessage,
+    Message,
+    SystemMessage,
+    UserContent,
+    UserMessage,
+    user,
+)
+
+
+def is_messages(
+    content: UserContent | Sequence[Message],
+) -> TypeIs[Sequence[Message]]:
+    if isinstance(content, list):
+        if not content:
+            raise ValueError("Empty array may not be used as message content")
+        return isinstance(content[0], SystemMessage | UserMessage | AssistantMessage)
+    return False
+
+
+def promote_to_messages(content: UserContent | Sequence[Message]) -> Sequence[Message]:
+    """Promote a prompt result to a list of messages.
+
+    If the result is already a list of Messages, returns it as-is.
+    If the result is str/UserContentPart/Sequence of content parts, wraps it in a user message.
+    """
+    if is_messages(content):
+        return content
+    return [user(content)]

mirascope/llm/models/__init__.py

@@ -7,9 +7,14 @@ creates a default one.
 """
 
 from .models import Model, model, model_from_context, use_model
+from .params import Params
+from .thinking_config import ThinkingConfig, ThinkingLevel
 
 __all__ = [
     "Model",
+    "Params",
+    "ThinkingConfig",
+    "ThinkingLevel",
     "model",
     "model_from_context",
     "use_model",