formatting

Class Format

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:

from mirascope import llm

class Book:
    title: str
    author: str

print(llm.format(Book, mode="tool"))

Bases:

Attribute FormattableT

Type: 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. If format is specified, it must extend Pydantic BaseModel.

Attribute FormattingMode

Type: Literal['strict', 'json', 'tool']

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).

• "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.

Note: When llm.format is not used, the provider will automatically choose a mode at call time.

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="openai:completions",
    model_id="gpt-4o-mini",
    format=Book,
)
def summarize_book(title: str, author: str):
    return f"Summarize {title} by {author}."

Class Partial

Generate a new class with all attributes optionals.

Bases:

Function format

Returns a Format that describes structured output for a Formattable type.

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.

The Formattable type may provide custom formatting instructions via a formatting_instructions(cls) classmethod. If that method is present, it will be called, and the resulting instructions will automatically be appended to the system prompt.

If no formatting instructions are present, then Mirascope may auto-generate instructions based on the active format mode. To disable this behavior and all prompt modification, you can add the formatting_instructions classmethod and have it return None.

Function resolve_format

Resolve a Format (or None) from a possible Format or Formattable.