Skip to content

MadBomber/shared_tools

BranchesTags

Repository files navigation

SharedTools

Two Robots sharing the same set of tools

A Ruby gem providing LLM-callable tools for browser automation, file operations, code evaluation, document processing, network queries, data science, workflow management, and more

Gem Version License Documentation

Overview

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.

Key Features

  • 🔧 21+ Production Tools — Browser automation, file operations, database queries, code evaluation, document processing, DNS and WHOIS lookups, IP geolocation, data science, weather data, workflow management, system utilities, notifications, 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

Installation

Add to your Gemfile:

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

Or install directly:

gem install shared_tools

Optional Dependencies

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

# For BrowserTool
gem 'watir'

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

# For DocTool
gem 'pdf-reader'   # PDF support
gem 'docx'         # Microsoft Word (.docx) support
gem 'roo'          # Spreadsheet support: CSV, XLSX, ODS, XLSM

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

Quick Start

require 'shared_tools'
require 'ruby_llm'

# Initialize an LLM agent with SharedTools
chat = RubyLLM.chat.with_tools(
  SharedTools::Tools::BrowserTool.new,
  SharedTools::Tools::DiskTool.new,
  SharedTools::Tools::DnsTool.new,
  SharedTools::Tools::WeatherTool.new,
  SharedTools::Tools::WorkflowManagerTool.new
)

