shared_tools 0.2.1 → 0.3.0

data/lib/shared_tools/tools/browser_tool.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # A tool for controller a browser.
+    class BrowserTool < ::RubyLLM::Tool
+      def self.name = 'browser_tool' 
+      module Action
+        VISIT = "visit"
+        PAGE_INSPECT = "page_inspect"
+        UI_INSPECT = "ui_inspect"
+        SELECTOR_INSPECT = "selector_inspect"
+        CLICK = "click"
+        TEXT_FIELD_SET = "text_field_set"
+        SCREENSHOT = "screenshot"
+      end
+
+      ACTIONS = [
+        Action::VISIT,
+        Action::PAGE_INSPECT,
+        Action::UI_INSPECT,
+        Action::SELECTOR_INSPECT,
+        Action::CLICK,
+        Action::TEXT_FIELD_SET,
+        Action::SCREENSHOT,
+      ].freeze
+
+      description <<~TEXT
+        Automates a web browser to perform various actions like visiting web pages, clicking elements, etc:
+
+        1. `#{Action::VISIT}` - Navigate to a website
+          Required: "action": "visit", "url": "[website URL]"
+
+        2. `#{Action::PAGE_INSPECT} - Get page HTML or summary
+          Required: "action": "page_inspect"
+          Optional: "full_html": true/false (get full HTML vs summary, default: summary)
+
+        3. `#{Action::UI_INSPECT}` - Find elements by text content
+          Required: "action": "ui_inspect", "text_content": "[text to search for]"
+          Optional:
+          - "selector": "[CSS selector]" (search within specific container)
+          - "context_size": [number] (parent elements to show, default: 2)
+
+        4. `#{Action::SELECTOR_INSPECT} - Find elements by CSS selector
+          Required: "action": "selector_inspect", "selector": "[CSS selector]"
+          Optional: "context_size": [number] (parent elements to show, default: 2)
+
+        5. `#{Action::CLICK}` - Click an element by CSS selector
+          Required: "action": "click", "selector": "[CSS selector]"
+
+        8. `#{Action::TEXT_FIELD_SET}` - Enter text in input fields/text areas
+          Required: "action": "text_field_set", "selector": "[field CSS selector]", "value": "[text to enter]"
+
+        9. `#{Action::SCREENSHOT}` - Take a screenshot of the page or specific element
+          Required: "action": "screenshot"
+
+        ## Examples:
+
+        Visit a website
+          {"action": "#{Action::VISIT}", "url": "https://example.com"}
+        Get page summary
+          {"action": "#{Action::PAGE_INSPECT}"}
+        Get full page HTML
+          {"action": "#{Action::PAGE_INSPECT}", "full_html": true}
+        Find elements containing text
+          {"action": "#{Action::UI_INSPECT}", "text_content": "Submit"}
+        Find elements with context
+          {"action": "#{Action::UI_INSPECT}", "text_content": "Login", "context_size": 3}
+        Find elements by CSS selector
+          {"action": "#{Action::SELECTOR_INSPECT}", "selector": ".button"}
+        Find selector with context
+          {"action": "#{Action::SELECTOR_INSPECT}", "selector": "h1", "context_size": 2}
+        Click a button by CSS selector
+          {"action": "#{Action::CLICK}", "selector": "button[type='Submit']"}
+        Click a link by CSS Selector
+          {"action": "#{Action::CLICK}", "selector": "a[href='/login']"}
+        Click an element by CSS selector
+          {"action": "#{Action::CLICK}", "selector": "div.panel > span.toggle"}
+        Click an element by CSS selector:
+          {"action": "#{Action::CLICK}", "selector": "[role='listitem']"}
+        Set text in an input field
+          {"action": "#{Action::TEXT_FIELD_SET}", "selector": "#search", "value": "search query"}
+        Take a full page screenshot
+          {"action": "#{Action::SCREENSHOT}"}
+      TEXT
+
+      params do
+        string :action, description: <<~TEXT.strip
+          The browser action to perform. Options:
+          * `#{Action::VISIT}`: Navigate to a website
+          * `#{Action::PAGE_INSPECT}`: Get full HTML or summarized page information
+          * `#{Action::UI_INSPECT}`: Find elements containing specific text
+          * `#{Action::SELECTOR_INSPECT}`: Find elements matching CSS selectors
+          * `#{Action::CLICK}`: Click an element by CSS selector
+          * `#{Action::TEXT_FIELD_SET}`: Enter text in input fields or text areas
+          * `#{Action::SCREENSHOT}`: Take a screenshot of the current page
+        TEXT
+
+        string :url, description: <<~TEXT.strip, required: false
+          The URL to visit. Required for the following actions:
+          * `#{Action::VISIT}`
+        TEXT
+
+        string :selector, description: <<~TEXT.strip, required: false
+          A CSS selector to locate an element:
+
+            * 'form button[type="submit"]': selects a button with type submit
+            * '.example': selects elements with the foo and bar classes
+            * '#example': selects an element by ID
+            * 'div#parent > span.child': selects span elements that are direct children of div elements
+            * 'a[href="/login"]': selects an anchor tag with a specific href attribute
+            * 'button[aria-label="Close"]': selects an element by ARIA label
+
+          Required for the following actions:
+          * `#{Action::CLICK}`
+          * `#{Action::TEXT_FIELD_SET}`
+          * `#{Action::SELECTOR_INSPECT}`
+
+          Optional for the following actions:
+          * `#{Action::UI_INSPECT}` (search within specific container)
+        TEXT
+
+        string :value, description: <<~TEXT.strip, required: false
+          The value to set in the text field. Required for the following actions:
+          * `#{Action::TEXT_FIELD_SET}`
+        TEXT
+
+        integer :context_size, description: <<~TEXT.strip, required: false
+          Number of parent elements to include in inspect results (default: 2). Optional for the following actions:
+          * `#{Action::UI_INSPECT}`
+          * `#{Action::SELECTOR_INSPECT}`
+        TEXT
+
+        boolean :full_html, description: <<~TEXT.strip, required: false
+          Return the full HTML of the page instead of a summary. Optional for the following actions:
+          * `#{Action::PAGE_INSPECT}`
+        TEXT
+
+        string :text_content, description: <<~TEXT.strip, required: false
+          Search for elements containing this text. Required for the following actions:
+          * `#{Action::UI_INSPECT}`
+        TEXT
+      end
+
+
+      # @param logger [Logger] optional logger
+      # @param driver [SharedTools::Tools::Browser::BaseDriver] optional, will attempt to create WatirDriver if not provided
+      def initialize(logger: nil, driver: nil)
+        @logger = logger || RubyLLM.logger
+        @driver = driver || default_driver
+      end
+
+      def cleanup!
+        @driver.close
+      end
+
+      # @param action [String]
+      # @param url [String, nil]
+      # @param selector [String, nil] e.g. "button[type='submit']", "div#parent > span.child", etc
+      # @param value [String, nil]
+      # @param context_size [Integer]
+      # @param full_html [Boolean]
+      # @param text_content [String, nil]
+      #
+      # @return [String]
+      def execute(action:, url: nil, selector: nil, value: nil, context_size: 2, full_html: false, text_content: nil)
+        case action.to_s.downcase
+        when Action::VISIT
+          require_param!(:url, url)
+          visit_tool.execute(url:)
+        when Action::PAGE_INSPECT
+          if full_html
+            page_inspect_tool.execute
+          else
+            page_inspect_tool.execute(summarize: true)
+          end
+        when Action::UI_INSPECT
+          require_param!(:text_content, text_content)
+          inspect_tool.execute(text_content:, selector:, context_size:)
+        when Action::SELECTOR_INSPECT
+          require_param!(:selector, selector)
+          selector_inspect_tool.execute(selector:, context_size:)
+        when Action::CLICK
+          require_param!(:selector, selector)
+          click_tool.execute(selector:)
+        when Action::TEXT_FIELD_SET
+          require_param!(:selector, selector)
+          require_param!(:value, value)
+          text_field_area_set_tool.execute(selector:, text: value)
+        when Action::SCREENSHOT
+          page_screenshot_tool.execute
+        else
+          { error: "Unsupported action: #{action}. Supported actions are: #{ACTIONS.join(', ')}" }
+        end
+      end
+
+    private
+
+      # @param name [Symbol]
+      # @param value [Object]
+      #
+      # @raise [ArgumentError]
+      # @return [void]
+      def require_param!(name, value)
+        raise ArgumentError, "#{name} param is required for this action" if value.nil?
+      end
+
+      # @return [Browser::VisitTool]
+      def visit_tool
+        Browser::VisitTool.new(driver: @driver, logger: @logger)
+      end
+
+      # @return [Browser::PageInspectTool]
+      def page_inspect_tool
+        Browser::PageInspectTool.new(driver: @driver, logger: @logger)
+      end
+
+      # @return [Browser::UIInspectTool]
+      def inspect_tool
+        Browser::InspectTool.new(driver: @driver, logger: @logger)
+      end
+
+      # @return [Browser::SelectorInspectTool]
+      def selector_inspect_tool
+        Browser::SelectorInspectTool.new(driver: @driver, logger: @logger)
+      end
+
+      # @return [Browser::ClickTool]
+      def click_tool
+        Browser::ClickTool.new(driver: @driver, logger: @logger)
+      end
+
+      # @return [Browser::TextFieldAreaSetTool]
+      def text_field_area_set_tool
+        Browser::TextFieldAreaSetTool.new(driver: @driver, logger: @logger)
+      end
+
+      # @return [Browser::PageScreenshotTool]
+      def page_screenshot_tool
+        Browser::PageScreenshotTool.new(driver: @driver, logger: @logger)
+      end
+
+      # @return [Browser::BaseDriver]
+      def default_driver
+        if defined?(Watir)
+          Browser::WatirDriver.new(logger: @logger)
+        else
+          raise LoadError, "BrowserTool requires a driver. Either install the 'watir' gem or pass a driver: parameter"
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/calculator_tool.rb

