shared_tools 0.1.3 → 0.2.1

data/lib/shared_tools/ruby_llm/incomplete/error_handling_tool.rb

@@ -0,0 +1,109 @@
+# error_handling_tool.rb - Comprehensive error handling
+require 'ruby_llm/tool'
+require 'securerandom'
+
+module Tools
+  class RobustTool < RubyLLM::Tool
+    def self.name = 'robust_tool'
+
+    description <<~DESCRIPTION
+      Reference tool demonstrating comprehensive error handling patterns and resilience strategies
+      for robust tool development. This tool showcases best practices for handling different
+      types of errors including validation errors, network failures, authorization issues,
+      and general exceptions. It implements retry mechanisms with exponential backoff,
+      proper resource cleanup, detailed error categorization, and user-friendly error messages.
+      Perfect as a template for building production-ready tools that need to handle
+      various failure scenarios gracefully.
+    DESCRIPTION
+
+    def execute(**params)
+      begin
+        validate_preconditions(params)
+        result = perform_operation(params)
+        validate_postconditions(result)
+
+        {
+          success:  true,
+          result:   result,
+          metadata: operation_metadata
+        }
+      rescue ValidationError => e
+        handle_validation_error(e, params)
+      rescue NetworkError => e
+        handle_network_error(e, params)
+      rescue AuthorizationError => e
+        handle_authorization_error(e, params)
+      rescue StandardError => e
+        handle_general_error(e, params)
+      ensure
+        cleanup_resources
+      end
+    end
+
+    private
+
+    def validate_preconditions(params)
+      # Check all preconditions before execution
+    end
+
+    def perform_operation(params)
+      # Main operation logic with retry mechanism
+      retry_count = 0
+      max_retries = 3
+
+      begin
+        # Operation implementation
+      rescue RetryableError => e
+        retry_count += 1
+        if retry_count <= max_retries
+          sleep(2 ** retry_count) # Exponential backoff
+          retry
+        else
+          raise e
+        end
+      end
+    end
+
+    def handle_validation_error(error, params)
+      {
+        success:         false,
+        error_type:      "validation",
+        error:           error.message,
+        suggestions:     error.suggestions,
+        provided_params: params.keys
+      }
+    end
+
+    def handle_network_error(error, params)
+      {
+        success:         false,
+        error_type:      "network",
+        error:           "Network operation failed",
+        retry_suggested: true,
+        retry_after:     30
+      }
+    end
+
+    def handle_authorization_error(error, params)
+      {
+        success:          false,
+        error_type:       "authorization",
+        error:            "Access denied",
+        documentation_url: "https://docs.example.com/auth"
+      }
+    end
+
+    def handle_general_error(error, params)
+      {
+        success:           false,
+        error_type:        "general",
+        error:             error.message,
+        support_reference: SecureRandom.uuid
+      }
+    end
+
+    def cleanup_resources
+      # Clean up any allocated resources
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/incomplete/secure_tool_template.rb

