GitHub

response

API reference for response.

The parts of a language model's response (Effect's Response).

A generated response is a list of parts: text, reasoning, tool calls, tool results, approval requests, files, sources, metadata and a finish part. A streamed one also has the start / delta / end parts of text, reasoning and tool parameters, and error parts. Match them by class::

for part in response.content:
    match part:
        case TextPart(text=text): ...
        case ToolResultSuccess(name="GetWeather", result=weather): ...

Tool calls and results are generic in the tool's name and types, so a toolkit's results keep their success and failure types. all_parts, part and stream_part give the schemas of a toolkit's parts in their wire form (Effect's, camelCase keys).

Values

AttributeTypeDescription
PROVIDER_METADATARecordSchema[str, bool | int | float | str | Sequence[JsonValue] | Mapping[str, JsonValue] | None, str, bool | int | float | str | Sequence[JsonValue] | Mapping[str, JsonValue] | None, Never, Never]
FINISH_REASONLiteralsSchema[Literal['stop', 'length', 'content-filter', 'tool-calls', 'error', 'pause', 'other', 'unknown']]

Types

TypeDefinitionDescription
ProviderMetadatatype ProviderMetadata = dict[str, JsonValue]

Provider-specific details, by provider name.

ToolResultParttype ToolResultPart[NN: str, SS, FF] = ToolResultSuccess[NN, SS] | ToolResultFailure[NN, FF]
FinishReasontype FinishReason = Literal['stop', 'length', 'content-filter', 'tool-calls', 'error', 'pause', 'other', 'unknown']
AnyToolCallParttype AnyToolCallPart = ToolCallPart[str, object]
AnyToolResultParttype AnyToolResultPart = ToolResultSuccess[str, object] | ToolResultFailure[str, object]
AnyParttype AnyPart = TextPart | TextStartPart | TextDeltaPart | TextEndPart | ReasoningPart | ReasoningStartPart | ReasoningDeltaPart | ReasoningEndPart | ToolParamsStartPart | ToolParamsDeltaPart | ToolParamsEndPart | AnyToolCallPart | AnyToolResultPart | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart
Parttype Part[NN: str, RP_co] = TextPart | ReasoningPart | ToolCallPart[NN, object] | RP_co | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart

A part of a generated response whose tools are named NN and whose tool results are RP_co.

StreamParttype StreamPart[NN: str, RP_co] = TextStartPart | TextDeltaPart | TextEndPart | ReasoningStartPart | ReasoningDeltaPart | ReasoningEndPart | ToolParamsStartPart | ToolParamsDeltaPart | ToolParamsEndPart | ToolCallPart[NN, object] | RP_co | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart

A part of a streamed response.

Classes

Functions

tool_result_part

tool_result_part(*, id, name, is_failure, result, encoded_result, provider_executed=False, preliminary=False, metadata=None, model_output=None) -> ToolResultSuccess[str, object] | ToolResultFailure[str, object]