@@ -0,0 +1,169 @@
+# calculator_tool.rb - Safe mathematical calculator
+require 'ruby_llm/tool'
+require 'dentaku'
+
+module SharedTools
+  module Tools
+    class CalculatorTool < RubyLLM::Tool
+      def self.name = 'calculator'
+
+      description <<~'DESCRIPTION'
+        Perform advanced mathematical calculations with comprehensive error handling and validation.
+        This tool supports basic arithmetic operations, parentheses, and common mathematical functions.
+        It uses Dentaku for safe evaluation of mathematical expressions without executing arbitrary code,
+        making it suitable for use in AI-assisted calculations where security is critical.
+        The tool returns formatted results with configurable precision and helpful error messages
+        when invalid expressions are provided.
+
+        Supported operations:
+        - Basic arithmetic: +, -, *, /, %
+        - Parentheses for grouping: ( )
+        - Exponentiation: ^ or pow(base, exponent)
+        - Comparison operators: =, <, >, <=, >=, !=
+        - Logical operators: and, or, not
+        - Mathematical functions: sqrt, round, roundup, rounddown, abs
+        - Trigonometric functions: sin, cos, tan
+
+        Example usage:
+          tool = SharedTools::Tools::CalculatorTool.new
+          result = tool.execute(expression: "2 + 2")
+          puts "Result: #{result[:result]}"
+
+          # With precision
+          result = tool.execute(expression: "10 / 3", precision: 4)
+          puts "Result: #{result[:result]}" # 3.3333
+      DESCRIPTION
+
+      params do
+        string :expression, description: <<~DESC.strip
+          Mathematical expression to evaluate using standard arithmetic operators and parentheses.
+          Supported operations include: addition (+), subtraction (-), multiplication (*),
+          division (/), modulo (%), exponentiation (**), and parentheses for grouping.
+          Examples: '2 + 2', '(10 * 5) / 2', '15.5 - 3.2', 'sqrt(16)', 'round(3.14159, 2)'.
+          The expression is evaluated safely using Dentaku math parser.
+        DESC
+
+        integer :precision, description: <<~DESC.strip, required: false
+          Number of decimal places to display in the result. Must be between 0 and 10.
+          Set to 0 for whole numbers only, or higher values for more precise decimal results.
+          Default is 2 decimal places, which works well for most financial and general calculations.
+        DESC
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+        @calculator = Dentaku::Calculator.new
+
+        # Enable case-insensitive function names
+        Dentaku.enable_caching!
+      end
+
+      # Execute mathematical calculation
+      #
+      # @param expression [String] Mathematical expression to evaluate
+      # @param precision [Integer] Number of decimal places (0-10), default 2
+      #
+      # @return [Hash] Calculation result with success status
+      def execute(expression:, precision: 2)
+        @logger.info("CalculatorTool#execute expression=#{expression.inspect} precision=#{precision}")
+
+        begin
+          # Validate precision
+          precision = validate_precision(precision)
+
+          # Evaluate expression safely using Dentaku
+          result = @calculator.evaluate(expression)
+
+          # Handle nil result (invalid expression)
+          unless result
+            raise Dentaku::ParseError, "Could not parse expression"
+          end
+
+          # Format result with specified precision
+          formatted_result = format_result(result, precision)
+
+          @logger.info("Calculation successful: #{expression} = #{formatted_result}")
+
+          {
+            success:    true,
+            result:     formatted_result,
+            expression: expression,
+            precision:  precision,
+            raw_result: result
+          }
+        rescue Dentaku::ParseError => e
+          @logger.error("Parse error for expression '#{expression}': #{e.message}")
+          {
+            success:    false,
+            error:      "Invalid expression: #{e.message}",
+            expression: expression,
+            suggestion: "Try expressions like '2 + 2', '(10 * 5) / 2', or 'sqrt(16)'"
+          }
+        rescue Dentaku::ArgumentError => e
+          @logger.error("Argument error for expression '#{expression}': #{e.message}")
+          {
+            success:    false,
+            error:      "Invalid arguments: #{e.message}",
+            expression: expression,
+            suggestion: "Check that functions have the correct number of arguments"
+          }
+        rescue ZeroDivisionError => e
+          @logger.error("Division by zero in expression '#{expression}'")
+          {
+            success:    false,
+            error:      "Division by zero",
+            expression: expression,
+            suggestion: "Ensure the denominator is not zero"
+          }
+        rescue => e
+          @logger.error("Calculation failed for '#{expression}': #{e.message}")
+          {
+            success:    false,
+            error:      "Calculation error: #{e.message}",
+            expression: expression,
+            suggestion: "Verify the expression syntax and try again"
+          }
+        end
+      end
+
+      private
+
+      # Validate and normalize precision value
+      #
+      # @param precision [Integer] Requested precision
+      # @return [Integer] Validated precision (0-10)
+      def validate_precision(precision)
+        precision = precision.to_i
+
+        if precision < 0
+          @logger.warn("Negative precision #{precision} adjusted to 0")
+          return 0
+        end
+
+        if precision > 10
+          @logger.warn("Precision #{precision} exceeds maximum, adjusted to 10")
+          return 10
+        end
+
+        precision
+      end
+
+      # Format result with specified precision
+      #
+      # @param result [Numeric] Raw calculation result
+      # @param precision [Integer] Number of decimal places
+      # @return [Numeric] Formatted result
+      def format_result(result, precision)
+        # Handle boolean results
+        return result if result == true || result == false
+
+        # Handle numeric results
+        return result unless result.is_a?(Numeric)
+
+        # Round to specified precision
+        result.round(precision)
+      end
+    end
+  end
+end