GitHub

API reference for toolkit.

Groups of tools and their handlers (Effect's Toolkit).

A toolkit is an effect: run, it reads its tools' handlers from the context and gives a WithHandler, which a language model uses to run the tool calls it makes::

toolkit = Toolkit.make(get_weather, get_time)
handlers = toolkit.to_layer(
    get_weather.handler(lambda params, ctx: fx.succeed(...)),
    get_time.handler(lambda params, ctx: fx.succeed(...)),
)
response = language_model.generate_text("...", toolkit=toolkit).pipe(
    fx.provide(handlers)
)

Toolkit[N_co, RP_co, HE_co, R_co] keeps the tool names N_co, the union RP_co of each tool's ToolResultSuccess and ToolResultFailure, the errors its handlers raise HE_co and the services they need R_co; the toolkit itself needs Handlers[N_co], which to_layer provides.

Re-exports

Values

AttributeTypeDescription
emptyToolkit[Never, Never, Never, Never]

The toolkit with no tools.

Types

TypeDefinitionDescription
AnyToolkittype AnyToolkit = Toolkit[Any, Any, Any, Any]

Classes

Functions

map_handler_contexts

map_handler_contexts(toolkit, context, f) -> Context[Any]

context with f applied to the context each of toolkit's handlers kept from where its layer was built.

ParameterTypeDescription
toolkitToolkit[Any, Any, Any, Any]
contextContext[Any]
fCallable[[Context[Any]], Context[Any]]

Returns Context[Any]

def map_handler_contexts(
    toolkit: Toolkit[Any, Any, Any, Any],
    context: Context[Any],
    f: Callable[[Context[Any]], Context[Any]],
) -> Context[Any]:
    """``context`` with ``f`` applied to the context each of ``toolkit``'s
    handlers kept from where its layer was built."""
    out = context
    for tool in toolkit.tools.values():
        tag = _handler_tag(tool.id)
        found, registered = out.lookup(tag)
        if found:
            out = out.add(tag, replace(registered, context=f(registered.context)))
    return out

make

make() -> Toolkit[Never, Never, Never, Never]
make(t1: Tool[N1, Any, S1, F1, EE, RR], /) -> Toolkit[N1, _Results[N1, S1, F1], EE, RR]
make(t1: Tool[N1, Any, S1, F1, EE, RR], t2: Tool[N2, Any, S2, F2, EE, RR], /) -> Toolkit[N1 | N2, _Results[N1, S1, F1] | _Results[N2, S2, F2], EE, RR]
make(t1: Tool[N1, Any, S1, F1, EE, RR], t2: Tool[N2, Any, S2, F2, EE, RR], t3: Tool[N3, Any, S3, F3, EE, RR], /) -> Toolkit[N1 | N2 | N3, _Results[N1, S1, F1] | _Results[N2, S2, F2] | _Results[N3, S3, F3], EE, RR]
make(t1: Tool[N1, Any, S1, F1, EE, RR], t2: Tool[N2, Any, S2, F2, EE, RR], t3: Tool[N3, Any, S3, F3, EE, RR], t4: Tool[N4, Any, S4, F4, EE, RR], /) -> Toolkit[N1 | N2 | N3 | N4, _Results[N1, S1, F1] | _Results[N2, S2, F2] | _Results[N3, S3, F3] | _Results[N4, S4, F4], EE, RR]
make(*tools: AnyTool = ()) -> AnyToolkit

A toolkit of tools, by name (a later tool replaces an earlier one of the same name).

ParameterTypeDescription
tools= ()
@overload
def make() -> Toolkit[Never, Never, Never, Never]: ...
@overload
def make(t1: Tool[N1, Any, S1, F1, EE, RR], /) -> Toolkit[N1, _Results[N1, S1, F1], EE, RR]: ...
@overload
def make(
    t1: Tool[N1, Any, S1, F1, EE, RR], t2: Tool[N2, Any, S2, F2, EE, RR], /
) -> Toolkit[N1 | N2, _Results[N1, S1, F1] | _Results[N2, S2, F2], EE, RR]: ...
@overload
def make(
    t1: Tool[N1, Any, S1, F1, EE, RR],
    t2: Tool[N2, Any, S2, F2, EE, RR],
    t3: Tool[N3, Any, S3, F3, EE, RR],
    /,
) -> Toolkit[
    N1 | N2 | N3, _Results[N1, S1, F1] | _Results[N2, S2, F2] | _Results[N3, S3, F3], EE, RR
]: ...
@overload
def make(
    t1: Tool[N1, Any, S1, F1, EE, RR],
    t2: Tool[N2, Any, S2, F2, EE, RR],
    t3: Tool[N3, Any, S3, F3, EE, RR],
    t4: Tool[N4, Any, S4, F4, EE, RR],
    /,
) -> Toolkit[
    N1 | N2 | N3 | N4,
    _Results[N1, S1, F1] | _Results[N2, S2, F2] | _Results[N3, S3, F3] | _Results[N4, S4, F4],
    EE,
    RR,
]: ...
@overload
def make(*tools: AnyTool) -> AnyToolkit: ...
def make(*tools: AnyTool) -> AnyToolkit:
    """A toolkit of ``tools``, by name (a later tool replaces an earlier
    one of the same name)."""
    return Toolkit({tool.name: tool for tool in tools})

merge

merge(k1: Toolkit[N1, RP1, EE, RR], k2: Toolkit[N2, RP2, EE, RR], /) -> Toolkit[N1 | N2, RP1 | RP2, EE, RR]
merge(*toolkits: AnyToolkit = ()) -> AnyToolkit

One toolkit of every toolkit's tools (a later one wins a name).

ParameterTypeDescription
toolkits= ()
@overload
def merge(
    k1: Toolkit[N1, RP1, EE, RR], k2: Toolkit[N2, RP2, EE, RR], /
) -> Toolkit[N1 | N2, RP1 | RP2, EE, RR]: ...
@overload
def merge(*toolkits: AnyToolkit) -> AnyToolkit: ...
def merge(*toolkits: AnyToolkit) -> AnyToolkit:
    """One toolkit of every toolkit's tools (a later one wins a name)."""
    tools: dict[str, AnyTool] = {}
    for toolkit in toolkits:
        tools.update(toolkit.tools)
    return Toolkit(tools)