@@ -0,0 +1,117 @@
+# secure_tool_template.rb - Security best practices
+require 'ruby_llm/tool'
+require 'timeout'
+
+module Tools
+  class SecureTool < RubyLLM::Tool
+    def self.name = 'secure_tool'
+
+    description <<~DESCRIPTION
+      Template tool demonstrating comprehensive security best practices for safe tool development.
+      This tool serves as a reference implementation for secure tool design, including input
+      validation, output sanitization, permission checks, rate limiting, audit logging,
+      timeout mechanisms, and proper error handling. It provides a complete security framework
+      that can be adapted for other tools that handle sensitive data or perform privileged
+      operations. All security violations are logged for monitoring and compliance purposes.
+    DESCRIPTION
+
+    # Input validation
+    param :user_input,
+          desc: <<~DESC,
+            User-provided input string that will be processed with comprehensive security validation.
+            Input is automatically sanitized and validated against multiple security criteria:
+            - Maximum length of 1000 characters to prevent buffer overflow attacks
+            - Character whitelist allowing only alphanumeric, spaces, hyphens, underscores, and dots
+            - Automatic removal of potentially dangerous characters and sequences
+            - Rate limiting to prevent abuse and denial-of-service attacks
+            All input validation failures are logged for security monitoring.
+          DESC
+          type: :string,
+          required: true,
+          validator: ->(value) {
+            # Custom validation logic
+            raise "Input too long" if value.length > 1000
+            raise "Invalid characters" unless value.match?(/\A[a-zA-Z0-9\s\-_\.]+\z/)
+            true
+          }
+
+    def execute(user_input:)
+      begin
+        # 1. Sanitize inputs
+        sanitized_input = sanitize_input(user_input)
+
+        # 2. Validate permissions
+        validate_permissions
+
+        # 3. Rate limiting
+        check_rate_limits
+
+        # 4. Audit logging
+        log_tool_usage(sanitized_input)
+
+        # 5. Execute with timeout
+        result = execute_with_timeout(sanitized_input)
+
+        # 6. Sanitize outputs
+        sanitized_result = sanitize_output(result)
+
+        {
+          success: true,
+          result:  sanitized_result,
+          executed_at: Time.now.iso8601
+        }
+      rescue SecurityError => e
+        log_security_violation(e, user_input)
+        {
+          success: false,
+          error:   "Security violation: Access denied",
+          violation_logged: true
+        }
+      rescue => e
+        {
+          success: false,
+          error:   "Tool execution failed: #{e.message}"
+        }
+      end
+    end
+
+    private
+
+    def sanitize_input(input)
+      # Remove potentially dangerous characters
+      # Validate against whitelist
+      input.gsub(/[^\w\s\-\.]/, '')
+    end
+
+    def validate_permissions
+      # Check user permissions
+      # Validate environment access
+      # Verify resource limits
+    end
+
+    def check_rate_limits
+      # Implement rate limiting logic
+    end
+
+    def log_tool_usage(input)
+      # Audit logging for compliance
+    end
+
+    def execute_with_timeout(input, timeout: 30)
+      # Implement timeout mechanism
+      Timeout::timeout(timeout) do
+        # Actual tool logic here
+      end
+    end
+
+    def sanitize_output(output)
+      # Remove sensitive information from output
+      # Validate output format
+      output
+    end
+
+    def log_security_violation(error, input)
+      # Log security violations for monitoring
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/incomplete/weather_tool.rb

@@ -0,0 +1,110 @@
+# weather_tool.rb - API integration example
+require 'ruby_llm/tool'
+require 'net/http'
+require 'json'
+
+module Tools
+  class WeatherTool < RubyLLM::Tool
+    def self.name = 'weather_tool'
+
+    description <<~DESCRIPTION
+      Retrieve comprehensive current weather information for any city worldwide using the OpenWeatherMap API.
+      This tool provides real-time weather data including temperature, atmospheric conditions, humidity,
+      and wind information. It supports multiple temperature units and can optionally include extended
+      forecast data. The tool requires a valid OpenWeatherMap API key to be configured in the
+      OPENWEATHER_API_KEY environment variable. All weather data is fetched in real-time and includes
+      timestamps for accuracy verification.
+    DESCRIPTION
+
+    param :city,
+          desc: <<~DESC,
+            Name of the city for weather lookup. Can include city name only (e.g., 'London')
+            or city with country code for better accuracy (e.g., 'London,UK' or 'Paris,FR').
+            For cities with common names in multiple countries, including the country code
+            is recommended to ensure accurate results. The API will attempt to find the
+            closest match if an exact match is not found.
+          DESC
+          type: :string,
+          required: true
+
+    param :units,
+          desc: <<~DESC,
+            Temperature unit system for the weather data. Options are:
+            - 'metric': Temperature in Celsius, wind speed in m/s, pressure in hPa
+            - 'imperial': Temperature in Fahrenheit, wind speed in mph, pressure in hPa
+            - 'kelvin': Temperature in Kelvin (scientific standard), wind speed in m/s
+            Default is 'metric' which is most commonly used internationally.
+          DESC
+          type: :string,
+          default: "metric",
+          enum: ["metric", "imperial", "kelvin"]
+
+    param :include_forecast,
+          desc: <<~DESC,
+            Boolean flag to include a 3-day weather forecast in addition to current conditions.
+            When set to true, the response will include forecast data with daily high/low temperatures,
+            precipitation probability, and general weather conditions for the next three days.
+            This requires additional API calls and may increase response time slightly.
+          DESC
+          type: :boolean,
+          default: false
+
+    def execute(city:, units: "metric", include_forecast: false)
+      begin
+        api_key = ENV['OPENWEATHER_API_KEY']
+        raise "OpenWeather API key not configured" unless api_key
+
+        current_weather = fetch_current_weather(city, units, api_key)
+        result = {
+          success:   true,
+          city:      city,
+          current:   current_weather,
+          units:     units,
+          timestamp: Time.now.iso8601
+        }
+
+        if include_forecast
+          forecast_data = fetch_forecast(city, units, api_key)
+          result[:forecast] = forecast_data
+        end
+
+        result
+      rescue => e
+        {
+          success:    false,
+          error:      e.message,
+          city:       city,
+          suggestion: "Verify city name and API key configuration"
+        }
+      end
+    end
+
+    private
+
+    def fetch_current_weather(city, units, api_key)
+      uri = URI("https://api.openweathermap.org/data/2.5/weather")
+      params = {
+        q:     city,
+        appid: api_key,
+        units: units
+      }
+      uri.query = URI.encode_www_form(params)
+
+      response = Net::HTTP.get_response(uri)
+      raise "Weather API error: #{response.code}" unless response.code == '200'
+
+      data = JSON.parse(response.body)
+      {
+        temperature: data['main']['temp'],
+        description: data['weather'][0]['description'],
+        humidity:    data['main']['humidity'],
+        wind_speed:  data['wind']['speed']
+      }
+    end
+
+    def fetch_forecast(city, units, api_key)
+      # Implementation for forecast data
+      # Similar pattern to current weather
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/incomplete/workflow_manager_tool.rb

