Release version 0.2.0: Merge branch '0.2.0-dev'0.2.0

- Major changes on gnosis-algorithm
  - Add deck specific configuration
  - Add ef-increase, ef-decrease, ef-threshold
- Update to new db schema
  - Update decks schema for ef-increase, ef-decrease, ef-threshold &
    initial interval
- Major changes on gnosis-dashboard
- Major changes on adding mcq notes
- Major changes on editing notes

Fixing packaging issues for gnosis as well.  Since 0.1.9 we are using
read-string-from-buffer, for which we have to depend on emacs-29.1

1 files changed, 115 insertions, 71 deletions

diff --git a/gnosis-algorithm.el b/gnosis-algorithm.el
index e850c9f..cee1d13 100644
--- a/gnosis-algorithm.el
+++ b/gnosis-algorithm.el
@@ -1,12 +1,14 @@
 ;;; gnosis-algorithm.el --- Spaced Repetition Algorithm for Gnosis  -*- lexical-binding: t; -*-
 
-;; Copyright (C) 2023  Thanos Apollo
+;; Copyright (C) 2023-2024  Thanos Apollo
 
 ;; Author: Thanos Apollo <[email protected]>
 ;; Keywords: extensions
 ;; URL: https://git.thanosapollo.org/gnosis
 ;; Version: 0.0.1
 
+;; Package-Requires: ((emacs "29.1"))
+
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
 ;; the Free Software Foundation, either version 3 of the License, or
@@ -22,7 +24,26 @@
 
 ;;; Commentary:
 
-;; Work in progress
+;; Handles date calculation as well as ef & interval calculations.
+
+;; Gnosis implements a highly customizable algorithm, inspired by SM-2.
+;; Gnosis algorithm does not use user's subjective rating of a note to
+;; determine the next review interval, but instead uses the user's
+;; success or failure in recalling the answer of a note.
+
+;; Each gnosis note has an ef (easiness factor), which is a list of 3
+;; values.  The last value is the total ef for a note, which will be
+;; used to determine the next interval upon a successful answer recall,
+;; the second value is the ef-decrease value, this value will be
+;; subtracted from the the total ef upon failure to recall the answer of
+;; a note, the first value is the ef increase, will be added to the
+;; total ef upon a successful recall.
+
+;; Each gnosis deck has a gnosis-algorithm-ef-threshold, it's an
+;; integer value that refers to the consecutive success or failures to
+;; recall an answer.  Upon reaching the threshold, gnosis-algorithm-ef-decrease
+;; or gnosis-algorithm-ef-increase will be applied to the ef-increase or
+;; ef-decrease of note.
 
 ;;; Code:
 
