active_recall 1.8.5 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e96531570c81f3e7457acc497a7db792708b6b765794e2294b00cce0bd0cfe2
-  data.tar.gz: 06c2f07e0438fc376beefe980dbdc579f06bb7d8bab77e692faed876b5a69629
+  metadata.gz: 5241d31af65cc21d9fd3ab8a68696587e5af6fdfe62ecf6b4ab719eadda9ee80
+  data.tar.gz: 7572b3444399f07faa04c093ca4b0f0b95f0d272804aee5e884852824f5718c7
 SHA512:
-  metadata.gz: c8c4385a5646b277f27b6a90505e6f55847eba3d5e96bb32e0694f9148a018f71846d5cb9d552078a5c215965e5d72f6661f96c64885e9199ff557e77b47b059
-  data.tar.gz: 9089edaa9ef21c0d1a8750d60b223ac4cda49c075268bee4bea25493b7951c3bd31747a129a93721f0e239efb41bb9d7db3a6f96d157d9b2f95930494f812c91
+  metadata.gz: 8d44c8efe2acb539484adcb6c4d421ddebf2cdfb35b05c9b49e02c72a65ea1047c8b7dd145261fbbd9e8678221dc5300cdc3551600e263ac7b52947a78d94660
+  data.tar.gz: bb043b33bd7242b2020a65d4e9e10953dcfbd136e42c5ac0964110c01a26400ad3b0a655d23ca2d74e634d7d41c8791d504f2cca78007c9db0cf49b35dd790c2

data/.github/workflows/tests.yml

@@ -19,16 +19,16 @@ jobs:
           - macos
           - ubuntu
         ruby:
-          - 2.7
           - 3.0
           - 3.1
           - 3.2
+          - 3.3
         allow_failures:
           - false
         include:
           - os: ubuntu
             ruby: ruby-head
-            allow_failures: false
+            allow_failures: true
     env:
       BUNDLE_GEMFILE: "${{ matrix.gemfile }}"
       ALLOW_FAILURES: "${{ matrix.allow_failures }}"

data/.gitignore

@@ -14,3 +14,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.idea/

data/.tool-versions

