tool

Documentation

Overview

Package tool defines a tool, its schema, and the wrappers that decorate one.

Index

• Constants
• type Call
• type DataType
• type Definition
  • func Describe(subject Tool) Definition
• type FocusedCall
• type Parameter
  • func Integer(name string, description string) Parameter
  • func String(name string, description string) Parameter
  • func (self Parameter) Optional() Parameter
• type Schema
  • func (self Schema) MarshalJSON() ([]byte, error)
• type Statistical
• type Statistics
  • func Stats(call Call) (Statistics, bool)
• type SyntaxCall
• type Tool
  • func Concurrent(inner Tool) Tool
  • func Define[T any](name string, description string, schema Schema, ...) Tool
  • func DefineMeasured[T any](name string, description string, schema Schema, ...) Tool
  • func Focus(inner Tool, pick func(Call) string) Tool
  • func FocusPath(inner Tool) Tool
  • func ReadOnly(inner Tool) Tool
  • func Syntax(inner Tool, language string) Tool

Constants

const (
	StatsResources = "resources"
	StatsRead      = "read"
	StatsWrite     = "write"
	StatsDiff      = "diff"
)

Statistics kinds classify call measurements.

Types

type Call

type Call interface {
	Render() string
	Detail() string
	Exec(ctx context.Context) (string, error)
}

Call is one decoded invocation. Render and Detail contain unstyled display text. Exec must pass its context to work started outside the process.

type DataType

type DataType string

DataType is the JSON Schema type of one value.

const (
	TypeObject  DataType = "object"
	TypeString  DataType = "string"
	TypeInteger DataType = "integer"
)

The JSON Schema types a parameter may declare.

type Definition

type Definition struct {
	Name        string // what the tool is called
	Description string // what the tool does
	Schema      Schema // what arguments it takes
}

Definition is what a tool is, in a form no wire format's shape leaks into.

func Describe

func Describe(subject Tool) Definition

Describe says what a tool is, for a provider to offer to the model however it offers things.

type FocusedCall

type FocusedCall interface {
	Call
	Focus() string
}

FocusedCall has one part of its rendering set apart from the rest.

type Parameter

type Parameter struct {
	Name        string   // what the argument is called
	Type        DataType // what kind of value it takes
	Description string   // what the argument means
	// contains filtered or unexported fields
}

Parameter is one argument a tool takes.

func Integer

func Integer(name string, description string) Parameter

Integer declares an integer parameter.

func String

func String(name string, description string) Parameter

String declares a string parameter.

func (Parameter) Optional

func (self Parameter) Optional() Parameter

Optional marks a parameter the model may leave out. An absent argument decodes as its zero value, which is what a call carrying none means, so a tool reads one the same either way.

type Schema

type Schema []Parameter

Schema is a tool's parameters, in the order the tool declares them.

func (Schema) MarshalJSON

func (self Schema) MarshalJSON() ([]byte, error)

MarshalJSON renders the parameters as the JSON Schema object the endpoint expects.

type Statistical

type Statistical interface {
	Call
	Statistics() (Statistics, bool)
}

Statistical is a call that records resource use while it runs.

type Statistics

type Statistics struct {
	Kind       string        `json:"kind,omitempty"`
	CPUTime    time.Duration `json:"cpu_time,omitempty"`
	PeakMemory uint64        `json:"peak_memory,omitempty"`
	Lines      int64         `json:"lines,omitempty"`
	Bytes      int64         `json:"bytes,omitempty"`
	Added      int64         `json:"added,omitempty"`
	Removed    int64         `json:"removed,omitempty"`
}

Statistics are resources consumed by a call, where its tool can measure them.

func Stats

func Stats(call Call) (Statistics, bool)

Stats returns a call's resource statistics and whether it measured any.

type SyntaxCall

type SyntaxCall interface {
	Call
	Syntax() string
}

SyntaxCall has a rendering written in a language a display may highlight.

type Tool

type Tool interface {
	Name() string
	Description() string
	Schema() Schema
	Concurrent() bool
	ReadOnly() bool
	Parse(arguments string) (Call, error)
}

Tool is one operation the model can call.

func Concurrent

func Concurrent(inner Tool) Tool

Concurrent marks a tool as safe to run alongside others.

func Define

func Define[T any](
	name string,
	description string,
	schema Schema,
	render func(args T) (string, string),
	exec func(ctx context.Context, args T) (string, error),
) Tool

Define builds a tool from functions that render and execute its argument type.

func DefineMeasured

func DefineMeasured[T any](
	name string,
	description string,
	schema Schema,
	render func(args T) (string, string),
	exec func(ctx context.Context, args T) (string, Statistics, error),
) Tool

DefineMeasured builds a tool whose calls report resource statistics.

func Focus

func Focus(inner Tool, pick func(Call) string) Tool

Focus marks the part of a call rendering a display should set apart.

func FocusPath

func FocusPath(inner Tool) Tool

FocusPath sets apart the last component of a path rendering.

func ReadOnly

func ReadOnly(inner Tool) Tool

ReadOnly marks a tool as changing nothing.

func Syntax

func Syntax(inner Tool, language string) Tool

Syntax marks the language a call rendering is written in.