# Use with human-in-the-loop authorization (default)
chat.ask("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)
chat.ask("Calculate the square root of 144 and tell me the weather in London")

Tool Collections

🌐 Browser Tools

Web automation and scraping capabilities.

Actions: visit, page_inspect, ui_inspect, selector_inspect, click, text_field_set, screenshot

browser = SharedTools::Tools::BrowserTool.new
browser.execute(action: "visit", url: "https://example.com")
browser.execute(action: "page_inspect", full_html: false)

📖 Full Browser Documentation

💾 Disk Tools

Secure file system operations with path traversal protection.

Actions: file_create, file_read, file_write, file_delete, file_move, file_replace, directory_create, directory_list, directory_move, directory_delete

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

🗄️ Database Tools

Execute SQL operations on databases.

Features: SELECT, INSERT, UPDATE, DELETE; read-only query mode; automatic LIMIT enforcement; pluggable drivers (SQLite, PostgreSQL, MySQL)

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

💻 Eval Tools

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

Languages: ruby, python, shell

eval_tool = SharedTools::Tools::EvalTool.new
result = eval_tool.execute(language: "ruby", code: "puts 2 + 2")
output = eval_tool.execute(language: "shell", code: "ls -la")

📖 Full Eval Documentation

📄 Doc Tools

Read and reason over documents in any format.

Actions: text_read, pdf_read, docx_read, spreadsheet_read

doc = SharedTools::Tools::DocTool.new

# Plain text
doc.execute(action: "text_read", doc_path: "./notes.txt")

# PDF — specific pages or ranges
doc.execute(action: "pdf_read", doc_path: "./report.pdf", page_numbers: "1, 5-10")

# Microsoft Word
doc.execute(action: "docx_read", doc_path: "./meeting.docx")

# Spreadsheets (CSV, XLSX, ODS, XLSM)
doc.execute(action: "spreadsheet_read", doc_path: "./data.xlsx", sheet: "Q1 Sales")

📖 Full Doc Documentation

🌐 DNS Tool

DNS resolution, WHOIS queries, IP geolocation, and external IP detection. No API key required.

Actions: a, aaaa, mx, ns, txt, cname, reverse, all, external_ip, ip_location, whois

dns = SharedTools::Tools::DnsTool.new

dns.execute(action: "mx", host: "gmail.com")
dns.execute(action: "whois", host: "ruby-lang.org")
dns.execute(action: "external_ip")
dns.execute(action: "ip_location")           # geolocate your own IP
dns.execute(action: "ip_location", host: "8.8.8.8")  # geolocate any IP

📖 Full DNS Documentation

🌤️ Weather Tool

Real-time weather data from OpenWeatherMap API. Combine with DnsTool for automatic local forecasts.

Features: Current conditions, 3-day forecast, metric/imperial/kelvin units, global coverage

weather = SharedTools::Tools::WeatherTool.new
weather.execute(city: "London,UK", units: "metric", include_forecast: true)

Local forecast with automatic location detection:

chat = RubyLLM.chat.with_tools(
  SharedTools::Tools::DnsTool.new,
  SharedTools::Tools::WeatherTool.new,
  SharedTools::Tools::CurrentDateTimeTool.new
)

chat.ask("Get my external IP, find my city, then give me the current weather and 3-day forecast.")

📖 Full Weather Documentation

🧮 Calculator Tool

Safe mathematical calculations without code execution risks.

Features: Arithmetic, math functions (sqrt, round, abs), trigonometry (sin, cos, tan), configurable precision

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

📊 Data Science Kit

Real statistical analysis on actual data — file-based or inline.

Analysis types: statistical_summary, correlation_analysis, time_series, clustering, prediction

Inline data formats: pipe-delimited tables, CSV strings, JSON arrays, comma-separated numbers

kit = SharedTools::Tools::DataScienceKit.new

# From a file
kit.execute(analysis_type: "statistical_summary", data_source: "./sales.csv")

# Inline pipe-delimited table
kit.execute(
  analysis_type: "correlation_analysis",
  data: "| month | revenue | cost |\n| Jan | 12400 | 8200 |\n| Feb | 11800 | 7900 |"
)

📖 Full Data Science Documentation

🖱️ Computer Tools

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

Actions: mouse_click, mouse_move, mouse_position, type, key, hold_key, scroll, wait

computer = SharedTools::Tools::ComputerTool.new
computer.execute(action: "mouse_click", coordinate: {x: 100, y: 200})
computer.execute(action: "type", text: "Hello, World!")

📖 Full Computer Documentation

🕐 Date/Time, System Info & Clipboard

Utility tools for context and system access:

# Current date and day of week (prevents LLM hallucination)
dt = SharedTools::Tools::CurrentDateTimeTool.new
dt.execute(format: "date")
# => { date: "2026-03-25", day_of_week: "Wednesday", ... }

# System hardware and OS info
info = SharedTools::Tools::SystemInfoTool.new
info.execute

# Clipboard
clipboard = SharedTools::Tools::ClipboardTool.new
clipboard.execute(action: "read")
clipboard.execute(action: "write", text: "Hello!")

🔔 Notification Tool

Cross-platform desktop notifications, modal alert dialogs, and text-to-speech. Supports macOS and Linux with no gem dependencies.

Actions: notify, alert, speak

tool = SharedTools::Tools::NotificationTool.new

# Non-blocking desktop banner
tool.execute(action: "notify", message: "Build complete", title: "CI", sound: "Glass")

# Modal dialog — blocks until user clicks; returns clicked button label
result = tool.execute(action: "alert", message: "Deploy to production?", buttons: ["Yes", "No"])
result[:button]  # => "Yes" or "No"

# Text-to-speech
tool.execute(action: "speak", message: "Task finished", voice: "Samantha", rate: 160)
Action macOS Linux
notify osascript notify-send
alert osascript dialog zenity or terminal fallback
speak say espeak-ng / espeak

🔄 Workflow Manager Tool

Persistent multi-step workflow orchestration with JSON file storage.

Actions: start, step, status, complete, list

workflow = SharedTools::Tools::WorkflowManagerTool.new

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

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

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

# List all workflows
workflow.execute(action: "list")

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

📊 Composite Analysis Tool

Multi-stage data analysis orchestration.

analyzer = SharedTools::Tools::CompositeAnalysisTool.new
analyzer.execute(
  data_source: "./sales_data.csv",
  analysis_type: "comprehensive",
  options: {include_correlations: true, visualization_limit: 5}
)

🐳 Docker Compose Tool

Execute Docker Compose commands safely.

docker = SharedTools::Tools::Docker::ComposeRunTool.new
docker.execute(service: "app", command: "rspec", args: ["spec/main_spec.rb"])

🛠️ Error Handling Tool

Reference implementation for robust error handling patterns.

error_tool = SharedTools::Tools::ErrorHandlingTool.new
error_tool.execute(
  operation: "process",
  data: {name: "test", value: 42},
  max_retries: 3
)

MCP Clients

SharedTools bundles Model Context Protocol clients that connect AI agents to external services. Each client is opt-in — require only the ones you need.

Remote HTTP (API key only)

Client Env var Provides
require 'shared_tools/mcp/tavily_client' TAVILY_API_KEY Web search, news, research, URL extraction

Brew-installed (auto-installs via Homebrew)

Client Env var Provides
require 'shared_tools/mcp/github_client' GITHUB_PERSONAL_ACCESS_TOKEN Repos, issues, PRs, code search
require 'shared_tools/mcp/notion_client' NOTION_TOKEN Pages, databases, search, content CRUD
require 'shared_tools/mcp/slack_client' SLACK_MCP_XOXP_TOKEN Channels, messages, threads, user info
require 'shared_tools/mcp/hugging_face_client' HF_TOKEN Models, datasets, Spaces, model cards

npx Auto-download (Node.js required)

Client Provides
require 'shared_tools/mcp/memory_client' Persistent knowledge graph
require 'shared_tools/mcp/sequential_thinking_client' Chain-of-thought reasoning
require 'shared_tools/mcp/chart_client' Chart and visualisation generation
require 'shared_tools/mcp/brave_search_client' Web and news search (BRAVE_API_KEY) 
# Load all available clients at once (skips any whose env vars are missing)
require 'shared_tools/mcp'

# Or load a specific client
require 'shared_tools/mcp/notion_client'
client = RubyLLM::MCP.clients["notion"]
chat   = RubyLLM.chat.with_tools(*client.tools)
chat.ask("Find my project planning pages and summarise what's in them")

See MCP Clients README for full configuration details.

Authorization System

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

Documentation

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

Documentation Sections

  • 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

Examples

The /examples directory contains runnable demonstrations using a shared common.rb helper:

bundle exec ruby -I examples examples/weather_tool_demo.rb
bundle exec ruby -I examples examples/dns_tool_demo.rb
bundle exec ruby -I examples examples/doc_tool_demo.rb
Demo What it shows
browser_tool_demo.rb Web automation
calculator_tool_demo.rb Math expressions
clipboard_tool_demo.rb Clipboard read/write
composite_analysis_tool_demo.rb Multi-stage analysis
computer_tool_demo.rb Mouse and keyboard
cron_tool_demo.rb Cron scheduling
current_date_time_tool_demo.rb Real date and time
data_science_kit_demo.rb Statistical analysis with inline data
database_tool_demo.rb SQL operations
database_query_tool_demo.rb Read-only SQL queries
disk_tool_demo.rb File operations
dns_tool_demo.rb DNS, WHOIS, geolocation
doc_tool_demo.rb Text, PDF, Word, spreadsheets
error_handling_tool_demo.rb Error handling patterns
eval_tool_demo.rb Code evaluation
mcp_client_demo.rb MCP client overview
mcp/tavily_demo.rb Tavily web search (HTTP)
mcp/github_demo.rb GitHub repos, issues, PRs
mcp/notion_demo.rb Notion pages and databases
mcp/slack_demo.rb Slack channels and messages
mcp/hugging_face_demo.rb Hugging Face models and datasets
mcp/memory_demo.rb Persistent knowledge graph
mcp/sequential_thinking_demo.rb Chain-of-thought reasoning
mcp/chart_demo.rb Chart generation
mcp/brave_search_demo.rb Brave web search
notification_tool_demo.rb Desktop notifications, alerts, TTS
system_info_tool_demo.rb System info
weather_tool_demo.rb Weather + local forecast
workflow_manager_tool_demo.rb Workflow orchestration
comprehensive_workflow_demo.rb Multi-tool pipeline

📖 View All Examples

Development

Setup

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

Running Tests

# 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

Building Documentation

pip install mkdocs-material
mkdocs serve    # Serve locally
mkdocs build    # Build static site

Code Quality

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

Contributing

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

  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. Open a Pull Request

📖 Contributing Guide

Requirements

  • Ruby 3.0 or higher
  • RubyLLM gem for LLM integration

License

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

Special Thanks

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.

Links

Support

Made with ❤️ by Dewayne VanHoozer

About

A collection of local tool definitions for various Ruby-based AI libraries for use in generative AI applications.

Resources

Readme

License

MIT license
Activity

Stars

12 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

9 tags

Packages

 
 
 

Contributors

Languages