@@ -0,0 +1,145 @@
+# workflow_manager_tool.rb - Managing state across tool invocations
+require 'ruby_llm/tool'
+require 'securerandom'
+require 'json'
+
+module Tools
+  class WorkflowManager < RubyLLM::Tool
+    def self.name = 'workflow_manager'
+
+    description <<~DESCRIPTION
+      Manage complex multi-step workflows with persistent state tracking across tool invocations.
+      This tool enables the creation and management of stateful workflows that can span multiple
+      AI interactions and tool calls. It provides workflow initialization, step-by-step execution,
+      status monitoring, and completion tracking. Each workflow maintains its state in persistent
+      storage, allowing for resumption of long-running processes and coordination between
+      multiple tools and AI interactions. Perfect for complex automation tasks that require
+      multiple stages and decision points.
+    DESCRIPTION
+
+    param :action,
+          desc: <<~DESC,
+            Workflow management action to perform:
+            - 'start': Initialize a new workflow with initial data and return workflow ID
+            - 'step': Execute the next step in an existing workflow using provided step data
+            - 'status': Check the current status and progress of an existing workflow
+            - 'complete': Mark a workflow as finished and clean up associated resources
+            Each action requires different combinations of the other parameters.
+          DESC
+          type: :string,
+          required: true,
+          enum: ["start", "step", "status", "complete"]
+
+    param :workflow_id,
+          desc: <<~DESC,
+            Unique identifier for an existing workflow. Required for 'step', 'status', and 'complete'
+            actions. This ID is returned when starting a new workflow and should be used for all
+            subsequent operations on that workflow. The ID is a UUID string that ensures
+            uniqueness across all workflow instances.
+          DESC
+          type: :string
+
+    param :step_data,
+          desc: <<~DESC,
+            Hash containing data and parameters specific to the current workflow step.
+            For 'start' action: Initial configuration and parameters for the workflow.
+            For 'step' action: Input data, parameters, and context needed for the next step.
+            The structure depends on the specific workflow type and current step requirements.
+            Can include nested hashes, arrays, and any JSON-serializable data types.
+          DESC
+          type: :hash,
+          default: {}
+
+    def execute(action:, workflow_id: nil, step_data: {})
+      case action
+      when "start"
+        start_workflow(step_data)
+      when "step"
+        process_workflow_step(workflow_id, step_data)
+      when "status"
+        get_workflow_status(workflow_id)
+      when "complete"
+        complete_workflow(workflow_id)
+      else
+        { success: false, error: "Unknown action: #{action}" }
+      end
+    end
+
+    private
+
+    def start_workflow(initial_data)
+      workflow_id = SecureRandom.uuid
+      workflow_state = {
+        id:         workflow_id,
+        status:     "active",
+        steps:      [],
+        created_at: Time.now.iso8601,
+        data:       initial_data
+      }
+
+      save_workflow_state(workflow_id, workflow_state)
+
+      {
+        success:      true,
+        workflow_id:  workflow_id,
+        status:       "started",
+        next_actions: suggested_next_actions(initial_data)
+      }
+    end
+
+    def process_workflow_step(workflow_id, step_data)
+      workflow_state = load_workflow_state(workflow_id)
+      return { success: false, error: "Workflow not found" } unless workflow_state
+
+      step = {
+        step_number:  workflow_state[:steps].length + 1,
+        data:         step_data,
+        processed_at: Time.now.iso8601,
+        result:       process_step_logic(step_data, workflow_state)
+      }
+
+      workflow_state[:steps] << step
+      workflow_state[:updated_at] = Time.now.iso8601
+
+      save_workflow_state(workflow_id, workflow_state)
+
+      {
+        success:         true,
+        workflow_id:     workflow_id,
+        step_completed:  step,
+        workflow_status: workflow_state[:status],
+        next_actions:    suggested_next_actions(workflow_state)
+      }
+    end
+
+    def save_workflow_state(workflow_id, state)
+      # Implementation for state persistence
+      # Could use files, database, or memory store
+      File.write(".workflow_#{workflow_id}.json", state.to_json)
+    end
+
+    def load_workflow_state(workflow_id)
+      # Implementation for state loading
+      file_path = ".workflow_#{workflow_id}.json"
+      return nil unless File.exist?(file_path)
+
+      JSON.parse(File.read(file_path), symbolize_names: true)
+    end
+
+    def get_workflow_status(workflow_id)
+      # Implementation for status retrieval
+    end
+
+    def complete_workflow(workflow_id)
+      # Implementation for workflow completion
+    end
+
+    def suggested_next_actions(workflow_state)
+      # Implementation for suggesting next actions
+    end
+
+    def process_step_logic(step_data, workflow_state)
+      # Implementation for processing step logic
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/list_files.rb

