ToolSearch

Search is a way to show a model a large set of tools, or one that changes from turn to turn. The model is given two tools in place of one for each: tool_search, which finds tools by what they do and tells their parameters, and tool_call, which runs one of them by its name. What the model is shown stays the same however many tools there are, and costs the tokens of what it searched for, not of the whole set.

toolkit makes that toolkit from the one it presents, which is the model’s to search and call. Running a tool is the presented toolkit’s own, so what it decides stays decided: a tool that needs approval needs it when the model calls it through tool_call, and a call fails as it fails there.

Since v0.1.0

Constructors

toolkit

Makes the toolkit of tool_search and tool_call over presented. Building contacts nothing.

Example (Presenting a large set of tools as a search)

import { Assembly, ToolSearch } from "@amends-dev/toolkit"
import { Effect } from "effect"

declare const members: ReadonlyArray<Assembly.Member> // an API's hundreds of operations

const program = Effect.gen(function* () {
  const assembled = yield* Assembly.toolkit(members, () => "allow")
  // The model is shown `tool_search` and `tool_call`, however many tools there are.
  return yield* ToolSearch.toolkit(assembled, { limit: 10 })
})

Signature

declare const toolkit: <Tools extends Record<string, Tool.Any>>(
  presented: Toolkit.WithHandler<Tools>,
  options?: Options | undefined
) => Effect.Effect<
  Toolkit.WithHandler<{
    readonly tool_search: Tool.Tool<
      "tool_search",
      {
        readonly parameters: Schema.Struct<{
          readonly query: Schema.String
          readonly limit: Schema.optional<Schema.Int>
        }>
        readonly success: Schema.Struct<{
          readonly tools: Schema.$Array<
            Schema.Struct<{
              readonly name: Schema.String
              readonly description: Schema.optional<Schema.String>
              readonly inputSchema: Schema.Codec<Schema.Json, Schema.Json, never, never>
            }>
          >
          readonly matched: Schema.Int
          readonly available: Schema.Int
        }>
        readonly failure: Schema.Struct<{
          readonly code: Schema.String
          readonly message: Schema.String
          readonly retryable: Schema.Boolean
        }>
        readonly failureMode: "return"
      },
      never
    >
    readonly tool_call: Tool.Tool<
      "tool_call",
      {
        readonly parameters: Schema.Struct<{
          readonly name: Schema.String
          readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>
        }>
        readonly success: Schema.Codec<Schema.Json, Schema.Json, never, never>
        readonly failure: Schema.Struct<{
          readonly code: Schema.String
          readonly message: Schema.String
          readonly retryable: Schema.Boolean
        }>
        readonly failureMode: "return"
      },
      never
    >
  }>,
  never,
  Tool.HandlerServices<Tools[keyof Tools]>
>

Source

Since v0.1.0

Options

Options (interface)

What toolkit takes besides the toolkit it presents.

Signature

export interface Options {
  /** How many tools a search returns when it does not ask for a number. Five by default. */
  readonly limit?: number
}

Source

Since v0.1.0