GitHub

API reference for tool.

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

AttributeTypeDescription
EMPTY_PARAMSRecordSchema[str, Never, str, Never, Never, Never]

The parameters of a tool that takes none (Effect's EmptyParams).

EXECUTION_FAILURES.Bottom[ExecutionFailureDict]

A tool call that never ran: the user denied it, or the response ended first (Effect's ExecutionFailure).

Types

TypeDefinitionDescription
FailureModetype FailureMode = Literal['error', 'return']
FailureOrigintype FailureOrigin = Literal['parameters', 'handler', 'result']
NeedsApprovaltype NeedsApproval = bool | Callable[[Any, NeedsApprovalContext], bool | Effect[bool]]
ToModelOutputtype ToModelOutput = Callable[[Any], Sequence[ToolModelOutputPart]]

A tool's to_model_output: a successful result to the parts the model sees.

AnyTooltype AnyTool = Tool[Any, Any, Any, Any, Any, Any]
CodecTransformertype 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 CodecTransformer).

Classes

Functions

is_user_defined

is_user_defined(u) -> bool
ParameterTypeDescription
uobject

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
ParameterTypeDescription
uobject

Returns bool

def is_provider_defined(u: object) -> bool:
    return isinstance(u, ProviderDefined)

is_dynamic

is_dynamic(u) -> bool
ParameterTypeDescription
uobject

Returns bool

def is_dynamic(u: object) -> bool:
    return isinstance(u, Dynamic)

failure_result_schema

failure_result_schema(tool) -> S.Top

What a tool's failed result can be: an AiError, the tool's failure or an EXECUTION_FAILURE.

ParameterTypeDescription
toolAnyTool

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.

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

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

ParameterTypeDescription
idstr
custom_nameNN
provider_namestr
argsS.Top | None = None
requires_handlerbool = False
parametersS.Codec[PP, Any, Any, Any] | None = None
successS.Codec[SS, Any, Any, Any] | None = None
failureS.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 construct

get_description

get_description(tool) -> str | None

The tool's description, or its parameters schema's.

ParameterTypeDescription
toolAnyTool

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 None

get_json_schema

get_json_schema(tool, *, transformer=None) -> JsonSchema

The JSON Schema of the tool's parameters.

ParameterTypeDescription
toolAnyTool
transformerCodecTransformer | 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) -> JsonSchema

schema's JSON Schema, its definitions under $defs.

ParameterTypeDescription
schemaS.Top
transformerCodecTransformer | 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 result

get_strict_mode

get_strict_mode(tool) -> bool | None
ParameterTypeDescription
toolAnyTool

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

ParameterTypeDescription
textstr

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