Tools Package

The tools package provides a comprehensive framework for registering, managing, and executing tools in the Dojo Genesis Go backend.

Features

• Type-safe tool definitions with JSON schema parameter validation
• Thread-safe global registry for tool management
• Context-aware execution with configurable timeouts
• Comprehensive helper functions for parameter extraction
• 94.7% test coverage with extensive unit tests

Core Components

ToolDefinition

Defines the structure of a tool:

type ToolDefinition struct {
    Name        string                 `json:"name"`
    Description string                 `json:"description"`
    Parameters  map[string]interface{} `json:"parameters"`
    Function    ToolFunc               `json:"-"`
}

ToolFunc

Function signature for all tools:

type ToolFunc func(context.Context, map[string]interface{}) (map[string]interface{}, error)

Registry Operations

RegisterTool

Register a new tool in the global registry:

def := &ToolDefinition{
    Name:        "echo_tool",
    Description: "Echoes the input message",
    Parameters: map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "message": map[string]interface{}{
                "type": "string",
            },
        },
        "required": []interface{}{"message"},
    },
    Function: func(ctx context.Context, params map[string]interface{}) (map[string]interface{}, error) {
        message := GetStringParam(params, "message", "")
        return map[string]interface{}{
            "success": true,
            "echo":    message,
        }, nil
    },
}

if err := RegisterTool(def); err != nil {
    log.Fatal(err)
}

GetTool

Retrieve a tool by name:

tool, err := GetTool("echo_tool")
if err != nil {
    log.Fatal(err)
}

GetAllTools

Get all registered tools:

tools := GetAllTools()
for _, tool := range tools {
    fmt.Printf("Tool: %s - %s\n", tool.Name, tool.Description)
}

InvokeTool

Execute a tool with default 30-second timeout:

result, err := InvokeTool(context.Background(), "echo_tool", map[string]interface{}{
    "message": "Hello, World!",
})

InvokeToolWithTimeout

Execute a tool with custom timeout:

result, err := InvokeToolWithTimeout(
    context.Background(),
    "slow_tool",
    params,
    2*time.Minute,
)

Parameter Validation

The framework automatically validates parameters against the JSON schema defined in the tool's Parameters field.

Supported JSON Schema Types

• string
• number
• integer
• boolean
• array
• object

Example Schema

Parameters: map[string]interface{}{
    "type": "object",
    "properties": map[string]interface{}{
        "name": map[string]interface{}{
            "type": "string",
        },
        "age": map[string]interface{}{
            "type": "integer",
        },
        "enabled": map[string]interface{}{
            "type": "boolean",
        },
    },
    "required": []interface{}{"name"},
}

Helper Functions

The package provides type-safe parameter extraction helpers:

GetStringParam

message := GetStringParam(params, "message", "default")

GetIntParam

count := GetIntParam(params, "count", 10)

GetBoolParam

enabled := GetBoolParam(params, "enabled", false)

GetFloat64Param

threshold := GetFloat64Param(params, "threshold", 0.5)

GetStringSliceParam

items := GetStringSliceParam(params, "items", []string{})

GetMapParam

metadata := GetMapParam(params, "metadata", map[string]interface{}{})

GetDurationParam

timeout := GetDurationParam(params, "timeout", 30*time.Second)

Thread Safety

The registry is fully thread-safe and can be accessed concurrently from multiple goroutines. All registry operations use read-write locks to ensure data consistency.

Testing

Run tests with:

go test -v ./tools/...

Check coverage:

go test -cover ./tools/...

Generate coverage report:

go test -coverprofile=coverage.out ./tools/...
go tool cover -html=coverage.out

Error Handling

All functions return descriptive errors:

• Tool registration errors (nil definition, empty name, nil function, duplicate)
• Tool retrieval errors (not found)
• Parameter validation errors (missing required, type mismatch)
• Execution errors (timeout, context cancellation, function errors)

Performance

• Lock-free reads when multiple goroutines read from the registry
• Parallel tool execution supported via goroutines
• Context-based cancellation for efficient resource management
• Configurable timeouts to prevent hanging operations