Tools a language model can call (Effect's Tool).
A tool has a name, a parameters schema, a success schema and a failure
schema. Its type Tool[N_co, P_co, S, F_co, HE_co, R_co] keeps the name N_co, the
decoded parameters P_co, the success S, the failure F_co, the error a
handler raises to the caller HE_co (F_co when failure_mode="error",
Never when failures are returned to the model) and the services the
handler needs R_co (its dependencies)::
get_weather = tool.make(
"GetWeather",
description="The weather in a city",
parameters=S.Struct(WeatherParams),
success=S.Struct(Weather),
)
handler = get_weather.handler(lambda params, ctx: fx.succeed({...}))handler checks the function against the tool: a wrong success, failure
or an undeclared service is a type error. Handlers are given to a toolkit's
to_layer.
Provider-defined tools (provider_defined) run on the provider's side or
take provider arguments; dynamic tools (dynamic) take a raw JSON Schema
for their parameters.
Values#
| Attribute | Type | Description |
|---|---|---|
EMPTY_PARAMS | RecordSchema[str, Never, str, Never, Never, Never] | The parameters of a tool that takes none (Effect's |
EXECUTION_FAILURE | S.Bottom[ExecutionFailureDict] | A tool call that never ran: the user denied it, or the response ended
first (Effect's |
Types#
| Type | Definition | Description |
|---|---|---|
FailureMode | type FailureMode = Literal['error', 'return'] | |
FailureOrigin | type FailureOrigin = Literal['parameters', 'handler', 'result'] | |
NeedsApproval | type NeedsApproval = bool | Callable[[Any, NeedsApprovalContext], bool | Effect[bool]] | |
ToModelOutput | type ToModelOutput = Callable[[Any], Sequence[ToolModelOutputPart]] | A tool's |
AnyTool | type AnyTool = Tool[Any, Any, Any, Any, Any, Any] | |
CodecTransformer | type CodecTransformer = Callable[[S.Top], tuple[S.Top, JsonSchema]] | A provider's rewrite of a schema: the codec to decode the model's output
with and the JSON Schema to send (Effect's |
Classes#
Functions#
is_user_defined#
is_user_defined(u) -> bool| Parameter | Type | Description |
|---|---|---|
u | object |
Returns bool
def is_user_defined(u: object) -> bool:
return isinstance(u, Tool) and not isinstance(u, (ProviderDefined, Dynamic))is_provider_defined#
is_provider_defined(u) -> bool| Parameter | Type | Description |
|---|---|---|
u | object |
Returns bool
def is_provider_defined(u: object) -> bool:
return isinstance(u, ProviderDefined)is_dynamic#
is_dynamic(u) -> bool| Parameter | Type | Description |
|---|---|---|
u | object |
Returns bool
def is_dynamic(u: object) -> bool:
return isinstance(u, Dynamic)failure_result_schema#
failure_result_schema(tool) -> S.TopWhat a tool's failed result can be: an AiError, the tool's
failure or an EXECUTION_FAILURE.
| Parameter | Type | Description |
|---|---|---|
tool | AnyTool |
Returns S.Top
def failure_result_schema(tool: AnyTool) -> S.Top:
"""What a tool's failed result can be: an ``AiError``, the tool's
failure or an ``EXECUTION_FAILURE``."""
return S.Union(cast("Any", AiError), tool.failure_schema, EXECUTION_FAILURE)make#
make[NN: LiteralString, PP = dict[str, Never], SS = None, FF = Never, RR = Never](name: NN, *, description: str | None = None, parameters: S.Codec[PP, Any, Any, Any] | None = None, success: S.Codec[SS, Any, Any, Any] | None = None, failure: S.Codec[FF, Any, Any, Any] | None = None, failure_mode: Literal['error'] = 'error', dependencies: Sequence[type[RR]] = (), needs_approval: NeedsApproval | None = None, to_model_output: Callable[[SS], Sequence[ToolModelOutputPart]] | None = None) -> Tool[NN, PP, SS, FF, FF, RR]
make[NN: LiteralString, PP = dict[str, Never], SS = None, FF = Never, RR = Never](name: NN, *, description: str | None = None, parameters: S.Codec[PP, Any, Any, Any] | None = None, success: S.Codec[SS, Any, Any, Any] | None = None, failure: S.Codec[FF, Any, Any, Any] | None = None, failure_mode: Literal['return'], dependencies: Sequence[type[RR]] = (), needs_approval: NeedsApproval | None = None, to_model_output: Callable[[SS], Sequence[ToolModelOutputPart]] | None = None) -> Tool[NN, PP, SS, FF, Never, RR]A tool the toolkit handles. Its parameters default to none, its
success to None and its failure to Never. to_model_output
maps a successful result to the parts the model sees in its place.
| Parameter | Type | Description |
|---|---|---|
name | ||
description | = None | |
parameters | = None | |
success | = None | |
failure | = None | |
failure_mode | = 'error' | |
dependencies | = () | |
needs_approval | = None | |
to_model_output | = None |
@overload
def make[NN: LiteralString, PP = dict[str, Never], SS = None, FF = Never, RR = Never](
name: NN,
*,
description: str | None = None,
parameters: S.Codec[PP, Any, Any, Any] | None = None,
success: S.Codec[SS, Any, Any, Any] | None = None,
failure: S.Codec[FF, Any, Any, Any] | None = None,
failure_mode: Literal["error"] = "error",
dependencies: Sequence[type[RR]] = (),
needs_approval: NeedsApproval | None = None,
to_model_output: Callable[[SS], Sequence[ToolModelOutputPart]] | None = None,
) -> Tool[NN, PP, SS, FF, FF, RR]: ...
@overload
def make[NN: LiteralString, PP = dict[str, Never], SS = None, FF = Never, RR = Never](
name: NN,
*,
description: str | None = None,
parameters: S.Codec[PP, Any, Any, Any] | None = None,
success: S.Codec[SS, Any, Any, Any] | None = None,
failure: S.Codec[FF, Any, Any, Any] | None = None,
failure_mode: Literal["return"],
dependencies: Sequence[type[RR]] = (),
needs_approval: NeedsApproval | None = None,
to_model_output: Callable[[SS], Sequence[ToolModelOutputPart]] | None = None,
) -> Tool[NN, PP, SS, FF, Never, RR]: ...
def make(
name: str,
*,
description: str | None = None,
parameters: S.Top | None = None,
success: S.Top | None = None,
failure: S.Top | None = None,
failure_mode: FailureMode = "error",
dependencies: Sequence[type] = (),
needs_approval: NeedsApproval | None = None,
to_model_output: ToModelOutput | None = None,
) -> Tool[Any, Any, Any, Any, Any, Any]:
"""A tool the toolkit handles. Its parameters default to none, its
success to ``None`` and its failure to ``Never``. ``to_model_output``
maps a successful result to the parts the model sees in its place."""
del dependencies
return Tool[Any, Any, Any, Any, Any, Any](
name=name,
parameters_schema=EMPTY_PARAMS if parameters is None else parameters,
success_schema=S.Null if success is None else success,
failure_schema=S.Never if failure is None else failure,
failure_mode=failure_mode,
description=description,
needs_approval=needs_approval,
to_model_output=to_model_output,
)dynamic#
dynamic[NN: LiteralString, PP = object, SS = object, FF = Never](name: NN, *, description: str | None = None, parameters: S.Codec[PP, Any, Any, Any] | None = None, success: S.Codec[SS, Any, Any, Any] | None = None, failure: S.Codec[FF, Any, Any, Any] | None = None, failure_mode: Literal['error'] = 'error', needs_approval: NeedsApproval | None = None, to_model_output: Callable[[SS], Sequence[ToolModelOutputPart]] | None = None) -> Dynamic[NN, PP, SS, FF, FF, Never]
dynamic[NN: LiteralString, SS = object, FF = Never](name: NN, *, description: str | None = None, parameters: JsonSchema, success: S.Codec[SS, Any, Any, Any] | None = None, failure: S.Codec[FF, Any, Any, Any] | None = None, failure_mode: Literal['error'] = 'error', needs_approval: NeedsApproval | None = None, to_model_output: Callable[[SS], Sequence[ToolModelOutputPart]] | None = None) -> Dynamic[NN, object, SS, FF, FF, Never]
dynamic[NN: LiteralString, PP = object, SS = object, FF = Never](name: NN, *, description: str | None = None, parameters: S.Codec[PP, Any, Any, Any] | JsonSchema | None = None, success: S.Codec[SS, Any, Any, Any] | None = None, failure: S.Codec[FF, Any, Any, Any] | None = None, failure_mode: Literal['return'], needs_approval: NeedsApproval | None = None, to_model_output: Callable[[SS], Sequence[ToolModelOutputPart]] | None = None) -> Dynamic[NN, PP, SS, FF, Never, Never]A tool whose parameters are a schema or a raw JSON Schema; its success defaults to any value.
| Parameter | Type | Description |
|---|---|---|
name | ||
description | = None | |
parameters | = None | |
success | = None | |
failure | = None | |
failure_mode | = 'error' | |
needs_approval | = None | |
to_model_output | = None |
@overload
def dynamic[NN: LiteralString, PP = object, SS = object, FF = Never](
name: NN,
*,
description: str | None = None,
parameters: S.Codec[PP, Any, Any, Any] | None = None,
success: S.Codec[SS, Any, Any, Any] | None = None,
failure: S.Codec[FF, Any, Any, Any] | None = None,
failure_mode: Literal["error"] = "error",
needs_approval: NeedsApproval | None = None,
to_model_output: Callable[[SS], Sequence[ToolModelOutputPart]] | None = None,
) -> Dynamic[NN, PP, SS, FF, FF, Never]: ...
@overload
def dynamic[NN: LiteralString, SS = object, FF = Never](
name: NN,
*,
description: str | None = None,
parameters: JsonSchema,
success: S.Codec[SS, Any, Any, Any] | None = None,
failure: S.Codec[FF, Any, Any, Any] | None = None,
failure_mode: Literal["error"] = "error",
needs_approval: NeedsApproval | None = None,
to_model_output: Callable[[SS], Sequence[ToolModelOutputPart]] | None = None,
) -> Dynamic[NN, object, SS, FF, FF, Never]: ...
@overload
def dynamic[NN: LiteralString, PP = object, SS = object, FF = Never](
name: NN,
*,
description: str | None = None,
parameters: S.Codec[PP, Any, Any, Any] | JsonSchema | None = None,
success: S.Codec[SS, Any, Any, Any] | None = None,
failure: S.Codec[FF, Any, Any, Any] | None = None,
failure_mode: Literal["return"],
needs_approval: NeedsApproval | None = None,
to_model_output: Callable[[SS], Sequence[ToolModelOutputPart]] | None = None,
) -> Dynamic[NN, PP, SS, FF, Never, Never]: ...
def dynamic(
name: str,
*,
description: str | None = None,
parameters: S.Top | JsonSchema | None = None,
success: S.Top | None = None,
failure: S.Top | None = None,
failure_mode: FailureMode = "error",
needs_approval: NeedsApproval | None = None,
to_model_output: ToModelOutput | None = None,
) -> Dynamic[Any, Any, Any, Any, Any, Any]:
"""A tool whose parameters are a schema or a raw JSON Schema; its
success defaults to any value."""
is_schema = parameters is not None and hasattr(parameters, "__codec__")
return Dynamic[Any, Any, Any, Any, Any, Any](
name=name,
parameters_schema=cast("S.Top", parameters) if is_schema else S.Unknown,
success_schema=S.Unknown if success is None else success,
failure_schema=S.Never if failure is None else failure,
failure_mode=failure_mode,
description=description,
needs_approval=needs_approval,
to_model_output=to_model_output,
json_schema=None if is_schema or parameters is None else cast("JsonSchema", parameters),
)provider_defined#
provider_defined[NN: LiteralString, PP = None, SS = None, FF = Never](*, id, custom_name, provider_name, args=None, requires_handler=False, parameters=None, success=None, failure=None) -> Callable[..., ProviderDefined[NN, PP, SS, FF, FF, Never]]A provider-defined tool's constructor: call it with the tool's
arguments (encoded) and, when requires_handler, failure_mode.
| Parameter | Type | Description |
|---|---|---|
id | str | |
custom_name | NN | |
provider_name | str | |
args | S.Top | None = None | |
requires_handler | bool = False | |
parameters | S.Codec[PP, Any, Any, Any] | None = None | |
success | S.Codec[SS, Any, Any, Any] | None = None | |
failure | S.Codec[FF, Any, Any, Any] | None = None |
Returns Callable[..., ProviderDefined[NN, PP, SS, FF, FF, Never]]
def provider_defined[NN: LiteralString, PP = None, SS = None, FF = Never](
*,
id: str,
custom_name: NN,
provider_name: str,
args: S.Top | None = None,
requires_handler: bool = False,
parameters: S.Codec[PP, Any, Any, Any] | None = None,
success: S.Codec[SS, Any, Any, Any] | None = None,
failure: S.Codec[FF, Any, Any, Any] | None = None,
) -> Callable[..., ProviderDefined[NN, PP, SS, FF, FF, Never]]:
"""A provider-defined tool's constructor: call it with the tool's
arguments (encoded) and, when ``requires_handler``, ``failure_mode``."""
parameters_schema: S.Top = S.Null if parameters is None else parameters
success_schema: S.Top = S.Null if success is None else success
failure_schema: S.Top = S.Never if failure is None else failure
def construct(
args_value: Mapping[str, object] | None = None, /, **kwargs: object
) -> ProviderDefined[NN, PP, SS, FF, FF, Never]:
values = {**(args_value or {}), **kwargs}
mode = cast("FailureMode", values.pop("failure_mode", "error"))
return ProviderDefined(
name=custom_name,
parameters_schema=parameters_schema,
success_schema=success_schema,
failure_schema=failure_schema,
failure_mode=mode,
provider_id=id,
provider_name=provider_name,
args=values,
args_schema=S.Null if args is None else args,
requires_handler=requires_handler,
)
return constructget_description#
get_description(tool) -> str | NoneThe tool's description, or its parameters schema's.
| Parameter | Type | Description |
|---|---|---|
tool | AnyTool |
Returns str | None
def get_description(tool: AnyTool) -> str | None:
"""The tool's description, or its parameters schema's."""
if tool.description is not None:
return tool.description
annotations = tool.parameters_schema.__codec__().ast.annotations or {}
description = annotations.get("description")
return description if isinstance(description, str) else Noneget_json_schema#
get_json_schema(tool, *, transformer=None) -> JsonSchemaThe JSON Schema of the tool's parameters.
| Parameter | Type | Description |
|---|---|---|
tool | AnyTool | |
transformer | CodecTransformer | None = None |
Returns JsonSchema
def get_json_schema(tool: AnyTool, *, transformer: CodecTransformer | None = None) -> JsonSchema:
"""The JSON Schema of the tool's parameters."""
if isinstance(tool, Dynamic) and tool.json_schema is not None:
return tool.json_schema
return get_json_schema_from_schema(tool.parameters_schema, transformer=transformer)get_json_schema_from_schema#
get_json_schema_from_schema(schema, *, transformer=None) -> JsonSchemaschema's JSON Schema, its definitions under $defs.
| Parameter | Type | Description |
|---|---|---|
schema | S.Top | |
transformer | CodecTransformer | None = None |
Returns JsonSchema
def get_json_schema_from_schema(
schema: S.Top, *, transformer: CodecTransformer | None = None
) -> JsonSchema:
"""``schema``'s JSON Schema, its definitions under ``$defs``."""
if transformer is not None:
return transformer(schema)[1]
document = S.to_json_schema_document(schema)
result = dict(document.schema)
if document.definitions:
result["$defs"] = dict(document.definitions)
return resultget_strict_mode#
get_strict_mode(tool) -> bool | None| Parameter | Type | Description |
|---|---|---|
tool | AnyTool |
Returns bool | None
def get_strict_mode(tool: AnyTool) -> bool | None:
return tool.annotations.get_unsafe(Strict)unsafe_secure_json_parse#
unsafe_secure_json_parse(text) -> objectjson.loads, refusing an object with a __proto__ key or a
constructor object holding prototype (raises ValueError):
JavaScript would let such keys reach a prototype.
| Parameter | Type | Description |
|---|---|---|
text | str |
Returns object
def unsafe_secure_json_parse(text: str) -> object:
"""``json.loads``, refusing an object with a ``__proto__`` key or a
``constructor`` object holding ``prototype`` (raises ``ValueError``):
JavaScript would let such keys reach a prototype."""
value: object = parse_json_text(text)
if _SUSPECT.search(text) is None:
return value
pending: list[object] = [value]
while pending:
node = pending.pop()
if isinstance(node, dict):
items = cast("dict[str, object]", node)
if "__proto__" in items:
raise ValueError("Object contains forbidden prototype property")
constructor = items.get("constructor")
if isinstance(constructor, dict) and "prototype" in constructor:
raise ValueError("Object contains forbidden prototype property")
pending.extend(items.values())
elif isinstance(node, list):
pending.extend(cast("list[object]", node))
return value