fsrs_ruby 1.0.0

data/lib/fsrs_ruby/helpers.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module FsrsRuby
+  module Helpers
+    # Round to 8 decimal places for TypeScript compatibility
+    def self.round8(value)
+      return value if value.nil?
+      (value * 100_000_000).round / 100_000_000.0
+    end
+
+    # Clamp value between min and max
+    def self.clamp(value, min, max)
+      [[value, min].max, max].min
+    end
+
+    # Add time offset to a date
+    # @param now [Time] Current time
+    # @param t [Numeric] Time offset value
+    # @param is_day [Boolean] If true, t is in days; if false, t is in minutes
+    # @return [Time] New time with offset applied
+    def self.date_scheduler(now, t, is_day = false)
+      if is_day
+        now + (t * 24 * 60 * 60)  # Days to seconds
+      else
+        now + (t * 60)  # Minutes to seconds
+      end
+    end
+
+    # Calculate difference between two dates
+    # @param now [Time] Current time
+    # @param pre [Time] Previous time
+    # @param unit [Symbol] :days or :minutes
+    # @return [Integer] Difference in specified units
+    def self.date_diff(now, pre, unit)
+      diff_seconds = now - pre
+
+      case unit
+      when :days
+        (diff_seconds / (24 * 60 * 60)).floor
+      when :minutes
+        (diff_seconds / 60).floor
+      else
+        raise ArgumentError, "Invalid unit: #{unit}. Use :days or :minutes"
+      end
+    end
+
+    # Calculate fuzz range for interval randomization
+    # @param interval [Numeric] Base interval
+    # @param elapsed_days [Integer] Days since last review
+    # @param maximum_interval [Integer] Maximum allowed interval
+    # @return [Hash] { min_ivl:, max_ivl: }
+    def self.get_fuzz_range(interval, elapsed_days, maximum_interval)
+      delta = 1.0
+
+      # Apply fuzzing factors based on interval ranges
+      if interval >= 2.5
+        delta += (interval - 2.5) * 0.15 if interval < 7.0
+        delta += (7.0 - 2.5) * 0.15 if interval >= 7.0
+        delta += (interval - 7.0) * 0.10 if interval >= 7.0 && interval < 20.0
+        delta += (20.0 - 7.0) * 0.10 if interval >= 20.0
+        delta += (interval - 20.0) * 0.05 if interval >= 20.0
+      end
+
+      # Clamp interval to maximum
+      interval = [interval, maximum_interval].min
+
+      min_ivl = [2, (interval - delta).round].max
+      max_ivl = [(interval + delta).round, maximum_interval].min
+
+      # Ensure min_ivl is greater than elapsed_days if interval exceeds it
+      min_ivl = [min_ivl, elapsed_days + 1].max if interval > elapsed_days
+
+      # Ensure min <= max
+      min_ivl = max_ivl if min_ivl > max_ivl
+
+      { min_ivl: min_ivl, max_ivl: max_ivl }
+    end
+
+    # Format date as YYYY-MM-DD HH:MM:SS
+    # @param time [Time] Time object
+    # @return [String] Formatted date string
+    def self.format_date(time)
+      time.strftime('%Y-%m-%d %H:%M:%S')
+    end
+
+    # Calculate day difference ignoring time
+    # @param last [Time] Last review time
+    # @param cur [Time] Current time
+    # @return [Integer] Day difference
+    def self.date_diff_in_days(last, cur)
+      (cur.to_date - last.to_date).to_i
+    end
+  end
+end

