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#
| Attribute | Type | Description |
|---|---|---|
PROVIDER_METADATA | RecordSchema[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_REASON | LiteralsSchema[Literal['stop', 'length', 'content-filter', 'tool-calls', 'error', 'pause', 'other', 'unknown']] |
Types#
| Type | Definition | Description |
|---|---|---|
ProviderMetadata | type ProviderMetadata = dict[str, JsonValue] | Provider-specific details, by provider name. |
ToolResultPart | type ToolResultPart[NN: str, SS, FF] = ToolResultSuccess[NN, SS] | ToolResultFailure[NN, FF] | |
FinishReason | type FinishReason = Literal['stop', 'length', 'content-filter', 'tool-calls', 'error', 'pause', 'other', 'unknown'] | |
AnyToolCallPart | type AnyToolCallPart = ToolCallPart[str, object] | |
AnyToolResultPart | type AnyToolResultPart = ToolResultSuccess[str, object] | ToolResultFailure[str, object] | |
AnyPart | type AnyPart = TextPart | TextStartPart | TextDeltaPart | TextEndPart | ReasoningPart | ReasoningStartPart | ReasoningDeltaPart | ReasoningEndPart | ToolParamsStartPart | ToolParamsDeltaPart | ToolParamsEndPart | AnyToolCallPart | AnyToolResultPart | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart | |
Part | type 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 |
StreamPart | type 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")).
| Parameter | Type | Description |
|---|---|---|
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 |
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).
| Parameter | Type | Description |
|---|---|---|
name | S.Top | str | |
params | S.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.
| Parameter | Type | Description |
|---|---|---|
name | str | None | |
success | S.Top | |
failure | S.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.
| Parameter | Type | Description |
|---|---|---|
toolkit | AnyToolkit | 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).
| Parameter | Type | Description |
|---|---|---|
toolkit | AnyToolkit | 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).
| Parameter | Type | Description |
|---|---|---|
toolkit | AnyToolkit | 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),
),
)