active_recall 2.1.0 → 2.3.0

data/gemfiles/rails_7_1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    active_recall (2.1.0)
+    active_recall (2.3.0)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
 
@@ -119,6 +119,7 @@ GEM
       net-smtp
     marcel (1.0.2)
     mini_mime (1.1.5)
+    mini_portile2 (2.8.8)
     minitest (5.21.2)
     mutex_m (0.2.0)
     net-imap (0.4.9.1)
@@ -131,7 +132,14 @@ GEM
     net-smtp (0.4.0.1)
       net-protocol
     nio4r (2.7.0)
-    nokogiri (1.16.0-arm64-darwin)
+    nokogiri (1.18.7)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.18.7-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.7-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.7-x86_64-linux-gnu)
       racc (~> 1.4)
     parallel (1.24.0)
     parser (3.3.1.0)
@@ -216,7 +224,8 @@ GEM
       rubocop-ast (>= 1.30.0, < 2.0)
     ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
-    sqlite3 (1.7.3-arm64-darwin)
+    sqlite3 (1.7.3)
+      mini_portile2 (~> 2.8.0)
     standard (1.35.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
@@ -242,11 +251,15 @@ GEM
     zeitwerk (2.6.12)
 
 PLATFORMS
-  arm64-darwin-23
+  arm64-darwin
+  ruby
+  x86_64-darwin
+  x86_64-linux
 
 DEPENDENCIES
   active_recall!
   appraisal
+  nokogiri (>= 1.16.2)
   rails (~> 7.1)
   rake (>= 12.0)
   rdoc

data/gemfiles/rails_8_0.gemfile

@@ -2,6 +2,7 @@
 
 source "https://rubygems.org"
 
+gem "nokogiri", ">= 1.16.2"
 gem "rails", "~> 8.0"
 gem "sqlite3", ">= 2.1"
 

data/gemfiles/rails_8_0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    active_recall (2.1.0)
+    active_recall (2.3.0)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
 
@@ -117,7 +117,7 @@ GEM
       net-smtp
     marcel (1.0.4)
     mini_mime (1.1.5)
-    mini_portile2 (2.8.5)
+    mini_portile2 (2.8.9)
     minitest (5.25.4)
     net-imap (0.5.4)
       date
@@ -129,8 +129,15 @@ GEM
     net-smtp (0.5.0)
       net-protocol
     nio4r (2.7.4)
+    nokogiri (1.18.0)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
     nokogiri (1.18.0-arm64-darwin)
       racc (~> 1.4)
+    nokogiri (1.18.0-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.0-x86_64-linux-gnu)
+      racc (~> 1.4)
     parallel (1.26.3)
     parser (3.3.6.0)
       ast (~> 2.4.1)
@@ -214,6 +221,9 @@ GEM
     securerandom (0.4.1)
     sqlite3 (2.5.0)
       mini_portile2 (~> 2.8.0)
+    sqlite3 (2.5.0-arm64-darwin)
+    sqlite3 (2.5.0-x86_64-darwin)
+    sqlite3 (2.5.0-x86_64-linux-gnu)
     standard (1.43.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
@@ -242,11 +252,15 @@ GEM
     zeitwerk (2.7.1)
 
 PLATFORMS
-  arm64-darwin-23
+  arm64-darwin
+  ruby
+  x86_64-darwin
+  x86_64-linux
 
 DEPENDENCIES
   active_recall!
   appraisal
+  nokogiri (>= 1.16.2)
   rails (~> 8.0)
   rake (>= 12.0)
   rdoc

data/lib/active_recall/algorithms/fibonacci_sequence.rb

@@ -63,11 +63,10 @@ module ActiveRecall
     SEQUENCE = [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181, 6765].freeze
 
     def fibonacci_number_at(index)
-      if (0...SEQUENCE.length).cover?(index)
-        SEQUENCE[index]
-      else
-        fibonacci_number_at(index - 1) + fibonacci_number_at(index - 2)
-      end
+      return SEQUENCE[index] if (0...SEQUENCE.length).cover?(index)
+
+      @fibonacci_cache ||= {}
+      @fibonacci_cache[index] ||= fibonacci_number_at(index - 1) + fibonacci_number_at(index - 2)
     end
 
     def next_review

data/lib/active_recall/algorithms/fsrs/internal.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+# Vendored from rb-fsrs 0.9.0 (https://github.com/open-spaced-repetition/rb-fsrs).
+# MIT License, Copyright (c) clayton. See VENDORED_LICENSES.md for the full notice.
+#
+# Pulled into ActiveRecall::FSRS::Internal because the published rb-fsrs gem
+# pins activesupport to ~> 7.0, which excludes Rails 8 — incompatible with
+# this gem's Rails 8 support. Re-evaluate when an upstream release widens
+# the constraint (master already does).
+#
+# Local divergence from upstream:
+#   - schedule_new_state uses 1.minute / 5.minutes / 10.minutes instead of
+#     bare integers (which DateTime treats as days). Tracks upstream PR
+#     https://github.com/open-spaced-repetition/rb-fsrs/pull/9; remove this
+#     patch once a release with that fix is available.
+
+require "date"
+
+module ActiveRecall
+  class FSRS
+    module Internal
+      class InvalidDateError < StandardError
+        def initialize(msg = "Date must be UTC and timezone-aware")
+          super
+        end
+      end
+
+      class SchedulingInfo
+        attr_accessor :card, :review_log
+
+        def initialize(card, review_log)
+          @card = card
+          @review_log = review_log
+        end
+      end
+
+      class ReviewLog
+        attr_accessor :rating, :scheduled_days, :elapsed_days, :review, :state
+
+        def initialize(rating, scheduled_days, elapsed_days, review, state)
+          @rating = rating
+          @scheduled_days = scheduled_days
+          @elapsed_days = elapsed_days
+          @review = review
+          @state = state
+        end
+      end
+
+      class Rating
+        AGAIN = 1
+        HARD = 2
+        GOOD = 3
+        EASY = 4
+      end
+
+      class State
+        NEW = 0
+        LEARNING = 1
+        REVIEW = 2
+        RELEARNING = 3
+      end
+
+      class Card
+        attr_accessor :due, :stability, :difficulty, :elapsed_days,
+          :scheduled_days, :reps, :lapses, :state, :last_review
+
+        def initialize
+          @due = DateTime.new
+          @stability = 0.0
+          @difficulty = 0.0
+          @elapsed_days = 0
+          @scheduled_days = 0
+          @reps = 0
+          @lapses = 0
+          @state = State::NEW
+        end
+
+        def get_retrievability(now)
+          decay = -0.5
+          factor = (0.9**(1 / decay)) - 1
+
+          return nil unless @state == State::REVIEW
+
+          elapsed_days = [0, (now - @last_review).to_i].max
+          (1 + (factor * elapsed_days / @stability))**decay
+        end
+
+        def deep_clone
+          Marshal.load(Marshal.dump(self))
+        end
+      end
+
+      class CardScheduler
+        attr_accessor :again, :hard, :good, :easy
+
+        def initialize(card)
+          @again = card.clone
+          @hard = card.clone
+          @good = card.clone
+          @easy = card.clone
+        end
+
+        def update_state(state)
+          case state
+          when State::NEW
+            update_new_state
+          when State::LEARNING, State::RELEARNING
+            update_learning_relearning_state(state)
+          when State::REVIEW
+            update_review_state
+          end
+        end
+
+        def schedule(now, hard_interval, good_interval, easy_interval)
+          update_schedule_days(hard_interval, good_interval, easy_interval)
+          update_due_dates(now, hard_interval, good_interval, easy_interval)
+        end
+
+        def record_log(card, now)
+          {
+            Rating::AGAIN => record_again_log(card, now),
+            Rating::HARD => record_hard_log(card, now),
+            Rating::GOOD => record_good_log(card, now),
+            Rating::EASY => record_easy_log(card, now)
+          }
+        end
+
+        private
+
+        def update_due_dates(now, hard_interval, good_interval, easy_interval)
+          @again.due = now + 5.minutes
+          @hard.due = hard_interval.positive? ? now + hard_interval.days : now + 10.minutes
+          @good.due = now + good_interval.days
+          @easy.due = now + easy_interval.days
+        end
+
+        def update_schedule_days(hard_interval, good_interval, easy_interval)
+          @again.scheduled_days = 0
+          @hard.scheduled_days = hard_interval
+          @good.scheduled_days = good_interval
+          @easy.scheduled_days = easy_interval
+        end
+
+        def update_new_state
+          @again.state = State::LEARNING
+          @hard.state = State::LEARNING
+          @good.state = State::LEARNING
+          @easy.state = State::REVIEW
+        end
+
+        def update_learning_relearning_state(state)
+          @again.state = state
+          @hard.state = state
+          @good.state = State::REVIEW
+          @easy.state = State::REVIEW
+        end
+
+        def update_review_state
+          @again.state = State::RELEARNING
+          @hard.state = State::REVIEW
+          @good.state = State::REVIEW
+          @easy.state = State::REVIEW
+          @again.lapses += 1
+        end
+
+        def record_again_log(card, now)
+          SchedulingInfo.new(
+            @again,
+            ReviewLog.new(Rating::AGAIN, @again.scheduled_days, card.elapsed_days, now, card.state)
+          )
+        end
+
+        def record_hard_log(card, now)
+          SchedulingInfo.new(
+            @hard,
+            ReviewLog.new(Rating::HARD, @hard.scheduled_days, card.elapsed_days, now, card.state)
+          )
+        end
+
+        def record_good_log(card, now)
+          SchedulingInfo.new(
+            @good,
+            ReviewLog.new(Rating::GOOD, @good.scheduled_days, card.elapsed_days, now, card.state)
+          )
+        end
+
+        def record_easy_log(card, now)
+          SchedulingInfo.new(
+            @easy,
+            ReviewLog.new(Rating::EASY, @easy.scheduled_days, card.elapsed_days, now, card.state)
+          )
+        end
+      end
+
+      class Parameters
+        attr_accessor :request_retention, :maximum_interval, :w
+
+        def initialize
+          @request_retention = 0.9
+          @maximum_interval = 36_500
+          @w = [
+            0.4, 0.6, 2.4, 5.8, 4.93, 0.94, 0.86, 0.01, 1.49, 0.14,
+            0.94, 2.18, 0.05, 0.34, 1.26, 0.29, 2.61
+          ]
+        end
+      end
+
+      class Scheduler
+        attr_accessor :p, :decay, :factor
+
+        def initialize
+          @p = Parameters.new
+          @decay = -0.5
+          @factor = (0.9**(1 / @decay)) - 1
+        end
+
+        def repeat(card, now)
+          raise InvalidDateError unless now.utc?
+
+          card = card.clone
+          card.elapsed_days = if card.state == State::NEW
+            0
+          else
+            (now - card.last_review).to_i
+          end
+          card.last_review = now
+          card.reps += 1
+          card_scheduler = CardScheduler.new(card)
+          card_scheduler.update_state(card.state)
+
+          case card.state
+          when State::NEW
+            schedule_new_state(card_scheduler, now)
+          when State::LEARNING, State::RELEARNING
+            schedule_learning_relearning_state(card_scheduler, now)
+          when State::REVIEW
+            schedule_review_state(card_scheduler, card, now)
+          end
+          card_scheduler.record_log(card, now)
+        end
+
+        def schedule_new_state(s, now)
+          init_ds(s)
+          s.again.due = now + 1.minute
+          s.hard.due = now + 5.minutes
+          s.good.due = now + 10.minutes
+          easy_interval = next_interval(s.easy.stability)
+          s.easy.scheduled_days = easy_interval
+          s.easy.due = now + easy_interval.days
+        end
+
+        def schedule_learning_relearning_state(s, now)
+          hard_interval = 0
+          good_interval = next_interval(s.good.stability)
+          easy_interval = [next_interval(s.easy.stability), good_interval + 1].max
+          s.schedule(now, hard_interval, good_interval, easy_interval)
+        end
+
+        def schedule_review_state(s, card, now)
+          interval = card.elapsed_days
+          last_d = card.difficulty
+          last_s = card.stability
+          retrievability = forgetting_curve(interval, last_s)
+          next_ds(s, last_d, last_s, retrievability)
+          hard_interval = next_interval(s.hard.stability)
+          good_interval = next_interval(s.good.stability)
+          hard_interval = [hard_interval, good_interval].min
+          good_interval = [good_interval, hard_interval + 1].max
+          easy_interval = [next_interval(s.easy.stability), good_interval + 1].max
+          s.schedule(now, hard_interval, good_interval, easy_interval)
+        end
+
+        def init_ds(s)
+          s.again.difficulty = init_difficulty(Rating::AGAIN)
+          s.again.stability = init_stability(Rating::AGAIN)
+          s.hard.difficulty = init_difficulty(Rating::HARD)
+          s.hard.stability = init_stability(Rating::HARD)
+          s.good.difficulty = init_difficulty(Rating::GOOD)
+          s.good.stability = init_stability(Rating::GOOD)
+          s.easy.difficulty = init_difficulty(Rating::EASY)
+          s.easy.stability = init_stability(Rating::EASY)
+        end
+
+        def next_ds(s, last_d, last_s, retrievability)
+          s.again.difficulty = next_difficulty(last_d, Rating::AGAIN)
+          s.again.stability = next_forget_stability(last_d, last_s, retrievability)
+          s.hard.difficulty = next_difficulty(last_d, Rating::HARD)
+          s.hard.stability = next_recall_stability(last_d, last_s, retrievability, Rating::HARD)
+          s.good.difficulty = next_difficulty(last_d, Rating::GOOD)
+          s.good.stability = next_recall_stability(last_d, last_s, retrievability, Rating::GOOD)
+          s.easy.difficulty = next_difficulty(last_d, Rating::EASY)
+          s.easy.stability = next_recall_stability(last_d, last_s, retrievability, Rating::EASY)
+        end
+
+        def init_stability(r)
+          [p.w[r - 1], 0.1].max
+        end
+
+        def init_difficulty(r)
+          (p.w[4] - (p.w[5] * (r - 3))).clamp(1, 10)
+        end
+
+        def forgetting_curve(elapsed_days, stability)
+          (1 + (factor * elapsed_days / stability))**decay
+        end
+
+        def next_interval(s)
+          new_interval = s / factor * ((p.request_retention**(1 / decay)) - 1)
+          new_interval.round.clamp(1, p.maximum_interval)
+        end
+
+        def next_difficulty(d, r)
+          next_d = d - (p.w[6] * (r - 3))
+          mean_reversion(p.w[4], next_d).clamp(1, 10)
+        end
+
+        def mean_reversion(init, current)
+          (p.w[7] * init) + ((1 - p.w[7]) * current)
+        end
+
+        def next_recall_stability(d, s, r, rating)
+          hard_penalty = (rating == Rating::HARD) ? p.w[15] : 1
+          easy_bonus = (rating == Rating::EASY) ? p.w[16] : 1
+          s * (1 + (Math.exp(p.w[8]) * (11 - d) * (s**-p.w[9]) *
+              (Math.exp((1 - r) * p.w[10]) - 1) * hard_penalty * easy_bonus))
+        end
+
+        def next_forget_stability(d, s, r)
+          p.w[11] * (d**-p.w[12]) * (((s + 1)**p.w[13]) - 1) *
+            Math.exp((1 - r) * p.w[14])
+        end
+      end
+    end
+  end
+end

data/lib/active_recall/algorithms/fsrs.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "active_recall/algorithms/fsrs/internal"
+
+module ActiveRecall
+  class FSRS
+    REQUIRED_ATTRIBUTES = [
+      :box,
+      :stability,
+      :difficulty,
+      :state,
+      :lapses,
+      :elapsed_days,
+      :scheduled_days,
+      :times_right,
+      :times_wrong,
+      :last_reviewed,
+      :grade
+    ].freeze
+
+    GRADE_TO_RATING = {
+      1 => Internal::Rating::AGAIN,
+      2 => Internal::Rating::HARD,
+      3 => Internal::Rating::GOOD,
+      4 => Internal::Rating::EASY
+    }.freeze
+
+    def self.required_attributes
+      REQUIRED_ATTRIBUTES
+    end
+
+    def self.type
+      :gradable
+    end
+
+    def self.score(**kwargs)
+      new(**kwargs).score
+    end
+
+    def initialize(box:, stability:, difficulty:, state:, lapses:,
+      elapsed_days:, scheduled_days:, times_right:, times_wrong:,
+      last_reviewed:, grade:, current_time: Time.current)
+      @box = box || 0
+      @stability = stability
+      @difficulty = difficulty
+      @state = state || Internal::State::NEW
+      @lapses = lapses || 0
+      @elapsed_days = elapsed_days || 0
+      @scheduled_days = scheduled_days || 0
+      @times_right = times_right || 0
+      @times_wrong = times_wrong || 0
+      @last_reviewed = last_reviewed
+      @grade = grade
+      @current_time = current_time
+    end
+
+    def score
+      raise "Grade must be between 1-4!" unless GRADE_TO_RATING.key?(@grade)
+
+      now = to_utc_datetime(@current_time)
+      scheduling = scheduler.repeat(build_card, now)
+      result = scheduling[GRADE_TO_RATING[@grade]].card
+
+      {
+        box: result.reps,
+        stability: result.stability,
+        difficulty: result.difficulty,
+        state: result.state,
+        lapses: result.lapses,
+        elapsed_days: result.elapsed_days,
+        scheduled_days: result.scheduled_days,
+        last_reviewed: result.last_review,
+        next_review: result.due,
+        times_right: @times_right + ((@grade >= 2) ? 1 : 0),
+        times_wrong: @times_wrong + ((@grade == 1) ? 1 : 0)
+      }
+    end
+
+    private
+
+    def build_card
+      card = Internal::Card.new
+      card.stability = @stability if @stability
+      card.difficulty = @difficulty if @difficulty
+      card.state = @state
+      card.lapses = @lapses
+      card.elapsed_days = @elapsed_days
+      card.scheduled_days = @scheduled_days
+      card.reps = @box
+      card.last_review = to_utc_datetime(@last_reviewed) if @last_reviewed
+      card
+    end
+
+    def scheduler
+      scheduler = Internal::Scheduler.new
+      config = ActiveRecall.configuration
+      scheduler.p.request_retention = config.fsrs_request_retention if config.fsrs_request_retention
+      scheduler.p.maximum_interval = config.fsrs_maximum_interval if config.fsrs_maximum_interval
+      scheduler.p.w = config.fsrs_weights if config.fsrs_weights
+      scheduler
+    end
+
+    def to_utc_datetime(value)
+      case value
+      when DateTime then value.new_offset(0)
+      else value.utc.to_datetime
+      end
+    end
+  end
+end

data/lib/active_recall/algorithms/sm2.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveRecall
   class SM2
     MIN_EASINESS_FACTOR = 1.3
@@ -38,7 +40,7 @@ module ActiveRecall
     def score
       raise "Grade must be between 0-5!" unless GRADES.include?(@grade)
       old_ef = @easiness_factor
-      update_easiness_factor
+      update_easiness_factor if @grade >= 3
       update_repetition_and_interval(old_ef)
 
       {

data/lib/active_recall/configuration.rb

@@ -2,7 +2,10 @@
 
 module ActiveRecall
   class Configuration
-    attr_accessor :algorithm_class
+    attr_accessor :algorithm_class,
+      :fsrs_request_retention,
+      :fsrs_maximum_interval,
+      :fsrs_weights
 
     def initialize
       @algorithm_class = LeitnerSystem

data/lib/active_recall/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecall
-  VERSION = "2.1.0"
+  VERSION = "2.3.0"
 end

data/lib/active_recall.rb

@@ -7,6 +7,7 @@ require "active_recall/algorithms/fibonacci_sequence"
 require "active_recall/algorithms/leitner_system"
 require "active_recall/algorithms/soft_leitner_system"
 require "active_recall/algorithms/sm2"
+require "active_recall/algorithms/fsrs"
 require "active_recall/configuration"
 require "active_recall/models/deck"
 require "active_recall/models/item"

data/lib/generators/active_recall/active_recall_generator.rb

@@ -21,6 +21,7 @@ class ActiveRecallGenerator < Rails::Generators::Base
     create_migration_file_if_not_exist "create_active_recall_tables"
     create_migration_file_if_not_exist "add_active_recall_item_answer_counts"
     create_migration_file_if_not_exist "add_active_recall_item_easiness_factor"
+    create_migration_file_if_not_exist "add_active_recall_item_fsrs_fields"
     create_migration_file_if_not_exist "migrate_okubo_to_active_recall" if options["migrate_data"]
   end
 

data/lib/generators/active_recall/templates/add_active_recall_item_fsrs_fields.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class AddActiveRecallItemFsrsFields < ActiveRecord::Migration[5.2]
+  def self.up
+    add_column :active_recall_items, :stability, :float
+    add_column :active_recall_items, :difficulty, :float
+    add_column :active_recall_items, :state, :integer, default: 0
+    add_column :active_recall_items, :lapses, :integer, default: 0
+    add_column :active_recall_items, :elapsed_days, :integer, default: 0
+    add_column :active_recall_items, :scheduled_days, :integer, default: 0
+  end
+
+  def self.down
+    remove_column :active_recall_items, :stability
+    remove_column :active_recall_items, :difficulty
+    remove_column :active_recall_items, :state
+    remove_column :active_recall_items, :lapses
+    remove_column :active_recall_items, :elapsed_days
+    remove_column :active_recall_items, :scheduled_days
+  end
+end

data/standard.yml

@@ -1,3 +1,3 @@
 fix: true
 parallel: true
-ruby_version: 3.0
+ruby_version: 3.2