---
# AUTO-GENERATED API DOCUMENTATION - DO NOT EDIT
title: formatting
description: API documentation for formatting
---

# 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/mirascope/v2/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/mirascope/v2/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/mirascope/v2/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/mirascope/v2/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/mirascope/v2/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/mirascope/v2/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/mirascope/v2/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/mirascope/v2/api/llm/formatting#output-parser"
          },
          "parameters": [
            {
              "type_str": "FormattableT",
              "description": null,
              "kind": "simple",
              "symbol_name": "FormattableT",
              "doc_url": "/docs/mirascope/v2/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/mirascope/v2/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/mirascope/v2/api/llm/formatting#format"
        },
        "parameters": [
          {
            "type_str": "FormattableT",
            "description": null,
            "kind": "simple",
            "symbol_name": "FormattableT",
            "doc_url": "/docs/mirascope/v2/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/mirascope/v2/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/mirascope/v2/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/mirascope/v2/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/mirascope/v2/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/mirascope/v2/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/mirascope/v2/api/llm/formatting#format"
          },
          "parameters": [
            {
              "type_str": "FormattableT",
              "description": null,
              "kind": "simple",
              "symbol_name": "FormattableT",
              "doc_url": "/docs/mirascope/v2/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/mirascope/v2/api/llm/formatting#output-parser"
          },
          "parameters": [
            {
              "type_str": "FormattableT",
              "description": null,
              "kind": "simple",
              "symbol_name": "FormattableT",
              "doc_url": "/docs/mirascope/v2/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/mirascope/v2/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/mirascope/v2/api/llm/formatting#format"
        },
        "parameters": [
          {
            "type_str": "FormattableT",
            "description": null,
            "kind": "simple",
            "symbol_name": "FormattableT",
            "doc_url": "/docs/mirascope/v2/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."
}}
/>


