Documentation
¶
Overview ¶
Package tool builds engine tools from typed Go handlers. The argument schema is generated from the input struct, and every call is validated against it before the handler runs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New[In, Out any](name, description string, fn func(ctx context.Context, inv cortex.Invocation, in In) (Out, error), opts ...Option) (llm.Tool, engine.ToolHandler)
New builds a tool definition and handler from a typed function. The schema comes from In, which must be a struct. It panics when the schema cannot be built, because that is a mistake in the program, not in a call.
The handler validates the call's arguments against the schema before fn runs. A failure comes back as an ordinary tool error the model can read. An Out of string or json.RawMessage is returned as is. Anything else is marshalled to JSON. fn's own error is returned unwrapped, so cortex.ErrEffectUncertain still matches with errors.Is.
New panics when given RetrySafe: a definition and a handler cannot carry the mark to the engine, and dropping it silently would leave a tool the host thinks is retry-safe stopping runs as uncertain after a crash. Use Register, or engine.WithToolRetrySafe(name).
func Register ¶
func Register[In, Out any](name, description string, fn func(ctx context.Context, inv cortex.Invocation, in In) (Out, error), opts ...Option) engine.Option
Register is New plus the engine wiring: it registers the tool with engine.WithTool and, when RetrySafe is given, marks it with engine.WithToolRetrySafe.
func Schema ¶
Schema returns the JSON Schema for In as the map an llm.Tool carries in Parameters. In must be a struct. The root is a closed object: unknown properties are rejected. Numbers decode as json.Number, the same shape the engine's hand-written tool schemas use, so a prepared snapshot hashes both alike.
Types ¶
type Option ¶
type Option func(*options)
Option adjusts how Register builds a tool. RetrySafe is the only one, and New panics when given it, since New cannot carry it to the engine.
func RetrySafe ¶
func RetrySafe() Option
RetrySafe declares that the handler may be run again after a crash: it only reads, or it is idempotent through the effect journal. Without it the engine treats an interrupted call as uncertain.
Only Register can act on it, because only Register reaches the engine. New panics when given it; mark a tool built with New by passing engine.WithToolRetrySafe with its name alongside engine.WithTool.
Source Files