htm 0.0.2 → 0.0.10

data/lib/htm/timeframe.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+
+class HTM
+  # Timeframe - Normalizes various timeframe inputs for database queries
+  #
+  # Handles multiple input types and normalizes them to either:
+  # - nil (no timeframe filter)
+  # - Range (single time window)
+  # - Array<Range> (multiple time windows, OR'd together)
+  #
+  # @example Various input types
+  #   Timeframe.normalize(nil)                    # => nil (no filter)
+  #   Timeframe.normalize(Date.today)             # => Range for entire day
+  #   Timeframe.normalize(Time.now)               # => Range for entire day
+  #   Timeframe.normalize("last week")            # => Range from chronic/extractor
+  #   Timeframe.normalize(:auto, query: "...")    # => Extract from query text
+  #   Timeframe.normalize(range1..range2)         # => Pass through
+  #   Timeframe.normalize([range1, range2])       # => Array of ranges
+  #
+  class Timeframe
+    # Result structure for :auto mode
+    Result = Struct.new(:timeframe, :query, :extracted, keyword_init: true)
+
+    class << self
+      # Normalize a timeframe input to nil, Range, or Array<Range>
+      #
+      # @param input [nil, Range, Array, Date, DateTime, Time, String, Symbol] Timeframe specification
+      # @param query [String, nil] Query text (required when input is :auto)
+      # @return [nil, Range, Array<Range>] Normalized timeframe
+      # @return [Result] When input is :auto, returns Result with :timeframe, :query, :extracted
+      #
+      def normalize(input, query: nil)
+        case input
+        when nil
+          nil
+
+        when :auto
+          normalize_auto(query)
+
+        when Range
+          validate_range!(input)
+          input
+
+        when Array
+          normalize_array(input)
+
+        when Date
+          normalize_date(input)
+
+        when DateTime
+          normalize_datetime(input)
+
+        when Time
+          normalize_time(input)
+
+        when String
+          normalize_string(input)
+
+        else
+          raise ArgumentError, "Unsupported timeframe type: #{input.class}. " \
+            "Expected nil, Range, Array<Range>, Date, DateTime, Time, String, or :auto"
+        end
+      end
+
+      # Check if a value is a valid timeframe input
+      #
+      # @param input [Object] Value to check
+      # @return [Boolean]
+      #
+      def valid?(input)
+        case input
+        when nil, :auto, Range, Date, DateTime, Time, String
+          true
+        when Array
+          input.all? { |r| r.is_a?(Range) }
+        else
+          false
+        end
+      end
+
+      private
+
+      # Normalize :auto - extract timeframe from query text
+      #
+      # @param query [String] Query text to parse
+      # @return [Result] Result with :timeframe, :query (cleaned), :extracted (original expression)
+      #
+      def normalize_auto(query)
+        raise ArgumentError, "query is required when timeframe is :auto" if query.nil? || query.strip.empty?
+
+        result = HTM::TimeframeExtractor.extract(query)
+
+        Result.new(
+          timeframe: result.timeframe,
+          query: result.query,
+          extracted: result.original_expression
+        )
+      end
+
+      # Normalize an array of ranges
+      #
+      # @param array [Array] Array of Range objects
+      # @return [Array<Range>] Validated array of ranges
+      #
+      def normalize_array(array)
+        raise ArgumentError, "Array timeframe cannot be empty" if array.empty?
+
+        array.map do |item|
+          case item
+          when Range
+            validate_range!(item)
+            item
+          when Date
+            normalize_date(item)
+          when DateTime
+            normalize_datetime(item)
+          when Time
+            normalize_time(item)
+          when String
+            normalize_string(item)
+          else
+            raise ArgumentError, "Array elements must be Range, Date, DateTime, Time, or String. Got: #{item.class}"
+          end
+        end
+      end
+
+      # Normalize a Date to a Range spanning the entire day
+      #
+      # @param date [Date] Date to normalize
+      # @return [Range] Time range for entire day
+      #
+      def normalize_date(date)
+        # Convert Date to Time at beginning of day in local timezone
+        beginning = Time.new(date.year, date.month, date.day, 0, 0, 0)
+        ending = Time.new(date.year, date.month, date.day, 23, 59, 59)
+        beginning..ending
+      end
+
+      # Normalize a DateTime to a Range spanning the entire day
+      #
+      # @param datetime [DateTime] DateTime to normalize
+      # @return [Range] Time range for entire day containing this moment
+      #
+      def normalize_datetime(datetime)
+        # Extract date portion and create full day range
+        normalize_date(datetime.to_date)
+      end
+
+      # Normalize a Time to a Range spanning the entire day
+      #
+      # @param time [Time] Time to normalize
+      # @return [Range] Time range for entire day containing this moment
+      #
+      def normalize_time(time)
+        beginning = Time.new(time.year, time.month, time.day, 0, 0, 0, time.utc_offset)
+        ending = Time.new(time.year, time.month, time.day, 23, 59, 59, time.utc_offset)
+        beginning..ending
+      end
+
+      # Normalize a String using TimeframeExtractor
+      #
+      # @param string [String] Natural language timeframe
+      # @return [Range, nil] Parsed timeframe or nil if unparseable
+      #
+      def normalize_string(string)
+        return nil if string.nil? || string.strip.empty?
+
+        result = HTM::TimeframeExtractor.extract(string)
+
+        # If extraction found a timeframe, return it
+        return result.timeframe if result.timeframe
+
+        # Fall back to treating the whole string as a timeframe expression
+        # (for cases like just "last week" without surrounding text)
+        fallback = HTM::TimeframeExtractor.extract("show me #{string}")
+        fallback.timeframe
+      end
+
+      # Validate that a Range has Time-compatible begin/end
+      #
+      # @param range [Range] Range to validate
+      # @raise [ArgumentError] If range is invalid
+      #
+      def validate_range!(range)
+        unless range.begin.respond_to?(:to_time) && range.end.respond_to?(:to_time)
+          raise ArgumentError, "Range must have Time-compatible begin and end values"
+        end
+      end
+    end
+  end
+end