data/lib/fsrs_ruby/models.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module FsrsRuby
+  # State enum - Card states
+  module State
+    NEW = 0
+    LEARNING = 1
+    REVIEW = 2
+    RELEARNING = 3
+
+    def self.valid?(value)
+      [NEW, LEARNING, REVIEW, RELEARNING].include?(value)
+    end
+
+    def self.from_string(str)
+      const_get(str.upcase.to_sym)
+    rescue NameError
+      raise ArgumentError, "Invalid state: #{str}"
+    end
+
+    def self.to_string(value)
+      case value
+      when NEW then 'New'
+      when LEARNING then 'Learning'
+      when REVIEW then 'Review'
+      when RELEARNING then 'Relearning'
+      else raise ArgumentError, "Invalid state value: #{value}"
+      end
+    end
+  end
+
+  # Rating enum - Review ratings
+  module Rating
+    MANUAL = 0
+    AGAIN = 1
+    HARD = 2
+    GOOD = 3
+    EASY = 4
+
+    def self.valid?(value)
+      (MANUAL..EASY).cover?(value)
+    end
+
+    def self.from_string(str)
+      const_get(str.upcase.to_sym)
+    rescue NameError
+      raise ArgumentError, "Invalid rating: #{str}"
+    end
+
+    def self.to_string(value)
+      case value
+      when MANUAL then 'Manual'
+      when AGAIN then 'Again'
+      when HARD then 'Hard'
+      when GOOD then 'Good'
+      when EASY then 'Easy'
+      else raise ArgumentError, "Invalid rating value: #{value}"
+      end
+    end
+  end
+
+  # Card class representing a flashcard
+  class Card
+    attr_accessor :due, :stability, :difficulty, :elapsed_days, :scheduled_days,
+                  :learning_steps, :reps, :lapses, :state, :last_review
+
+    def initialize(
+      due:,
+      stability: 0.0,
+      difficulty: 0.0,
+      elapsed_days: 0,
+      scheduled_days: 0,
+      learning_steps: 0,
+      reps: 0,
+      lapses: 0,
+      state: State::NEW,
+      last_review: nil
+    )
+      @due = due
+      @stability = stability.to_f
+      @difficulty = difficulty.to_f
+      @elapsed_days = elapsed_days
+      @scheduled_days = scheduled_days
+      @learning_steps = learning_steps
+      @reps = reps
+      @lapses = lapses
+      @state = state
+      @last_review = last_review
+    end
+
+    def clone
+      Card.new(
+        due: @due.dup,
+        stability: @stability,
+        difficulty: @difficulty,
+        elapsed_days: @elapsed_days,
+        scheduled_days: @scheduled_days,
+        learning_steps: @learning_steps,
+        reps: @reps,
+        lapses: @lapses,
+        state: @state,
+        last_review: @last_review&.dup
+      )
+    end
+
+    def to_h
+      {
+        due: @due,
+        stability: @stability,
+        difficulty: @difficulty,
+        elapsed_days: @elapsed_days,
+        scheduled_days: @scheduled_days,
+        learning_steps: @learning_steps,
+        reps: @reps,
+        lapses: @lapses,
+        state: @state,
+        last_review: @last_review
+      }
+    end
+  end
+
+  # ReviewLog class for tracking review history
+  class ReviewLog
+    attr_accessor :rating, :state, :due, :stability, :difficulty,
+                  :elapsed_days, :last_elapsed_days, :scheduled_days,
+                  :learning_steps, :review
+
+    def initialize(
+      rating:,
+      state:,
+      due:,
+      stability:,
+      difficulty:,
+      elapsed_days:,
+      last_elapsed_days:,
+      scheduled_days:,
+      learning_steps:,
+      review:
+    )
+      @rating = rating
+      @state = state
+      @due = due
+      @stability = stability.to_f
+      @difficulty = difficulty.to_f
+      @elapsed_days = elapsed_days
+      @last_elapsed_days = last_elapsed_days
+      @scheduled_days = scheduled_days
+      @learning_steps = learning_steps
+      @review = review
+    end
+
+    def to_h
+      {
+        rating: @rating,
+        state: @state,
+        due: @due,
+        stability: @stability,
+        difficulty: @difficulty,
+        elapsed_days: @elapsed_days,
+        last_elapsed_days: @last_elapsed_days,
+        scheduled_days: @scheduled_days,
+        learning_steps: @learning_steps,
+        review: @review
+      }
+    end
+  end
+
+  # RecordLogItem - Container for card and log pair
+  RecordLogItem = Struct.new(:card, :log, keyword_init: true)
+
+  # Parameters class for FSRS parameters
+  class Parameters
+    attr_accessor :request_retention, :maximum_interval, :w, :enable_fuzz,
+                  :enable_short_term, :learning_steps, :relearning_steps
+
+    def initialize(
+      request_retention: Constants::DEFAULT_REQUEST_RETENTION,
+      maximum_interval: Constants::DEFAULT_MAXIMUM_INTERVAL,
+      w: Constants::DEFAULT_WEIGHTS.dup,
+      enable_fuzz: Constants::DEFAULT_ENABLE_FUZZ,
+      enable_short_term: Constants::DEFAULT_ENABLE_SHORT_TERM,
+      learning_steps: Constants::DEFAULT_LEARNING_STEPS.dup,
+      relearning_steps: Constants::DEFAULT_RELEARNING_STEPS.dup
+    )
+      @request_retention = request_retention
+      @maximum_interval = maximum_interval
+      @w = w
+      @enable_fuzz = enable_fuzz
+      @enable_short_term = enable_short_term
+      @learning_steps = learning_steps
+      @relearning_steps = relearning_steps
+    end
+
+    def to_h
+      {
+        request_retention: @request_retention,
+        maximum_interval: @maximum_interval,
+        w: @w,
+        enable_fuzz: @enable_fuzz,
+        enable_short_term: @enable_short_term,
+        learning_steps: @learning_steps,
+        relearning_steps: @relearning_steps
+      }
+    end
+  end
+end

