tools

Documentation

Overview

Package tools provides a registry, dispatch, and explicit JSON-Schema helpers for tools the LLM may call.

Schemas are explicit; the package does not generate schemas from struct types (ADR-018). Callers who want struct-driven schemas use invopop/jsonschema:

import jsonschema "github.com/invopop/jsonschema"
schema, _ := json.Marshal(jsonschema.Reflect(&FooArgs{}))

Tool handlers capture the dependencies they need (storage, logger, clock) at registration time via closure (ADR-021). The Env passed to a Handler carries only fields that genuinely change per dispatch: SessionID and TurnID.

Index

• Variables
• func Array(items any, description string) map[string]any
• func Boolean(description string) map[string]any
• func Enum(description string, values ...string) map[string]any
• func Integer(description string) map[string]any
• func Number(description string) map[string]any
• func Object(props map[string]any, required ...string) json.RawMessage
• func String(description string) map[string]any
• type Env
• type Handler
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Defs() []llm.ToolDef
  • func (r *Registry) Dispatch(ctx context.Context, call llm.ToolCall, env Env) (Result, error)
  • func (r *Registry) Has(name string) bool
  • func (r *Registry) Register(def llm.ToolDef, h Handler) error
• type Result

Variables

var (
	ErrDuplicateTool = errors.New("aikido/tools: duplicate tool registration")
	ErrUnknownTool   = errors.New("aikido/tools: unknown tool")
)

Functions

func Array

func Array(items any, description string) map[string]any

Array builds an array-typed property schema.

func Boolean

func Boolean(description string) map[string]any

Boolean builds a boolean-typed property schema.

func Enum

func Enum(description string, values ...string) map[string]any

Enum builds a string-typed enum property schema.

func Integer

func Integer(description string) map[string]any

Integer builds an integer-typed property schema.

func Number

func Number(description string) map[string]any

Number builds a number-typed property schema.

func Object

func Object(props map[string]any, required ...string) json.RawMessage

Object builds a JSON Schema "object" from a property map and a list of required property names. Output is deterministic (properties are emitted in the order Go's encoding/json sorts map keys, which is alphabetical).

func String

func String(description string) map[string]any

String builds a string-typed property schema.

Types

type Env

type Env struct {
	SessionID string
	TurnID    uuid.UUID
}

Env carries per-call execution context to a Handler.

type Handler

type Handler func(ctx context.Context, args json.RawMessage, env Env) (Result, error)

Handler is the function signature every tool implements.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds tool definitions and their handlers.

func NewRegistry

func NewRegistry() *Registry

func (*Registry) Defs

func (r *Registry) Defs() []llm.ToolDef

Defs returns all registered ToolDefs in registration order.

func (*Registry) Dispatch

func (r *Registry) Dispatch(ctx context.Context, call llm.ToolCall, env Env) (Result, error)

Dispatch routes a ToolCall to its handler.

Returns ErrUnknownTool if the name is not registered. Argument bytes are passed verbatim — handlers parse them.

func (*Registry) Has

func (r *Registry) Has(name string) bool

Has reports whether a tool is registered.

func (*Registry) Register

func (r *Registry) Register(def llm.ToolDef, h Handler) error

Register adds a tool. Returns ErrDuplicateTool if the name is taken.

type Result

type Result struct {
	Content any
	Display string
}

Result is what a Handler returns. Content is JSON-serialized to the model.