active_recall 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25a05ad2ad88bc270c9e58cb8a2760b280677fb6d1d3c35ee76df8b021e1c6fd
-  data.tar.gz: 1503c4d5cc0863a42d51a084c7651d79fe574f9d98fb60254fd2084b6cf4ec13
+  metadata.gz: 32cd4469689b6a3cdd5fb86aef54cdb886a41eeb0d3feafe8378faa5748fa267
+  data.tar.gz: a4e4711f9a8ebb85339b2b66c83f1ca9b9c54a360d9aa89a3aacb53998d9db4c
 SHA512:
-  metadata.gz: aab226bca430aac827eb11c7c46b1765f6b367181e233a614748f509640589306d86cd3fc4ad32655b431f4b49d5beaa163f056b7dfb09ccd51a17e5d727cc9b
-  data.tar.gz: c630d5a2fe83551b8929ef1a9f22b9408c908f3cb90a376b56dd056cdfa90e0c530f0c6aac02cae4d3a6d6891b457db6022258cf549687241783954a61ceb65f
+  metadata.gz: feb48c5d0f80cc200dbd61322e647c3af982e92833e4727c3d801c5b77e6316af1d83315ee1bce4479f9aad537a026ba331d075a271e6a726d8c07cc0fdebf34
+  data.tar.gz: a2ffe9ade4ab0703572e7e5168b0326a46601c5ce84fc136f82433927787c395d754a47ccef7020a264ad6f15e6dcd4620a2d7298db7e948cb7f7afb219520de

data/CLAUDE.md

@@ -95,6 +95,7 @@ bundle exec rake release
    - Binary algorithms: LeitnerSystem (default), SoftLeitnerSystem, FibonacciSequence
    - Gradable algorithm: SM2
    - All algorithms are stateless; they accept current state and return new state as a hash
+   - SM2 follows the canonical recurrence `I(1)=1, I(2)=6, I(n)=round(I(n-1) * EF)`, recovering the prior interval from the card's `last_reviewed`/`next_review` (no extra columns), updates EF on every grade (clamped to 1.3), and schedules failures one day out. Because SM2 reads those timestamps as its own state, switching algorithms on already-reviewed cards is unsupported without a state reset/migration.
 
 5. **Configuration** (lib/active_recall/configuration.rb)
    - Global configuration via `ActiveRecall.configure`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    active_recall (2.3.1)
+    active_recall (2.4.0)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
       fsrs (>= 0.9.2, < 1.0)

data/README.md

@@ -160,17 +160,23 @@ user.words.expired #=> [word]
 | `1` | Incorrect response with familiarity |
 | `0` | Complete blackout |
 
-Grades **≥ 3** count as a success: the box advances and `times_right` increments. Grades **< 3** reset the box to `0` and increment `times_wrong`. Each item's `easiness_factor` starts at `2.5` and is clamped to a minimum of `1.3`.
+Grades **≥ 3** count as a success: the box advances and `times_right` increments. Grades **< 3** reset the box to `0` and increment `times_wrong`. The `easiness_factor` is updated on **every** grade (including failures), starts at `2.5`, and is clamped to a minimum of `1.3` — so a poor grade lowers the EF and shortens future intervals.
+
+Intervals follow the canonical SM-2 recurrence: `I(1) = 1`, `I(2) = 6`, and `I(n) = round(I(n − 1) × EF)` for `n > 2`. Fractional intervals use ordinary rounding (matching the published SuperMemo 2 source), so six consecutive perfect reviews schedule at `1, 6, 16, 45, 131, 393` days. The prior interval is recovered from the card's stored `last_reviewed`/`next_review`, so **no extra columns are required**.
+
+A failed card is scheduled one day out (`next_review = now + 1 day`) and does **not** reappear in `review`/`failed` until that day arrives.
 
 ```ruby
 user.words << word
 
 user.score!(5, word)  # perfect recall — box advances, EF rises
-user.score!(2, word)  # incorrect — box resets to 0
+user.score!(2, word)  # incorrect — box resets to 0, EF drops, due again tomorrow
 ```
 
 Calling `user.right_answer_for!(word)` while SM2 is configured raises `ActiveRecall::IncompatibleAlgorithmError` — use `score!` instead.
 
