fsrs_ruby 1.0.0

data/lib/fsrs_ruby/schedulers/basic_scheduler.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module FsrsRuby
+  module Schedulers
+    # Scheduler with short-term learning support
+    class BasicScheduler < BaseScheduler
+      def initialize(card, now, algorithm, strategies = {})
+        super
+        @learning_steps_strategy = strategies[:learning_steps] || method(:default_learning_steps)
+      end
+
+      protected
+
+      def default_learning_steps(parameters, state, cur_step)
+        Strategies.basic_learning_steps_strategy(parameters, state, cur_step)
+      end
+
+      # Get learning step info for current card and grade
+      def get_learning_info(card, grade)
+        @learning_steps_strategy.call(@algorithm.parameters, card.state, card.learning_steps || 0)[grade]
+      end
+
+      # Apply learning steps to next card
+      def apply_learning_steps(next_card, grade, to_state)
+        step_info = get_learning_info(@current, grade)
+
+        if step_info
+          scheduled_minutes = step_info[:scheduled_minutes]
+          next_steps = step_info[:next_step]
+
+          if scheduled_minutes > 0 && scheduled_minutes < 1440
+            # Schedule by minutes, stay in learning state
+            next_card.learning_steps = next_steps
+            next_card.scheduled_days = 0
+            next_card.state = to_state
+            next_card.due = Helpers.date_scheduler(@review_time, scheduled_minutes, false)
+          elsif scheduled_minutes >= 1440
+            # Promote to REVIEW, schedule by days
+            next_card.state = State::REVIEW
+            scheduled_days = (scheduled_minutes / 1440.0).round
+            next_card.scheduled_days = scheduled_days
+            next_card.due = Helpers.date_scheduler(@review_time, scheduled_days, true)
+            next_card.learning_steps = 0
+          else
+            # Negative or zero: promote to REVIEW with full interval
+            next_card.state = State::REVIEW
+            interval = @algorithm.next_interval(next_card.stability, @elapsed_days)
+            next_card.scheduled_days = interval
+            next_card.due = Helpers.date_scheduler(@review_time, interval, true)
+            next_card.learning_steps = 0
+          end
+        else
+          # No step info: promote to REVIEW
+          next_card.state = State::REVIEW
+          interval = @algorithm.next_interval(next_card.stability, @elapsed_days)
+          next_card.scheduled_days = interval
+          next_card.due = Helpers.date_scheduler(@review_time, interval, true)
+          next_card.learning_steps = 0
+        end
+      end
+
+      def new_state(grade)
+        next_card = @current.clone
+        state_result = @algorithm.next_state(
+          { difficulty: 0, stability: 0 },
+          0,
+          grade
+        )
+
+        next_card.difficulty = state_result[:difficulty]
+        next_card.stability = state_result[:stability]
+
+        apply_learning_steps(next_card, grade, State::LEARNING)
+
+        log = build_log(grade)
+        RecordLogItem.new(card: next_card, log: log)
+      end
+
+      def learning_state(grade)
+        next_card = @current.clone
+        interval = @elapsed_days
+
+        state_result = @algorithm.next_state(
+          { difficulty: @last.difficulty, stability: @last.stability },
+          interval,
+          grade
+        )
+
+        next_card.difficulty = state_result[:difficulty]
+        next_card.stability = state_result[:stability]
+
+        to_state = @current.state == State::RELEARNING ? State::RELEARNING : State::LEARNING
+
+        if [Rating::AGAIN, Rating::HARD].include?(grade)
+          to_state = @current.state == State::RELEARNING ? State::RELEARNING : State::LEARNING
+        end
+
+        apply_learning_steps(next_card, grade, to_state)
+
+        log = build_log(grade)
+        RecordLogItem.new(card: next_card, log: log)
+      end
+
+      def review_state(grade)
+        interval = @elapsed_days
+        retrievability = @algorithm.forgetting_curve(@algorithm.parameters.w, interval, @last.stability)
+
+        next_card = @current.clone
+
+        state_result = @algorithm.next_state(
+          { difficulty: @last.difficulty, stability: @last.stability },
+          interval,
+          grade
+        )
+
+        next_card.difficulty = state_result[:difficulty]
+        next_card.stability = state_result[:stability]
+
+        if grade == Rating::AGAIN
+          next_card.lapses += 1
+          apply_learning_steps(next_card, grade, State::RELEARNING)
+        else
+          # Hard, Good, Easy: stay in REVIEW
+          next_card.state = State::REVIEW
+          next_card.learning_steps = 0
+
+          # Calculate stability for HARD rating to get correct hard_interval
+          hard_state = @algorithm.next_state(
+            { difficulty: @last.difficulty, stability: @last.stability },
+            interval,
+            Rating::HARD
+          )
+          hard_interval = @algorithm.next_interval(hard_state[:stability], interval)
+
+          # Calculate different intervals for each grade
+          if grade == Rating::HARD
+            next_card.scheduled_days = hard_interval
+          elsif grade == Rating::GOOD
+            good_interval = @algorithm.next_interval(next_card.stability, interval)
+            # Only enforce ordering if intervals would violate it and we're not at max_interval
+            if good_interval <= hard_interval && hard_interval < @algorithm.parameters.maximum_interval
+              good_interval = [good_interval, hard_interval + 1].max
+            end
+            next_card.scheduled_days = good_interval
+          else # EASY
+            good_state = @algorithm.next_state(
+              { difficulty: @last.difficulty, stability: @last.stability },
+              interval,
+              Rating::GOOD
+            )
+            good_interval = @algorithm.next_interval(good_state[:stability], interval)
+
+            easy_state = @algorithm.next_state(
+              { difficulty: @last.difficulty, stability: @last.stability },
+              interval,
+              Rating::EASY
+            )
+            easy_interval = @algorithm.next_interval(easy_state[:stability], interval)
+            # Only enforce ordering if intervals would violate it and we're not at max_interval
+            if easy_interval <= good_interval && good_interval < @algorithm.parameters.maximum_interval
+              easy_interval = [easy_interval, good_interval + 1].max
+            end
+            next_card.scheduled_days = easy_interval
+          end
+
+          next_card.due = Helpers.date_scheduler(@review_time, next_card.scheduled_days, true)
+        end
+
+        log = build_log(grade)
+        RecordLogItem.new(card: next_card, log: log)
+      end
+    end
+  end
+end

