SharedTools

A Ruby gem providing LLM-callable tools for browser automation, file operations, code evaluation, and more

SharedTools is a comprehensive collection of production-ready tools designed for LLM (Large Language Model) applications. Built on the RubyLLM framework, it provides a unified interface for common automation tasks while maintaining safety through a human-in-the-loop authorization system.

• 🔧 13+ Production Tools - Browser automation, file operations, database queries, code evaluation, PDF processing, system control, mathematical calculations, weather data, workflow management, data analysis, Docker integration, and more
• 🔒 Human-in-the-Loop Authorization - Built-in safety system for sensitive operations
• 🎯 Facade Pattern - Simplified interfaces with complex capabilities under the hood
• 🔌 Pluggable Drivers - Swap implementations for testing or different backends
• 📚 Comprehensive Documentation - Detailed guides, examples, and API reference
• ✅ Well Tested - 85%+ test coverage with Minitest

Add to your Gemfile:

gem 'shared_tools'
gem 'ruby_llm'  # Required LLM framework

Or install directly:

gem install shared_tools

Depending on which tools you use, you may need additional gems:

# For BrowserTool
gem 'watir'
gem 'webdrivers'

# For DatabaseTool and DatabaseQueryTool
gem 'sqlite3'  # or pg, mysql2, etc.

# For DocTool
gem 'pdf-reader'

# Core dependencies (automatically installed)
gem 'dentaku'          # For CalculatorTool
gem 'openweathermap'   # For WeatherTool
gem 'sequel'           # For DatabaseQueryTool
gem 'nokogiri'         # For various tools

require 'shared_tools'
require 'ruby_llm'

# Initialize an LLM agent with SharedTools
agent = RubyLLM::Agent.new(
  tools: [
    SharedTools::Tools::BrowserTool.new,
    SharedTools::Tools::DiskTool.new,
    SharedTools::Tools::DatabaseTool.new,
    SharedTools::Tools::CalculatorTool.new,
    SharedTools::Tools::WeatherTool.new,
    SharedTools::Tools::WorkflowManagerTool.new
  ]
)

# Use with human-in-the-loop authorization (default)
agent.process("Visit example.com and save the page title to title.txt")
# User will be prompted: "Allow BrowserTool to visit https://example.com? (y/n)"

# Or enable auto-execution for automated workflows
SharedTools.auto_execute(true)
agent.process("Calculate the square root of 144 and tell me the weather in London")

Web automation and scraping capabilities.

Actions:

• visit - Navigate to URLs
• page_inspect - Get page HTML content
• ui_inspect - Find elements by text
• selector_inspect - Find elements by CSS selector
• click - Click elements
• text_field_set - Fill in forms
• screenshot - Capture page screenshots

Example:

browser = SharedTools::Tools::BrowserTool.new

browser.execute(action: "visit", url: "https://example.com")
browser.execute(action: "page_inspect", full_html: false)

📖 Full Browser Documentation

Secure file system operations with path traversal protection.

Actions:

• file_create - Create new files
• file_read - Read file contents
• file_write - Write to files
• file_delete - Delete files
• file_move - Move/rename files
• file_replace - Find and replace text in files
• directory_create - Create directories
• directory_list - List directory contents
• directory_move - Move directories
• directory_delete - Delete directories

Example:

disk = SharedTools::Tools::DiskTool.new

disk.execute(action: "file_create", path: "./report.txt")
disk.execute(action: "file_write", path: "./report.txt", text: "Hello, World!")
content = disk.execute(action: "file_read", path: "./report.txt")

📖 Full Disk Documentation

Execute SQL operations on databases.

Actions:

• Execute SQL statements (CREATE, INSERT, SELECT, UPDATE, DELETE)
• Batch statement execution
• Transaction-like error handling (stops on first error)
• Support for SQLite, PostgreSQL, MySQL via drivers

Example:

require 'sqlite3'

db = SQLite3::Database.new(':memory:')
driver = SharedTools::Tools::Database::SqliteDriver.new(db: db)
database = SharedTools::Tools::DatabaseTool.new(driver: driver)

results = database.execute(
  statements: [
    "CREATE TABLE users (id INTEGER, name TEXT)",
    "INSERT INTO users VALUES (1, 'Alice')",
    "SELECT * FROM users"
  ]
)

📖 Full Database Documentation

Safe code evaluation for Ruby, Python, and shell commands.

Languages:

• ruby - Execute Ruby code
• python - Execute Python code (with sandboxing)
• shell - Execute shell commands

Example:

