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 frameworkOr install directly:
gem install shared_toolsDepending 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 toolsrequire '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 URLspage_inspect- Get page HTML contentui_inspect- Find elements by textselector_inspect- Find elements by CSS selectorclick- Click elementstext_field_set- Fill in formsscreenshot- 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)Secure file system operations with path traversal protection.
Actions:
file_create- Create new filesfile_read- Read file contentsfile_write- Write to filesfile_delete- Delete filesfile_move- Move/rename filesfile_replace- Find and replace text in filesdirectory_create- Create directoriesdirectory_list- List directory contentsdirectory_move- Move directoriesdirectory_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")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"
]
)Safe code evaluation for Ruby, Python, and shell commands.
Languages:
ruby- Execute Ruby codepython- 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")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")System-level automation for mouse, keyboard, and screen control.
Actions:
mouse_click- Click at coordinatesmouse_move- Move mouse cursormouse_position- Get current mouse positiontype- Type textkey- Press keyboard keys and shortcutshold_key- Hold keys for durationscroll- Scroll windowswait- 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")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 forecastManage 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 visualizationsSafe, 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 patternsSharedTools 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 promptingComprehensive 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 automationdisk_tool_example.rb- File operationsdatabase_tool_example.rb- SQL operationseval_tool_example.rb- Code evaluationdoc_tool_example.rb- PDF processingcomprehensive_workflow_example.rb- Multi-tool workflow
Run examples:
bundle install
ruby examples/browser_tool_example.rbgit 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 buildThe 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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes with tests
- Ensure tests pass (
bundle exec rake test) - Commit your changes (
git commit -m 'Add amazing feature') - Push to your branch (
git push origin feature/amazing-feature) - 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
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
Made with ❤️ by Dewayne VanHoozer