nagori-fsrs 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 302362c037692cd7f93735fff5006eef832e014f55395302ff30f96d70adaabe
+  data.tar.gz: 1feeafec2ace2dee429a15095dffa08e5c2bfb1159fcd7b67965f7371714a787
+SHA512:
+  metadata.gz: 6dca3dd247c4db075346f5a9e2a60ddb28e77433cbb4867de0bbcb3da71ccdc1f362eaa7fc92680014f7d418140c82065e59f2079ba4bbf9d3090eaaad791424
+  data.tar.gz: 3982242047ccfde18eac3e5351421c9e3c3cdaddd01b97e53522de3f8371708391036c35ace372300bed1c6301f8c0de97253932bc71c741e3cd6545b1fb53d2

data/LICENSE

@@ -0,0 +1,33 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, David Afonso (Nagori Ruby bindings)
+Copyright (c) 2023, Open Spaced Repetition (fsrs-rs, the wrapped `fsrs` crate)
+
+Nagori is a Ruby binding for fsrs-rs (https://github.com/open-spaced-repetition/fsrs-rs),
+which is distributed under the BSD 3-Clause License. This gem redistributes and
+links against that crate; its copyright notice is retained above as required.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,169 @@
+# Nagori 名残
+
+Ruby bindings for [fsrs-rs](https://github.com/open-spaced-repetition/fsrs-rs)
+(the [`fsrs`](https://crates.io/crates/fsrs) crate) — the **FSRS-6** spaced-
+repetition scheduler, optimizer, and simulator, in Rust.
+
+Nagori is a thin, idiomatic wrapper: plain Ruby values in and out (hashes,
+arrays, keyword args), the number crunching in Rust. Long-running calls
+(`compute_parameters`, `evaluate`, `simulate`, `optimal_retention`) release the
+GVL so they don't block other threads.
+
+Built the same way as [kabosu](https://github.com/davafons/kabosu):
+[rb_sys](https://github.com/oxidize-rb/rb-sys) + [magnus](https://github.com/matsadler/magnus),
+precompiled for the usual platform matrix.
+
+## Install
+
+```ruby
+# Gemfile
+gem "nagori-fsrs"
+```
+
+During development against a checkout:
+
+```ruby
+gem "nagori-fsrs", path: "../nagori-fsrs"
+```
+
+## Concepts
+
+- **Rating** is `1 = Again`, `2 = Hard`, `3 = Good`, `4 = Easy` (symbols
+  `:again/:hard/:good/:easy` are accepted anywhere a rating is taken).
+- **A review** is `{ rating:, delta_t: }`, where `delta_t` is **whole days since
+  the previous review**, `0` for the first review and for same-day re-reviews.
+- **Intervals** come back as **fractional, unrounded `f32` days**. Nagori never
+  rounds — rounding, fuzz, and load-balancing are application policy.
+- **Parameters** are the FSRS weight vector. `nil`/empty uses
+  `Nagori::DEFAULT_PARAMETERS`; 17- (FSRS-4.5) and 19-length (FSRS-5) vectors are
+  accepted and padded to the 21-length FSRS-6 shape.
+
+## Scheduling
+
+```ruby
+require "nagori-fsrs"
+
+fsrs = Nagori::FSRS.new                 # default parameters
+# fsrs = Nagori::FSRS.new(my_21_floats) # or a trained vector
+
+# The four answer buttons for a brand-new card (nil memory state):
+fsrs.next_states(nil, 0.9, 0)
+# => { again: { stability: 0.212, difficulty: 6.413, interval: 0.212 },
+#      hard:  { ... }, good: { ... }, easy: { ... } }
+
+# For a card with an existing memory state, 5 days elapsed:
+fsrs.next_states({ stability: 10.0, difficulty: 5.0 }, 0.9, 5)
+```
+
+`next_states(memory_state, desired_retention, days_elapsed)` returns a hash of
+the four buttons; each is `{ stability:, difficulty:, interval: }`.
+
+## Replaying history → memory state
+
+```ruby
+reviews = [
+  { rating: 3, delta_t: 0 },   # first review, same day
+  { rating: 3, delta_t: 5 },
+  { rating: 4, delta_t: 20 }
+]
+fsrs.memory_state(reviews)              # => { stability:, difficulty: }
+
+# Batch (Anki import / FSRS-6 migration):
+fsrs.memory_state_batch([reviews, other_reviews])
+# => [{ stability:, difficulty: }, ...]
+
+# No revlog, only SM-2 values:
+fsrs.memory_state_from_sm2(2.5, 10.0, 0.9)   # ease, interval, retention
+```
+
+## Intervals & retrievability
+
+```ruby
+fsrs.next_interval(nil, 0.9, 3)             # new card, Good -> fractional days
+fsrs.next_interval(100.0, 0.9, 3)           # from a known stability
+
+Nagori.current_retrievability({ stability: 10.0, difficulty: 5.0 }, 5.0)
+# decay defaults to Nagori::FSRS6_DEFAULT_DECAY; pass a third arg to override
+```
+
+## Optimizer
+
+`compute_parameters` and `evaluate` take a **training set**: one item per
+review, each item a *prefix* of a card's history (all prefixes of length ≥ 2).
+fsrs-rs does not expand histories for you — pretraining keys off the
+exactly-one-long-term-review prefixes.
+
+```ruby
+# items: Array of Array-of-{rating:, delta_t:}
+params = Nagori.compute_parameters(items, enable_short_term: true)
+# => 21 floats (GVL released during training)
+
+# Health check: does a candidate parameter set fit the data?
+Nagori::FSRS.new(params).evaluate(items)     # => { log_loss:, rmse_bins: }
+```
+
+Typical apply-only-if-better gate:
+
+```ruby
+old_fit = Nagori::FSRS.new(current_params).evaluate(items)
+new_fit = Nagori::FSRS.new(candidate_params).evaluate(items)
+apply = new_fit[:log_loss] < old_fit[:log_loss]
+```
+
+## Simulator
+
+```ruby
+# Project reviews/day and memorized count over a horizon:
+Nagori.simulate(Nagori::DEFAULT_PARAMETERS, 0.9,
+                config: { learn_span: 90, deck_size: 1000 }, seed: 42)
+# => { memorized_cnt_per_day:, review_cnt_per_day:, learn_cnt_per_day:,
+#      cost_per_day:, correct_cnt_per_day:, introduced_cnt_per_day:,
+#      average_desired_retention: }
+
+# Retention-slider preview (expected daily seconds of work):
+Nagori.expected_workload(params, 0.95, config: { deck_size: 1000 })
+
+# Suggested retention (CMRR); GVL released:
+Nagori.optimal_retention(params, config: { learn_span: 365 })
+
+# Calibrate a config from Anki-style revlog rows:
+config = Nagori.extract_simulator_config(revlog_entries, day_cutoff)
+Nagori.simulate(params, 0.9, config: config)
+```
+
+`config` is a plain hash; any omitted key falls back to fsrs-rs's default
+`SimulatorConfig`. The closure hooks (`post_scheduling_fn`,
+`review_priority_fn`) are intentionally not exposed. Each revlog entry is a hash
+with `:id, :cid, :usn, :button_chosen, :interval, :last_interval, :ease_factor,
+:taken_millis, :review_kind` (review_kind `0..4`).
+
+## Errors
+
+Invalid input (bad parameter length, rating outside `1..4`, negative `delta_t`,
+malformed memory state) raises `ArgumentError`. Computation failures surface as
+`RuntimeError`.
+
+## Version pinning
+
+The wrapped crate is pinned exactly (`fsrs = "=6.6.x"` in
+`ext/nagori/Cargo.toml`) because a crate bump can shift scheduler outputs. The
+gem's golden tests assert exact stability/difficulty/interval values, so a bump
+that changes results fails loudly. Bump the pin and the golden vectors together.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake compile
+bundle exec rake test
+```
+
+Requires a Rust toolchain (stable). Tests are Minitest with golden vectors
+generated from fsrs-rs itself.
+
+## License & attribution
+
+Nagori is released under the **BSD 3-Clause License**. It wraps and
+redistributes [fsrs-rs](https://github.com/open-spaced-repetition/fsrs-rs)
+(© 2023 Open Spaced Repetition), also BSD 3-Clause. See [LICENSE](LICENSE) for
+both copyright notices.

data/lib/nagori/version.rb

@@ -0,0 +1,3 @@
+module Nagori
+  VERSION = "0.1.0".freeze
+end

data/lib/nagori-fsrs.rb

@@ -0,0 +1,2 @@
+# Bundler auto-requires the gem name; the code lives under lib/nagori.
+require_relative "nagori"

data/lib/nagori.rb

@@ -0,0 +1,233 @@
+require_relative "nagori/version"
+
+# Load the native extension. Precompiled gems place it under a per-Ruby-version
+# subdirectory (lib/nagori/3.3/nagori.bundle, etc.); a source build leaves it at
+# lib/nagori/nagori.{bundle,so}. Try the version-suffixed path first, fall back
+# to the flat path so dev/source builds keep working.
+begin
+  major_minor = RUBY_VERSION.split(".").take(2).join(".")
+  require_relative "nagori/#{major_minor}/nagori"
+rescue LoadError
+  require_relative "nagori/nagori"
+end
+
+# Ruby bindings for fsrs-rs (the `fsrs` crate), FSRS-6.
+#
+# Plain values in and out: reviews are `{ rating:, delta_t: }` hashes (rating
+# 1=Again 2=Hard 3=Good 4=Easy; delta_t = whole days since the previous review,
+# 0 for the first review and same-day re-reviews). Intervals come back as
+# fractional, unrounded f32 days — rounding/fuzz policy lives in the caller.
+module Nagori
+  class Error < StandardError; end
+
+  # The 21-float FSRS-6 default weights (fallback when a user has no trained
+  # parameters yet).
+  DEFAULT_PARAMETERS = _default_parameters.freeze
+
+  # FSRS-6's default forgetting-curve decay; the default for
+  # `current_retrievability`'s decay argument. Equals DEFAULT_PARAMETERS[20].
+  FSRS6_DEFAULT_DECAY = 0.1542
+
+  # Rating encoding, matching Anki / Shirabe's Review::RATINGS.
+  RATINGS = { again: 1, hard: 2, good: 3, easy: 4 }.freeze
+
+  module_function
+
+  # Train 21 FSRS-6 parameters from review history. `items` is an array of
+  # cards, each a chronological array of `{ rating:, delta_t: }` reviews.
+  # Returns 21 floats. Releases the GVL — this is CPU-heavy.
+  def compute_parameters(items, enable_short_term: true, num_relearning_steps: nil)
+    unless num_relearning_steps.nil?
+      num_relearning_steps = Integer(num_relearning_steps)
+      raise ArgumentError, "num_relearning_steps must be >= 0" if num_relearning_steps.negative?
+    end
+    _compute_parameters(flatten_items(items), enable_short_term ? true : false, num_relearning_steps)
+  end
+
+  # Retrievability (recall probability) of a memory state after `days_elapsed`
+  # days. `state` is `{ stability:, difficulty: }`.
+  def current_retrievability(state, days_elapsed, decay = FSRS6_DEFAULT_DECAY)
+    stability, difficulty = memory_pair(state)
+    _current_retrievability(stability, difficulty, Float(days_elapsed), Float(decay))
+  end
+
+  # Project reviews/day and memorized count over the horizon. Returns a hash of
+  # per-day arrays (`:memorized_cnt_per_day`, `:review_cnt_per_day`,
+  # `:learn_cnt_per_day`, `:cost_per_day`, `:correct_cnt_per_day`,
+  # `:introduced_cnt_per_day`, `:average_desired_retention`). Releases the GVL.
+  def simulate(parameters, desired_retention, config: nil, seed: nil, existing_cards: nil)
+    result = _simulate(
+      params_array(parameters),
+      Float(desired_retention),
+      stringify_keys(config),
+      seed.nil? ? nil : Integer(seed),
+      cards_array(existing_cards)
+    )
+    symbolize_keys(result)
+  end
+
+  # Expected daily workload (seconds) at the given retention. Powers the
+  # retention-slider preview.
+  def expected_workload(parameters, desired_retention, config: nil)
+    _expected_workload(params_array(parameters), Float(desired_retention), stringify_keys(config))
+  end
+
+  # Suggested retention (CMRR) minimizing workload for the memorized target.
+  # Releases the GVL.
+  def optimal_retention(parameters, config: nil)
+    _optimal_retention(params_array(parameters), stringify_keys(config))
+  end
+
+  # Calibrate a SimulatorConfig from Anki-style revlog rows. Each entry is a
+  # hash with keys :id, :cid, :usn, :button_chosen, :interval, :last_interval,
+  # :ease_factor, :taken_millis, :review_kind (0..4). Returns a config hash
+  # suitable for `simulate`/`expected_workload`.
+  def extract_simulator_config(revlog_entries, day_cutoff, smooth: true)
+    entries = Array(revlog_entries).map { |entry| stringify_keys(entry) }
+    config = _extract_simulator_config(entries, Integer(day_cutoff), smooth ? true : false)
+    symbolize_keys(config)
+  end
+
+  # ── Shared input coercion (also used by Nagori::FSRS) ──
+
+  def rating_int(rating)
+    value = rating.is_a?(Symbol) ? RATINGS[rating] : rating
+    value = Integer(value) if value
+    unless value&.between?(1, 4)
+      raise ArgumentError, "rating must be 1..4 or #{RATINGS.keys.inspect}, got #{rating.inspect}"
+    end
+
+    value
+  end
+
+  def flatten_reviews(reviews)
+    Array(reviews).flat_map do |review|
+      rating = rating_int(review.fetch(:rating) { review[:rating] })
+      delta_t = Integer(review.fetch(:delta_t) { review[:delta_t] })
+      raise ArgumentError, "delta_t must be >= 0, got #{delta_t}" if delta_t.negative?
+
+      [rating, delta_t]
+    end
+  end
+
+  def flatten_items(items)
+    Array(items).map { |reviews| flatten_reviews(reviews) }
+  end
+
+  def memory_pair(state)
+    raise ArgumentError, "memory state is required" if state.nil?
+
+    [Float(state.fetch(:stability)), Float(state.fetch(:difficulty))]
+  end
+
+  def memory_pair_or_empty(state)
+    state.nil? ? [] : memory_pair(state)
+  end
+
+  def params_array(parameters)
+    return [] if parameters.nil?
+
+    Array(parameters).map { |value| Float(value) }
+  end
+
+  def stringify_keys(hash)
+    hash&.to_h { |key, value| [key.to_s, value] }
+  end
+
+  def symbolize_keys(hash)
+    hash.to_h { |key, value| [key.to_sym, value] }
+  end
+
+  def cards_array(cards)
+    cards.nil? ? nil : Array(cards).map { |card| stringify_keys(card) }
+  end
+
+  # A configured FSRS-6 scheduler. Build once per parameter set and reuse.
+  class FSRS
+    # nil/empty parameters use DEFAULT_PARAMETERS; 17/19/21-length vectors are
+    # accepted (padded internally). Invalid input raises ArgumentError.
+    def self.new(parameters = nil)
+      _new(Nagori.params_array(parameters))
+    end
+
+    # The 21-float parameter vector (input padded to FSRS-6 length).
+    def parameters
+      _parameters
+    end
+
+    # Memory states and intervals for each answer button. `memory_state` is nil
+    # for a new card or `{ stability:, difficulty: }`. Returns
+    # `{ again:, hard:, good:, easy: }`, each `{ stability:, difficulty:,
+    # interval: }` with interval in fractional, unrounded days.
+    def next_states(memory_state, desired_retention, days_elapsed)
+      raw = _next_states(
+        Nagori.memory_pair_or_empty(memory_state),
+        Float(desired_retention),
+        Integer(days_elapsed)
+      )
+      {
+        again: state_at(raw, 0),
+        hard: state_at(raw, 3),
+        good: state_at(raw, 6),
+        easy: state_at(raw, 9)
+      }
+    end
+
+    # Memory state after replaying `reviews` (array of `{ rating:, delta_t: }`).
+    # `starting_state` seeds a truncated history (e.g. from SM-2). Returns
+    # `{ stability:, difficulty: }`.
+    def memory_state(reviews, starting_state = nil)
+      pair = _memory_state(Nagori.flatten_reviews(reviews), Nagori.memory_pair_or_empty(starting_state))
+      { stability: pair[0], difficulty: pair[1] }
+    end
+
+    # Batch form of #memory_state. `items` is an array of review arrays;
+    # `starting_states` is a matching array of `{ stability:, difficulty: }` or
+    # nil (defaults to all-new). Returns an array of `{ stability:, difficulty: }`.
+    def memory_state_batch(items, starting_states = nil)
+      flat_items = Nagori.flatten_items(items)
+      starts = normalize_starting_states(starting_states, flat_items.length)
+      _memory_state_batch(flat_items, starts).each_slice(2).map do |stability, difficulty|
+        { stability: stability, difficulty: difficulty }
+      end
+    end
+
+    # Approximate a memory state from SM-2 values for cards imported without a
+    # full revlog. Returns `{ stability:, difficulty: }`.
+    def memory_state_from_sm2(ease_factor, interval, sm2_retention)
+      pair = _memory_state_from_sm2(Float(ease_factor), Float(interval), Float(sm2_retention))
+      { stability: pair[0], difficulty: pair[1] }
+    end
+
+    # Interval (fractional days) for a memory state at the desired retention.
+    # `stability` is nil for a new card (initial stability for `rating` is used;
+    # rating is otherwise ignored).
+    def next_interval(stability, desired_retention, rating)
+      stab = stability.nil? ? [] : [Float(stability)]
+      _next_interval(stab, Float(desired_retention), Nagori.rating_int(rating))
+    end
+
+    # Model fit over `items` (array of review arrays). Returns
+    # `{ log_loss:, rmse_bins: }`. Releases the GVL.
+    def evaluate(items)
+      log_loss, rmse_bins = _evaluate(Nagori.flatten_items(items))
+      { log_loss: log_loss, rmse_bins: rmse_bins }
+    end
+
+    private
+
+    def state_at(raw, offset)
+      { stability: raw[offset], difficulty: raw[offset + 1], interval: raw[offset + 2] }
+    end
+
+    def normalize_starting_states(starting_states, count)
+      return Array.new(count) { [] } if starting_states.nil?
+
+      unless starting_states.length == count
+        raise ArgumentError, "starting_states length #{starting_states.length} != items length #{count}"
+      end
+
+      starting_states.map { |state| Nagori.memory_pair_or_empty(state) }
+    end
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: nagori-fsrs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-linux
+authors:
+- davafons
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-07-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !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: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: 'Nagori provides Ruby bindings for fsrs-rs (the `fsrs` crate), a Rust
+  implementation of the Free Spaced Repetition Scheduler (FSRS-6): scheduling, memory-state
+  replay, parameter optimization, and simulation.'
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/nagori-fsrs.rb
+- lib/nagori.rb
+- lib/nagori/3.1/nagori.so
+- lib/nagori/3.2/nagori.so
+- lib/nagori/3.3/nagori.so
+- lib/nagori/3.4/nagori.so
+- lib/nagori/4.0/nagori.so
+- lib/nagori/version.rb
+homepage: https://github.com/davafons/nagori-fsrs
+licenses:
+- BSD-3-Clause
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Ruby bindings for fsrs-rs, the FSRS-6 spaced-repetition scheduler and optimizer
+test_files: []