shared_tools 0.3.0 → 0.4.1

data/lib/shared_tools/tools/cron_tool.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Parse, validate, explain, and generate cron expressions.
+    #
+    # @example
+    #   tool = SharedTools::Tools::CronTool.new
+    #   tool.execute(action: 'parse',      expression: '0 9 * * 1-5')
+    #   tool.execute(action: 'validate',   expression: '*/15 * * * *')
+    #   tool.execute(action: 'next_times', expression: '0 * * * *', count: 5)
+    #   tool.execute(action: 'generate',   description: 'every day at 9am')
+    class CronTool < ::RubyLLM::Tool
+      def self.name = 'cron_tool'
+
+      description <<~DESC
+        Parse, validate, explain, and generate cron expressions (standard 5-field format).
+
+        Actions:
+        - 'parse'      — Parse and explain a cron expression
+        - 'validate'   — Check whether a cron expression is valid
+        - 'next_times' — List the next N execution times (default 5)
+        - 'generate'   — Generate a cron expression from a natural language description
+
+        Cron format: minute hour day month weekday
+          - Each field accepts: number, range (1-5), list (1,3,5), step (*/15), or wildcard (*)
+          - Weekday: 0-7 (0 and 7 both mean Sunday)
+
+        Generate examples: 'every day at 9am', 'every monday at noon', 'every 15 minutes',
+                           'every weekday', 'first day of every month at midnight'
+      DESC
+
+      params do
+        string  :action,      description: "Action: 'parse', 'validate', 'next_times', 'generate'"
+        string  :expression,  required: false, description: "5-field cron expression. Required for parse, validate, next_times."
+        integer :count,       required: false, description: "Number of next execution times. Default: 5."
+        string  :description, required: false, description: "Natural language schedule description. Required for generate."
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param action      [String]       action to perform
+      # @param expression  [String, nil]  cron expression
+      # @param count       [Integer, nil] number of times for next_times
+      # @param description [String, nil]  natural language description for generate
+      # @return [Hash] result
+      def execute(action:, expression: nil, count: nil, description: nil)
+        @logger.info("CronTool#execute action=#{action}")
+
+        case action.to_s.downcase
+        when 'parse'      then parse_expression(expression)
+        when 'validate'   then validate_expression(expression)
+        when 'next_times' then next_times(expression, (count || 5).to_i)
+        when 'generate'   then generate_expression(description)
+        else
+          { success: false, error: "Unknown action '#{action}'. Use: parse, validate, next_times, generate" }
+        end
+      rescue => e
+        @logger.error("CronTool error: #{e.message}")
+        { success: false, error: e.message }
+      end
+
+      private
+
+      FIELD_NAMES   = %w[minute hour day month weekday].freeze
+      FIELD_RANGES  = {
+        'minute'  => 0..59,
+        'hour'    => 0..23,
+        'day'     => 1..31,
+        'month'   => 1..12,
+        'weekday' => 0..7
+      }.freeze
+      DAY_NAMES     = %w[Sunday Monday Tuesday Wednesday Thursday Friday Saturday].freeze
+      MONTH_NAMES   = %w[January February March April May June July August
+                         September October November December].freeze
+
+      # -------------------------------------------------------------------------
+      # Action implementations
+      # -------------------------------------------------------------------------
+
+      def parse_expression(expr)
+        require_expr!(expr)
+        parts = split_expr(expr)
+        fields = {}
+        FIELD_NAMES.zip(parts).each do |name, raw|
+          fields[name] = { raw: raw, values: expand_field(raw, FIELD_RANGES[name]) }
+        end
+        { success: true, valid: true, expression: expr, fields: fields, explanation: explain(parts) }
+      rescue ArgumentError => e
+        { success: false, valid: false, expression: expr, error: e.message }
+      end
+
+      def validate_expression(expr)
+        require_expr!(expr)
+        parts = split_expr(expr)
+        FIELD_NAMES.zip(parts).each { |name, raw| expand_field(raw, FIELD_RANGES[name]) }
+        { success: true, valid: true, expression: expr, explanation: explain(parts) }
+      rescue ArgumentError => e
+        { success: true, valid: false, expression: expr, error: e.message }
+      end
+
+      def next_times(expr, count)
+        require_expr!(expr)
+        parts = split_expr(expr)
+
+        sets = FIELD_NAMES.map.with_index { |name, i| expand_field(parts[i], FIELD_RANGES[name]) }
+        mins_set, hrs_set, days_set, months_set, wdays_set = sets
+
+        # Normalise Sunday: weekday 7 == 0
+        wdays_set = wdays_set.map { |d| d == 7 ? 0 : d }.uniq.sort
+
+        times  = []
+        t      = Time.now
+        # Advance to the next minute boundary
+        t      = Time.new(t.year, t.month, t.day, t.hour, t.min + 1, 0)
+        limit  = 527_040 # 1 year of minutes — safety cap
+
+        while times.size < count && limit > 0
+          limit -= 1
+          if months_set.include?(t.month) &&
+             days_set.include?(t.day) &&
+             wdays_set.include?(t.wday) &&
+             hrs_set.include?(t.hour) &&
+             mins_set.include?(t.min)
+            times << t.strftime('%Y-%m-%d %H:%M (%A)')
+          end
+          t += 60
+        end
+
+        { success: true, expression: expr, explanation: explain(parts), next_times: times }
+      end
+
+      def generate_expression(desc)
+        raise ArgumentError, "description is required for the generate action" if desc.nil? || desc.strip.empty?
+
+        d    = desc.downcase
+        expr = match_pattern(d)
+
+        if expr
+          parts = expr.split
+          { success: true, description: desc, expression: expr, explanation: explain(parts) }
+        else
+          {
+            success: false,
+            description: desc,
+            error: "Could not generate an expression from that description. " \
+                   "Try: 'every day at 9am', 'every monday at noon', 'every 15 minutes', " \
+                   "'every weekday', 'first day of every month at midnight'."
+          }
+        end
+      end
+
+      # -------------------------------------------------------------------------
+      # Pattern matching for generate
+      # -------------------------------------------------------------------------
+
+      def match_pattern(d)
+        return '* * * * *' if d.include?('every minute')
+
+        if (m = d.match(/every\s+(\d+)\s+minutes?/))
+          return "*/#{m[1]} * * * *"
+        end
+
+        if d.match?(/every\s+hour\b/) && !d.match?(/\d+\s+hours?/)
+          return '0 * * * *'
+        end
+
+        if (m = d.match(/every\s+(\d+)\s+hours?/))
+          return "0 */#{m[1]} * * *"
+        end
+
+        return '0 9 * * 1-5' if d.include?('weekday')
+        return '0 0 * * 0,6' if d.include?('weekend')
+
+        day_pattern = DAY_NAMES.map(&:downcase).join('|')
+
+        if (m = d.match(/every\s+(#{day_pattern})\s+at\s+(\d+)(?::(\d+))?\s*(am|pm)?/))
+          day_num = DAY_NAMES.map(&:downcase).index(m[1])
+          return "#{hm_to_cron(m[2], m[3], m[4])} * * #{day_num}"
+        end
+
+        if (m = d.match(/every\s+(#{day_pattern})\s+at\s+noon/))
+          day_num = DAY_NAMES.map(&:downcase).index(m[1])
+          return "0 12 * * #{day_num}"
+        end
+
+        if (m = d.match(/every\s+(#{day_pattern})/))
+          day_num = DAY_NAMES.map(&:downcase).index(m[1])
+          return "0 0 * * #{day_num}"
+        end
+
+        return '0 12 * * *'  if d.include?('noon')
+        return '0 0 * * *'   if d.include?('midnight')
+
+        if (m = d.match(/every\s+day\s+at\s+(\d+)(?::(\d+))?\s*(am|pm)?/))
+          return "#{hm_to_cron(m[1], m[2], m[3])} * * *"
+        end
+
+        if (m = d.match(/first\s+day\s+(?:of\s+(?:every\s+)?month\s+)?at\s+(\d+)(?::(\d+))?\s*(am|pm)?/))
+          return "#{hm_to_cron(m[1], m[2], m[3])} 1 * *"
+        end
+
+        return '0 0 1 * *' if d.match?(/first\s+day/)
+
+        nil
+      end
+
+      # Convert hour/minute/ampm strings to "min hour" cron tokens.
+      def hm_to_cron(h, m, ap)
+        hour = h.to_i
+        min  = (m || '0').to_i
+        hour += 12 if ap == 'pm' && hour != 12
+        hour  = 0  if ap == 'am' && hour == 12
+        "#{min} #{hour}"
+      end
+
+      # -------------------------------------------------------------------------
+      # Field expansion
+      # -------------------------------------------------------------------------
+
+      # Expand one cron field to a sorted array of integers.
+      def expand_field(value, range)
+        return range.to_a if value == '*'
+
+        result = []
+        value.split(',').each do |part|
+          if part.include?('/')
+            base_str, step_str = part.split('/')
+            step = step_str.to_i
+            raise ArgumentError, "Step must be >= 1, got #{step}" if step < 1
+            base_set = base_str == '*' ? range.to_a : expand_range_part(base_str, range)
+            result.concat(base_set.each_with_index.filter_map { |v, i| v if (i % step).zero? })
+          elsif part.include?('-')
+            a, b = part.split('-').map(&:to_i)
+            unless range_with_sunday(range).cover?(a) && range_with_sunday(range).cover?(b)
+              raise ArgumentError, "Range #{part} is out of bounds for #{range}"
+            end
+            result.concat((a..b).to_a)
+          else
+            v = part.to_i
+            unless range_with_sunday(range).cover?(v)
+              raise ArgumentError, "Value #{v} is out of range #{range}"
+            end
+            result << v
+          end
+        end
+
+        result.uniq.sort
+      end
+
+      def expand_range_part(str, range)
+        if str.include?('-')
+          a, b = str.split('-').map(&:to_i)
+          (a..b).to_a
+        else
+          v = str.to_i
+          (v..range.last).to_a
+        end
+      end
+
+      # Allow weekday 7 (Sunday alias)
+      def range_with_sunday(range)
+        range == FIELD_RANGES['weekday'] ? (0..7) : range
+      end
+
+      # -------------------------------------------------------------------------
+      # Human-readable explanation
+      # -------------------------------------------------------------------------
+
+      def explain(parts)
+        min, hour, day, month, weekday = parts
+        segments = []
+
+        segments << if min == '*'           then 'every minute'
+                    elsif min.start_with?('*/') then "every #{min[2..]} minutes"
+                    else                         "at minute #{min}"
+                    end
+
+        segments << if hour == '*'            then 'of every hour'
+                    elsif hour.start_with?('*/') then "every #{hour[2..]} hours"
+                    else                           "at #{fmt_hour(hour)}"
+                    end
+
+        segments << "on day #{day} of the month"  unless day == '*'
+        segments << "in #{fmt_month(month)}"       unless month == '*'
+        segments << "on #{fmt_weekday(weekday)}"   unless weekday == '*'
+
+        segments.join(', ')
+      end
+
+      def fmt_hour(h)
+        return h if h.match?(/[,\-\/]/)
+        n    = h.to_i
+        disp = n == 0 ? 12 : (n > 12 ? n - 12 : n)
+        ampm = n < 12 ? 'AM' : 'PM'
+        "#{disp}:00 #{ampm}"
+      end
+
+      def fmt_month(m)
+        return m if m.match?(/[,\-\/]/)
+        MONTH_NAMES[m.to_i - 1] || m
+      end
+
+      def fmt_weekday(w)
+        return 'weekdays (Mon–Fri)' if w == '1-5'
+        return w if w.match?(/[,\/]/)
+        return w if w.include?('-')
+        DAY_NAMES[w.to_i % 7] || w
+      end
+
+      # -------------------------------------------------------------------------
+      # Helpers
+      # -------------------------------------------------------------------------
+
+      def require_expr!(expr)
+        raise ArgumentError, "expression is required for this action" if expr.nil? || expr.strip.empty?
+      end
+
+      def split_expr(expr)
+        parts = expr.strip.split(/\s+/)
+        raise ArgumentError, "Cron expression must have 5 fields, got #{parts.size}" unless parts.size == 5
+        parts
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/current_date_time_tool.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Returns the current date, time, and timezone from the local system.
+    #
+    # @example
+    #   tool = SharedTools::Tools::CurrentDateTimeTool.new
+    #   tool.execute                    # full output
+    #   tool.execute(format: 'date')    # date fields only
+    class CurrentDateTimeTool < ::RubyLLM::Tool
+      def self.name = 'current_date_time_tool'
+
+      description <<~DESC
+        Returns the current date, time, timezone, and calendar metadata from the system clock.
+
+        Supported formats:
+        - 'full'    (default) — all fields: date, time, timezone, ISO 8601, unix timestamp, DST flag
+        - 'date'    — year, month, day, day_of_week, week_of_year, quarter, ordinal_day
+        - 'time'    — hour, minute, second, timezone, utc_offset
+        - 'iso8601' — iso8601, iso8601_utc, unix_timestamp
+      DESC
+
+      params do
+        string :format, required: false, description: <<~DESC.strip
+          Output format. Options: 'full' (default), 'date', 'time', 'iso8601'.
+        DESC
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param format [String] output format
+      # @return [Hash] date/time information
+      def execute(format: 'full')
+        @logger.info("CurrentDateTimeTool#execute format=#{format}")
+
+        now = Time.now
+        utc = now.utc
+
+        date_info = {
+          year:            now.year,
+          month:           now.month,
+          day:             now.day,
+          day_of_week:     now.strftime('%A'),
+          day_of_week_num: now.wday,
+          week_of_year:    now.strftime('%U').to_i,
+          quarter:         ((now.month - 1) / 3) + 1,
+          ordinal_day:     now.yday
+        }
+
+        time_info = {
+          hour:             now.hour,
+          minute:           now.min,
+          second:           now.sec,
+          timezone:         now.zone,
+          utc_offset:       now.strftime('%z'),
+          utc_offset_hours: (now.utc_offset / 3600.0).round(2)
+        }
+
+        iso_info = {
+          iso8601:       now.iso8601,
+          iso8601_utc:   utc.iso8601,
+          unix_timestamp: now.to_i
+        }
+
+        case format.to_s.downcase
+        when 'date'
+          { success: true }.merge(date_info)
+        when 'time'
+          { success: true }.merge(time_info)
+        when 'iso8601'
+          { success: true }.merge(iso_info)
+        else
+          { success: true, dst: now.dst? }
+            .merge(date_info)
+            .merge(time_info)
+            .merge(iso_info)
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/data_science_kit.rb

@@ -28,13 +28,22 @@ module SharedTools
           Each analysis type requires specific data formats and optional parameters.
         DESC
 
-        string :data_source, description: <<~DESC.strip, required: true
+        string :data_source, description: <<~DESC.strip, required: false
           Data source specification for analysis. Can be:
           - File path: Relative or absolute path to CSV, JSON, Excel, or Parquet files
           - Database query: SQL SELECT statement for database-sourced data
           - API endpoint: HTTP URL for REST API data sources
           The tool automatically detects the format and applies appropriate parsing.
           Examples: './sales_data.csv', 'SELECT * FROM transactions', 'https://api.company.com/data'
+          Either data_source or data must be provided.
+        DESC
+
+        string :data, description: <<~DESC.strip, required: false
+          Inline data to analyse, provided directly as a JSON string. Accepted formats:
+          - Array of hashes: '[{"month":"Jan","value":42},{"month":"Feb","value":45}]'
+          - Pipe-delimited table string: "Col A | Col B\n1 | 2\n3 | 4"
+          - Comma-separated numbers (single series): "42,45,51,48,55" — parsed as [{value: n}]
+          Either data or data_source must be provided.
         DESC
 
         object :parameters, description: <<~DESC.strip, required: false do
@@ -82,11 +91,18 @@ module SharedTools
         @logger = logger || RubyLLM.logger
       end
 
-      def execute(analysis_type:, data_source:, **parameters)
+      def execute(analysis_type:, data_source: nil, data: nil, **parameters)
         analysis_start = Time.now
 
         begin
-          @logger.info("DataScienceKit#execute analysis_type=#{analysis_type} data_source=#{data_source}")
+          if data_source.nil? && data.nil?
+            return {
+              success: false,
+              error: "Either data_source or data must be provided."
+            }
+          end
+
+          @logger.info("DataScienceKit#execute analysis_type=#{analysis_type}")
 
           # Validate analysis type
           unless VALID_ANALYSIS_TYPES.include?(analysis_type)
@@ -99,21 +115,21 @@ module SharedTools
           end
 
           # Load and validate data
-          data = load_data(data_source)
-          validate_data_for_analysis(data, analysis_type, parameters)
+          loaded_data = data ? parse_inline_data(data) : load_data(data_source)
+          validate_data_for_analysis(loaded_data, analysis_type, parameters)
 
           # Perform analysis
           result = case analysis_type
           when "statistical_summary"
-            generate_statistical_summary(data, parameters)
+            generate_statistical_summary(loaded_data, parameters)
           when "correlation_analysis"
-            perform_correlation_analysis(data, parameters)
+            perform_correlation_analysis(loaded_data, parameters)
           when "time_series"
-            analyze_time_series(data, parameters)
+            analyze_time_series(loaded_data, parameters)
           when "clustering"
-            perform_clustering(data, parameters)
+            perform_clustering(loaded_data, parameters)
           when "prediction"
-            generate_predictions(data, parameters)
+            generate_predictions(loaded_data, parameters)
           end
 
           analysis_duration = (Time.now - analysis_start).round(3)
@@ -123,7 +139,7 @@ module SharedTools
             success: true,
             analysis_type: analysis_type,
             result: result,
-            data_summary: summarize_data(data),
+            data_summary: summarize_data(loaded_data),
             analyzed_at: Time.now.iso8601,
             duration_seconds: analysis_duration
           }
@@ -133,8 +149,7 @@ module SharedTools
             success: false,
             error: e.message,
             error_type: e.class.name,
-            analysis_type: analysis_type,
-            data_source: data_source
+            analysis_type: analysis_type
           }
         end
       end
@@ -189,6 +204,41 @@ module SharedTools
         end
       end
 
+      def parse_inline_data(raw)
+        raw = raw.strip
+        # JSON array or object
+        if raw.start_with?('{', '[')
+          begin
+            return JSON.parse(raw)
+          rescue JSON::ParserError
+          end
+        end
+        lines = raw.lines.map(&:strip).reject(&:empty?)
+        # Pipe-delimited table
+        if lines.first&.include?('|')
+          headers = lines.first.split('|').map(&:strip).reject(&:empty?)
+          data_lines = lines.drop(1).reject { |l| l.match?(/^\|?[-:\s|]+$/) }
+          return data_lines.map do |line|
+            values = line.split('|').map(&:strip).reject(&:empty?)
+            headers.zip(values).to_h
+          end
+        end
+        # CSV header row
+        if lines.size > 1 && lines.first.include?(',') && lines.first.match?(/[a-zA-Z]/)
+          headers = lines.first.split(',').map(&:strip)
+          return lines.drop(1).map do |line|
+            values = line.split(',').map(&:strip)
+            headers.zip(values).to_h
+          end
+        end
+        # Comma-separated numbers — single series
+        if lines.size == 1 && lines.first.match?(/^[\d.,\s]+$/)
+          return lines.first.split(',').map { |v| { "value" => v.strip.to_f } }
+        end
+        # Plain lines
+        lines.map { |l| { "value" => l } }
+      end
+
       # Generate sample data for testing
       def generate_sample_data(size = 30)
         (1..size).map do |i|

data/lib/shared_tools/tools/database_tool.rb

@@ -62,14 +62,17 @@ module SharedTools
       end
 
 
-      # @param driver [SharedTools::Tools::Database::BaseDriver] required database driver (SqliteDriver, PostgresDriver, etc.)
+      # @param driver [SharedTools::Tools::Database::BaseDriver] database driver (SqliteDriver, PostgresDriver, etc.)
+      #   Required for execute, but optional for instantiation to support RubyLLM tool discovery
       # @param logger [Logger] optional logger
-      def initialize(driver:, logger: nil)
-        raise ArgumentError, "driver is required for DatabaseTool" if driver.nil?
+      def initialize(driver: nil, logger: nil)
         @driver = driver
         @logger = logger || RubyLLM.logger
       end
 
+      # Set driver after instantiation (useful when tool is discovered by RubyLLM)
+      attr_writer :driver
+
       # @example
       #   tool = SharedTools::Tools::Database::BaseTool.new
       #   tool.execute(statements: ["SELECT * FROM people"])
@@ -78,6 +81,8 @@ module SharedTools
       #
       # @return [Array<Hash>]
       def execute(statements:)
+        raise ArgumentError, "driver is required for DatabaseTool#execute. Set via initialize(driver:) or tool.driver=" if @driver.nil?
+
         [].tap do |executions|
           statements.map do |statement|
             execution = perform(statement:).merge(statement:)