eval_tool = SharedTools::Tools::EvalTool.new

# Ruby evaluation
result = eval_tool.execute(language: "ruby", code: "puts 2 + 2")

# Shell command execution (requires authorization by default)
output = eval_tool.execute(language: "shell", code: "ls -la")

📖 Full Eval Documentation

PDF document processing and text extraction.

Actions:

• read_pdf - Read PDF content from specific pages or entire documents
• Extract text, statistics, and metadata
• Process multi-page documents

Example:

doc = SharedTools::Tools::DocTool.new

# Read first page
content = doc.execute(action: "read_pdf", path: "./document.pdf", page: 1)

# Read entire document
full_content = doc.execute(action: "read_pdf", path: "./document.pdf")

📖 Full Doc Documentation

System-level automation for mouse, keyboard, and screen control.

Actions:

• mouse_click - Click at coordinates
• mouse_move - Move mouse cursor
• mouse_position - Get current mouse position
• type - Type text
• key - Press keyboard keys and shortcuts
• hold_key - Hold keys for duration
• scroll - Scroll windows
• wait - Wait for specified duration

Example:

computer = SharedTools::Tools::ComputerTool.new

computer.execute(action: "mouse_click", coordinate: {x: 100, y: 200})
computer.execute(action: "type", text: "Hello, World!")
computer.execute(action: "key", text: "Return")

📖 Full Computer Documentation

Safe mathematical calculations without code execution risks.

Features:

• Safe expression evaluation using Dentaku parser
• Basic arithmetic: +, -, *, /, %, ^
• Mathematical functions: sqrt, round, abs
• Trigonometric functions: sin, cos, tan
• Configurable precision (0-10 decimal places)
• Comprehensive error handling

Example:

calculator = SharedTools::Tools::CalculatorTool.new

calculator.execute(expression: "2 + 2")
# => {success: true, result: 4.0, precision: 2}

calculator.execute(expression: "sqrt(16) * 2", precision: 4)
# => {success: true, result: 8.0, precision: 4}

Real-time weather data from OpenWeatherMap API.

Features:

• Current weather conditions for any city worldwide
• Multiple temperature units (metric, imperial, kelvin)
• Optional 3-day forecast data
• Comprehensive atmospheric data (humidity, pressure, wind)
• Requires OPENWEATHER_API_KEY environment variable

Example:

weather = SharedTools::Tools::WeatherTool.new

weather.execute(city: "London,UK", units: "metric")
# => {success: true, current: {temperature: 15.5, ...}}

weather.execute(city: "New York,US", units: "imperial", include_forecast: true)
# => Includes current weather and 3-day forecast

Manage complex multi-step workflows with persistent state.

Features:

• Create and track stateful workflows
• Step-by-step execution with state persistence
• Status monitoring and progress tracking
• Workflow completion and cleanup
• Survives process restarts

Example:

workflow = SharedTools::Tools::WorkflowManagerTool.new

# Start a workflow
result = workflow.execute(action: "start", step_data: {project: "demo"})
workflow_id = result[:workflow_id]

# Execute steps
workflow.execute(action: "step", workflow_id: workflow_id, step_data: {task: "compile"})
workflow.execute(action: "step", workflow_id: workflow_id, step_data: {task: "test"})

# Check status
workflow.execute(action: "status", workflow_id: workflow_id)

# Complete
workflow.execute(action: "complete", workflow_id: workflow_id)

Multi-stage data analysis orchestration.

Features:

• Automatic data source detection (files or URLs)
• Data structure analysis
• Statistical insights generation
• Visualization suggestions
• Correlation analysis
• Supports CSV, JSON, and text formats

Example:

analyzer = SharedTools::Tools::CompositeAnalysisTool.new

analyzer.execute(
  data_source: "./sales_data.csv",
  analysis_type: "comprehensive",
  options: {include_correlations: true, visualization_limit: 5}
)
# => Complete analysis with structure, insights, and visualizations

Safe, read-only database query execution.

Features:

• SELECT-only queries for security
• Automatic LIMIT clause enforcement
• Query timeout protection
• Prepared statement support
• Connection pooling
• Supports PostgreSQL, MySQL, SQLite, and more

Example:

db_query = SharedTools::Tools::DatabaseQueryTool.new

db_query.execute(
  query: "SELECT * FROM users WHERE active = ?",
  params: [true],
  limit: 50,
  timeout: 10
)
# => {success: true, row_count: 50, data: [...]}

Execute Docker Compose commands safely.

Features:

• Run commands in Docker containers
• Service specification
• Automatic container cleanup
• Build and run in one step

