agentic.ModelResponse

Page status: scaffold Source state: generated Applies to: Shepherd v1.0-dev Owner: @docs-system-owner (TBD) Validation: scripts/gen_shepherd_api_inventory.py --check

This is reference — exact, generated facts. The mental model lives in concepts; recipes live in guides.

Pre-rename surface

Generated from the internal agentic facade; names and paths change at the Shepherd rename.

class

ModelResponse dataclass

Provider response payload (embedded in EffectCapture).

Mutual exclusion enforced at construction: exactly one of text, structured_output, or non-empty tool_calls. Adapters normalize text="" to text=None per DECISIONS D15 before constructing.

finish_reason class-attribute instance-attribute

finish_reason: Literal[
    "end_turn", "max_tokens", "stop_sequence", "tool_use"
] = "end_turn"

session_id class-attribute instance-attribute

session_id: str | None = None

structured_output class-attribute instance-attribute

structured_output: dict[str, Any] | None = None

text class-attribute instance-attribute

text: str | None = None

tool_calls class-attribute instance-attribute

tool_calls: tuple[ToolCallRecord, ...] = ()

usage class-attribute instance-attribute

usage: Usage = field(default_factory=Usage)

__init__

__init__(
    text: str | None = None,
    structured_output: dict[str, Any] | None = None,
    tool_calls: tuple[ToolCallRecord, ...] = (),
    usage: Usage = Usage(),
    session_id: str | None = None,
    finish_reason: Literal[
        "end_turn",
        "max_tokens",
        "stop_sequence",
        "tool_use",
    ] = "end_turn",
) -> None

__post_init__

__post_init__() -> None