shared_tools 0.2.3 → 0.3.0

data/lib/shared_tools/tools/composite_analysis_tool.rb

@@ -0,0 +1,520 @@
+# composite_analysis_tool.rb - Tool that orchestrates multiple analysis steps
+require 'ruby_llm/tool'
+require 'json'
+
+module SharedTools
+  module Tools
+    class CompositeAnalysisTool < RubyLLM::Tool
+      def self.name = "composite_analysis"
+
+      description <<~'DESCRIPTION'
+        Perform comprehensive multi-stage data analysis by orchestrating multiple specialized analysis steps
+        to provide complete insights from various data sources. This composite tool automatically
+        determines the appropriate data fetching method (web scraping for URLs, file reading for
+        local paths), analyzes data structure and content, generates statistical insights,
+        and suggests appropriate visualizations based on the data characteristics.
+        Ideal for exploratory data analysis workflows where you need a complete picture
+        from initial data loading through final insights. Handles CSV, JSON, and text data formats.
+      DESCRIPTION
+
+      params do
+        string :data_source, description: <<~DESC.strip, required: true
+          Primary data source to analyze. Can be either a local file path or a web URL.
+          For files: Use relative or absolute paths to CSV, JSON, XML, or text files.
+          For URLs: Use complete HTTP/HTTPS URLs to accessible data endpoints or web pages.
+          The tool automatically detects the source type and uses appropriate fetching methods.
+          Examples: './data/sales.csv', '/home/user/data.json', 'https://api.example.com/data'
+        DESC
+
+        string :analysis_type, description: <<~DESC.strip, required: false
+          Type of analysis to perform: 'quick', 'standard', or 'comprehensive'.
+          Quick: Basic structure and summary statistics only (fastest).
+          Standard: Includes structure, insights, and visualization suggestions (recommended).
+          Comprehensive: Full analysis with detailed correlations and patterns (slowest).
+          Default: standard
+        DESC
+
+        object :options, description: <<~DESC.strip, required: false do
+          Additional analysis options for customizing the analysis behavior.
+          These options allow fine-tuning the analysis process for different dataset sizes and requirements.
+        DESC
+          integer :sample_size, description: "Maximum number of rows to analyze for large datasets. Helps manage performance on very large files.", required: false
+          boolean :include_correlations, description: "Enable correlation analysis. Set to false to skip correlation calculations. Default: true", required: false
+          integer :visualization_limit, description: "Maximum number of visualizations to suggest. Default: 5", required: false
+        end
+      end
+
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      def execute(data_source:, analysis_type: "standard", **options)
+        results = {}
+        analysis_start = Time.now
+
+        begin
+          @logger.info("CompositeAnalysisTool#execute data_source=#{data_source} analysis_type=#{analysis_type}")
+
+          # Step 1: Fetch data using appropriate method
+          @logger.debug("Fetching data from source...")
+          if data_source.start_with?('http://', 'https://')
+            results[:data] = fetch_web_data(data_source)
+            results[:source_type] = 'web'
+          else
+            results[:data] = read_file_data(data_source)
+            results[:source_type] = 'file'
+          end
+
+          # Step 2: Analyze data structure
+          @logger.debug("Analyzing data structure...")
+          results[:structure] = analyze_data_structure(results[:data])
+
+          # Step 3: Generate insights based on analysis type
+          if ['standard', 'comprehensive'].include?(analysis_type)
+            @logger.debug("Generating insights...")
+            results[:insights] = generate_insights(results[:data], results[:structure], options)
+          end
+
+          # Step 4: Create visualization suggestions
+          if results[:structure][:numeric_columns]&.any?
+            @logger.debug("Suggesting visualizations...")
+            viz_limit = options[:visualization_limit] || 5
+            results[:visualizations] = suggest_visualizations(results[:structure], viz_limit)
+          end
+
+          # Step 5: Perform correlation analysis for comprehensive mode
+          if analysis_type == 'comprehensive' && results[:structure][:numeric_columns]&.length.to_i > 1
+            include_corr = options[:include_correlations].nil? ? true : options[:include_correlations]
+            if include_corr
+              @logger.debug("Performing correlation analysis...")
+              results[:correlations] = perform_correlation_analysis(results[:data], results[:structure])
+            end
+          end
+
+          analysis_duration = (Time.now - analysis_start).round(3)
+          @logger.info("Analysis completed in #{analysis_duration}s")
+
+          {
+            success: true,
+            analysis: results,
+            data_source: data_source,
+            analysis_type: analysis_type,
+            analyzed_at: Time.now.iso8601,
+            duration_seconds: analysis_duration
+          }
+        rescue => e
+          @logger.error("Analysis failed: #{e.message}")
+          {
+            success: false,
+            error: e.message,
+            error_type: e.class.name,
+            data_source: data_source,
+            partial_results: results
+          }
+        end
+      end
+
+      private
+
+      # Fetch data from web URL
+      def fetch_web_data(url)
+        @logger.debug("Fetching web data from: #{url}")
+
+        # In a real implementation, this would use HTTP client
+        # For simulation, return sample data based on URL patterns
+        case url
+        when /\.json$/
+          simulate_json_data
+        when /\.csv$/
+          simulate_csv_data
+        else
+          simulate_api_response
+        end
+      end
+
+      # Read data from local file
+      def read_file_data(file_path)
+        @logger.debug("Reading file data from: #{file_path}")
+
+        # Check if file exists (for real files)
+        unless File.exist?(file_path)
+          # For demo/testing, return simulated data based on file extension
+          @logger.warn("File not found (#{file_path}), using simulated data")
+          case File.extname(file_path).downcase
+          when '.json'
+            return simulate_json_data
+          when '.txt'
+            return ["Sample text line 1", "Sample text line 2", "Sample text line 3"]
+          else
+            return simulate_csv_data
+          end
+        end
+
+        # Determine file type and parse accordingly
+        case File.extname(file_path).downcase
+        when '.json'
+          JSON.parse(File.read(file_path))
+        when '.txt'
+          File.readlines(file_path).map(&:chomp)
+        else
+          # For real CSV files in production, would need csv gem
+          # For now, return simulated data
+          @logger.warn("CSV parsing requires csv gem, using simulated data")
+          simulate_csv_data
+        end
+      end
+
+      # Analyze the structure of the data
+      def analyze_data_structure(data)
+        structure = {
+          data_type: determine_data_type(data),
+          row_count: count_rows(data),
+          columns: [],
+          numeric_columns: [],
+          categorical_columns: [],
+          text_columns: []
+        }
+
+        case structure[:data_type]
+        when 'tabular'
+          analyze_tabular_structure(data, structure)
+        when 'json'
+          analyze_json_structure(data, structure)
+        when 'text'
+          analyze_text_structure(data, structure)
+        end
+
+        structure
+      end
+
+      # Generate insights from the data
+      def generate_insights(data, structure, options)
+        insights = {
+          summary: generate_summary(structure),
+          quality: assess_data_quality(data, structure),
+          recommendations: generate_recommendations(structure)
+        }
+
+        # Add statistical insights for numeric columns
+        if structure[:numeric_columns]&.any?
+          insights[:statistics] = calculate_statistics(data, structure)
+        end
+
+        # Add patterns for categorical data
+        if structure[:categorical_columns]&.any?
+          insights[:patterns] = identify_patterns(data, structure)
+        end
+
+        insights
+      end
+
+      # Suggest appropriate visualizations
+      def suggest_visualizations(structure, limit = 5)
+        suggestions = []
+
+        # Distribution plots for numeric columns
+        structure[:numeric_columns]&.each do |col|
+          suggestions << {
+            type: 'histogram',
+            column: col[:name],
+            purpose: "Show distribution of #{col[:name]} values",
+            priority: 'high'
+          }
+        end
+
+        # Bar charts for categorical data
+        structure[:categorical_columns]&.each do |col|
+          if col[:unique_values] < 20
+            suggestions << {
+              type: 'bar_chart',
+              column: col[:name],
+              purpose: "Show frequency of #{col[:name]} categories",
+              priority: 'medium'
+            }
+          end
+        end
+
+        # Scatter plots for numeric pairs
+        if structure[:numeric_columns]&.length.to_i > 1
+          num_cols = structure[:numeric_columns]
+          suggestions << {
+            type: 'scatter_plot',
+            columns: [num_cols[0][:name], num_cols[1][:name]],
+            purpose: "Explore relationship between #{num_cols[0][:name]} and #{num_cols[1][:name]}",
+            priority: 'high'
+          }
+        end
+
+        # Time series if date column exists
+        if structure[:columns]&.any? { |c| c[:type] == 'date' }
+          suggestions << {
+            type: 'time_series',
+            purpose: "Track changes over time",
+            priority: 'high'
+          }
+        end
+
+        # Limit and sort by priority
+        suggestions
+          .sort_by { |s| s[:priority] == 'high' ? 0 : 1 }
+          .first(limit)
+      end
+
+      # Perform correlation analysis
+      def perform_correlation_analysis(data, structure)
+        return {} unless structure[:numeric_columns]&.length.to_i > 1
+
+        correlations = []
+        numeric_cols = structure[:numeric_columns]
+
+        # Calculate correlations between numeric column pairs
+        numeric_cols.combination(2).each do |col1, col2|
+          correlation = calculate_correlation(data, col1[:name], col2[:name])
+
+          correlations << {
+            columns: [col1[:name], col2[:name]],
+            correlation: correlation,
+            strength: interpret_correlation(correlation),
+            significant: correlation.abs > 0.5
+          }
+        end
+
+        {
+          pairs: correlations.sort_by { |c| -c[:correlation].abs },
+          strongest: correlations.max_by { |c| c[:correlation].abs }
+        }
+      end
+
+      # Helper methods
+
+      def determine_data_type(data)
+        case data
+        when Array
+          data.first.is_a?(Hash) ? 'tabular' : 'text'
+        when Hash
+          'json'
+        when String
+          'text'
+        else
+          'unknown'
+        end
+      end
+
+      def count_rows(data)
+        case data
+        when Array then data.length
+        when Hash then data.keys.length
+        when String then data.lines.count
+        else 0
+        end
+      end
+
+      def analyze_tabular_structure(data, structure)
+        return if data.empty?
+
+        first_row = data.first
+        first_row.keys.each do |key|
+          values = data.map { |row| row[key] }.compact
+          col_info = {
+            name: key,
+            type: infer_column_type(values),
+            null_count: data.length - values.length,
+            unique_values: values.uniq.length
+          }
+
+          structure[:columns] << col_info
+
+          case col_info[:type]
+          when 'numeric'
+            structure[:numeric_columns] << col_info
+          when 'categorical'
+            structure[:categorical_columns] << col_info
+          when 'text'
+            structure[:text_columns] << col_info
+          end
+        end
+      end
+
+      def analyze_json_structure(data, structure)
+        keys = data.is_a?(Hash) ? data.keys : []
+        structure[:columns] = keys.map { |k| {name: k, type: 'json'} }
+      end
+
+      def analyze_text_structure(data, structure)
+        lines = data.is_a?(Array) ? data : data.lines
+        structure[:line_count] = lines.length
+        structure[:total_chars] = lines.sum(&:length)
+        structure[:avg_line_length] = lines.empty? ? 0 : structure[:total_chars] / structure[:line_count]
+      end
+
+      def infer_column_type(values)
+        sample = values.first(100)
+
+        numeric_count = sample.count { |v| v.to_s.match?(/^-?\d+\.?\d*$/) }
+        return 'numeric' if numeric_count > sample.length * 0.8
+
+        # Check for categorical data
+        unique_ratio = sample.uniq.length.to_f / sample.length
+        avg_length = sample.map(&:to_s).sum(&:length) / sample.length rescue 0
+
+        # If unique values are low relative to sample size, it's categorical
+        # Also consider short text values as likely categorical
+        return 'categorical' if unique_ratio < 0.7 || (unique_ratio < 0.9 && avg_length < 30)
+
+        'text'
+      end
+
+      def generate_summary(structure)
+        "Dataset contains #{structure[:row_count]} rows with #{structure[:columns]&.length || 0} columns. " \
+        "#{structure[:numeric_columns]&.length || 0} numeric, " \
+        "#{structure[:categorical_columns]&.length || 0} categorical, " \
+        "#{structure[:text_columns]&.length || 0} text columns."
+      end
+
+      def assess_data_quality(data, structure)
+        total_cells = structure[:row_count] * (structure[:columns]&.length || 0)
+        null_cells = structure[:columns]&.sum { |c| c[:null_count] || 0 } || 0
+
+        {
+          completeness: total_cells > 0 ? ((total_cells - null_cells).to_f / total_cells * 100).round(2) : 100,
+          null_percentage: total_cells > 0 ? (null_cells.to_f / total_cells * 100).round(2) : 0,
+          quality_score: calculate_quality_score(structure)
+        }
+      end
+
+      def calculate_quality_score(structure)
+        score = 100
+
+        # Penalize for high null counts
+        structure[:columns]&.each do |col|
+          null_ratio = col[:null_count].to_f / structure[:row_count]
+          score -= (null_ratio * 10) if null_ratio > 0.1
+        end
+
+        [score, 0].max.round(2)
+      end
+
+      def generate_recommendations(structure)
+        recommendations = []
+
+        # Check for high null counts
+        structure[:columns]&.each do |col|
+          null_ratio = col[:null_count].to_f / structure[:row_count]
+          if null_ratio > 0.2
+            recommendations << "Column '#{col[:name]}' has #{(null_ratio * 100).round(1)}% missing values - consider imputation or removal"
+          end
+        end
+
+        # Check for low variance categorical columns
+        structure[:categorical_columns]&.each do |col|
+          if col[:unique_values] == 1
+            recommendations << "Column '#{col[:name]}' has only one unique value - consider removing"
+          end
+        end
+
+        recommendations << "Data quality is good" if recommendations.empty?
+        recommendations
+      end
+
+      def calculate_statistics(data, structure)
+        stats = {}
+
+        structure[:numeric_columns]&.each do |col|
+          values = data.map { |row| row[col[:name]].to_f }.compact
+          next if values.empty?
+
+          sorted = values.sort
+          stats[col[:name]] = {
+            min: sorted.first.round(2),
+            max: sorted.last.round(2),
+            mean: (values.sum / values.length).round(2),
+            median: sorted[sorted.length / 2].round(2),
+            std_dev: calculate_std_dev(values).round(2)
+          }
+        end
+
+        stats
+      end
+
+      def calculate_std_dev(values)
+        mean = values.sum / values.length
+        variance = values.sum { |v| (v - mean) ** 2 } / values.length
+        Math.sqrt(variance)
+      end
+
+      def identify_patterns(data, structure)
+        patterns = {}
+
+        structure[:categorical_columns]&.each do |col|
+          values = data.map { |row| row[col[:name]] }.compact
+          frequency = values.each_with_object(Hash.new(0)) { |v, h| h[v] += 1 }
+
+          patterns[col[:name]] = {
+            most_common: frequency.max_by { |_, count| count },
+            distribution: frequency.sort_by { |_, count| -count }.first(5).to_h
+          }
+        end
+
+        patterns
+      end
+
+      def calculate_correlation(data, col1, col2)
+        values1 = data.map { |row| row[col1].to_f }
+        values2 = data.map { |row| row[col2].to_f }
+
+        return 0.0 if values1.empty? || values2.empty?
+
+        # Simplified correlation calculation
+        mean1 = values1.sum / values1.length
+        mean2 = values2.sum / values2.length
+
+        covariance = values1.zip(values2).sum { |v1, v2| (v1 - mean1) * (v2 - mean2) } / values1.length
+        std1 = Math.sqrt(values1.sum { |v| (v - mean1) ** 2 } / values1.length)
+        std2 = Math.sqrt(values2.sum { |v| (v - mean2) ** 2 } / values2.length)
+
+        return 0.0 if std1 == 0 || std2 == 0
+
+        (covariance / (std1 * std2)).round(3)
+      end
+
+      def interpret_correlation(corr)
+        abs_corr = corr.abs
+        case abs_corr
+        when 0.0...0.3 then 'weak'
+        when 0.3...0.7 then 'moderate'
+        else 'strong'
+        end
+      end
+
+      # Simulation methods for testing
+
+      def simulate_json_data
+        {
+          "users" => [
+            {"id" => 1, "name" => "Alice", "age" => 30, "score" => 85},
+            {"id" => 2, "name" => "Bob", "age" => 25, "score" => 92},
+            {"id" => 3, "name" => "Charlie", "age" => 35, "score" => 78}
+          ]
+        }
+      end
+
+      def simulate_csv_data
+        [
+          {"id" => "1", "product" => "Widget A", "sales" => "100", "revenue" => "1000.50", "category" => "Electronics"},
+          {"id" => "2", "product" => "Widget B", "sales" => "150", "revenue" => "2250.75", "category" => "Electronics"},
+          {"id" => "3", "product" => "Gadget C", "sales" => "80", "revenue" => "960.00", "category" => "Home"},
+          {"id" => "4", "product" => "Tool D", "sales" => "120", "revenue" => "1800.00", "category" => "Tools"},
+          {"id" => "5", "product" => "Widget E", "sales" => "90", "revenue" => "1350.00", "category" => "Electronics"}
+        ]
+      end
+
+      def simulate_api_response
+        {
+          "status" => "success",
+          "data" => simulate_csv_data,
+          "timestamp" => Time.now.iso8601
+        }
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/computer/base_driver.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    module Computer
+      # A tool for interacting with a computer. Be careful with using as it can perform actions on your computer!
+      #
+      # @example
+      #   class SomeDriver < BaseDriver
+      #     @param text [String]
+      #     def key(text:)
+      #       # TODO
+      #     end
+      #
+      #     # @param text [String]
+      #     # @param duration [Integer]
+      #     def hold_key(text:, duration:)
+      #       # TODO
+      #     end
+      #
+      #     # @return [Hash<{ x: Integer, y: Integer }>]
+      #     def mouse_position
+      #       # TODO
+      #     end
+      #
+      #     # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+      #     # @param button [String] e.g. "left", "middle", "right"
+      #     def mouse_move(coordinate:)
+      #       # TODO
+      #     end
+      #
+      #     # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+      #     # @param button [String] e.g. "left", "middle", "right"
+      #     def mouse_click(coordinate:, button:)
+      #       # TODO
+      #     end
+      #
+      #     # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+      #     # @param button [String] e.g. "left", "middle", "right"
+      #     def mouse_down(coordinate:, button:)
+      #       # TODO
+      #     end
+      #
+      #     # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+      #     # @param button [String] e.g. "left", "middle", "right"
+      #     def mouse_up(coordinate:, button:)
+      #       # TODO
+      #     end
+      #
+      #     # @param text [String]
+      #     def type(text:)
+      #       # TODO
+      #     end
+      #
+      #     # @param amount [Integer]
+      #     # @param direction [String] e.g. "up", "down", "left", "right"
+      #     def scroll(amount:, direction:)
+      #       # TODO
+      #     end
+      #
+      #     # @yield [file]
+      #     # @yieldparam file [File]
+      #     def screenshot
+      #       # TODO
+      #     end
+      #   end
+      class BaseDriver
+        DEFAULT_MOUSE_BUTTON = "left"
+        DEFAULT_DISPLAY_SCALE = 2
+
+        # @!attr_accessor :display_height
+        #   @return [Integer] the height of the display in pixels
+        attr_accessor :display_width
+
+        # @!attr_accessor :display_height
+        #   @return [Integer] the height of the display in pixels
+        attr_accessor :display_height
+
+        # @!attr_accessor :display_number
+        #   @return [Integer] the display number
+        attr_accessor :display_number
+
+        # @param display_width [Integer] the width of the display in pixels
+        # @param display_height [Integer] the height of the display in pixels
+        # @param display_number [Integer] the display number
+        def initialize(display_width:, display_height:, display_number:)
+          @display_width = display_width
+          @display_height = display_height
+
+          @display_number = display_number
+        end
+
+        # @param text [String]
+        def key(text:)
+          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+        end
+
+        # @param text [String]
+        # @param duration [Integer]
+        def hold_key(text:, duration:)
+          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+        end
+
+        # @return [Hash<{ x: Integer, y: Integer }>]
+        def mouse_position
+          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+        end
+
+        # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+        # @param button [String] e.g. "left", "middle", "right"
+        def mouse_move(coordinate:)
+          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+        end
+
+        # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+        # @param button [String] e.g. "left", "middle", "right"
+        def mouse_click(coordinate:, button:)
+          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+        end
+
+        # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+        # @param button [String] e.g. "left", "middle", "right"
+        def mouse_down(coordinate:, button:)
+          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+        end
+
+        # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+        # @param button [String] e.g. "left", "middle", "right"
+        def mouse_up(coordinate:, button:)
+          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+        end
+
+        # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+        # @param button [String] e.g. "left", "middle", "right"
+        def mouse_drag(coordinate:, button: DEFAULT_MOUSE_BUTTON)
+          mouse_down(coordinate: mouse_position, button:)
+          mouse_move(coordinate:, button:)
+          mouse_up(coordinate:, button:)
+        end
+
+        # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+        # @param button [String] e.g. "left", "middle", "right"
+        def mouse_double_click(coordinate:, button:)
+          2.times { mouse_click(coordinate:, button:) }
+        end
+
+        # @param coordinate [Hash<{ x: Integer, y: Integer }>]
+        # @param button [String] e.g. "left", "middle", "right"
+        def mouse_triple_click(coordinate:, button:)
+          3.times { mouse_click(coordinate:, button:) }
+        end
+
+        # @param text [String]
+        def type(text:)
+          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+        end
+
+        # @param amount [Integer]
+        # @param direction [String] e.g. "up", "down", "left", "right"
+        def scroll(amount:, direction:)
+          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+        end
+
+        # @yield [file]
+        # @yieldparam file [File]
+        def screenshot
+          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+        end
+
+        # @param duration [Integer]
+        def wait(duration:)
+          Kernel.sleep(duration)
+        end
+      end
+    end
+  end
+end