data/lib/fsrs_ruby/parameters.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module FsrsRuby
+  module ParameterUtils
+    # Clip parameters to valid ranges
+    # @param parameters [Array<Numeric>] Parameter array
+    # @param num_relearning_steps [Integer] Number of relearning steps
+    # @param enable_short_term [Boolean] Whether short-term learning is enabled
+    # @return [Array<Float>] Clipped parameters
+    def self.clip_parameters(parameters, num_relearning_steps, enable_short_term = true)
+      w17_w18_ceiling = Constants::W17_W18_CEILING
+
+      if [num_relearning_steps, 0].max > 1
+        # Calculate ceiling: w17 * w18 <= -[ln(w11) + ln(2^w13 - 1) + w14*0.3] / num_relearning_steps
+        value = -(
+          Math.log(parameters[11]) +
+          Math.log(2.0**parameters[13] - 1.0) +
+          parameters[14] * 0.3
+        ) / num_relearning_steps
+
+        w17_w18_ceiling = Helpers.clamp(Helpers.round8(value), 0.01, 2.0)
+      end
+
+      clamp_ranges = Constants.clamp_parameters(w17_w18_ceiling, enable_short_term)
+      clamp_ranges = clamp_ranges.slice(0, parameters.length)
+
+      clamp_ranges.each_with_index.map do |(min, max), index|
+        Helpers.clamp(parameters[index] || 0, min, max)
+      end
+    end
+
+    # Check if parameters are valid
+    # @param parameters [Array<Numeric>] Parameter array
+    # @return [Array<Numeric>] Same array if valid
+    # @raise [ArgumentError] If parameters are invalid
+    def self.check_parameters(parameters)
+      invalid = parameters.find { |param| !param.is_a?(Numeric) || !param.finite? }
+      if invalid
+        raise ArgumentError, "Non-finite or NaN value in parameters: #{parameters}"
+      elsif ![17, 19, 21].include?(parameters.length)
+        raise ArgumentError,
+              "Invalid parameter length: #{parameters.length}. Must be 17, 19 or 21 for FSRSv4, 5 and 6 respectively."
+      end
+
+      parameters
+    end
+
+    # Migrate parameters from v4/v5 to v6 format
+    # @param parameters [Array<Numeric>, nil] Parameter array
+    # @param num_relearning_steps [Integer] Number of relearning steps
+    # @param enable_short_term [Boolean] Whether short-term learning is enabled
+    # @return [Array<Float>] Migrated parameters (always 21 elements)
+    def self.migrate_parameters(parameters = nil, num_relearning_steps = 0, enable_short_term = true)
+      return Constants::DEFAULT_WEIGHTS.dup if parameters.nil?
+
+      case parameters.length
+      when 21
+        # v6: Just clip
+        clip_parameters(parameters.dup, num_relearning_steps, enable_short_term)
+      when 19
+        # v5: Clip and append [0.0, FSRS5_DEFAULT_DECAY]
+        warn '[FSRS-6] Auto fill w from 19 to 21 length'
+        clipped = clip_parameters(parameters.dup, num_relearning_steps, enable_short_term)
+        clipped + [0.0, Constants::FSRS5_DEFAULT_DECAY]
+      when 17
+        # v4: Clip, transform w[4], w[5], w[6], then append [0.0, 0.0, 0.0, FSRS5_DEFAULT_DECAY]
+        w = clip_parameters(parameters.dup, num_relearning_steps, enable_short_term)
+
+        # Transform parameters for v6
+        w[4] = Helpers.round8(w[5] * 2.0 + w[4])
+        w[5] = Helpers.round8(Math.log(w[5] * 3.0 + 1.0) / 3.0)
+        w[6] = Helpers.round8(w[6] + 0.5)
+
+        warn '[FSRS-6] Auto fill w from 17 to 21 length'
+        w + [0.0, 0.0, 0.0, Constants::FSRS5_DEFAULT_DECAY]
+      else
+        # Invalid length, use defaults
+        warn '[FSRS] Invalid parameters length, using default parameters'
+        Constants::DEFAULT_WEIGHTS.dup
+      end
+    end
+
+    # Generate FSRS parameters from partial input
+    # @param props [Hash] Partial parameters
+    # @return [Parameters] Complete parameters object
+    def self.generate_parameters(props = {})
+      learning_steps = props[:learning_steps] || Constants::DEFAULT_LEARNING_STEPS.dup
+      relearning_steps = props[:relearning_steps] || Constants::DEFAULT_RELEARNING_STEPS.dup
+      enable_short_term = props.key?(:enable_short_term) ? props[:enable_short_term] : Constants::DEFAULT_ENABLE_SHORT_TERM
+
+      w = migrate_parameters(
+        props[:w],
+        relearning_steps.length,
+        enable_short_term
+      )
+
+      Parameters.new(
+        request_retention: props[:request_retention] || Constants::DEFAULT_REQUEST_RETENTION,
+        maximum_interval: props[:maximum_interval] || Constants::DEFAULT_MAXIMUM_INTERVAL,
+        w: w,
+        enable_fuzz: props.key?(:enable_fuzz) ? props[:enable_fuzz] : Constants::DEFAULT_ENABLE_FUZZ,
+        enable_short_term: enable_short_term,
+        learning_steps: learning_steps,
+        relearning_steps: relearning_steps
+      )
+    end
+
+    # Create an empty card
+    # @param now [Time, nil] Current time (defaults to Time.now)
+    # @return [Card] New empty card
+    def self.create_empty_card(now = nil)
+      now ||= Time.now
+
+      Card.new(
+        due: now,
+        stability: 0.0,
+        difficulty: 0.0,
+        elapsed_days: 0,
+        scheduled_days: 0,
+        learning_steps: 0,
+        reps: 0,
+        lapses: 0,
+        state: State::NEW,
+        last_review: nil
+      )
+    end
+  end
+end