data/lib/htm/timeframe_extractor.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require 'chronic'
+
+class HTM
+  # Timeframe Extractor - Extracts temporal expressions from queries
+  #
+  # This service parses natural language time expressions from recall queries
+  # and returns both the timeframe and the cleaned query text.
+  #
+  # Supports:
+  # - Standard time expressions via Chronic gem ("yesterday", "last week", etc.)
+  # - "few" keyword mapped to FEW constant (e.g., "few days ago" → "3 days ago")
+  # - "recent/recently" without units defaults to FEW days
+  #
+  # @example Basic usage
+  #   result = TimeframeExtractor.extract("what did we discuss last week about PostgreSQL")
+  #   result[:query]     # => "what did we discuss about PostgreSQL"
+  #   result[:timeframe] # => #<Range: 2025-11-21..2025-11-28>
+  #
+  # @example With "few" keyword
+  #   result = TimeframeExtractor.extract("show me notes from a few days ago")
+  #   result[:timeframe] # => Time object for 3 days ago
+  #
+  # @example With "recently"
+  #   result = TimeframeExtractor.extract("what did we recently discuss")
+  #   result[:timeframe] # => Range from 3 days ago to now
+  #
+  class TimeframeExtractor
+    # The numeric value for "few" and "recently" without units
+    FEW = 3
+
+    # Default unit for "recently" when no time unit is specified
+    DEFAULT_RECENT_UNIT = :days
+
+    # Time unit patterns for matching
+    TIME_UNITS = %w[
+      seconds? minutes? hours? days? weeks? months? years?
+    ].join('|').freeze
+
+    # Word-to-number mapping for written numbers
+    WORD_NUMBERS = {
+      'one' => 1, 'two' => 2, 'three' => 3, 'four' => 4, 'five' => 5,
+      'six' => 6, 'seven' => 7, 'eight' => 8, 'nine' => 9, 'ten' => 10
+    }.freeze
+
+    # Patterns for temporal expressions (order matters - more specific first)
+    # Each pattern should match ORIGINAL text (including "few", "a few")
+    TEMPORAL_PATTERNS = [
+      # "between X and Y" - date ranges
+      /\bbetween\s+(.+?)\s+and\s+(.+?)(?=\s+(?:about|regarding|for|on|with)|$)/i,
+
+      # "from X to Y" - date ranges
+      /\bfrom\s+(.+?)\s+to\s+(.+?)(?=\s+(?:about|regarding|for|on|with)|$)/i,
+
+      # "since X" - from date to now
+      /\bsince\s+(.+?)(?=\s+(?:about|regarding|for|on|with)|$)/i,
+
+      # "before/after X"
+      /\b(before|after)\s+(.+?)(?=\s+(?:about|regarding|for|on|with)|$)/i,
+
+      # "in the last/past X units" (including "few", "a few", "several")
+      /\bin\s+the\s+(?:last|past)\s+(?:\d+|few|a\s+few|several)\s+(?:#{TIME_UNITS})/i,
+
+      # "weekend before last" / "the weekend before last"
+      /\b(?:the\s+)?weekend\s+before\s+last\b/i,
+
+      # "N weekends ago" (numeric or written)
+      /\b(?:\d+|one|two|three|four|five|six|seven|eight|nine|ten|few|a\s+few|several)\s+weekends?\s+ago\b/i,
+
+      # "a few X ago" or "few X ago"
+      /\b(?:a\s+)?few\s+(?:#{TIME_UNITS})\s+ago\b/i,
+
+      # "X units ago"
+      /\b\d+\s+(?:#{TIME_UNITS})\s+ago\b/i,
+
+      # "last/this/next weekend"
+      /\b(?:last|this|next)\s+weekend\b/i,
+
+      # "last/this/next X" (week, month, year, monday, etc.)
+      /\b(?:last|this|next)\s+(?:week|month|year|monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/i,
+
+      # "recently" or "recent" as standalone or with context
+      /\b(?:recently|recent)\b/i,
+
+      # Standard time words
+      /\b(?:yesterday|today|tonight|this\s+morning|this\s+afternoon|this\s+evening|last\s+night)\b/i,
+    ].freeze
+
+    # Result structure for extracted timeframe
+    Result = Struct.new(:query, :timeframe, :original_expression, keyword_init: true)
+
+    class << self
+      # Extract timeframe from a query string
+      #
+      # @param query [String] The query to parse
+      # @return [Result] Struct with :query (cleaned), :timeframe, :original_expression
+      #
+      def extract(query)
+        return Result.new(query: query, timeframe: nil, original_expression: nil) if query.nil? || query.strip.empty?
+
+        # Try each pattern against the ORIGINAL query
+        TEMPORAL_PATTERNS.each do |pattern|
+          match = query.match(pattern)
+          next unless match
+
+          original_expression = match[0].strip
+          timeframe = parse_expression(original_expression)
+          next unless timeframe
+
+          # Remove the matched expression from query
+          cleaned_query = clean_query(query, original_expression)
+
+          return Result.new(
+            query: cleaned_query,
+            timeframe: timeframe,
+            original_expression: original_expression
+          )
+        end
+
+        # No temporal expression found
+        Result.new(query: query, timeframe: nil, original_expression: nil)
+      end
+
+      # Check if query contains a temporal expression
+      #
+      # @param query [String] The query to check
+      # @return [Boolean]
+      #
+      def temporal?(query)
+        return false if query.nil? || query.strip.empty?
+
+        TEMPORAL_PATTERNS.any? { |pattern| query.match?(pattern) }
+      end
+
+      private
+
+      # Normalize "few" and "a few" to the FEW constant value
+      #
+      # @param text [String] Text to normalize
+      # @return [String] Normalized text
+      #
+      def normalize_few_keywords(text)
+        text
+          .gsub(/\ba\s+few\b/i, FEW.to_s)
+          .gsub(/\bfew\b/i, FEW.to_s)
+          .gsub(/\bseveral\b/i, FEW.to_s)
+      end
+
+      # Parse a temporal expression into a timeframe
+      #
+      # @param expression [String] The temporal expression
+      # @return [Time, Range, nil] Parsed timeframe
+      #
+      def parse_expression(expression)
+        # Handle "recently/recent" specially - default to FEW days
+        if expression.match?(/\b(?:recently|recent)\b/i)
+          return parse_recent
+        end
+
+        # Handle "weekend before last" - 2 weekends ago
+        if expression.match?(/\bweekend\s+before\s+last\b/i)
+          return parse_weekends_ago(2)
+        end
+
+        # Handle "N weekends ago" (numeric or written)
+        if match = expression.match(/\b(\d+|one|two|three|four|five|six|seven|eight|nine|ten|few|a\s+few|several)\s+weekends?\s+ago\b/i)
+          count = parse_number(match[1])
+          return parse_weekends_ago(count)
+        end
+
+        # Normalize "few" to numeric value for Chronic
+        normalized = normalize_few_keywords(expression)
+
+        # Handle "in the last/past X units" - create range from X ago to now
+        if match = normalized.match(/(?:in\s+the\s+)?(?:last|past)\s+(\d+)\s+(#{TIME_UNITS})/i)
+          return parse_last_x(match[1].to_i, match[2])
+        end
+
+        # Strip "in the" prefix for Chronic
+        chronic_expr = normalized.gsub(/\bin\s+the\s+/i, '')
+
+        # Get week_start from HTM configuration (default: :sunday)
+        week_start = :sunday
+        if defined?(HTM) && HTM.respond_to?(:configuration)
+          week_start = HTM.configuration.week_start
+        end
+
+        # Try to get a span/range first
+        result = Chronic.parse(chronic_expr, guess: false, week_start: week_start)
+
+        # Convert Chronic::Span to Range if needed
+        if result.respond_to?(:begin) && result.respond_to?(:end)
+          return result.begin..result.end
+        end
+
+        # Fall back to point in time
+        Chronic.parse(chronic_expr, week_start: week_start)
+      end
+
+      # Parse a number from string (numeric or written word)
+      #
+      # @param str [String] Number as digit or word
+      # @return [Integer] Parsed number
+      #
+      def parse_number(str)
+        normalized = str.downcase.strip
+        return FEW if normalized == 'few' || normalized == 'a few' || normalized == 'several'
+        return WORD_NUMBERS[normalized] if WORD_NUMBERS.key?(normalized)
+        normalized.to_i
+      end
+
+      # Parse "N weekends ago" to a Saturday-Sunday range
+      #
+      # @param count [Integer] Number of weekends ago (1 = last weekend)
+      # @return [Range] Time range for that weekend (Saturday 00:00 to Monday 00:00)
+      #
+      def parse_weekends_ago(count)
+        now = Time.now
+
+        # Find last Saturday (most recent Saturday before or equal to today)
+        days_since_saturday = (now.wday - 6) % 7
+        days_since_saturday = 7 if days_since_saturday == 0 && now.wday != 6  # If today is Sunday, last Saturday was yesterday
+
+        last_saturday = Time.new(now.year, now.month, now.day, 0, 0, 0) - (days_since_saturday * 24 * 60 * 60)
+
+        # Go back (count - 1) more weeks to get to the target weekend
+        # count=1 means "last weekend" = the most recent past weekend
+        # count=2 means "weekend before last" = 2 weekends ago
+        target_saturday = last_saturday - ((count - 1) * 7 * 24 * 60 * 60)
+
+        # Weekend spans Saturday 00:00 to Monday 00:00
+        weekend_start = target_saturday
+        weekend_end = target_saturday + (2 * 24 * 60 * 60)  # Monday 00:00
+
+        weekend_start..weekend_end
+      end
+
+      # Parse "last X units" or "past X units" to a proper range
+      #
+      # @param count [Integer] Number of units
+      # @param unit [String] Time unit (days, hours, etc.)
+      # @return [Range] Time range from count units ago to now
+      #
+      def parse_last_x(count, unit)
+        now = Time.now
+        unit_normalized = unit.downcase.sub(/s$/, '')  # Remove trailing 's'
+
+        seconds = case unit_normalized
+        when 'second' then count
+        when 'minute' then count * 60
+        when 'hour' then count * 60 * 60
+        when 'day' then count * 24 * 60 * 60
+        when 'week' then count * 7 * 24 * 60 * 60
+        when 'month' then count * 30 * 24 * 60 * 60
+        when 'year' then count * 365 * 24 * 60 * 60
+        else count * 24 * 60 * 60  # Default to days
+        end
+
+        (now - seconds)..now
+      end
+
+      # Parse "recently" to a range from FEW days ago to now
+      #
+      # @return [Range] Time range
+      #
+      def parse_recent
+        now = Time.now
+        case DEFAULT_RECENT_UNIT
+        when :seconds
+          (now - FEW)..now
+        when :minutes
+          (now - (FEW * 60))..now
+        when :hours
+          (now - (FEW * 60 * 60))..now
+        when :days
+          (now - (FEW * 24 * 60 * 60))..now
+        when :weeks
+          (now - (FEW * 7 * 24 * 60 * 60))..now
+        when :months
+          (now - (FEW * 30 * 24 * 60 * 60))..now
+        when :years
+          (now - (FEW * 365 * 24 * 60 * 60))..now
+        else
+          (now - (FEW * 24 * 60 * 60))..now
+        end
+      end
+
+      # Clean the query by removing the temporal expression
+      #
+      # @param query [String] Original query
+      # @param expression [String] Expression to remove
+      # @return [String] Cleaned query
+      #
+      def clean_query(query, expression)
+        # Escape special regex characters in the expression
+        escaped = Regexp.escape(expression)
+
+        query
+          .sub(/#{escaped}/i, '')      # Remove the expression
+          .gsub(/\s{2,}/, ' ')          # Collapse multiple spaces
+          .gsub(/\s+([,.])/,  '\1')     # Fix space before punctuation
+          .strip
+      end
+    end
+  end
+end

data/lib/htm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class HTM
-  VERSION = "0.0.2"
+  VERSION = "0.0.10"
 end