data/lib/fsrs_ruby/schedulers/long_term_scheduler.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module FsrsRuby
+  module Schedulers
+    # Scheduler without short-term learning (no learning steps)
+    class LongTermScheduler < BaseScheduler
+      protected
+
+      def new_state(grade)
+        next_card = @current.clone
+
+        state_result = @algorithm.next_state(
+          { difficulty: 0, stability: 0 },
+          0,
+          grade
+        )
+
+        next_card.difficulty = state_result[:difficulty]
+        next_card.stability = state_result[:stability]
+        next_card.state = State::REVIEW
+        next_card.learning_steps = 0
+
+        interval = @algorithm.next_interval(next_card.stability, 0)
+        next_card.scheduled_days = interval
+        next_card.due = Helpers.date_scheduler(@review_time, interval, true)
+
+        log = build_log(grade)
+        RecordLogItem.new(card: next_card, log: log)
+      end
+
+      def learning_state(grade)
+        # Treat learning as review
+        review_state(grade)
+      end
+
+      def review_state(grade)
+        interval = @elapsed_days
+        next_card = @current.clone
+
+        state_result = @algorithm.next_state(
+          { difficulty: @last.difficulty, stability: @last.stability },
+          interval,
+          grade
+        )
+
+        next_card.difficulty = state_result[:difficulty]
+        next_card.stability = state_result[:stability]
+        next_card.state = State::REVIEW
+        next_card.learning_steps = 0
+
+        next_card.lapses += 1 if grade == Rating::AGAIN
+
+        # Calculate intervals for all ratings using their respective stabilities
+        intervals = [Rating::AGAIN, Rating::HARD, Rating::GOOD, Rating::EASY].map do |g|
+          temp_state = @algorithm.next_state(
+            { difficulty: @last.difficulty, stability: @last.stability },
+            interval,
+            g
+          )
+          @algorithm.next_interval(temp_state[:stability], interval)
+        end
+
+        # Ensure ordering only when necessary (don't artificially inflate intervals)
+        # But respect maximum_interval - don't force intervals beyond it
+        max_interval = @algorithm.parameters.maximum_interval
+        intervals[0] = [intervals[0], intervals[1]].min # again <= hard
+        if intervals[1] <= intervals[0] && intervals[0] < max_interval
+          intervals[1] = [intervals[1], intervals[0] + 1].max
+        end  # hard > again
+        if intervals[2] <= intervals[1] && intervals[1] < max_interval
+          intervals[2] = [intervals[2], intervals[1] + 1].max
+        end  # good > hard
+        if intervals[3] <= intervals[2] && intervals[2] < max_interval
+          intervals[3] = [intervals[3], intervals[2] + 1].max
+        end  # easy > good
+
+        scheduled_days = intervals[[Rating::AGAIN, Rating::HARD, Rating::GOOD, Rating::EASY].index(grade)]
+        next_card.scheduled_days = scheduled_days
+        next_card.due = Helpers.date_scheduler(@review_time, scheduled_days, true)
+
+        log = build_log(grade)
+        RecordLogItem.new(card: next_card, log: log)
+      end
+    end
+  end
+end