data/lib/fsrs_ruby/schedulers/base_scheduler.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module FsrsRuby
+  module Schedulers
+    # Base scheduler implementing template method pattern
+    class BaseScheduler
+      attr_reader :last, :current, :review_time, :algorithm, :strategies, :elapsed_days
+
+      def initialize(card, now, algorithm, strategies = {})
+        @last = card.is_a?(Card) ? card : TypeConverter.card(card)
+        @current = @last.clone
+        @review_time = now.is_a?(Time) ? now : TypeConverter.time(now)
+        @algorithm = algorithm
+        @strategies = strategies
+        @next_cache = {}
+
+        init
+      end
+
+      # Preview all possible outcomes
+      # @return [Hash] { Rating::AGAIN =>, Rating::HARD =>, Rating::GOOD =>, Rating::EASY => }
+      def preview
+        {
+          Rating::AGAIN => review(Rating::AGAIN),
+          Rating::HARD => review(Rating::HARD),
+          Rating::GOOD => review(Rating::GOOD),
+          Rating::EASY => review(Rating::EASY)
+        }
+      end
+
+      # Apply specific rating
+      # @param grade [Integer] Rating (1-4)
+      # @return [RecordLogItem] { card:, log: }
+      def review(grade)
+        raise ArgumentError, "Invalid grade: #{grade}" unless (Rating::AGAIN..Rating::EASY).cover?(grade)
+
+        return @next_cache[grade] if @next_cache.key?(grade)
+
+        result = case @current.state
+                 when State::NEW
+                   new_state(grade)
+                 when State::LEARNING, State::RELEARNING
+                   learning_state(grade)
+                 when State::REVIEW
+                   review_state(grade)
+                 else
+                   raise "Unknown state: #{@current.state}"
+                 end
+
+        @next_cache[grade] = result
+        result
+      end
+
+      protected
+
+      def init
+        @elapsed_days = if @last.last_review
+                          Helpers.date_diff(@review_time, @last.last_review, :days)
+                        else
+                          0
+                        end
+
+        @current.last_review = @review_time
+        @current.reps += 1
+
+        # Initialize seed strategy if provided
+        @seed_strategy = @strategies[:seed]
+      end
+
+      # Build review log
+      # @param rating [Integer] Rating given
+      # @return [ReviewLog]
+      def build_log(rating)
+        ReviewLog.new(
+          rating: rating,
+          state: @last.state,
+          due: @last.due,
+          stability: @last.stability,
+          difficulty: @last.difficulty,
+          elapsed_days: @elapsed_days,
+          last_elapsed_days: @last.scheduled_days,
+          scheduled_days: @current.scheduled_days,
+          learning_steps: @current.learning_steps,
+          review: @review_time
+        )
+      end
+
+      # Calculate next difficulty and stability
+      # @param interval [Integer] Elapsed interval
+      # @return [Hash] { difficulty:, stability: }
+      def next_ds(interval = 0)
+        @algorithm.next_state(
+          { difficulty: @last.difficulty, stability: @last.stability },
+          interval,
+          @current.state == State::NEW ? Rating::GOOD : @current.state
+        )
+      end
+
+      # Template methods (to be overridden by subclasses)
+      def new_state(grade)
+        raise NotImplementedError, "#{self.class} must implement #new_state"
+      end
+
+      def learning_state(grade)
+        raise NotImplementedError, "#{self.class} must implement #learning_state"
+      end
+
+      def review_state(grade)
+        raise NotImplementedError, "#{self.class} must implement #review_state"
+      end
+    end
+  end
+end