Iris Tools Package

tools

The tools package provides the tool registry, middleware system, and helper types for building tool-augmented AI applications. As of v0.11.0+, it includes a comprehensive middleware system for logging, caching, rate limiting, retries, and circuit breakers.

Tool Interface

type Tool interface {
    Name() string                                                  // Unique identifier
    Description() string                                           // Human-readable description
    Schema() ToolSchema                                            // JSON Schema for parameters
    Call(ctx context.Context, args json.RawMessage) (any, error)   // Execution
}

Registry

Thread-safe tool registry for managing and executing tools:

func NewRegistry(opts ...RegistryOption) *Registry
func WithRegistryMiddleware(middlewares ...Middleware) RegistryOption

func (r *Registry) Register(t Tool) error
func (r *Registry) RegisterWithMiddleware(t Tool, middlewares ...Middleware) error
func (r *Registry) Get(name string) (Tool, bool)
func (r *Registry) List() []Tool
func (r *Registry) Execute(ctx context.Context, name string, args json.RawMessage) (any, error)

Middleware System

Middleware wraps tool execution to add cross-cutting concerns:

type ToolCallFunc func(ctx context.Context, args json.RawMessage) (any, error)
type Middleware func(next ToolCallFunc) ToolCallFunc

func Chain(middlewares ...Middleware) Middleware
func ApplyMiddleware(tool Tool, middlewares ...Middleware) Tool
func ForTools(toolNames []string, middleware Middleware) Middleware
func ExceptTools(toolNames []string, middleware Middleware) Middleware

Built-in Middleware

Middleware	Function	Description
Logging	WithLogging(logger)	Log tool calls with timing
Detailed Logging	WithDetailedLogging(logger)	Log with arguments (dev only)
Timeout	WithTimeout(duration)	Enforce execution time limit
Rate Limit	WithRateLimit(ratePerSecond)	Token bucket rate limiting
Cache	WithCache(cache, ttl)	Cache idempotent tool results
Validation	WithBasicValidation()	Validate JSON arguments
Metrics	WithMetrics(collector)	Collect execution metrics
Retry	WithRetry(config)	Retry transient failures
Circuit Breaker	WithCircuitBreaker(config)	Prevent cascading failures

Middleware Configuration Types

type RetryConfig struct {
    MaxAttempts int
    InitialWait time.Duration
    MaxWait     time.Duration
    Multiplier  float64
    Retryable   func(err error) bool
}

type CircuitBreakerConfig struct {
    FailureThreshold int           // Failures before opening
    SuccessThreshold int           // Successes to close from half-open
    OpenDuration     time.Duration // Time to stay open
}

func DefaultRetryConfig() RetryConfig
func DefaultCircuitBreakerConfig() CircuitBreakerConfig

ToolContext

Share data between middleware:

type ToolContext struct {
    ToolName  string
    CallID    string
    Iteration int
    Schema    ToolSchema
    Metadata  map[string]any
}

func ContextWithToolContext(ctx context.Context, tc *ToolContext) context.Context
func ToolContextFromContext(ctx context.Context) *ToolContext

Typical Usage

// Create middleware chain
middleware := tools.Chain(
    tools.WithLogging(log.Default()),
    tools.WithTimeout(30 * time.Second),
    tools.WithRetry(tools.DefaultRetryConfig()),
)

// Create registry with middleware
registry := tools.NewRegistry(
    tools.WithRegistryMiddleware(middleware),
)

// Register tools
registry.Register(weatherTool)
registry.Register(searchTool)

// Use with ChatBuilder
resp, err := client.Chat("gpt-4o").
    User("What's the weather in SF?").
    Tools(registry.List()...).
    GetResponse(ctx)