llmtools

README

LLM Tools for Go

LLM Tool implementations for Golang

• Features at a glance
• Package overview
• Installation
• Quickstart
  • Registry with Built-ins
  • Direct Tool Usage
• Development

Features at a glance

• Go-native tool implementations for common local tasks. Current tools:

  • File system (fstool):

    • List directory (listdir): Lists entries under a directory, optionally filtered via glob.
    • Read file (readfile): Reads local files as UTF-8 text (rejects non-text content) or base64 binary (with image/file output kinds). Includes a size cap for safety.
    • Search files (searchfiles): Recursively searches path and (text) content using RE2 regex.
    • Inspect path (statpath): Returns existence, size, timestamps, and directory flag.

  • Images (imagetool):

    • Inspect image (inspectimage): Returns dimensions, format, size, modtime for local images.

• Tool registry for:

  • collecting and listing tool manifests (stable ordering)
  • invoking tools via JSON input/output with strict JSON input decoding
  • tool call timeout handling

Package overview

• llmtools: Registry and registration helpers
• spec: Tool manifests + IO/output schema
• fstool: Filesystem tools (standalone callable)
• imagetool: Image tools (standalone callable)

Installation

# Go 1.25+
go get github.com/flexigpt/llmtools-go

Quickstart

Registry with Built-ins

package main

import (
    "context"
    "encoding/json"
    "fmt"

    "github.com/flexigpt/llmtools-go"
    "github.com/flexigpt/llmtools-go/spec"
)

func main() {
    r, err := llmtools.NewBuiltinRegistry(
        llmtools.WithCallTimeoutForAll(5), // or 5*time.Second
    )
    if err != nil {
        panic(err)
    }

    // List tool manifests (for prompt/tool definition)
    for _, t := range r.Tools() {
        fmt.Printf("%s (%s): %s\n", t.Slug, t.GoImpl.FuncID, t.Description)
    }

    // Call a tool by FuncID using JSON input
    in := json.RawMessage(`{"path": ".", "pattern": "*.go"}`)
    out, err := r.Call(context.Background(), spec.FuncID("..."), in)
    if err != nil {
        panic(err)
    }

    fmt.Printf("tool outputs: %+v\n", out)
}

Direct Tool Usage

package main

import (
    "context"
    "fmt"

    "github.com/flexigpt/llmtools-go/fstool"
)

func main() {
    out, err := fstool.ListDirectory(context.Background(), fstool.ListDirectoryArgs{
        Path:    ".",
        Pattern: "*.md",
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(out.Entries)
}

Development

• Formatting follows gofumpt and golines via golangci-lint, which is also used for linting. All rules are in .golangci.yml.
• Useful scripts are defined in taskfile.yml; requires Task.
• Bug reports and PRs are welcome:
  • Keep the public API (package llmtools and spec) small and intentional.
  • Avoid leaking provider‑specific types through the public surface; put them under internal/.
  • Please run tests and linters before sending a PR.

Documentation

Index

• func RegisterBuiltins(r *Registry) error
• func RegisterOutputsTool[T any](r *Registry, tool spec.Tool, ...) error
• func RegisterTypedAsTextTool[T, R any](r *Registry, tool spec.Tool, fn func(context.Context, T) (R, error)) error
• type CallOption
  • func WithCallTimeout(d time.Duration) CallOption
• type Registry
  • func NewBuiltinRegistry(opts ...RegistryOption) (*Registry, error)
  • func NewRegistry(opts ...RegistryOption) (*Registry, error)
  • func (r *Registry) Call(ctx context.Context, funcID spec.FuncID, in json.RawMessage, ...) ([]spec.ToolStoreOutputUnion, error)
  • func (r *Registry) Lookup(funcID spec.FuncID) (spec.ToolFunc, bool)
  • func (r *Registry) RegisterTool(tool spec.Tool, fn spec.ToolFunc) error
  • func (r *Registry) Tools() []spec.Tool
• type RegistryOption
  • func WithDefaultCallTimeout(d time.Duration) RegistryOption
  • func WithLogger(logger *slog.Logger) RegistryOption

Functions

func RegisterBuiltins

func RegisterBuiltins(r *Registry) error

RegisterBuiltins registers the built-in tools into r.

func RegisterOutputsTool

func RegisterOutputsTool[T any](
	r *Registry,
	tool spec.Tool,
	fn func(context.Context, T) ([]spec.ToolStoreOutputUnion, error),
) error

RegisterOutputsTool registers a typed tool function that directly returns []ToolStoreOutputUnion. This is a function and not a method on struct as methods cannot have type params in go.

func RegisterTypedAsTextTool

func RegisterTypedAsTextTool[T, R any](
	r *Registry,
	tool spec.Tool,
	fn func(context.Context, T) (R, error),
) error

RegisterTypedAsTextTool registers a typed tool function whose output R is JSON-encodable. The JSON representation of R is wrapped into a single text block. This is a function and not a method on struct as methods cannot have type params in go.

Types

type CallOption

type CallOption func(*callOptions)

CallOption configures per-call behavior.

func WithCallTimeout

func WithCallTimeout(d time.Duration) CallOption

WithCallTimeout overrides the timeout for this single call. 0 means "no timeout" for this call (even if tool/registry default is non-zero).

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry provides lookup/register for Go tools by funcID, with json.RawMessage I/O.

func NewBuiltinRegistry

func NewBuiltinRegistry(opts ...RegistryOption) (*Registry, error)

NewBuiltinRegistry returns a Registry with all built-in tools registered. By default it applies a 5s timeout, but callers can override it by passing WithDefaultCallTimeout as a later option.

func NewRegistry

func NewRegistry(opts ...RegistryOption) (*Registry, error)

func (*Registry) Call

func (r *Registry) Call(
	ctx context.Context,
	funcID spec.FuncID,
	in json.RawMessage,
	callOpts ...CallOption,
) ([]spec.ToolStoreOutputUnion, error)

func (*Registry) Lookup

func (r *Registry) Lookup(funcID spec.FuncID) (spec.ToolFunc, bool)

func (*Registry) RegisterTool

func (r *Registry) RegisterTool(tool spec.Tool, fn spec.ToolFunc) error

func (*Registry) Tools

func (r *Registry) Tools() []spec.Tool

type RegistryOption

type RegistryOption func(*Registry) error

func WithDefaultCallTimeout

func WithDefaultCallTimeout(d time.Duration) RegistryOption

func WithLogger

func WithLogger(logger *slog.Logger) RegistryOption