Output¶

OutputFormat, encoders, and the ToolResult builder.

OutputFormat ¶

Bases: str, Enum

Output format for the human-readable text block of a ToolResult.

structuredContent is always JSON; this enum only controls the encoding of the content[0] text block:

JSON: pretty-printed JSON, the safe default.
TOON: token-oriented object notation. Compact for large uniform arrays; falls back to JSON if the optional toon extra is not installed.
AUTO: encoder picks per-payload — TOON for uniform list-of-objects, JSON otherwise.

coerce `classmethod` ¶

coerce(value: OutputFormat | str | None) -> OutputFormat

Accept either an enum member or its string value; default to JSON.

encode_json ¶

encode_json(payload: Any) -> str

Encode payload as a stable, pretty JSON string.

Uses default=str so DRF outputs containing Decimal, UUID, datetime, etc. are rendered without raising. Sorts keys for deterministic output (helpful in tests and diff-friendly transcripts).

encode_toon ¶

encode_toon(payload: Any) -> str

Encode payload as TOON (token-oriented object notation).

TOON is an optional dependency. If python-toon is not installed, this encoder issues a warning and falls back to JSON so a tool call never breaks just because the extra is absent. The warning fires every time — silencing it is the consumer's job (warnings.filterwarnings or installing the extra).

The import goes through importlib so static analysers (ty) don't flag the optional module as unresolved on environments without the [toon] extra installed.

build_tool_result ¶

build_tool_result(
    payload: Any,
    *,
    output_format: OutputFormat = OutputFormat.JSON,
    is_error: bool = False,
    include_structured_content: bool = True,
) -> ToolResult

Build a :class:ToolResult for a successful (or tool-level error) call.

payload is the JSON-shaped tool output; it becomes structuredContent verbatim and is also rendered as the first content block per output_format. TOON output is wrapped in a fenced toon block with a leading marker line so clients that don't parse TOON natively can still display it.

When include_structured_content is False, the structuredContent field is omitted from the response. The text rendering in content[0] still carries the full payload, so clients that don't consume the structured field lose nothing.