A tool result of either kind (Effect's makePart("tool-result")).

ParameterTypeDescription
idstr
namestr
is_failurebool
resultobject
encoded_resultobject
provider_executedbool = False
preliminarybool = False
metadataProviderMetadata | None = None
model_outputtuple[P.ToolModelOutputPart, ...] | None = None

Returns ToolResultSuccess[str, object] | ToolResultFailure[str, object]

def tool_result_part(
    *,
    id: str,
    name: str,
    is_failure: bool,
    result: object,
    encoded_result: object,
    provider_executed: bool = False,
    preliminary: bool = False,
    metadata: ProviderMetadata | None = None,
    model_output: tuple[P.ToolModelOutputPart, ...] | None = None,
) -> ToolResultSuccess[str, object] | ToolResultFailure[str, object]:
    """A tool result of either kind (Effect's ``makePart("tool-result")``)."""
    cls: Any = ToolResultFailure if is_failure else ToolResultSuccess
    return cls(
        id=id,
        name=name,
        result=result,
        encoded_result=encoded_result,
        provider_executed=provider_executed,
        preliminary=preliminary,
        metadata=metadata if metadata is not None else {},
        model_output=model_output,
    )

tool_call_part_schema

tool_call_part_schema(name, params) -> S.Bottom[Any, Mapping[str, object]]

The schema of the calls of the tool name (a literal name, or a schema of names) with params (Effect's ToolCallPart).

ParameterTypeDescription
nameS.Top | str
paramsS.Top

Returns S.Bottom[Any, Mapping[str, object]]

def tool_call_part_schema(name: S.Top | str, params: S.Top) -> S.Bottom[Any, Mapping[str, object]]:
    """The schema of the calls of the tool ``name`` (a literal name, or a
    schema of names) with ``params`` (Effect's ``ToolCallPart``)."""
    name_schema: S.Top = S.Literal(cast("Any", name)) if isinstance(name, str) else name
    return wire_codec(
        cast("type[Any]", ToolCallPart),
        [
            Const("type", "tool-call"),
            key("id", "id", S.String),
            key("name", "name", name_schema),
            key("params", "params", params),
            key("providerExecuted", "provider_executed", S.Boolean, default=lambda: False),
            _metadata_key(),
        ],
        identifier="ToolCallPart",
    )

tool_result_part_schema

tool_result_part_schema(name, success, failure) -> S.Bottom[Any, Mapping[str, object]]

The schema of the tool name's results (any tool's for None) with success and failure (Effect's ToolResultPart): the branch is the part's is_failure.

ParameterTypeDescription
namestr | None
successS.Top
failureS.Top

Returns S.Bottom[Any, Mapping[str, object]]

def tool_result_part_schema(
    name: str | None, success: S.Top, failure: S.Top
) -> S.Bottom[Any, Mapping[str, object]]:
    """The schema of the tool ``name``'s results (any tool's for ``None``)
    with ``success`` and ``failure`` (Effect's ``ToolResultPart``): the
    branch is the part's ``is_failure``."""
    results = (success.__codec__().ast, failure.__codec__().ast)
    wires = (_wire_branch(name, results[0], False), _wire_branch(name, results[1], True))

    def is_part(u: object) -> bool:
        return isinstance(u, (ToolResultSuccess, ToolResultFailure)) and (
            name is None or cast("Any", u).name == name
        )

    def decode(input: object, options: ParseOptions) -> Any:
        values = cast("Mapping[str, Any]", input)
        is_failure = bool(values["isFailure"])
        cls: Any = ToolResultFailure if is_failure else ToolResultSuccess
        wire = wires[is_failure]
        decoded = ast.parse_at_key(
            wire, "result", results[is_failure], values["result"], input=input, options=options
        )

        def part(value: object, model_output: object) -> object:
            return cls(
                id=values["id"],
                name=values["name"],
                result=value,
                encoded_result=values["result"],
                provider_executed=values.get("providerExecuted", False),
                preliminary=values.get("preliminary", False),
                metadata=values.get("metadata", {}),
                model_output=model_output,
            )

        return ast.to_effect(
            ast.flat_map(
                decoded,
                lambda value: ast.map_value(
                    _model_output(wire, values.get("modelOutput"), False, input, options),
                    lambda model_output: part(value, model_output),
                ),
            )
        )

    def encode(input: object, options: ParseOptions) -> Any:
        part = cast("ToolResultSuccess[str, object] | ToolResultFailure[str, object]", input)
        wire, result = wires[part.is_failure], results[part.is_failure]
        checked = ast.parse_at_key(
            wire,
            "encodedResult",
            ast.to_encoded(result),
            part.encoded_result,
            input=input,
            options=options,
        )
        return ast.to_effect(
            ast.flat_map(
                checked,
                lambda _: ast.flat_map(
                    ast.parse_at_key(
                        wire, "result", result.flip(), part.result, input=input, options=options
                    ),
                    lambda encoded: ast.map_value(
                        _model_output(wire, part.model_output, True, input, options),
                        lambda model_output: {
                            "type": "tool-result",
                            "id": part.id,
                            "name": part.name,
                            "isFailure": part.is_failure,
                            "result": encoded,
                            **({} if model_output is None else {"modelOutput": model_output}),
                            "providerExecuted": part.provider_executed,
                            "preliminary": part.preliminary,
                            "metadata": part.metadata,
                        },
                    ),
                ),
            )
        )

    target: S.Bottom[Any] = S.declare(
        cast("Any", is_part), expected="ToolResultPart", identifier=f"ToolResultPart({name})"
    )
    wire_union: S.Bottom[Any, Mapping[str, object]] = cast(
        "Any", S.Union(S.Bottom[Any, Any](wires[0]), S.Bottom[Any, Any](wires[1]))
    )
    return wire_union.pipe(
        S.decode_to(
            target, T.Transformation(G.transform_effect(decode), G.transform_effect(encode))
        )
    )

all_parts

all_parts(toolkit=None) -> S.Bottom[AnyPart, Mapping[str, object]]

The schema of every part (Effect's AllParts): of toolkit's tool calls and results, or of any tool's without one.

ParameterTypeDescription
toolkitAnyToolkit | None = None

Returns S.Bottom[AnyPart, Mapping[str, object]]

def all_parts(toolkit: AnyToolkit | None = None) -> S.Bottom[AnyPart, Mapping[str, object]]:
    """The schema of every part (Effect's ``AllParts``): of ``toolkit``'s
    tool calls and results, or of any tool's without one."""
    return cast(
        "Any",
        S.Union(
            TextPart,
            TextStartPart,
            TextDeltaPart,
            TextEndPart,
            ReasoningPart,
            ReasoningStartPart,
            ReasoningDeltaPart,
            ReasoningEndPart,
            ToolParamsStartPart,
            ToolParamsDeltaPart,
            ToolParamsEndPart,
            ToolApprovalRequestPart,
            FilePart,
            DocumentSourcePart,
            UrlSourcePart,
            ResponseMetadataPart,
            FinishPart,
            ErrorPart,
            *_tool_schemas(toolkit),
        ),
    )

part

part(toolkit=None) -> S.Bottom[AnyPart, Mapping[str, object]]

The schema of a generated response's parts (Effect's Part).

ParameterTypeDescription
toolkitAnyToolkit | None = None

Returns S.Bottom[AnyPart, Mapping[str, object]]

def part(toolkit: AnyToolkit | None = None) -> S.Bottom[AnyPart, Mapping[str, object]]:
    """The schema of a generated response's parts (Effect's ``Part``)."""
    return cast(
        "Any",
        S.Union(
            TextPart,
            ReasoningPart,
            ToolApprovalRequestPart,
            FilePart,
            DocumentSourcePart,
            UrlSourcePart,
            ResponseMetadataPart,
            FinishPart,
            *_tool_schemas(toolkit),
        ),
    )

stream_part

stream_part(toolkit=None) -> S.Bottom[AnyPart, Mapping[str, object]]

The schema of a streamed response's parts (Effect's StreamPart).

ParameterTypeDescription
toolkitAnyToolkit | None = None

Returns S.Bottom[AnyPart, Mapping[str, object]]

def stream_part(toolkit: AnyToolkit | None = None) -> S.Bottom[AnyPart, Mapping[str, object]]:
    """The schema of a streamed response's parts (Effect's ``StreamPart``)."""
    return cast(
        "Any",
        S.Union(
            TextStartPart,
            TextDeltaPart,
            TextEndPart,
            ReasoningStartPart,
            ReasoningDeltaPart,
            ReasoningEndPart,
            ToolParamsStartPart,
            ToolParamsDeltaPart,
            ToolParamsEndPart,
            ToolApprovalRequestPart,
            FilePart,
            DocumentSourcePart,
            UrlSourcePart,
            ResponseMetadataPart,
            FinishPart,
            ErrorPart,
            *_tool_schemas(toolkit),
        ),
    )