@@ -6,6 +6,7 @@ module SharedTools
   verify_gem :ruby_llm
 
   class ListFiles < ::RubyLLM::Tool
+      def self.name = 'list_files'
 
     description "List files and directories at a given path. If no path is provided, lists files in the current directory."
     param :path, desc: "Optional relative path to list files from. Defaults to current directory if not provided."

data/lib/shared_tools/ruby_llm/mcp/github_mcp_server.rb

@@ -0,0 +1,51 @@
+# shared_tools/ruby_llm/mcp/github_mcp_server.rb
+# brew install github_mcp_server
+
+require 'debug_me'
+include DebugMe
+
+require 'ruby_llm'
+require 'ruby_llm/mcp'
+
+require_relative '../../../shared_tools'
+
+module SharedTools
+  verify_gem :ruby_llm
+
+  mcp_servers << RubyLLM::MCP.client(
+    name: "github-mcp-server",
+    transport_type: :stdio,
+    config: {
+      command: "/opt/homebrew/bin/github-mcp-server", # brew install github-mcp-server
+      args: %w[stdio],
+      env: { "GITHUB_PERSONAL_ACCESS_TOKEN" => ENV.fetch('GITHUB_PERSONAL_ACCESS_TOKEN') }
+    }
+  )
+end
+
+
+__END__
+
+
+A GitHub MCP server that handles various tools and resources.
+
+Usage:
+  server [command]
+
+Available Commands:
+  completion  Generate the autocompletion script for the specified shell
+  help        Help about any command
+  stdio       Start stdio server
+
+Flags:
+      --dynamic-toolsets         Enable dynamic toolsets
+      --enable-command-logging   When enabled, the server will log all command requests and responses to the log file
+      --export-translations      Save translations to a JSON file
+      --gh-host string           Specify the GitHub hostname (for GitHub Enterprise etc.)
+  -h, --help                     help for server
+      --log-file string          Path to log file
+      --read-only                Restrict the server to read-only operations
+      --toolsets strings         An optional comma separated list of groups of tools to allow, defaults to enabling all (default [all])
+  -v, --version                  version for server
+
+Use "server [command] --help" for more information about a command.

data/lib/shared_tools/ruby_llm/mcp/imcp.rb

@@ -0,0 +1,33 @@
+# shared_tools/ruby_llm/mcp/imcp.rb
+# iMCP is a MacOS program that provides access to notes,calendar,contacts, etc.
+# See: https://github.com/loopwork/iMCP
+# brew install --cask loopwork/tap/iMCP
+#
+# CAUTION: AIA is getting an exception when trying to use this MCP client.  Its returning to
+#          do a to_sym on a nil value.  This is due to a lack of a nil guard in the
+#          version 0.3.1 of the ruby_llm-mpc Parameter#item_type method.
+#
+# NOTE: iMCP's server is a noisy little thing shooting all its log messages to STDERR.
+#       To silence it, redirect STDERR to /dev/null.
+#       If you messages then you might want to redirect STDERR to a file.
+#
+
+require 'debug_me'
+include DebugMe
+
+require 'ruby_llm'
+require 'ruby_llm/mcp'
+
+require_relative '../../../shared_tools'
+
+module SharedTools
+  verify_gem :ruby_llm
+
+  mcp_servers << RubyLLM::MCP.client(
+    name: "imcp-server",
+    transport_type: :stdio,
+    config: {
+      command: "/Applications/iMCP.app/Contents/MacOS/imcp-server 2> /dev/null"
+    }
+  )
+end

