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

mirascope/llm/formatting/format.py

@@ -1,32 +1,173 @@
 """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 ._utils import default_formatting_instructions
-from .types import Format, FormattableT, FormattingMode, HasFormattingInstructions
+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.
+        )
 
 
 def format(
-    formattable: type[FormattableT] | None,
+    formattable: type[FormattableT] | OutputParser[FormattableT] | None,
     *,
     mode: FormattingMode,
 ) -> Format[FormattableT] | None:
-    """Returns a `Format` that describes structured output for a Formattable type.
+    """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.
 
-    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.
+    Primitive types are automatically wrapped in a `BaseModel` with an "output" field
+    for schema generation, then unwrapped during parsing.
 
     Args:
-        mode: The format mode to use, one of the following:
+        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):
             - "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,
@@ -37,34 +178,44 @@ def format(
     you can add the `formatting_instructions` classmethod and have it return `None`.
 
     Returns:
-      A `Format` object describing the Formattable type.
+      A `Format` object describing the format type or parser.
 
     Example:
-      Using with an LLM call:
+      Using with a BaseModel:
 
       ```python
       from pydantic import BaseModel
-
       from mirascope import llm
 
-
       class Book(BaseModel):
           title: str
           author: str
 
       format = llm.format(Book, mode="strict")
 
-      @llm.call(
-          provider_id="openai",
-          model_id="openai/gpt-5-mini",
-          format=format,
-      )
+      @llm.call("openai/gpt-5-mini", format=format)
       def recommend_book(genre: str):
           return f"Recommend a {genre} book."
 
       response = recommend_book("fantasy")
       book: Book = response.parse()
-      print(f"{book.title} by {book.author}")
+      ```
+
+    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."
       ```
     """
     # TODO: Add caching or memoization to this function (e.g. functools.lru_cache)
@@ -72,33 +223,71 @@ 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] | None,
+    formattable: (
+        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
+    ),
     default_mode: FormattingMode,
 ) -> Format[FormattableT] | None:
-    """Resolve a `Format` (or None) from a possible `Format` or Formattable."""
+    """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.
+    """
     if isinstance(formattable, Format):
         return formattable
-    else:
-        return format(formattable, mode=default_mode)
+
+    if is_output_parser(formattable):
+        return format(formattable, mode="parser")
+
+    return format(formattable, mode=default_mode)

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)