@@ -30,7 +51,7 @@
 (require 'calendar)
 
 (defcustom gnosis-algorithm-interval '(1 3)
-  "Gnosis initial interval for successful reviews.
+  "Gnosis initial interval for initial successful reviews.
 
 First item: First interval,
 Second item: Second interval."
@@ -40,11 +61,9 @@ Second item: Second interval."
 (defcustom gnosis-algorithm-ef '(0.35 0.30 1.3)
   "Gnosis easiness factor.
 
-First item : Increase factor
-Second item: Decrease factor
-Third item : Starting total ef
-
-Note: Starting total ef should not be above 3.0"
+First item : Increase value
+Second item: Decrease value
+Third item : Total ef"
   :group 'gnosis
   :type '(list float))
 
@@ -53,10 +72,43 @@ Note: Starting total ef should not be above 3.0"
 
 Used to calcuate new interval for failed questions.
 
-NOTE: Do not change this value above 1"
+NOTE: This value should be less than 1.0."
+  :group 'gnosis
+  :type 'float)
+
+(defcustom gnosis-algorithm-ef-increase 0.1
+  "Value to increase ef increase value with.
+
+Increase ef-increase value by this amount for every
+`gnosis-algorithm-ef-threshold' number of successful reviews."
   :group 'gnosis
   :type 'float)
 
+(defcustom gnosis-algorithm-ef-decrease 0.2
+  "Value to decrease ef decrease value with.
+
+Decrease ef decrease value by this amount for every
+`gnosis-algorithm-ef-threshold' number of failed reviews."
+  :group 'gnosis
+  :type 'float)
+
+(defcustom gnosis-algorithm-ef-threshold 3
+  "Threshold for updating ef increase/decrease values.
+
+Refers to the number of consecutive successful or failed reviews."
+  :group 'gnosis
+  :type 'integer)
+
+(defun gnosis-algorithm-replace-at-index (index new-item list)
+  "Replace item at INDEX with NEW-ITEM in LIST."
+  (cl-loop for item in list
+	   for i from 0
+	   collect (if (= i index) new-item item)))
+
+(defun gnosis-algorithm-round-items (list)
+  "Round all items in LIST to 2 decimal places."
+  (cl-loop for item in list
+	   collect (/ (round (* item 100)) 100.0)))
 
 (defun gnosis-algorithm-date (&optional offset)
   "Return the current date in a list (year month day).
@@ -74,76 +126,68 @@ Optional integer OFFSET is a number of days from the current date."
 (defun gnosis-algorithm-date-diff (date)
   "Find the difference between the current date and the given DATE.
 
-DATE format must be given as (yyyy mm dd)
-The structure of the given date is (YEAR MONTH DAY)."
+DATE format must be given as (year month day)."
   (let ((given-date (encode-time 0 0 0 (caddr date) (cadr date) (car date))))
     (- (time-to-days (current-time))
        (time-to-days given-date))))
 
+(cl-defun gnosis-algorithm-next-ef (&key ef success increase decrease threshold
+					 c-successes c-failures)
+  "Return the new EF, (increase-value decrease-value total-value)
+
+Calculate the new e-factor given existing EF and SUCCESS, either t or nil.
 
-(defun gnosis-algorithm-e-factor (ef success)
-  "Calculate the new e-factor given existing EF and SUCCESS, either t or nil."
-  (pcase success
-    (`t (+ ef (car gnosis-algorithm-ef)))
-    (`nil (max 1.3 (- ef (cadr gnosis-algorithm-ef))))))
+Next EF is calculated as follows:
 
+Upon a successful review, increase total ef value (nth 2) by
+ef-increase value (nth 0).
 
-(cl-defun gnosis-algorithm-next-interval (&key last-interval review-num ef success failure-factor successful-reviews successful-reviews-c fails-c fails-t initial-interval)
+Upon a failed review, decrease total ef by ef-decrease value (nth 1).
+
+For every THRESHOLD of C-SUCCESSES (consecutive successful reviews)
+reviews, increase ef-increase by INCREASE.
+
+For every THRESHOLD of C-FAILURES reviews, decrease ef-decrease value
+by DECREASE."
+  (cl-assert (listp ef) nil "Assertion failed: ef must be a list")
+  (cl-assert (booleanp success) nil "Assertion failed: success must be a boolean value")
+  (cl-assert (numberp increase) nil "Assertion failed: increase must be a number")
+  (cl-assert (numberp decrease) nil "Assertion failed: decrease must be a number")
+  (cl-assert (numberp threshold) nil "Assertion failed: threshold must be a number")
+  (let ((threshold-p (= (% (max 1 (if success c-successes c-failures)) threshold) 0))
+	(new-ef (if success (gnosis-algorithm-replace-at-index 2 (+ (nth 2 ef) (nth 0 ef)) ef)
+		  (gnosis-algorithm-replace-at-index 2 (max 1.3 (- (nth 2 ef) (nth 1 ef))) ef))))
+    (cond ((and success threshold-p)
+	   (setf new-ef (gnosis-algorithm-replace-at-index 0 (+ (nth 0 ef) increase) new-ef)))
+	  ((and (not success) threshold-p
+		(setf new-ef (gnosis-algorithm-replace-at-index 1 (+ (nth 1 ef) decrease) new-ef)))))
+    (gnosis-algorithm-round-items new-ef)))
+
+(cl-defun gnosis-algorithm-next-interval (&key last-interval ef success successful-reviews
+					       failure-factor initial-interval)
   "Calculate next interval.
-- LAST-INTERVAL : The number of days since the item was last reviewed.
--review-num: Number of times the item has been reviewed.
-- EF : Easiness Factor.
-- SUCCESS : Success of the recall, ranges from 0 (unsuccessful) to 1
-  (successful).
-- FF: Failure factor
-- SUCCESSFUL-REVIEWS : Number of successful reviews.
-- SUCCESSFULL-REVIEWS-C: Successful reviews in a row.
-- FAILS-C: Failed reviews in a row.
-- FAILS-T: Total failed reviews.
-- INITIAL-INTERVAL: Initial intervals for successful reviews.
-
-Returns a list of: (INTERVAL N EF) where,
-- Next review date in (yyyy mm dd) format.
-- REVIEW-NUM: Incremented by 1.
-- EF : Modified based on the recall success for the item."
-  ;; Check if gnosis-algorithm-ff is lower than 1 & is total-ef above 1.3
-  (cond ((>= gnosis-algorithm-ff 1)
-	 (error "Value of `gnosis-algorithm-ff' must be lower than 1"))
-	((< (nth 2 gnosis-algorithm-ef) 1.3)
-	 (error "Value of total-ef from `gnosis-algorithm-ef' must be above 1.3")))
-  ;; Calculate the next easiness factor.
-  (let* ((next-ef (gnosis-algorithm-e-factor ef success))
-         (interval
-          (cond
-	   ;; TODO: Rewrite this!
-           ;; First successful review -> first interval
-           ((and (= successful-reviews 0) success
-		 (car initial-interval)))
-           ;; Second successful review -> second interval
-           ((and (= successful-reviews 1) success)
-	    (cadr initial-interval))
-	   ;; When successful-reviews-c is above 3, use 150% or 180%
-	   ;; of ef depending on the value of successful-reviews
-	   ((and success
-		 (>= successful-reviews-c 3)
-		 (>= review-num 5)
-		 (> last-interval 1))
-	    (* (* ef (if (>= successful-reviews 10) 1.8 1.5)) last-interval))
-	   ((and (equal success nil)
-		 (> fails-c 3)
-		 (>= review-num 5)
-		 (> last-interval 1))
-	    ;; When fails-c is above 3, use 150% or 180% of
-	    ;; failure-factor depending on the value of total failed
-	    ;; reviews.
-	    (* (max (min 0.8 (* failure-factor (if (>= fails-t 10) 1.8 1.5)))
-		     failure-factor)
-		last-interval))
-	   ;; For everything else
-           (t (if success
-                  (* ef last-interval)
-                (* failure-factor last-interval))))))
-    (list (gnosis-algorithm-date (round interval)) next-ef)))
+
+LAST-INTERVAL: number of days since last review
+EF: Easiness factor
+SUCCESS: t if review was successful, nil otherwise
+SUCCESSFUL-REVIEWS: number of successful reviews
+FAILURE-FACTOR: factor to multiply last interval by if review was unsuccessful
+INITIAL-INTERVAL: list of initial intervals for initial successful
+reviews.  Will be used to determine the next interval for the first 2
+successful reviews."
+  (cl-assert (< gnosis-algorithm-ff 1) "Value of `gnosis-algorithm-ff' must be lower than 1")
+  ;; This should only occur in testing env or when the user has made breaking changes.
+  (cl-assert (> (nth 2 ef) 1) "Total ef value must be above 1")
+  (let* ((ef (nth 2 gnosis-algorithm-ef))
+	 (interval (cond ((and (= successful-reviews 0) success)
+			  (car initial-interval))
+			 ((and (= successful-reviews 1) success)
+			  (cadr initial-interval))
+			 (t (if success
+				(* ef last-interval)
+			      (* failure-factor last-interval))))))
+    (gnosis-algorithm-date (round interval))))
+
 
 (provide 'gnosis-algorithm)
 ;;; gnosis-algorithm.el ends here