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

build_tool_result ¶

build_tool_result(
    payload: Any,
    *,
    output_format: OutputFormat = OutputFormat.JSON,
    is_error: bool = False,
) -> 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.