data/lib/shared_tools/ruby_llm/mcp.rb

@@ -0,0 +1,10 @@
+# shared_tools/ruby_llm/mcp.rb
+# This file loads all Ruby files in the mcp directory
+
+# Get the directory path
+mcp_dir = File.join(__dir__, 'mcp')
+
+# Load all .rb files in the mcp directory
+Dir.glob(File.join(mcp_dir, '*.rb')).each do |file|
+  require file
+end

data/lib/shared_tools/ruby_llm/pdf_page_reader.rb

@@ -8,6 +8,7 @@ module SharedTools
   verify_gem :ruby_llm
 
   class PdfPageReader < ::RubyLLM::Tool
+      def self.name = 'pdf_page_reader'
 
     description "Read the text of any set of pages from a PDF document."
     param :page_numbers,

data/lib/shared_tools/ruby_llm/python_eval.rb

@@ -6,6 +6,7 @@ module SharedTools
   verify_gem :ruby_llm
 
   class PythonEval < ::RubyLLM::Tool
+      def self.name = 'python_eval'
 
     description <<~DESCRIPTION
                   Execute Python source code safely and return the result.
@@ -29,7 +30,7 @@ module SharedTools
       end
 
       # Show user the code and ask for confirmation
-      allowed = SharedTools.execute?(tool: self.class.name, stuff: code)
+      allowed = SharedTools.execute?(tool: self.class.to_s, stuff: code)
 
       unless allowed
         RubyLLM.logger.warn("User declined to execute the Python code")

data/lib/shared_tools/ruby_llm/read_file.rb

@@ -6,6 +6,7 @@ module SharedTools
   verify_gem :ruby_llm
 
   class ReadFile < ::RubyLLM::Tool
+    def self.name = 'read_file'
 
     description "Read the contents of a given relative file path. Use this when you want to see what's inside a file. Do not use this with directory names."
     param :path, desc: "The relative path of a file in the working directory."

data/lib/shared_tools/ruby_llm/ruby_eval.rb

@@ -6,6 +6,7 @@ module SharedTools
   verify_gem :ruby_llm
 
   class RubyEval < ::RubyLLM::Tool
+    def self.name = 'ruby_eval'
 
     description <<~DESCRIPTION
                   Execute Ruby source code safely and return the result.
@@ -27,7 +28,7 @@ module SharedTools
       end
 
       # Show user the code and ask for confirmation
-      allowed = SharedTools.execute?(tool: self.class.name, stuff: code)
+      allowed = SharedTools.execute?(tool: self.class.to_s, stuff: code)
 
       unless allowed
         RubyLLM.logger.warn("User declined to execute the Ruby code")

data/lib/shared_tools/ruby_llm/run_shell_command.rb

@@ -6,6 +6,7 @@ module SharedTools
   SharedTools.verify_gem :ruby_llm
 
   class RunShellCommand < ::RubyLLM::Tool
+    def self.name = 'run_shell_command'
 
     description "Execute a shell command"
     param :command, desc: "The command to execute"
@@ -20,7 +21,7 @@ module SharedTools
       end
 
       # Show user the command and ask for confirmation
-      allowed = SharedTools.execute?(tool: self.class.name, stuff: command)
+      allowed = SharedTools.execute?(tool: self.class.to_s, stuff: command)
 
       unless allowed
         RubyLLM.logger.warn("User declined to execute the command: '#{command}'")

data/lib/shared_tools/ruby_llm.rb

@@ -4,6 +4,9 @@ require_relative '../shared_tools'
 
 SharedTools.verify_gem :ruby_llm
 
-Dir.glob(File.join(__dir__, "ruby_llm", "*.rb")).each do |file|
+# This excludes the sub-directories and mcp.rb
+Dir.glob(File.join(__dir__, "ruby_llm", "*.rb"))
+   .reject { |f| File.basename(f) == 'mcp.rb' }
+   .each do |file|
   require file
 end

data/lib/shared_tools/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SharedTools
-  VERSION = "0.1.3"
+  VERSION = "0.2.1"
 end