+> **Switching algorithms on existing cards is unsupported.** Each card's `box`, `next_review`, and `last_reviewed` are written by whichever algorithm scored it, and SM-2 derives its prior interval from those timestamps. Pointing SM-2 at cards previously scheduled by another algorithm will misread their state. Choose an algorithm before reviewing, or reset/migrate card state before switching.
+
 ## Usage with FSRS
 
 [FSRS](https://github.com/open-spaced-repetition/fsrs4anki) uses a 1–4 grade scale matching the familiar Anki buttons:

data/gemfiles/rails_7_0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    active_recall (2.3.1)
+    active_recall (2.4.0)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
       fsrs (>= 0.9.2, < 1.0)

data/gemfiles/rails_7_1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    active_recall (2.3.1)
+    active_recall (2.4.0)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
       fsrs (>= 0.9.2, < 1.0)

data/gemfiles/rails_8_0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    active_recall (2.3.1)
+    active_recall (2.4.0)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
       fsrs (>= 0.9.2, < 1.0)

data/lib/active_recall/algorithms/sm2.rb

@@ -8,13 +8,15 @@ module ActiveRecall
       REQUIRED_ATTRIBUTES
     end
 
-    def self.score(box:, easiness_factor:, times_right:, times_wrong:, grade:, current_time: Time.current)
+    def self.score(box:, easiness_factor:, times_right:, times_wrong:, grade:, last_reviewed: nil, next_review: nil, current_time: Time.current)
       new(
         box: box,
         easiness_factor: easiness_factor,
         times_right: times_right,
         times_wrong: times_wrong,
         grade: grade,
+        last_reviewed: last_reviewed,
+        next_review: next_review,
         current_time: current_time
       ).score
     end
@@ -23,24 +25,22 @@ module ActiveRecall
       :gradable
     end
 
-    def initialize(box:, easiness_factor:, times_right:, times_wrong:, grade:, current_time: Time.current)
+    def initialize(box:, easiness_factor:, times_right:, times_wrong:, grade:, last_reviewed: nil, next_review: nil, current_time: Time.current)
       @box = box # box serves as repetition number n
       @easiness_factor = easiness_factor || 2.5
       @times_right = times_right
       @times_wrong = times_wrong
       @grade = grade
+      @last_reviewed = last_reviewed       # the card's prior review time
+      @previous_next_review = next_review   # the card's prior scheduled due date
       @current_time = current_time
-      @interval = case box
-      when 0 then 1  # First review
-      when 1 then 6  # Second review
-      else 17       # Will be overwritten for boxes > 1
-      end
+      @interval = 1
     end
 
     def score
       raise "Grade must be between 0-5!" unless GRADES.include?(@grade)
       old_ef = @easiness_factor
-      update_easiness_factor if @grade >= 3
+      update_easiness_factor
       update_repetition_and_interval(old_ef)
 
       {
@@ -69,7 +69,9 @@ module ActiveRecall
       :easiness_factor,
       :grade,
       :times_right,
-      :times_wrong
+      :times_wrong,
+      :last_reviewed,
+      :next_review
     ].freeze
 
     def update_easiness_factor
@@ -79,13 +81,13 @@ module ActiveRecall
 
     def update_repetition_and_interval(old_ef)
       if @grade >= 3
-        @interval = if @box == 0
-          1
-        elsif @box == 1
-          6
-        else
-          # Apply exponential scaling based on the box number
-          (6 * (old_ef**(@box - 1))).round
+        # Canonical SM-2 recurrence: I(1)=1, I(2)=6, I(n)=round(I(n-1) * EF).
+        # EF here is the value from before this review's update (old_ef), which
+        # reproduces the published Delphi sequence (1, 6, 16, 45, 131, 393).
+        @interval = case @box
+        when 0 then 1
+        when 1 then 6
+        else (previous_interval * old_ef).round
         end
 
         @box += 1
@@ -97,6 +99,15 @@ module ActiveRecall
       end
     end
 
+    # Recover the card's previously scheduled interval (in days) from its stored
+    # timestamps. Falls back to I(2)=6 when the prior schedule is unavailable
+    # (e.g. a card whose history predates this calculation).
+    def previous_interval
+      return 6 unless @last_reviewed && @previous_next_review
+
+      [((@previous_next_review - @last_reviewed) / 1.day).round, 1].max
+    end
+
     def next_review
       @current_time + @interval.days
     end

data/lib/active_recall/models/item.rb

@@ -6,9 +6,15 @@ module ActiveRecall
 
     belongs_to :deck
 
-    scope :failed, -> { where(["box = ? and last_reviewed is not null", 0]) }
     scope :untested, -> { where(["box = ? and last_reviewed is null", 0]) }
 
+    # Lapsed (box 0, already reviewed) cards that are due now. A null next_review
+    # means "review immediately" (binary algorithms reset this way); a future
+    # next_review (e.g. SM-2's one-day failure interval) is excluded until due.
+    def self.failed(current_time: Time.current)
+      where(["box = ? and last_reviewed is not null and (next_review is null or next_review <= ?)", 0, current_time])
+    end
+
     def self.expired(current_time: Time.current)
       where(["box > ? and next_review <= ?", 0, current_time])
     end

data/lib/active_recall/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_recall
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.0
 platform: ruby
 authors:
 - Robert Gravina