@@ -1 +1 @@
-ruby 3.2.2
+ruby 3.3.0

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    active_recall (1.8.5)
-      activerecord (>= 5.2.3, <= 7.1)
-      activesupport (>= 5.2.3, <= 7.1)
+    active_recall (2.0.0)
+      activerecord (>= 6.0, <= 7.2)
+      activesupport (>= 6.0, <= 7.2)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -2,7 +2,7 @@
 
 **ActiveRecall** is a spaced-repetition system that allows you to treat arbitrary [ActiveRecord](https://github.com/rails/rails/tree/master/activerecord) models as if they were flashcards to be learned and reviewed.
 It it based on, and is intended to be backwards compatible with, the [okubo](https://github.com/rgravina/okubo) gem.
-The primary differentiating features are that it lets the user specify the scheduling algorithm and is fully compatible with Rails 6+ and Ruby 3+.
+The primary differentiating features are that it lets the user specify the scheduling algorithm and is fully compatible with (and requires) Rails 6+ and Ruby 3+.
 
 ## Installation
 
@@ -35,6 +35,7 @@ ActiveRecall.configure do |config|
   config.algorithm_class = ActiveRecall::FibonacciSequence
 end
 ```
+Algorithms include `FibonacciSequence`, `LeitnerSystem`, `SoftLeitnerSystem`, and `SM2` (see [here](https://en.wikipedia.org/wiki/SuperMemo#Description_of_SM-2_algorithm)).
 For Rails applications, try doing this from within an [initializer file](https://guides.rubyonrails.org/configuring.html#using-initializer-files).
 
 Assume you have an application allowing your users to study words in a foreign language. Using the `has_deck` method you can set up a deck of flashcards that the user will study:
@@ -58,7 +59,7 @@ You can add words and record attempts to guess the word as right or wrong. Vario
 user.words << word
 user.words.untested #=> [word]
 
-# Guessing a word correctly
+# Guessing a word correctly (when using a binary algorithm)
 user.right_answer_for!(word)
 user.words.known #=> [word]
 
@@ -92,6 +93,16 @@ user.right_answer_for!(word)
 user.words.expired #=> [word]
 ```
 
+When using a gradable algorithm (rather than binary) such as the SM2 algorithm, you will need to supply your own grade along with the item:
+```ruby
+grade = 3
+user.score!(grade, word)
+
+# Using the binary-only methods will raise an error
+user.right_answer_for!(word)
+=> ActiveRecall::IncompatibleAlgorithmError
+```
+
 Reviewing
 ---------
 

data/active_recall.gemspec

@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rdoc"
   spec.add_development_dependency "rspec", ">= 3.0"
   spec.add_development_dependency "sqlite3"
-  spec.add_runtime_dependency "activerecord", ">= 5.2.3", "<= 7.1"
-  spec.add_runtime_dependency "activesupport", ">= 5.2.3", "<= 7.1"
-  spec.required_ruby_version = ">= 2.6"
+  spec.add_runtime_dependency "activerecord", ">= 6.0", "<= 7.2"
+  spec.add_runtime_dependency "activesupport", ">= 6.0", "<= 7.2"
+  spec.required_ruby_version = ">= 3.0"
 end

data/lib/active_recall/algorithms/fibonacci_sequence.rb

@@ -2,6 +2,10 @@
 
 module ActiveRecall
   class FibonacciSequence
+    def self.required_attributes
+      REQUIRED_ATTRIBUTES
+    end
+
     def self.right(box:, times_right:, times_wrong:, current_time: Time.current)
       new(
         box: box,
@@ -11,6 +15,10 @@ module ActiveRecall
       ).right
     end
 
+    def self.type
+      :binary
+    end
+
     def self.wrong(box:, times_right:, times_wrong:, current_time: Time.current)
       new(
         box: box,
@@ -51,6 +59,7 @@ module ActiveRecall
 
     attr_reader :box, :current_time, :times_right, :times_wrong
 
+    REQUIRED_ATTRIBUTES = [:box, :times_right, :times_wrong].freeze
     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)

data/lib/active_recall/algorithms/leitner_system.rb

@@ -2,7 +2,9 @@
 
 module ActiveRecall
   class LeitnerSystem
-    DELAYS = [3, 7, 14, 30, 60, 120, 240].freeze
+    def self.required_attributes
+      REQUIRED_ATTRIBUTES
+    end
 
     def self.right(box:, times_right:, times_wrong:, current_time: Time.current)
       new(
@@ -13,6 +15,10 @@ module ActiveRecall
       ).right
     end
 
+    def self.type
+      :binary
+    end
+
     def self.wrong(box:, times_right:, times_wrong:, current_time: Time.current)
       new(
         box: box,
@@ -53,6 +59,9 @@ module ActiveRecall
 
     attr_reader :box, :current_time, :times_right, :times_wrong
 
+    DELAYS = [3, 7, 14, 30, 60, 120, 240].freeze
+    REQUIRED_ATTRIBUTES = [:box, :times_right, :times_wrong].freeze
+
     def next_review
       (current_time + DELAYS[[DELAYS.count, box + 1].min - 1].days)
     end

data/lib/active_recall/algorithms/sm2.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module ActiveRecall
+  class SM2
+    MIN_EASINESS_FACTOR = 1.3
+
+    def self.required_attributes
+      REQUIRED_ATTRIBUTES
+    end
+
+    def self.score(box:, easiness_factor:, times_right:, times_wrong:, grade:, current_time: Time.current)
+      new(
+        box: box,
+        easiness_factor: easiness_factor,
+        times_right: times_right,
+        times_wrong: times_wrong,
+        grade: grade,
+        current_time: current_time
+      ).score
+    end
+
+    def self.type
+      :gradable
+    end
+
+    def initialize(box:, easiness_factor:, times_right:, times_wrong:, grade:, current_time: Time.current)
+      @box = box
+      @easiness_factor = easiness_factor || 2.5
+      @times_right = times_right
+      @times_wrong = times_wrong
+      @grade = grade
+      @current_time = current_time
+      @interval = [1, box].max
+    end
+
+    def score
+      raise "Grade must be between 0-5!" unless GRADES.include?(@grade)
+      update_easiness_factor
+      update_repetition_and_interval
+
+      {
+        box: @box,
+        easiness_factor: @easiness_factor,
+        times_right: @times_right,
+        times_wrong: @times_wrong,
+        last_reviewed: @current_time,
+        next_review: next_review
+      }
+    end
+
+    private
+
+    GRADES = [
+      5, # Perfect response. The learner recalls the information without hesitation.
+      4, # Correct response after a hesitation. The learner recalls the information but with some difficulty.
+      3, # Correct response recalled with serious difficulty. The learner struggles but eventually recalls the information.
+      2, # Incorrect response, but the learner was very close to the correct answer. This might involve recalling some of the information correctly but not all of it.
+      1, # Incorrect response, but the learner feels they should have remembered it. This is typically used when the learner has a sense of familiarity with the material but fails to recall it correctly.
+      0 # Complete blackout. The learner does not recall the information at all.
+    ].freeze
+    REQUIRED_ATTRIBUTES = [
+      :box,
+      :easiness_factor,
+      :grade,
+      :times_right,
+      :times_wrong
+    ].freeze
+
+    def update_easiness_factor
+      @easiness_factor += (0.1 - (5 - @grade) * (0.08 + (5 - @grade) * 0.02))
+      @easiness_factor = [@easiness_factor, MIN_EASINESS_FACTOR].max
+    end
+
+    def update_repetition_and_interval
+      if @grade >= 3
+        @box += 1
+        @times_right += 1
+        @interval = case @box
+        when 1
+          1
+        when 2
+          6
+        else
+          (@interval || 1) * @easiness_factor
+        end
+      else
+        @box = 0
+        @times_wrong += 1
+        @interval = 1
+      end
+    end
+
+    def next_review
+      @current_time + @interval.days
+    end
+  end
+end

data/lib/active_recall/algorithms/soft_leitner_system.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ActiveRecall
+  class SoftLeitnerSystem
+    def self.required_attributes
+      REQUIRED_ATTRIBUTES
+    end
+
+    def self.right(box:, times_right:, times_wrong:, current_time: Time.current)
+      new(
+        box: box,
+        current_time: current_time,
+        times_right: times_right,
+        times_wrong: times_wrong
+      ).right
+    end
+
+    def self.type
+      :binary
+    end
+
+    def self.wrong(box:, times_right:, times_wrong:, current_time: Time.current)
+      new(
+        box: box,
+        current_time: current_time,
+        times_right: times_right,
+        times_wrong: times_wrong
+      ).wrong
+    end
+
+    def initialize(box:, times_right:, times_wrong:, current_time: Time.current)
+      @box = box
+      @current_time = current_time
+      @times_right = times_right
+      @times_wrong = times_wrong
+    end
+
+    def right
+      self.box = [box + 1, DELAYS.count].min
+
+      {
+        box: box,
+        times_right: times_right + 1,
+        times_wrong: times_wrong,
+        last_reviewed: current_time,
+        next_review: next_review
+      }
+    end
+
+    def wrong
+      self.box = [box - 1, 0].max
+
+      {
+        box: box,
+        times_right: times_right,
+        times_wrong: times_wrong + 1,
+        last_reviewed: current_time,
+        next_review: next_review
+      }
+    end
+
+    private
+
+    DELAYS = [3, 7, 14, 30, 60, 120, 240].freeze
+    REQUIRED_ATTRIBUTES = [:box, :times_right, :times_wrong].freeze
+
+    attr_accessor :box
+    attr_reader :current_time, :times_right, :times_wrong
+
+    def next_review
+      (current_time + DELAYS[[DELAYS.count, box].min - 1].days)
+    end
+  end
+end

data/lib/active_recall/item_methods.rb

@@ -9,5 +9,9 @@ module ActiveRecall
     def wrong_answer_for!(item)
       deck.items.find_by(source_id: item.id).wrong!
     end
+
+    def score!(grade, item)
+      deck.items.find_by(source_id: item.id).score!(grade)
+    end
   end
 end

data/lib/active_recall/models/item.rb

@@ -17,16 +17,34 @@ module ActiveRecall
       where(["box > ? and next_review > ?", 0, current_time])
     end
 
+    def score!(grade)
+      if algorithm_class.type == :gradable
+        update!(
+          algorithm_class.score(**scoring_attributes.merge(grade: grade))
+        ).score
+      else
+        raise IncompatibleAlgorithmError, "#{algorithm_class.name} is a not an gradable algorithm, so is not compatible with the #score! method"
+      end
+    end
+
     def source
       source_type.constantize.find(source_id)
     end
 
     def right!
-      update!(algorithm_class.right(**scoring_attributes))
+      if algorithm_class.type == :binary
+        update!(algorithm_class.right(**scoring_attributes))
+      else
+        raise IncompatibleAlgorithmError, "#{algorithm_class.name} is not a binary algorithm, so is not compatible with the #right! method"
+      end
     end
 
     def wrong!
-      update!(algorithm_class.wrong(**scoring_attributes))
+      if algorithm_class.type == :binary
+        update!(algorithm_class.wrong(**scoring_attributes))
+      else
+        raise IncompatibleAlgorithmError, "#{algorithm_class.name} is not a binary algorithm, so is not compatible with the #wrong! method"
+      end
     end
 
     private
@@ -36,7 +54,9 @@ module ActiveRecall
     end
 
     def scoring_attributes
-      attributes.symbolize_keys.slice(:box, :times_right, :times_wrong)
+      attributes
+        .symbolize_keys
+        .slice(*algorithm_class.required_attributes)
     end
   end
 end

data/lib/active_recall/version.rb

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

data/lib/active_recall.rb

@@ -5,6 +5,8 @@ require "active_recall/deck_methods"
 require "active_recall/item_methods"
 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/configuration"
 require "active_recall/models/deck"
 require "active_recall/models/item"
@@ -28,4 +30,6 @@ module ActiveRecall
   def self.reset
     @configuration = Configuration.new
   end
+
+  class IncompatibleAlgorithmError < StandardError; end
 end

data/lib/generators/active_recall/active_recall_generator.rb

@@ -20,6 +20,7 @@ class ActiveRecallGenerator < Rails::Generators::Base
   def create_migration_files
     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 "migrate_okubo_to_active_recall" if options["migrate_data"]
   end
 

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class AddActiveRecallItemEasinessFactor < ActiveRecord::Migration[5.2]
+  def self.up
+    add_column :active_recall_items, :easiness_factor, :float, default: 2.5
+  end
+
+  def self.down
+    remove_column :active_recall_items, :easiness_factor
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_recall
 version: !ruby/object:Gem::Version
-  version: 1.8.5
+  version: 2.0.0
 platform: ruby
 authors:
 - Robert Gravina
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-06 00:00:00.000000000 Z
+date: 2024-01-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -73,40 +73,40 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.2.3
+        version: '6.0'
     - - "<="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.2.3
+        version: '6.0'
     - - "<="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.2.3
+        version: '6.0'
     - - "<="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.2.3
+        version: '6.0'
     - - "<="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
 description: A spaced-repetition system to be used with ActiveRecord models
 email:
 - robert.gravina@gmail.com
@@ -130,6 +130,8 @@ files:
 - lib/active_recall.rb
 - lib/active_recall/algorithms/fibonacci_sequence.rb
 - lib/active_recall/algorithms/leitner_system.rb
+- lib/active_recall/algorithms/sm2.rb
+- lib/active_recall/algorithms/soft_leitner_system.rb
 - lib/active_recall/base.rb
 - lib/active_recall/configuration.rb
 - lib/active_recall/deck_methods.rb
@@ -139,6 +141,7 @@ files:
 - lib/active_recall/version.rb
 - lib/generators/active_recall/active_recall_generator.rb
 - lib/generators/active_recall/templates/add_active_recall_item_answer_counts.rb
+- lib/generators/active_recall/templates/add_active_recall_item_easiness_factor.rb
 - lib/generators/active_recall/templates/create_active_recall_tables.rb
 - lib/generators/active_recall/templates/migrate_okubo_to_active_recall.rb
 homepage: https://github.com/jaysonvirissimo/active_recall
@@ -154,14 +157,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: A spaced-repetition system