data/lib/fsrs_ruby/strategies/learning_steps.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module FsrsRuby
+  module Strategies
+    # Convert step unit string to minutes
+    # @param step [String] Step string like "1m", "10m", "5h", "2d"
+    # @return [Integer] Minutes
+    def self.convert_step_unit_to_minutes(step)
+      unit = step[-1]
+      value = step[0...-1].to_i
+
+      raise ArgumentError, "Invalid step value: #{step}" if value < 0
+
+      case unit
+      when 'm'
+        value
+      when 'h'
+        value * 60
+      when 'd'
+        value * 1440
+      else
+        raise ArgumentError, "Invalid step unit: #{step}, expected m/h/d"
+      end
+    end
+
+    # Basic learning steps strategy
+    # @param parameters [Parameters] FSRS parameters
+    # @param state [Integer] Current state
+    # @param cur_step [Integer] Current step index
+    # @return [Hash] Mapping of ratings to { scheduled_minutes:, next_step: }
+    def self.basic_learning_steps_strategy(parameters, state, cur_step)
+      learning_steps = if [State::RELEARNING, State::REVIEW].include?(state)
+                         parameters.relearning_steps
+                       else
+                         parameters.learning_steps
+                       end
+
+      steps_length = learning_steps.length
+      return {} if steps_length.zero? || cur_step >= steps_length
+
+      first_step = learning_steps[0]
+
+      result = {}
+
+      if state == State::REVIEW
+        # Review → again: return first relearning step
+        result[Rating::AGAIN] = {
+          scheduled_minutes: convert_step_unit_to_minutes(first_step),
+          next_step: 0
+        }
+      else
+        # New, Learning, Relearning states
+        result[Rating::AGAIN] = {
+          scheduled_minutes: convert_step_unit_to_minutes(first_step),
+          next_step: 0
+        }
+
+        # Hard interval
+        hard_minutes = if steps_length == 1
+                         (convert_step_unit_to_minutes(first_step) * 1.5).round
+                       else
+                         second_step = learning_steps[1]
+                         ((convert_step_unit_to_minutes(first_step) + convert_step_unit_to_minutes(second_step)) / 2.0).round
+                       end
+
+        result[Rating::HARD] = {
+          scheduled_minutes: hard_minutes,
+          next_step: cur_step
+        }
+
+        # Good: advance to next step if it exists
+        next_step_index = cur_step + 1
+        if next_step_index < steps_length
+          next_step = learning_steps[next_step_index]
+          result[Rating::GOOD] = {
+            scheduled_minutes: convert_step_unit_to_minutes(next_step).round,
+            next_step: next_step_index
+          }
+        end
+      end
+
+      result
+    end
+  end
+end

