Documentation
¶
Overview ¶
Package tool defines the provider-neutral executable tool contract, its binding and authorization boundaries, typed function adapter, and instance-scoped registry.
Example ¶
package main
import (
"context"
"fmt"
"github.com/Tangerg/scope/core/chat"
"github.com/Tangerg/scope/core/tool"
)
func main() {
type input struct {
A int `json:"a"`
B int `json:"b"`
}
add, err := tool.NewFunc(tool.FuncConfig{
Name: "add",
Description: "add two integers",
}, func(_ context.Context, value input) (int, error) {
return value.A + value.B, nil
})
if err != nil {
panic(err)
}
registry, err := tool.NewRegistry(add)
if err != nil {
panic(err)
}
fmt.Println(registry.Definitions()[0].Name)
binding, ok := registry.Resolve("add")
if !ok {
panic("missing add")
}
invocation, err := binding.Prepare(chat.ToolCall{ID: "call-1", Name: "add", Arguments: `{"a":2,"b":3}`})
if err != nil {
panic(err)
}
result, err := binding.Call(context.Background(), invocation)
if err != nil {
panic(err)
}
text, _ := result.Text()
fmt.Println(text)
}
Output: add 5
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrDuplicateTool = errors.New("tool: duplicate tool") ErrInvalidRegistry = errors.New("tool: invalid registry") )
var ( ErrInvalidTool = errors.New("tool: invalid tool") ErrInvalidInvocation = errors.New("tool: invalid invocation") )
var ErrAuthorizationDenied = errors.New("tool: authorization denied")
var ErrInvalidWrappingChain = errors.New("tool: invalid wrapping chain")
Functions ¶
Types ¶
type Authorization ¶
type Authorization struct {
// contains filtered or unexported fields
}
Authorization carries only the frozen model-visible contract and validated arguments, so policy code cannot bypass Binding or execute the invocation.
func (Authorization) Arguments ¶
func (a Authorization) Arguments() []byte
Arguments is detached for the same reason as Definition.
func (Authorization) Definition ¶
func (a Authorization) Definition() chat.ToolDefinition
Definition is detached because policy implementations may retain or annotate what they inspect without changing the executable contract.
type Authorizer ¶
type Authorizer interface {
Authorize(ctx context.Context, authorization Authorization) error
}
Authorizer is deliberately smaller than an application permission system: identity, consent, tenancy, and policy storage remain caller-owned context. Returning any error denies execution and preserves that cause.
type AuthorizerFunc ¶
type AuthorizerFunc func(context.Context, Authorization) error
func (AuthorizerFunc) Authorize ¶
func (a AuthorizerFunc) Authorize(ctx context.Context, authorization Authorization) error
type Binding ¶
type Binding struct {
// contains filtered or unexported fields
}
Binding freezes one Tool definition and compiles its input schema. It is the canonical trust boundary between an untrusted chat.ToolCall and execution. A successfully constructed Binding and every Invocation it creates are safe for concurrent use when the underlying Tool is safe for concurrent calls.
func (Binding) Call ¶
func (b Binding) Call(ctx context.Context, invocation Invocation) (chat.ToolOutput, error)
Call executes an Invocation created by this exact Binding. It rejects values promoted by another binding even when the public Tool name happens to match.
func (Binding) Definition ¶
func (b Binding) Definition() chat.ToolDefinition
Definition returns an independent snapshot of the frozen definition.
type Func ¶
type Func[In, Out any] struct { // contains filtered or unexported fields }
Func adapts a typed Go function to Tool. It owns the derived input contract, strict argument decoding, invocation, and result encoding.
Func is immutable after construction and is safe for concurrent calls when the wrapped function is safe for concurrent calls.
func (Func[In, Out]) Call ¶
func (f Func[In, Out]) Call(ctx context.Context, invocation Invocation) (chat.ToolOutput, error)
Call strictly decodes a promoted invocation, invokes the wrapped function, and returns a provider-neutral result.
func (Func[In, Out]) Definition ¶
func (f Func[In, Out]) Definition() chat.ToolDefinition
type FuncConfig ¶
FuncConfig describes a typed function tool. NewFunc derives InputSchema from In so the decoder and model-visible contract cannot drift independently.
type Guard ¶
type Guard struct {
// contains filtered or unexported fields
}
Guard keeps authorization at the universal Tool.Call boundary, which makes the same policy work for direct calls, registries, and managed runtimes.
func NewGuard ¶
func NewGuard(config GuardConfig) (Guard, error)
func (Guard) Call ¶
func (g Guard) Call(ctx context.Context, invocation Invocation) (chat.ToolOutput, error)
func (Guard) Definition ¶
func (g Guard) Definition() chat.ToolDefinition
type GuardConfig ¶
type GuardConfig struct {
Tool Tool
Authorizer Authorizer
}
type Invocation ¶
type Invocation struct {
// contains filtered or unexported fields
}
Invocation is a complete JSON object validated against one exact frozen Tool definition. Its fields are intentionally private: only Binding.Prepare can promote an untrusted model proposal into an executable invocation.
func (Invocation) Arguments ¶
func (i Invocation) Arguments() []byte
Arguments returns an owned copy of the validated JSON object.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is an instance-scoped, concurrency-safe collection of executable tools. Its zero value is ready to use. Each runtime or process owns its registry explicitly; there is no package-global counterpart. Registration is atomic for the full batch, definitions are snapshotted at registration time, and model-visible views are returned as defensive copies in stable name order.
func NewRegistry ¶
func (*Registry) Definitions ¶
func (r *Registry) Definitions() []chat.ToolDefinition
type Tool ¶
type Tool interface {
// Definition returns a detached, valid schema snapshot. Callers may expose or
// mutate the returned value without changing subsequent calls or execution.
Definition() chat.ToolDefinition
// Call executes one schema-validated invocation. Implementations still own
// capability-specific semantic validation. Ordinary failure is returned as
// error without assigning retry or control-flow meaning. Implementations must
// honor ctx and must not retain the invocation or its arguments.
Call(ctx context.Context, invocation Invocation) (chat.ToolOutput, error)
}
Tool is the minimal executable capability used by model-driven runtimes. Definition returns an independent snapshot safe to expose to a model. Call receives only an Invocation promoted by the exact frozen Binding.
Tool assigns no control-flow meaning to errors. Retry, pause, abort, and ordinary error feedback belong to the runtime driving the tool.
type WrappingTool ¶
type WrappingTool interface {
// Unwrap returns the next inner tool in a finite decorator chain. It must
// return the same tool for the wrapper's lifetime and must not perform I/O;
// cycles and excessive depth make the chain invalid.
Unwrap() Tool
}
WrappingTool is implemented by a decorator that stands in for another tool. Optional capabilities are resolved through this chain, so a decorator states once that it wraps a tool instead of re-implementing every optional interface the inner tool may acquire.
Source Files