RubyLLM::Tool Support in AIA

Overview

AIA supports function calling capabilities through the RubyLLM::Tool framework, enabling LLMs to execute custom functions during a chat session. Tools allow LLMs to perform actions beyond generating text, such as retrieving real-time information, executing system commands, accessing external APIs, and performing calculations.

AIA includes the shared_tools gem which provides a curated collection of commonly-used RubyLLM::Tool implementations. This collection is automatically available when using AIA and provides ready-to-use tools for common tasks.

For custom tool implementation details, refer to the examples found in the examples/tools directory, which contains several ready-to-use tool implementations.

How to Use Tools

AIA provides three CLI options to manage function calling:

--tools Option

This option specifies where to find tool implementations:

# Load shared tools collection (automatically included with AIA)
aia --chat --tools shared

# Load tools from multiple sources for use in a chat session
aia --chat --tools /path/to/tools/directory,other/tools/dir,my_tool.rb

# Combine shared tools with custom tools
aia --chat --tools shared,~/my-tools/

# Or use multiple --tools flags
aia --chat --tools my_first_tool.rb --tools /tool_repo/tools

Each path can be:

• The keyword shared - loads the shared_tools collection
• A Ruby file implementing a RubyLLM::Tool subclass
• A directory containing tool implementations (all Ruby files in that directory will be loaded)

Supporting files for tools can be placed in the same directory or subdirectories.

Shared Tools Collection

AIA includes a comprehensive collection of ready-to-use tools via the shared_tools gem:

File Operations

• read_file - Read file contents
• write_file - Write content to files
• edit_file - Edit existing files
• list_files - List directory contents
• search_files - Search for files and content

Web Utilities

• fetch_web_page - Retrieve web page content
• parse_html - Parse HTML content
• parse_json - Parse JSON data
• http_request - Make HTTP requests

System Tools

• run_shell_command - Execute shell commands
• get_system_info - Retrieve system information
• get_environment_vars - Access environment variables

Data Processing

• csv_reader - Read and process CSV files
• json_processor - Process JSON data
• text_analyzer - Analyze text content
• data_transformer - Transform data formats

API Helpers

• api_client - Generic API client
• webhook_handler - Handle webhook requests
• authentication - Handle API authentication

To use shared tools:

# Access all shared tools
aia --chat --tools shared

# Use specific shared tools only
aia --chat --tools shared --allowed_tools read_file,write_file,run_shell_command

Filtering the Tool Paths

The --tools option must have exact relative or absolute paths to the tool files to be used by AIA for function callbacks. If you are specifying directories, you may need to filter the entire set of tools to either allow some or reject others based upon some indicator in their file name. The following two options allow you to specify multiple sub-strings to match the tool paths against.

--at, --allowed_tools Option

Filters which tools to make available when loading from directories:

# Only allow tools with 'test' in their filename
--tools my_tools_directory --allowed_tools test

This is useful when you have many tools but only want to use specific ones in a session.

--rt, --rejected_tools Option

Excludes specific tools:

# Exclude tools with '_v1' in their filename
--tools my_tools_directory --rejected_tools _v1

This is ideal for excluding older versions or temporarily disabling specific tools.

Creating Your Own Tools

To create a custom tool:

1. Create a Ruby file that subclasses RubyLLM::Tool
2. Define the tool's parameters and functionality
3. Use the --tools option to load it in your AIA session

Example Custom Tool

# my_calculator.rb
require 'ruby_llm/tool'

module Tools
  class Calculator < RubyLLM::Tool
    description "Perform basic mathematical calculations"
    param :expression, desc: "Mathematical expression to evaluate (e.g., '2 + 2', '10 * 5')"

    def execute(expression:)
      begin
        # Note: eval is dangerous - use a proper math parser in production
        result = eval(expression)
        { result: result, expression: expression }
      rescue => e
        { error: "Invalid expression: #{e.message}" }
      end
    end
  end
end

Usage:

aia --chat --tools my_calculator.rb

Tool Development Best Practices

• Error handling: Always include proper error handling in your tools
• Input validation: Validate all parameters before processing
• Security: Be cautious with tools that execute system commands or eval code
• Documentation: Use clear descriptions and parameter documentation
• Return formats: Return structured data (hashes/arrays) for better LLM understanding

For further details, refer to the examples in the repository or the RubyLLM documentation.