active_recall 2.3.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63a48f6351a76013bbf2922ca75b507b6dccb1ab23867896217b53bc6a77e26f
-  data.tar.gz: 9d8e3189bb8f5b1f15b284168e5973e87070bf223c0427b5a574cacd38c8e4b0
+  metadata.gz: 25a05ad2ad88bc270c9e58cb8a2760b280677fb6d1d3c35ee76df8b021e1c6fd
+  data.tar.gz: 1503c4d5cc0863a42d51a084c7651d79fe574f9d98fb60254fd2084b6cf4ec13
 SHA512:
-  metadata.gz: efe496383029f35391f1b54533f525451c5ee8a02e440316b990b812923b2061fc94eeff2ed1d691b17a1838b2d266b51ec9dde7d3305d511b484edb53b606b7
-  data.tar.gz: ff9f67e94b77d93175af60926ad889655862989c18a9b2fb07b8e75503526b8281f32cd3a982ab1d70933363454e40461a10dd2be72784bc5097243173ff5b1e
+  metadata.gz: aab226bca430aac827eb11c7c46b1765f6b367181e233a614748f509640589306d86cd3fc4ad32655b431f4b49d5beaa163f056b7dfb09ccd51a17e5d727cc9b
+  data.tar.gz: c630d5a2fe83551b8929ef1a9f22b9408c908f3cb90a376b56dd056cdfa90e0c530f0c6aac02cae4d3a6d6891b457db6022258cf549687241783954a61ceb65f

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    active_recall (2.3.0)
+    active_recall (2.3.1)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
+      fsrs (>= 0.9.2, < 1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -98,6 +99,8 @@ GEM
     drb (2.2.0)
       ruby2_keywords
     erubi (1.12.0)
+    fsrs (0.9.2)
+      activesupport (>= 7.0, < 9.0)
     globalid (1.2.1)
       activesupport (>= 6.1)
     i18n (1.14.1)

data/active_recall.gemspec

@@ -41,5 +41,9 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "standard"
   spec.add_runtime_dependency "activerecord", ">= 7.0", "< 9.0"
   spec.add_runtime_dependency "activesupport", ">= 7.0", "< 9.0"
+  # fsrs 0.9.2 is the first release that widens activesupport to allow Rails 8
+  # and ships the new-card scheduling fix (minute-vs-day in schedule_new_state).
+  # Do not relax this floor without verifying both still hold.
+  spec.add_runtime_dependency "fsrs", ">= 0.9.2", "< 1.0"
   spec.required_ruby_version = ">= 3.2"
 end

data/gemfiles/rails_7_0.gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: ..
   specs:
-    active_recall (2.3.0)
+    active_recall (2.3.1)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
+      fsrs (>= 0.9.2, < 1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -98,6 +99,8 @@ GEM
     drb (2.2.0)
       ruby2_keywords
     erubi (1.12.0)
+    fsrs (0.9.2)
+      activesupport (>= 7.0, < 9.0)
     globalid (1.2.1)
       activesupport (>= 6.1)
     i18n (1.14.1)

data/gemfiles/rails_7_1.gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: ..
   specs:
-    active_recall (2.3.0)
+    active_recall (2.3.1)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
+      fsrs (>= 0.9.2, < 1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -98,6 +99,8 @@ GEM
     drb (2.2.0)
       ruby2_keywords
     erubi (1.12.0)
+    fsrs (0.9.2)
+      activesupport (>= 7.0, < 9.0)
     globalid (1.2.1)
       activesupport (>= 6.1)
     i18n (1.14.1)

data/gemfiles/rails_8_0.gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: ..
   specs:
-    active_recall (2.3.0)
+    active_recall (2.3.1)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
+      fsrs (>= 0.9.2, < 1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -95,6 +96,8 @@ GEM
     diff-lcs (1.5.1)
     drb (2.2.1)
     erubi (1.13.1)
+    fsrs (0.9.2)
+      activesupport (>= 7.0, < 9.0)
     globalid (1.2.1)
       activesupport (>= 6.1)
     i18n (1.14.6)

data/lib/active_recall/algorithms/fsrs.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "active_recall/algorithms/fsrs/internal"
+require "fsrs"
 
 module ActiveRecall
   class FSRS
@@ -19,10 +19,10 @@ module ActiveRecall
     ].freeze
 
     GRADE_TO_RATING = {
-      1 => Internal::Rating::AGAIN,
-      2 => Internal::Rating::HARD,
-      3 => Internal::Rating::GOOD,
-      4 => Internal::Rating::EASY
+      1 => Fsrs::Rating::AGAIN,
+      2 => Fsrs::Rating::HARD,
+      3 => Fsrs::Rating::GOOD,
+      4 => Fsrs::Rating::EASY
     }.freeze
 
     def self.required_attributes
@@ -33,8 +33,8 @@ module ActiveRecall
       :gradable
     end
 
-    def self.score(**kwargs)
-      new(**kwargs).score
+    def self.score(**)
+      new(**).score
     end
 
     def initialize(box:, stability:, difficulty:, state:, lapses:,
@@ -43,7 +43,7 @@ module ActiveRecall
       @box = box || 0
       @stability = stability
       @difficulty = difficulty
-      @state = state || Internal::State::NEW
+      @state = state || Fsrs::State::NEW
       @lapses = lapses || 0
       @elapsed_days = elapsed_days || 0
       @scheduled_days = scheduled_days || 0
@@ -79,7 +79,7 @@ module ActiveRecall
     private
 
     def build_card
-      card = Internal::Card.new
+      card = Fsrs::Card.new
       card.stability = @stability if @stability
       card.difficulty = @difficulty if @difficulty
       card.state = @state
@@ -92,7 +92,7 @@ module ActiveRecall
     end
 
     def scheduler
-      scheduler = Internal::Scheduler.new
+      scheduler = Fsrs::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

data/lib/active_recall/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_recall
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.3.1
 platform: ruby
 authors:
 - Robert Gravina
@@ -154,6 +154,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: fsrs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: A spaced-repetition system to be used with ActiveRecord models
 email:
 - robert.gravina@gmail.com
@@ -173,7 +193,6 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- VENDORED_LICENSES.md
 - active_recall.gemspec
 - bin/console
 - bin/flatten
@@ -189,7 +208,6 @@ files:
 - lib/active_recall.rb
 - lib/active_recall/algorithms/fibonacci_sequence.rb
 - lib/active_recall/algorithms/fsrs.rb
-- lib/active_recall/algorithms/fsrs/internal.rb
 - lib/active_recall/algorithms/leitner_system.rb
 - lib/active_recall/algorithms/sm2.rb
 - lib/active_recall/algorithms/soft_leitner_system.rb

data/VENDORED_LICENSES.md

@@ -1,54 +0,0 @@
-# Vendored Licenses
-
-This file records third-party source code that has been vendored into this
-repository, along with the upstream license terms. ActiveRecall's own license
-is in [LICENSE](LICENSE).
-
-## rb-fsrs
-
-- **Vendored at:** [`lib/active_recall/algorithms/fsrs/internal.rb`](lib/active_recall/algorithms/fsrs/internal.rb)
-- **Upstream:** https://github.com/open-spaced-repetition/rb-fsrs
-- **Version:** 0.9.0 (commit pulled from the published gem)
-- **License:** MIT
-- **Reason for vendoring:** The published `fsrs` 0.9.0 gem pins
-  `activesupport ~> 7.0`, which excludes Rails 8. ActiveRecall supports
-  Rails 8, so the code was vendored under `ActiveRecall::FSRS::Internal`.
-  The constraint has been widened on rb-fsrs `master`; revisit the
-  dependency-vs-vendoring decision once a release with the wider
-  constraint ships.
-
-### Local divergences from upstream
-
-- `Scheduler#schedule_new_state` uses `1.minute` / `5.minutes` /
-  `10.minutes` in place of upstream's bare integer arithmetic
-  (`now + 60`, `now + (5 * 60)`, `now + (10 * 60)`). With `now` as a
-  `DateTime`, the upstream form adds days, not seconds, scheduling new
-  cards rated Again/Hard/Good 60 / 300 / 600 days out instead of
-  1 / 5 / 10 minutes. Tracks upstream PR
-  https://github.com/open-spaced-repetition/rb-fsrs/pull/9.
-
-### Upstream license text
-
-```
-The MIT License (MIT)
-
-Copyright (c) 2024 clayton
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-```

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

@@ -1,335 +0,0 @@
-# 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