data/lib/fsrs_ruby/strategies/seed.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module FsrsRuby
+  module Strategies
+    # Default seed strategy using review time and card properties
+    # @param scheduler [BaseScheduler] Scheduler instance
+    # @return [String] Seed string
+    def self.default_init_seed_strategy(scheduler)
+      time = scheduler.review_time.to_i
+      reps = scheduler.current.reps
+      mul = (scheduler.current.difficulty * scheduler.current.stability).round(2)
+      "#{time}_#{reps}_#{mul}"
+    end
+
+    # Generate seed strategy with card ID field
+    # @param card_id_field [String, Symbol] Field name for card ID
+    # @return [Proc] Seed strategy proc
+    def self.gen_seed_strategy_with_card_id(card_id_field)
+      ->(scheduler) do
+        card_id = scheduler.current.send(card_id_field)
+        reps = scheduler.current.reps || 0
+        "#{card_id}#{reps}"
+      end
+    end
+  end
+end

data/lib/fsrs_ruby/type_converter.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module FsrsRuby
+  # Type conversion utilities for normalizing inputs
+  class TypeConverter
+    # Convert various time formats to Time object
+    # @param value [Time, Integer, String] Time value
+    # @return [Time] Normalized Time object
+    def self.time(value)
+      case value
+      when Time
+        value
+      when Integer
+        Time.at(value)
+      when String
+        Time.parse(value)
+      else
+        raise ArgumentError, "Invalid time: #{value}"
+      end
+    end
+
+    # Convert string or integer to State constant
+    # @param value [Integer, String, Symbol] State value
+    # @return [Integer] State constant
+    def self.state(value)
+      case value
+      when Integer
+        raise ArgumentError, "Invalid state: #{value}" unless State.valid?(value)
+        value
+      when String, Symbol
+        State.from_string(value.to_s)
+      else
+        raise ArgumentError, "Invalid state: #{value}"
+      end
+    end
+
+    # Convert string or integer to Rating constant
+    # @param value [Integer, String, Symbol] Rating value
+    # @return [Integer] Rating constant
+    def self.rating(value)
+      case value
+      when Integer
+        raise ArgumentError, "Invalid rating: #{value}" unless Rating.valid?(value)
+        value
+      when String, Symbol
+        Rating.from_string(value.to_s)
+      else
+        raise ArgumentError, "Invalid rating: #{value}"
+      end
+    end
+
+    # Normalize Card object
+    # @param card_input [Card, Hash] Card or hash with card data
+    # @return [Card] Normalized Card object
+    def self.card(card_input)
+      return card_input if card_input.is_a?(Card)
+
+      Card.new(
+        due: time(card_input[:due]),
+        stability: card_input[:stability] || 0.0,
+        difficulty: card_input[:difficulty] || 0.0,
+        elapsed_days: card_input[:elapsed_days] || 0,
+        scheduled_days: card_input[:scheduled_days] || 0,
+        learning_steps: card_input[:learning_steps] || 0,
+        reps: card_input[:reps] || 0,
+        lapses: card_input[:lapses] || 0,
+        state: state(card_input[:state] || State::NEW),
+        last_review: card_input[:last_review] ? time(card_input[:last_review]) : nil
+      )
+    end
+  end
+end

data/lib/fsrs_ruby/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module FsrsRuby
+  VERSION = '1.0.0'
+  FSRS_VERSION = "v#{VERSION} using FSRS-6.0"
+end