Example:

docker = SharedTools::Tools::Docker::ComposeRunTool.new

docker.execute(
  service: "app",
  command: "rspec",
  args: ["spec/main_spec.rb"]
)

Reference implementation for robust error handling patterns.

Features:

• Multiple error type handling
• Retry mechanisms with exponential backoff
• Input/output validation
• Resource cleanup patterns
• Detailed error categorization
• Support reference IDs for debugging

Example:

error_tool = SharedTools::Tools::ErrorHandlingTool.new

error_tool.execute(
  operation: "process",
  data: {name: "test", value: 42},
  max_retries: 3
)
# => Demonstrates comprehensive error handling patterns

SharedTools includes a human-in-the-loop authorization system for safety:

# Require user confirmation (default)
SharedTools.auto_execute(false)

# The LLM proposes an action
disk.execute(action: "file_delete", path: "./important.txt")
# Prompt: "Allow DiskTool to delete ./important.txt? (y/n)"

# Enable auto-execution for trusted workflows
SharedTools.auto_execute(true)
disk.execute(action: "file_delete", path: "./temp.txt")
# Executes immediately without prompting

📖 Authorization Guide

Comprehensive documentation is available at madbomber.github.io/shared_tools

• Getting Started - Installation, quick start, basic usage
• Tool Collections - Detailed documentation for each tool
• Guides - Authorization, drivers, error handling, testing
• Examples - Working code examples and workflows
• API Reference - Tool base class, facade pattern, driver interface
• Development - Architecture, contributing, changelog

The /examples directory contains working demonstrations:

• browser_tool_example.rb - Web automation
• disk_tool_example.rb - File operations
• database_tool_example.rb - SQL operations
• eval_tool_example.rb - Code evaluation
• doc_tool_example.rb - PDF processing
• comprehensive_workflow_example.rb - Multi-tool workflow

Run examples:

bundle install
ruby examples/browser_tool_example.rb

📖 View All Examples

git clone https://github.com/madbomber/shared_tools.git
cd shared_tools
bundle install

# Run all tests
bundle exec rake test

# Run specific test file
bundle exec ruby test/shared_tools/tools/browser_tool_test.rb

# Run with SimpleCov coverage report
COVERAGE=true bundle exec rake test

# Install MkDocs and dependencies
pip install mkdocs-material

# Serve documentation locally
mkdocs serve

# Build static site
mkdocs build

The project uses standard Ruby tooling:

• Testing: Minitest (85%+ coverage)
• Code Loading: Zeitwerk for autoloading
• Documentation: MkDocs with Material theme
• Examples: Executable Ruby scripts in /examples

Contributions are welcome! Here's how you can help:

Found a bug or have a feature request? Please open an issue with:

• Clear description of the problem
• Steps to reproduce (for bugs)
• Expected vs actual behavior
• Ruby version and gem version
• Code examples if applicable

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Ensure tests pass (bundle exec rake test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

• Add tests for new features
• Update documentation as needed
• Follow existing code style
• Keep commits focused and atomic
• Write clear commit messages

📖 Contributing Guide

See the Changelog for version history and upcoming features.

• ✅ Calculator Tool - Safe mathematical calculations with Dentaku
• ✅ Weather Tool - Real-time weather data via OpenWeatherMap API
• ✅ Workflow Manager Tool - Stateful multi-step workflow orchestration
• ✅ Composite Analysis Tool - Multi-stage data analysis
• ✅ Database Query Tool - Safe read-only database queries
• ✅ Docker Compose Tool - Container command execution
• ✅ Error Handling Tool - Reference implementation for robust patterns

• Additional browser drivers (Selenium, Playwright)
• More database adapters and query builders
• Enhanced PDF processing capabilities
• Additional document formats (Word, Excel)
• Video and image processing tools
• Extended data science and analytics capabilities

• Ruby 3.0 or higher
• RubyLLM gem for LLM integration

This gem is available as open source under the terms of the MIT License.

This gem was originally inspired by Kevin Sylvestre's omniai-tools gem. SharedTools has since evolved to focus exclusively on RubyLLM support with enhanced features and comprehensive documentation.

• Documentation: madbomber.github.io/shared_tools
• RubyGems: rubygems.org/gems/shared_tools
• Source Code: github.com/madbomber/shared_tools
• Issue Tracker: github.com/madbomber/shared_tools/issues
• RubyLLM: github.com/mariochavez/ruby_llm

• 📖 Documentation
• 💬 GitHub Discussions
• 🐛 Issue Tracker