# formatting
## <ApiType type="Class" slug="format" symbolName="Format" /> 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:
```python
from mirascope import llm
class Book:
title: str
author: str
print(llm.format(Book, mode="tool"))
```
**Bases:**
<TypeLink type={{"type_str": "Generic[FormattableT]", "description": null, "kind": "generic", "base_type": {"type_str": "Generic", "description": null, "kind": "simple", "symbol_name": "Generic", "doc_url": "https://docs.python.org/3/library/typing.html#typing.Generic"}, "parameters": [{"type_str": "FormattableT", "description": null, "kind": "simple", "symbol_name": "FormattableT", "doc_url": "/docs/api/llm/formatting#formattable-t"}], "doc_url": null}} />
<AttributesTable
attributes={[
{
"name": "name",
"type_info": {
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": null
},
"description": "The name of the response format."
},
{
"name": "description",
"type_info": {
"type_str": "str | None",
"description": null,
"kind": "union",
"base_type": {
"type_str": "Union",
"description": null,
"kind": "simple",
"symbol_name": "Union",
"doc_url": null
},
"parameters": [
{
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": null
},
{
"type_str": "None",
"description": null,
"kind": "simple",
"symbol_name": "None",
"doc_url": null
}
],
"doc_url": null
},
"description": "A description of the response format, if available."
},
{
"name": "schema",
"type_info": {
"type_str": "dict[str, object]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "dict",
"description": null,
"kind": "simple",
"symbol_name": "dict",
"doc_url": null
},
"parameters": [
{
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": null
},
{
"type_str": "object",
"description": null,
"kind": "simple",
"symbol_name": "object",
"doc_url": null
}
],
"doc_url": null
},
"description": "JSON schema representation of the structured output format."
},
{
"name": "mode",
"type_info": {
"type_str": "FormattingMode",
"description": null,
"kind": "simple",
"symbol_name": "FormattingMode",
"doc_url": null
},
"description": "The decorator-provided mode of the response format.\n\nDetermines how the LLM call may be modified in order to extract the expected format."
},
{
"name": "formattable",
"type_info": {
"type_str": "type[FormattableT] | OutputParser[FormattableT]",
"description": null,
"kind": "union",
"base_type": {
"type_str": "Union",
"description": null,
"kind": "simple",
"symbol_name": "Union",
"doc_url": null
},
"parameters": [
{
"type_str": "type[FormattableT]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "type",
"description": null,
"kind": "simple",
"symbol_name": "type",
"doc_url": null
},
"parameters": [
{
"type_str": "FormattableT",
"description": null,
"kind": "simple",
"symbol_name": "FormattableT",
"doc_url": null
}
],
"doc_url": null
},
{
"type_str": "OutputParser[FormattableT]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "OutputParser",
"description": null,
"kind": "simple",
"symbol_name": "OutputParser",
"doc_url": null
},
"parameters": [
{
"type_str": "FormattableT",
"description": null,
"kind": "simple",
"symbol_name": "FormattableT",
"doc_url": null
}
],
"doc_url": null
}
],
"doc_url": null
},
"description": "The formattable type or custom output parser.\n\nCan be one of:\n- type[BaseModel]: A Pydantic model class for structured output\n- PrimitiveType: A primitive type (str, int, list, etc.) for simple output\n- OutputParser[FormattableT]: A custom parser created with @llm.output_parser\n\nThe type determines how the response will be parsed in response.parse().\nOutputParser uses Any for the response type since it works with any response."
},
{
"name": "formatting_instructions",
"type_info": {
"type_str": "str | None",
"description": null,
"kind": "union",
"base_type": {
"type_str": "Union",
"description": null,
"kind": "simple",
"symbol_name": "Union",
"doc_url": null
},
"parameters": [
{
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": null
},
{
"type_str": "None",
"description": null,
"kind": "simple",
"symbol_name": "None",
"doc_url": null
}
],
"doc_url": null
},
"description": "The formatting instructions that will be added to the LLM system prompt.\n\nIf the format has a custom `OutputParser`, its formatting instructions will be used.\nOtherwise, if the format type has a `formatting_instructions` class method,\nthe output of that call will be used. Otherwise, instructions may be\nauto-generated based on the formatting mode."
}
]}
/>
## <ApiType type="Function" slug="mirascope-llm-formatting-format--format-create_tool_schema" symbolName="create_tool_schema" /> create_tool_schema
Generate a `ToolSchema` for parsing this format.
<ParametersTable
parameters={[
{
"name": "self",
"type_info": {
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": null,
"doc_url": null
}
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "ToolSchema[ToolFn[..., None]]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "ToolSchema",
"description": null,
"kind": "simple",
"symbol_name": "ToolSchema",
"doc_url": "/docs/api/llm/tools#tool-schema"
},
"parameters": [
{
"type_str": "ToolFn[..., None]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "ToolFn",
"description": null,
"kind": "simple",
"symbol_name": "ToolFn",
"doc_url": "/docs/api/llm/tools#tool-fn"
},
"parameters": [
{
"type_str": "...",
"description": null,
"kind": "simple",
"symbol_name": "...",
"doc_url": null
},
{
"type_str": "None",
"description": null,
"kind": "simple",
"symbol_name": "None",
"doc_url": "https://docs.python.org/3/library/constants.html#None"
}
],
"doc_url": null
}
],
"doc_url": null
},
"description": "`ToolSchema` for the format tool"
}}
/>
## <ApiType type="Attribute" slug="formattable-t" symbolName="FormattableT" /> FormattableT
**Type:** <TypeLink type={{"type_str": "TypeVar('FormattableT', bound=BaseModel | PrimitiveType | None, default=None)", "description": null, "kind": "simple", "symbol_name": null, "doc_url": null}} />
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
## <ApiType type="Attribute" slug="formatting-mode" symbolName="FormattingMode" /> FormattingMode
**Type:** <TypeLink type={{"type_str": "Literal['strict', 'json', 'tool', 'parser']", "description": null, "kind": "generic", "base_type": {"type_str": "Literal", "description": null, "kind": "simple", "symbol_name": "Literal", "doc_url": null}, "parameters": [{"type_str": "'strict'", "description": null, "kind": "simple", "symbol_name": "'strict'", "doc_url": null}, {"type_str": "'json'", "description": null, "kind": "simple", "symbol_name": "'json'", "doc_url": null}, {"type_str": "'tool'", "description": null, "kind": "simple", "symbol_name": "'tool'", "doc_url": null}, {"type_str": "'parser'", "description": null, "kind": "simple", "symbol_name": "'parser'", "doc_url": null}], "doc_url": null}} />
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.
## <ApiType type="Class" slug="from-call-args" symbolName="FromCallArgs" /> 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}."
```
## <ApiType type="Class" slug="output-parser" symbolName="OutputParser" /> OutputParser
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.
**Bases:**
<TypeLink type={{"type_str": "Generic[OutputT]", "description": null, "kind": "generic", "base_type": {"type_str": "Generic", "description": null, "kind": "simple", "symbol_name": "Generic", "doc_url": "https://docs.python.org/3/library/typing.html#typing.Generic"}, "parameters": [{"type_str": "OutputT", "description": null, "kind": "simple", "symbol_name": "OutputT", "doc_url": null}], "doc_url": null}} />
<AttributesTable
attributes={[
{
"name": "func",
"type_info": {
"type_str": "func",
"description": null,
"kind": "simple",
"symbol_name": "func",
"doc_url": null
}
}
]}
/>
## <ApiType type="Function" slug="mirascope-llm-formatting-output_parser--output-parser-formatting_instructions" symbolName="formatting_instructions" /> formatting_instructions
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.
<ParametersTable
parameters={[
{
"name": "self",
"type_info": {
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": null,
"doc_url": null
}
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": "https://docs.python.org/3/library/stdtypes.html#str"
},
"description": "The formatting instructions string."
}}
/>
## <ApiType type="Class" slug="partial" symbolName="Partial" /> Partial
Generate a new class with all attributes optionals.
**Bases:**
<TypeLink type={{"type_str": "Generic[FormattableT]", "description": null, "kind": "generic", "base_type": {"type_str": "Generic", "description": null, "kind": "simple", "symbol_name": "Generic", "doc_url": "https://docs.python.org/3/library/typing.html#typing.Generic"}, "parameters": [{"type_str": "FormattableT", "description": null, "kind": "simple", "symbol_name": "FormattableT", "doc_url": "/docs/api/llm/formatting#formattable-t"}], "doc_url": null}} />
## <ApiType type="Attribute" slug="primitive-type" symbolName="PrimitiveType" /> PrimitiveType
**Type:** <TypeLink type={{"type_str": "TypeAlias", "description": null, "kind": "simple", "symbol_name": "TypeAlias", "doc_url": null}} />
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.
## <ApiType type="Class" slug="primitive-wrapper-model" symbolName="PrimitiveWrapperModel" /> PrimitiveWrapperModel
Protocol for wrapper models with an output field.
**Bases:**
<TypeLink type={{"type_str": "Protocol", "description": null, "kind": "simple", "symbol_name": "Protocol", "doc_url": "https://docs.python.org/3/library/typing.html#typing.Protocol"}} />
<AttributesTable
attributes={[
{
"name": "output",
"type_info": {
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": "Any",
"doc_url": null
}
},
{
"name": "model_fields",
"type_info": {
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": "Any",
"doc_url": null
}
}
]}
/>
## <ApiType type="Function" slug="mirascope-llm-formatting-primitives--primitive-wrapper-model-model_json_schema" symbolName="model_json_schema" /> model_json_schema
<ParametersTable
parameters={[
{
"name": "cls",
"type_info": {
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": null,
"doc_url": null
}
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "dict[str, Any]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "dict",
"description": null,
"kind": "simple",
"symbol_name": "dict",
"doc_url": "https://docs.python.org/3/library/stdtypes.html#dict"
},
"parameters": [
{
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": "https://docs.python.org/3/library/stdtypes.html#str"
},
{
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": "Any",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Any"
}
],
"doc_url": null
}
}}
/>
## <ApiType type="Function" slug="mirascope-llm-formatting-primitives--primitive-wrapper-model-model_validate_json" symbolName="model_validate_json" /> model_validate_json
<ParametersTable
parameters={[
{
"name": "cls",
"type_info": {
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": null,
"doc_url": null
}
},
{
"name": "json_data",
"type_info": {
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": "https://docs.python.org/3/library/stdtypes.html#str"
}
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "PrimitiveWrapperModel",
"description": null,
"kind": "simple",
"symbol_name": "PrimitiveWrapperModel",
"doc_url": "/docs/api/llm/formatting#primitive-wrapper-model"
}
}}
/>
## <ApiType type="Function" slug="create_wrapper_model" symbolName="create_wrapper_model" /> create_wrapper_model
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.
<ParametersTable
parameters={[
{
"name": "primitive_type",
"type_info": {
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": "Any",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Any"
},
"description": "The primitive type to wrap"
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "type[PrimitiveWrapperModel]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "type",
"description": null,
"kind": "simple",
"symbol_name": "type",
"doc_url": "https://docs.python.org/3/library/functions.html#type"
},
"parameters": [
{
"type_str": "PrimitiveWrapperModel",
"description": null,
"kind": "simple",
"symbol_name": "PrimitiveWrapperModel",
"doc_url": "/docs/api/llm/formatting#primitive-wrapper-model"
}
],
"doc_url": null
},
"description": "A dynamically created BaseModel with an \"output\" field"
}}
/>
## <ApiType type="Function" slug="format_fn" symbolName="format" /> format
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.
Primitive types are automatically wrapped in a `BaseModel` with an "output" field
for schema generation, then unwrapped during parsing.
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`.
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."
```
<ParametersTable
parameters={[
{
"name": "formattable",
"type_info": {
"type_str": "type[FormattableT] | OutputParser[FormattableT] | None",
"description": null,
"kind": "union",
"base_type": {
"type_str": "Union",
"description": null,
"kind": "simple",
"symbol_name": "Union",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Union"
},
"parameters": [
{
"type_str": "type[FormattableT]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "type",
"description": null,
"kind": "simple",
"symbol_name": "type",
"doc_url": "https://docs.python.org/3/library/functions.html#type"
},
"parameters": [
{
"type_str": "FormattableT",
"description": null,
"kind": "simple",
"symbol_name": "FormattableT",
"doc_url": "/docs/api/llm/formatting#formattable-t"
}
],
"doc_url": null
},
{
"type_str": "OutputParser[FormattableT]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "OutputParser",
"description": null,
"kind": "simple",
"symbol_name": "OutputParser",
"doc_url": "/docs/api/llm/formatting#output-parser"
},
"parameters": [
{
"type_str": "FormattableT",
"description": null,
"kind": "simple",
"symbol_name": "FormattableT",
"doc_url": "/docs/api/llm/formatting#formattable-t"
}
],
"doc_url": null
},
{
"type_str": "None",
"description": null,
"kind": "simple",
"symbol_name": "None",
"doc_url": "https://docs.python.org/3/library/constants.html#None"
}
],
"doc_url": null
},
"description": "The type or parser to format:\n- BaseModel type: Uses structured output with JSON schema\n- Primitive type: Wrapped in schema for structured output\n- OutputParser: Uses custom parsing with instructions"
},
{
"name": "mode",
"type_info": {
"type_str": "FormattingMode",
"description": null,
"kind": "simple",
"symbol_name": "FormattingMode",
"doc_url": "/docs/api/llm/formatting#formatting-mode"
},
"description": "The format mode to use (required):\n- \"strict\": Use model strict structured outputs, or fail if unavailable.\n- \"tool\": Use forced tool calling with a special tool that represents a\n formatted response.\n- \"json\": Use provider json mode if available, or modify prompt to request\n json if not.\n- \"parser\": Must be used for OutputParser types."
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "Format[FormattableT] | None",
"description": null,
"kind": "union",
"base_type": {
"type_str": "Union",
"description": null,
"kind": "simple",
"symbol_name": "Union",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Union"
},
"parameters": [
{
"type_str": "Format[FormattableT]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "Format",
"description": null,
"kind": "simple",
"symbol_name": "Format",
"doc_url": "/docs/api/llm/formatting#format"
},
"parameters": [
{
"type_str": "FormattableT",
"description": null,
"kind": "simple",
"symbol_name": "FormattableT",
"doc_url": "/docs/api/llm/formatting#formattable-t"
}
],
"doc_url": null
},
{
"type_str": "None",
"description": null,
"kind": "simple",
"symbol_name": "None",
"doc_url": "https://docs.python.org/3/library/constants.html#None"
}
],
"doc_url": null
},
"description": "A `Format` object describing the format type or parser."
}}
/>
## <ApiType type="Function" slug="is_output_parser" symbolName="is_output_parser" /> is_output_parser
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.
<ParametersTable
parameters={[
{
"name": "obj",
"type_info": {
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": "Any",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Any"
},
"description": "The object to check."
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "TypeIs[OutputParser[Any]]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "TypeIs",
"description": null,
"kind": "simple",
"symbol_name": "TypeIs",
"doc_url": null
},
"parameters": [
{
"type_str": "OutputParser[Any]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "OutputParser",
"description": null,
"kind": "simple",
"symbol_name": "OutputParser",
"doc_url": "/docs/api/llm/formatting#output-parser"
},
"parameters": [
{
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": "Any",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Any"
}
],
"doc_url": null
}
],
"doc_url": null
},
"description": "True if the object is an OutputParser instance, False otherwise."
}}
/>
## <ApiType type="Function" slug="is_primitive_type" symbolName="is_primitive_type" /> is_primitive_type
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
<ParametersTable
parameters={[
{
"name": "type_",
"type_info": {
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": "Any",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Any"
},
"description": "The type to check"
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "TypeIs[type[PrimitiveType]]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "TypeIs",
"description": null,
"kind": "simple",
"symbol_name": "TypeIs",
"doc_url": null
},
"parameters": [
{
"type_str": "type[PrimitiveType]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "type",
"description": null,
"kind": "simple",
"symbol_name": "type",
"doc_url": "https://docs.python.org/3/library/functions.html#type"
},
"parameters": [
{
"type_str": "PrimitiveType",
"description": null,
"kind": "simple",
"symbol_name": "PrimitiveType",
"doc_url": "/docs/api/llm/formatting#primitive-type"
}
],
"doc_url": null
}
],
"doc_url": null
},
"description": "True if the type is a primitive that needs wrapping"
}}
/>
## <ApiType type="Function" slug="output_parser" symbolName="output_parser" /> output_parser
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.
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
]
```
<ParametersTable
parameters={[
{
"name": "formatting_instructions",
"type_info": {
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": "https://docs.python.org/3/library/stdtypes.html#str"
},
"description": "Instructions for the LLM on how to format\nthe output. These will be added to the system prompt."
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "Callable[[Callable[[AnyResponse], OutputT]], OutputParser[OutputT]]",
"description": null,
"kind": "callable",
"base_type": {
"type_str": "Callable",
"description": null,
"kind": "simple",
"symbol_name": "Callable",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Callable"
},
"parameters": [
{
"type_str": "[Callable[[AnyResponse], OutputT]]",
"description": null,
"kind": "tuple",
"base_type": {
"type_str": "tuple",
"description": null,
"kind": "simple",
"symbol_name": "tuple",
"doc_url": "https://docs.python.org/3/library/stdtypes.html#tuple"
},
"parameters": [
{
"type_str": "Callable[[AnyResponse], OutputT]",
"description": null,
"kind": "callable",
"base_type": {
"type_str": "Callable",
"description": null,
"kind": "simple",
"symbol_name": "Callable",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Callable"
},
"parameters": [
{
"type_str": "[AnyResponse]",
"description": null,
"kind": "tuple",
"base_type": {
"type_str": "tuple",
"description": null,
"kind": "simple",
"symbol_name": "tuple",
"doc_url": "https://docs.python.org/3/library/stdtypes.html#tuple"
},
"parameters": [
{
"type_str": "AnyResponse",
"description": null,
"kind": "simple",
"symbol_name": "AnyResponse",
"doc_url": "/docs/api/llm/responses#any-response"
}
],
"doc_url": null
},
{
"type_str": "OutputT",
"description": null,
"kind": "simple",
"symbol_name": "OutputT",
"doc_url": null
}
],
"doc_url": null
}
],
"doc_url": null
},
{
"type_str": "OutputParser[OutputT]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "OutputParser",
"description": null,
"kind": "simple",
"symbol_name": "OutputParser",
"doc_url": "/docs/api/llm/formatting#output-parser"
},
"parameters": [
{
"type_str": "OutputT",
"description": null,
"kind": "simple",
"symbol_name": "OutputT",
"doc_url": null
}
],
"doc_url": null
}
],
"doc_url": null
},
"description": "Decorator that converts a function into an OutputParser."
}}
/>
## <ApiType type="Function" slug="resolve_format" symbolName="resolve_format" /> resolve_format
Resolve a `Format` (or None) from a possible `Format`, Formattable, or `OutputParser`.
<ParametersTable
parameters={[
{
"name": "formattable",
"type_info": {
"type_str": "type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None",
"description": null,
"kind": "union",
"base_type": {
"type_str": "Union",
"description": null,
"kind": "simple",
"symbol_name": "Union",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Union"
},
"parameters": [
{
"type_str": "type[FormattableT]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "type",
"description": null,
"kind": "simple",
"symbol_name": "type",
"doc_url": "https://docs.python.org/3/library/functions.html#type"
},
"parameters": [
{
"type_str": "FormattableT",
"description": null,
"kind": "simple",
"symbol_name": "FormattableT",
"doc_url": "/docs/api/llm/formatting#formattable-t"
}
],
"doc_url": null
},
{
"type_str": "Format[FormattableT]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "Format",
"description": null,
"kind": "simple",
"symbol_name": "Format",
"doc_url": "/docs/api/llm/formatting#format"
},
"parameters": [
{
"type_str": "FormattableT",
"description": null,
"kind": "simple",
"symbol_name": "FormattableT",
"doc_url": "/docs/api/llm/formatting#formattable-t"
}
],
"doc_url": null
},
{
"type_str": "OutputParser[FormattableT]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "OutputParser",
"description": null,
"kind": "simple",
"symbol_name": "OutputParser",
"doc_url": "/docs/api/llm/formatting#output-parser"
},
"parameters": [
{
"type_str": "FormattableT",
"description": null,
"kind": "simple",
"symbol_name": "FormattableT",
"doc_url": "/docs/api/llm/formatting#formattable-t"
}
],
"doc_url": null
},
{
"type_str": "None",
"description": null,
"kind": "simple",
"symbol_name": "None",
"doc_url": "https://docs.python.org/3/library/constants.html#None"
}
],
"doc_url": null
},
"description": "The format specification:\n- Format: Returned as-is\n- BaseModel/primitive type: Converted to Format with default_mode\n- OutputParser: Converted to Format with mode='parser'"
},
{
"name": "default_mode",
"type_info": {
"type_str": "FormattingMode",
"description": null,
"kind": "simple",
"symbol_name": "FormattingMode",
"doc_url": "/docs/api/llm/formatting#formatting-mode"
},
"description": "The mode to use for BaseModel/primitive types."
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "Format[FormattableT] | None",
"description": null,
"kind": "union",
"base_type": {
"type_str": "Union",
"description": null,
"kind": "simple",
"symbol_name": "Union",
"doc_url": "https://docs.python.org/3/library/typing.html#typing.Union"
},
"parameters": [
{
"type_str": "Format[FormattableT]",
"description": null,
"kind": "generic",
"base_type": {
"type_str": "Format",
"description": null,
"kind": "simple",
"symbol_name": "Format",
"doc_url": "/docs/api/llm/formatting#format"
},
"parameters": [
{
"type_str": "FormattableT",
"description": null,
"kind": "simple",
"symbol_name": "FormattableT",
"doc_url": "/docs/api/llm/formatting#formattable-t"
}
],
"doc_url": null
},
{
"type_str": "None",
"description": null,
"kind": "simple",
"symbol_name": "None",
"doc_url": "https://docs.python.org/3/library/constants.html#None"
}
],
"doc_url": null
},
"description": "A Format object or None."
}}
/>