data/lib/fsrs_ruby.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Main FSRS Ruby module
+module FsrsRuby
+  class Error < StandardError; end
+end
+
+# Require all components in correct order
+require_relative 'fsrs_ruby/version'
+require_relative 'fsrs_ruby/constants'
+require_relative 'fsrs_ruby/models'
+require_relative 'fsrs_ruby/helpers'
+require_relative 'fsrs_ruby/type_converter'
+require_relative 'fsrs_ruby/alea'
+require_relative 'fsrs_ruby/parameters'
+require_relative 'fsrs_ruby/algorithm'
+require_relative 'fsrs_ruby/strategies/learning_steps'
+require_relative 'fsrs_ruby/strategies/seed'
+require_relative 'fsrs_ruby/schedulers/base_scheduler'
+require_relative 'fsrs_ruby/schedulers/basic_scheduler'
+require_relative 'fsrs_ruby/schedulers/long_term_scheduler'
+require_relative 'fsrs_ruby/fsrs_instance'
+
+module FsrsRuby
+  # Factory method to create FSRS instance
+  # @param params [Hash] FSRS parameters
+  # @return [FSRSInstance] FSRS instance
+  def self.new(params = {})
+    FSRSInstance.new(params)
+  end
+
+  # Create an empty card
+  # @param now [Time, nil] Current time
+  # @return [Card] New empty card
+  def self.create_empty_card(now = nil)
+    ParameterUtils.create_empty_card(now)
+  end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: fsrs_ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ondrej Rohon
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: "    A complete Ruby port of the TypeScript FSRS v6.0 algorithm for spaced
+  repetition \n    scheduling. Implements exponential difficulty, linear damping,
+  and 21-parameter \n    optimization for optimal review timing in flashcard and learning
+  applications.\n"
+email:
+- ondrej.rohon@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- TESTING.md
+- VERIFICATION_REPORT.md
+- VERIFICATION_SUMMARY.md
+- lib/fsrs_ruby.rb
+- lib/fsrs_ruby/alea.rb
+- lib/fsrs_ruby/algorithm.rb
+- lib/fsrs_ruby/constants.rb
+- lib/fsrs_ruby/fsrs_instance.rb
+- lib/fsrs_ruby/helpers.rb
+- lib/fsrs_ruby/models.rb
+- lib/fsrs_ruby/parameters.rb
+- lib/fsrs_ruby/schedulers/base_scheduler.rb
+- lib/fsrs_ruby/schedulers/basic_scheduler.rb
+- lib/fsrs_ruby/schedulers/long_term_scheduler.rb
+- lib/fsrs_ruby/strategies/learning_steps.rb
+- lib/fsrs_ruby/strategies/seed.rb
+- lib/fsrs_ruby/type_converter.rb
+- lib/fsrs_ruby/version.rb
+homepage: https://github.com/ondrejrohon/fsrs_ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ondrejrohon/fsrs_ruby
+  source_code_uri: https://github.com/ondrejrohon/fsrs_ruby
+  changelog_uri: https://github.com/ondrejrohon/fsrs_ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ondrejrohon/fsrs_ruby/issues
+  documentation_uri: https://rubydoc.info/gems/fsrs_ruby
+  wiki_uri: https://github.com/ondrejrohon/fsrs_ruby/wiki
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+post_install_message: "    ✨ Thank you for installing fsrs_ruby! ✨\n\n    This is
+  a Ruby port of FSRS v6.0 (Free Spaced Repetition Scheduler).\n\n    \U0001F4D6 Documentation:
+  https://github.com/ondrejrohon/fsrs_ruby\n    \U0001F41B Report issues: https://github.com/ondrejrohon/fsrs_ruby/issues\n\n
+  \   Cross-validated with 80%+ test coverage and 8-decimal precision.\n"
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby implementation of FSRS (Free Spaced Repetition Scheduler) v6.0
+test_files: []